Skip to content
This repository was archived by the owner on Dec 21, 2025. It is now read-only.

EmilyMoonstone/Moonforge_v1

BranchesTags

Repository files navigation

Caution

This repository is no longer maintained.

Active development has moved. Please use the current version here: https://github.com/EmilyMoonstone/Moonforge

Moonforge

A multi-platform campaign manager for Dungeons & Dragons built with Flutter. Moonforge helps Game Masters plan, run, and archive entire campaigns: chapters, scenes, encounters, entities, sessions, media, and more — all synchronized across devices.

Flutter License Platforms Router Backend

  • Website/Docs coming soon — see docs folder for developer docs.
  • Status: Actively developed. Desktop and Web are primary targets; iOS/macOS planned.

Table of Contents

Features

  • Campaign management with chapters, adventures, and scenes
  • Rich text authoring with a markdown-compatible editor (Flutter Quill)
  • Entity management: locations, items, NPCs/creatures, organizations
  • Tagging and cross-linking between entities and story content
  • Session planning and note-taking
  • Media library: images, audio, video, with drag-and-drop on desktop
  • Offline-first sync powered by Firebase; automatic conflict handling
  • Player view for read-only campaign access
  • Encounter builder and initiative tracker
  • NPC and monster management; integration with the D&D SRD
  • Multi-window support on desktop, split panes, keyboard shortcuts
  • Deep linking support across all platforms with moonforge:// URLs

Platform Support

Platform Notes
Desktop (Windows/Linux; macOS planned) Full feature set; multi-window; drag-and-drop media; split panes.
Web Parity with desktop where possible; Player view opens in new tab; filesystem APIs limited by browser.
Mobile (Android; iOS planned) Streamlined editor; read-only Player view; constrained media workflows; background sync defaults to Wi‑Fi.

Architecture & Tech Stack

  • Flutter + Dart (stable channel)
  • State management: custom in-house providers/controllers (see docs/architecture/overview.md)
  • Navigation: go_router with type-safe routes via go_router_builder
  • Deep linking: app_links for cross-platform deep linking support
  • Data: Firebase (Auth, Firestore, Storage, Remote Config), offline-first patterns
  • Data modeling: Freezed, Json Serializable, Firestore ODM
  • Code generation: build_runner, flutter_gen (assets, colors)
  • UI: Material 3, dynamic_color, window_manager, flutter_acrylic
  • Rich text: flutter_quill
  • Utilities: uuid, shared_preferences, package_info_plus, share_plus, hotkey_manager, command_palette
  • Notifications & logging: toastification, logger (see lib/core/utils/logger.dart)

Project Structure

High-level layout:

  • moonforge/ — Flutter application (app root)
    • lib/
      • core/ — models, repositories, services, utils, widgets (generated *.g.dart committed)
      • features/ — adventure, auth, campaign, chapter, encounters, entities, home, parties, scene, session, settings
      • layout/ — App-level scaffolding and navigation shells
      • gen/ — Generated asset accessors via FlutterGen
      • l10n/ — App localization ARB files
    • platform folders — android/, ios/, macos/, linux/, windows/, web/
    • test/ — Unit/widget tests
    • pubspec.yaml, analysis_options.yaml, l10n.yaml, firebase_options.dart
  • docs/ — Developer documentation (app_router.md, firebase_schema.md, folder_structure.md)
  • moonforge/docs/ — Platform-specific documentation (deep_linking.md, testing_deep_links.md)
  • tools/ — Scripts/CI helpers (optional)
  • .github/workflows/ — CI definitions (optional)
  • README.md, LICENSE, CONTRIBUTING.md

See also: moonforge/analysis_options.yaml for lints and code style.

Getting Started

Prerequisites:

Quickstart (three commands)

Run these from the project root to get a working development environment quickly:

cd moonforge
flutter pub get
flutter pub run build_runner build --delete-conflicting-outputs
flutter run -d windows   # or -d chrome / -d linux / -d macos / -d <device_id>

Tip: On some systems dart run build_runner ... is equivalent; we recommend flutter pub run build_runner when working inside Flutter projects.

Setup

1. Install dependencies

cd moonforge
flutter pub get

2. Configure environment variables

Create a .env file in the moonforge/ directory for the Firebase Web API key:

cp .env.example .env

Then edit .env and add your Firebase Web API key:

FIREBASE_API_KEY=your-firebase-web-api-key-here

Note: The .env file is gitignored for security. Get your API key from the Firebase Console under Project Settings > General > Your apps > Web apps > Config.

3. Generate code (models, router, assets)

# Recommended: use the Flutter pub wrapper so tool versions match the Flutter SDK
flutter pub run build_runner build --delete-conflicting-outputs
# Alternatively (works in many environments):
dart run build_runner build --delete-conflicting-outputs

Additions:

Generated files (do not edit)

The project relies on generated code for serialization, routing, and database helpers. Do not edit these files by hand — update the source annotations and re-run code generation.

Common generated file patterns:

  • *.g.dart (JSON serialization, Firestore ODM)
  • *.freezed.dart (Freezed data classes)
  • *.gr.dart (generated router code, e.g., app_router.gr.dart)
  • Drift-related generated files (e.g., *.drift.dart or generated database helpers)

To regenerate generated sources:

cd moonforge
flutter pub run build_runner build --delete-conflicting-outputs
# For a clean rebuild:
dart run build_runner clean && flutter pub run build_runner build --delete-conflicting-outputs
# Drift setup helpers (if needed):
# ./drift_setup.sh   (Linux/macOS)
# scripts\drift_setup.ps1  (Windows PowerShell if present)

4. Run the app

  • Windows/Linux/macOS: 
    flutter run -d windows|linux|macos
  • Web: 
    flutter run -d chrome
  • Android/iOS: 
    flutter run -d <device_id>

5. Quality checks

  • Static analysis: 
    flutter analyze
  • Format: 
    dart format .
  • Tests: 
    flutter test

Development Workflow

  • Code generation in watch mode during active development:
    • dart run build_runner watch --delete-conflicting-outputs
  • Keep lints clean; follow the repository’s analysis_options.yaml
  • Prefer small, focused widgets and keep business logic out of UI when possible
  • Generated files (*.g.dart, *.gr.dart) must not be edited by hand
  • When changing routes or models, update annotations and rerun build_runner

Internationalization (i18n)

  • All user-facing text is internationalized
  • ARB source files live under moonforge/lib/l10n (e.g., app_de.arb)
  • After adding new strings, run: flutter pub get (from moonforge/, to regenerate l10n delegates)
  • See moonforge/l10n.yaml for configuration

Documentation

Comprehensive developer documentation is available in the docs/ directory:

  • Getting Started - Setup guide for new developers
  • Architecture - System design, data layer, routing, state management
  • Features - Campaign management, entities, encounters, sessions, media
  • Development - Code generation, testing, localization, platform configs
  • Deployment - Building, packaging, releases, CI/CD
  • Reference - Firebase schema, folder structure, troubleshooting

See docs/README.md for the complete documentation index.

Routing

Moonforge uses go_router with type-safe route definitions and supports deep linking across all platforms. See docs/architecture/routing.md for details.

Data & Firebase Schema

The canonical Firestore and Storage layout, index recommendations, and security notes are documented in docs/reference/firebase-schema.md.

Assets

  • Asset management is powered by FlutterGen
  • Access assets via generated helpers (e.g., moonforge/lib/gen/assets.gen.dart)
  • Configure assets in moonforge/pubspec.yaml under flutter/assets and flutter_gen

Contributing

Contributions are welcome! Please read the contributing guide for setup, coding standards, and the PR checklist:

  • CONTRIBUTING.md

Quick start for contributors:

  • Ensure Flutter (stable) is installed
  • cd moonforge
  • flutter pub get
  • dart run build_runner build --delete-conflicting-outputs
  • flutter test

Please keep PRs focused, follow Conventional Commits when possible, and ensure lints/tests pass.

Packaging & Distribution

Moonforge uses Fastforge for packaging and distribution, with automatic updates powered by auto_updater.

Building Releases

For maintainers and contributors interested in packaging:

Supported Platforms

Platform Package Formats
Windows EXE installer
macOS DMG disk image
Linux AppImage, DEB

Automatic Updates

Desktop versions of Moonforge check for updates automatically every 24 hours and on startup. Updates are downloaded from GitHub Releases.

Roadmap

  • macOS and iOS runners and UI polish
  • Extended Player mode for tablets/phones
  • Deeper D&D 5e SRD integration and import tools
  • Collaboration tooling (presence, comments), conflict resolution improvements
  • Improved media workflows (batch uploads, clipping, annotations)

FAQ

  • Why Flutter? Single codebase for Desktop/Web/Mobile, excellent developer ergonomics, and strong community tooling.
  • Offline-first? Firestore’s local cache and sync primitives are leveraged; we increment a rev field for conflict resolution patterns.
  • Can I self-host? The app targets Firebase; advanced users can fork and adapt providers, but Moonforge ships with Firebase by default.

License

This project is licensed under the MIT License. See LICENSE for details.

About

a manager for dungeons & dragons campaigns

emilymoonstone.github.io/Moonforge/

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages