alexandregpereira/monster-compendium

DnD 5th edition monster compendium multiplataform app for Android & iOS.

Monster Compendium - D&D 5th Edition Bestiary

Monsters Compendium is an open-source Kotlin Multiplatform application for both Android and iOS, offering extensive information on monsters from the Dungeons & Dragons 5th edition role-playing game. The default content is derived from the SRD (System Reference Document), providing a solid foundation for users. Furthermore, the app supports the addition of new custom content, enhancing its versatility and adaptability for players and game masters alike.

Preview

Key features:

• A well-organized monster compendium, divided into intuitive sections for easy navigation, complete with visually appealing images for an engaging user experience.
• Comprehensive monster details, featuring stat blocks, monster lore, captivating high-resolution images, and links to related spell details. Users can navigate through the compendium pages seamlessly, simulating the feel of paging through a physical book.
• Quick access to spell details of the monsters, providing essential information at your fingertips.
• A powerful search functionality that allows users to quickly find specific monsters.
• A user-friendly interface to organize monsters into customizable folders for better campaign management.

Tech Stack

The following is an overview of the key technologies and libraries used in this Kotlin Multiplatform project, each with a brief description and a URL for further information:

• Jetpack Compose: Android’s modern toolkit for building native UI. It simplifies and accelerates UI development on Android.
• SwiftUI:: A user interface toolkit for building modern, responsive apps for iOS, macOS, and more using Swift.
• Kotlin Coroutines: A coroutine is a concurrency design pattern that you can use on Android to simplify code that executes asynchronously.
• Kotlin Flow: Stream of data that can be computed asynchronously. Built in top of the Kotlin Coroutines.
• Koin: A pragmatic lightweight dependency injection framework for Kotlin & Kotlin Multiplatform.
• SQLDelight: A multiplatform SQLite library that generates Kotlin typesafe APIs from SQL statements.
• Ktor-client: A multiplatform asynchronous HTTP client for Kotlin, providing a clean and extensible API for making network requests.
• Multiplatform Settings: A library that provides a simple and consistent API for persisting key-value data across iOS, Android, and JVM platforms.
• Accompanist: A group of libraries that aim to supplement Jetpack Compose with features that are commonly required by developers but not yet available.
• Coil Compose: An image loading library for Android backed by Kotlin Coroutines and Jetpack Compose.
• Kotlin Serialization: A library for parsing and serializing JSON data, seamlessly converting API responses into Kotlin objects.

App Architecture

The app's architecture is based on the Model-View-Intent (MVI) pattern with Clean Architecture principles, implemented in a multi-module project, as illustrated in the image below:

Components Responsibilities

• UI: It is responsible for displaying data from the UI State to the user and handling user interactions.
• ViewModel: It transforms the domain model into a UI Model and sends it to the UI.
• StateHolder: It holds the UI State, manages the app's UI state and logic, and dispatches changes when receiving intents, enabling a reactive UI experience.
• UseCases: It contains the business logic, retrieving data from the Repository interface or coordinating with other use cases to perform complex tasks.
• Repository: It acts as a mediator between different data sources (network or database) and converts the data models into domain models, ensuring a clean separation of concerns
• DataSources: It is responsible for fetching and transferring data from a single source, such as an API or a local database, and returning the data in a consistent format.

Roadmap

UI

• Monster detail (iOS): In Progress
• Master Lore Detail (iOS): To Do
• Spell detail (iOS): To Do
• Bottom Bar Navigation (iOS): To Do
• Configuration screen (iOS): To Do
• Folder preview (iOS): To Do
• Monster folders (iOS): To Do
• Add Monster to Folder (iOS): To Do
• Search (iOS): To Do

Feature

• Remove monsters from folder (Android, iOS): To Do

Bugs

• Fix duplication of damage dice when changing to meters: To Fix

Adding New Content

You can add custom image and new monsters to the app. The tutorial can be found here.

API

Currently, there is no dedicated backend for the app. The app retrieves the data from static JSON files stored here. The JSON were formatted from the API https://dnd5eapi.co.

Content License

The content in this app is licensed under the Open-Gaming License (OGL). The content and license can found at the D&D 5th Systems Reference Document (SRD). Dungeons & Dragons (D&D) is a trademark of Wizards of the Coast company.

Icons License

The icons used in this app have a free license. They are designed by macrovector from Freepik, Freepik from Flaticon and Material Design from Google.

License

Copyright 2023 Alexandre Gomes Pereira

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

monster-compendium's Issues

Add DC structure to AbilityDescriptions

Create monster detail toolbar

Move to Kotlin Multiplatform project

Create folders feature

Create about screen

Change jetpack compose componentes names to be more easy to identify that is compose function in the code.

When reading the view code by PR, it very hard to distinguish if the composable function is model instance or not. Like the code below, it was removed from a fragment and took me some time to understand that is not a instance of a model (it is the call of composable component MonsterDetail).

    CircularLoading(viewState.isLoading) {
        viewState.monsters.takeIf { it.isNotEmpty() }?.let {
            MonsterDetail(
                it,
                viewState.initialMonsterIndex,
                contentPadding,
                onMonsterChanged = { monster ->
                    viewModel.setMonsterIndex(monster.index)
                },
                onOptionsClicked = viewModel::onShowOptionsClicked
            )
            ...
        }
    }

I think that is a good idea to add a prefix or suffix to identify that is composable function more easily.

Folder Deletion Bug

How to reproduce

1. Launch the app
2. Open the folder tab
3. Hold down on an existing folder
4. Click delete

Expected behavior

The folder disappears and is deleted.

Actual behavior

The folder does not disappear

Additional information:

1. Google Pixel 5 - Android 14
2. App version 24.02.16.14489

Adjust card colors and app colors

Change monster compendium saved scroll item position when monster detail view pager changes

Convert feet to meters

Monster Detail - Change page when image and view pager is not long visible

Monster detail - Add strings to the options

Monster Compendium - Create summary

Remove dependency between domain models and jetpack compose components

Create SortBy, GroupBy and SortGroupBy structure

Change dependency injection from Koin to Hilt

Add environments to the app

Create empty state screens

Add reactions to the app

Add legendary actions to the app