PKForge

Contributing

PKForge is a GPLv3 .NET MAUI Android app. Contributions are welcome: code, data for ROM hacks, translations of game data, bug reports with logs.

Get the code

git clone --recurse-submodules https://github.com/sofianeelhor/PKForge.git

Two submodules come with it:

PathWhat
external/PKHeXPKForge's fork of PKHeX.Core, sofianeelhor/PKForge-PKHeX. It only carries what PKHeX cannot: save formats and data for games PKHeX does not know (Luminescent Platinum, Compass), one pkforge/* branch per change.
external/PKHeX-PluginsThe Auto Legality Mod sources, built directly into the app by src/PKForge.AutoMod against the pinned PKHeX.Core so the two can never drift.

Build and test

Requirements: the .NET 10 SDK with the MAUI Android workload, and the Android SDK.

dotnet test tests/PKForge.Engine.Tests
dotnet test tests/PKForge.Domain.Tests
dotnet build src/PKForge.App/PKForge.App.csproj -f net10.0-android
dotnet publish src/PKForge.App/PKForge.App.csproj -f net10.0-android -c Release -o dist/
  • Warnings are errors everywhere. A raw & or < in a /// comment breaks the build.
  • Debug builds use Fast Deployment and do not run from a plain adb install; use a Release build for on-device testing.
  • The interface components can be previewed off-device: dotnet run --project tools/ChromePreview renders every component to PNG.
  • Tests that need real saves read them from .local-testdata/ and are skipped when the file is absent. Save files are never committed.

Architecture

Project architecture

ProjectRole
PKForge.AppThe MAUI Android app: pages, view models, services, controller routing, the second screen. Never touches PKHeX directly.
PKForge.ChromeThe DS / PKSM-style drawing kit the UI is built from.
PKForge.EnginePKHeX adapters and format detection. SaveEngine opens bytes into an ISaveEngineSession; ROM hack sessions live here too.
PKForge.InfrastructureAndroid folder access, per-emulator save discovery, the Bank store, restore points, the safe writer.
PKForge.DomainInterfaces and records shared by all projects. No PKHeX.
PKForge.AutoModBuilds the Auto Legality Mod against the pinned PKHeX.Core.
tools/Generators and previews: data tables, sprite packs, event archives, dex facts.

Rules the codebase keeps

  1. Data safety comes first. Every write is validated, then backed up with a restore point, then written, bulk operations included. An invalid candidate means no backup and no write, and tests cover it.
  2. Offline first. Assets are bundled or cached; the app works without a network.
  3. Layering. The App uses the Engine and Infrastructure, which both build on Domain. Game-specific behaviour lives in the Engine, not in the fork.
  4. No secrets in the app. API keys such as the SteamGridDB key are gitignored and must never end up in an APK.
  5. Evidence. Save-format work cites its source (engine source, a real save used for validation, a pinned commit), and data tables record where they come from.

Pull requests

  • Branch from dev; main only receives releases.
  • Keep one change per pull request, with tests for engine changes.
  • Commit subjects use a short prefix: feat:, fix:, docs:, release:.
  • Describe how you verified the change: tests run, device tested, saves used.

Reporting bugs

Use Settings > Misc > Share logs and attach the zip to a GitHub issue or send it on Discord, with the steps that led to the problem and your device.

Image viewer