dart-mobile-game-studio

name

dart-mobile-game-studio

description

Build simple 2D mobile games in Flutter/Dart for iOS and Android — coloring books, jigsaw/sliding puzzles, light platformers, drag-and-drop puzzles, memory/matching card games, lite endless runners, tap-reaction, and educational mini-games. Use when a request involves Dart, Flutter, Flame, Forge2D, the Flutter Casual Games Toolkit, a mobile game, a kids/children's game, game architecture, level design, an asset pipeline, child-safety/privacy review (Apple Kids + Google Play Families), game testing, or `flutter`/`dart` build & test. Produces a Mini-GDD, an MVP, tests, and a review checklist.

Dart Mobile Game Studio

Operational guide for building simple, polished 2D games for iOS and Android in Flutter/Dart. You are the implementer: produce a working MVP, keep core logic testable, and finish with a child-safety / privacy / accessibility / performance review and an honest handoff.

When to use

Trigger on any 2D mobile game task: coloring, puzzles, platformers, drag-and-drop, memory/matching, lite arcades, tap-reaction, or educational mini-games. Trigger on mentions of Dart, Flutter, Flame, Forge2D, the Casual Games Toolkit, flutter/dart CLI, or "kids app".

Supported stack & official sources

Dart · Flutter · Flame (2D game engine) · Forge2D (Box2D physics, optional) · games_services (Game Center / Play Games, optional) · dart test / flutter_test / integration_test · flutter/dart CLI. Target: a single Flutter codebase shipping to iOS and Android, portrait + landscape, phone + tablet, privacy-first defaults.

Ground decisions in the official org (https://github.com/orgs/flutter):

• flutter/games — the Casual Games Toolkit and gaming templates (app scaffolding, state, audio, settings, achievements, ads/IAP hooks). The canonical first-party reference.
• flame-engine/flame — the de-facto 2D engine (FlameGame, components, game loop, collisions).
• flutter/samples, flutter/packages — official examples and first-party packages.

Execution workflow

Run these in order. Skip a step only with a stated reason.

1. Understand the game request. Genre, target age, core verb (tap / drag / match / move), win/lose vs no-fail, session length, platforms (iOS + Android), orientation. For non-trivial repo work, run scripts/ai-context-pack.py --markdown first so the agent sees project modes, commands, rules, references, agents, and current doctor findings before editing. Then run scripts/task-router.py "<task>" to pick the right workflows, references, agents, and required checks for the concrete request.
2. Generate a Mini-GDD. Start from the closest genre brief in templates/<genre>.md (it ships a filled Mini-GDD + an architecture skeleton for the genre), then refine with assets/gdd-template.md. One page.
3. Select implementation mode:
   • Flutter-widgets-only — static/turn-based boards, coloring, memory, matching, drag-and-drop, tap-reaction. CustomPainter/Canvas, AnimatedBuilder, gestures. Simplest, most testable.
   • Flame — continuous motion, physics, sprites, particles: platformer, runner. FlameGame
     • components + game loop (update/render); Forge2D for real physics.
   • Hybrid — Flame gameplay embedded in a Flutter widget tree via GameWidget, with Flutter widgets for menus/HUD/settings. Default for action games that need real UI. See references/flutter-game-architecture.md and references/flutter-flame-patterns.md.
4. Define architecture. Separate pure Dart logic (model + rules + state machine, no Flutter imports) from rendering. The core is unit-tested with dart test — no device. Choose state management for the shell (ValueNotifier/ChangeNotifier, Provider, or Riverpod/Bloc) and keep it thin over the model.
5. Implement the MVP. Copy a complete model/renderer pair: assets/flame_game_model_template.dart + assets/flame_game_template.dart, or assets/tile_game_model_template.dart + assets/flutter_game_widget_template.dart. Small files, modular folders (lib/models/, lib/systems/, lib/game/, lib/widgets/, assets/). Recipes in references/game-templates.md. Write excellent Dart — meet the quality bar in references/dart/README.md and generate to the defaults in references/common-pitfalls.md (so the common Dart/Flutter/Flame bugs never land). Mirror the worked example in examples/.
6. Add tests. Cover the pure model: legal moves, scoring, win/lose, level loading, transitions, deterministic (seeded) shuffles/spawns. dart test for the core; flutter_test for widgets.
7. Run build/test when available. Use scripts/verify-flutter-project.sh to detect a project and run dart analyze + dart test (+ flutter test). If you cannot (no toolchain), say so and give the exact commands — exit 4 means unverified, not passed. The verifier does not resolve dependencies by default; set RESOLVE_DEPS=yes only when an explicit pub get is intended. In automated / long-running runs, gate first with scripts/flutter-preflight.sh --require … (environment + clean git), skip redundant installs with scripts/pub-get-if-changed.sh, fence any codegen/clean/build in scripts/safe-run.sh (savepoint → atomic commit on success / rollback on failure), and pipe failing build logs through scripts/triage-log.py. See references/ci-and-automation.md.
8. Review. For a meaningful change, run scripts/self-review-loop.py "<task>" to refresh context, route the task, and execute the available static/format/analyze/test checks as one honest report. Use --project <path> when the task text does not name a project. The loop includes scripts/dart-doctor.py <project> and scripts/design-doctor.py <project>; then sweep references/common-pitfalls.md (the analyzer-invisible classes: layout constraints, Flame hot-path/lifecycle/collision, layering — tag findings by code + severity) and walk assets/review-checklist.md: child safety, privacy, accessibility, performance. See references/accessibility-child-safety.md.
9. Handoff. Report: what you built, chosen mode and why, changed files, commands run with real output (or why none ran), assumptions, open risks, next steps.

Genre design templates — templates/

Per-genre design starting points (a filled Mini-GDD + an architecture skeleton you copy at step 2), distinct from the implementation recipes below. Pick one, fill its brackets, build to its skeleton: casual, coloring, card, puzzle, platformer-flame, endless-runner, quiz, educational-kids, ui-heavy. Index + how-to in templates/README.md.

Game templates (implementation recipes)

Pick the closest and adapt (full recipes in references/game-templates.md):

• coloring-shapes — tap-to-fill vector regions. Flutter-widgets-only (CustomPainter).
• simple-platformer — run/jump on platforms, simple physics. Flame (hybrid shell).
• drag-and-drop-puzzle — drag pieces to slots / snap-to-grid. Flutter-widgets-only (Draggable).
• memory-cards — flip-and-match pairs, no-fail. Flutter-widgets-only.
• shape-matching — match shape/color to target slot. Flutter-widgets-only.
• endless-runner-lite — auto-run, tap to jump. Flame (hybrid).
• tap-reaction — tap targets before they vanish. Flutter-widgets or Flame.

Strict rules

• No copyrighted assets. Generate placeholder vector shapes (CustomPainter/flutter_svg) or use only user-owned assets. No third-party characters/logos/fonts/music/sprites.
• Minimal dependencies. Prefer Flutter SDK + Flame. Justify any other pub.dev package.
• Testable core. Game logic runs and is tested with dart test, outside Flutter/Flame.
• Small, modular files; prefer const constructors; many focused files.
• Accessibility. Wrap interactive controls in Semantics (label/value/button); honor text scaling, MediaQuery.disableAnimations / Reduce Motion, screen readers (TalkBack/VoiceOver).
• Children's apps: no tracking, no third-party analytics, no ads, no AdvertisingId/IDFA/GAID, no external links, no accounts, no dark patterns; offline-first; no personal data. Must satisfy both Apple Kids Category and Google Play Families policy.
• No compliance guarantees. Produce a checklist and a risk list, never "store-approved".
• Savepoint before destructive commands. Never run codegen (build_runner), flutter clean, or a platform build on an unknown/dirty tree in an automated run. Preflight the environment, then fence the command in scripts/safe-run.sh so a half-run never persists. Don't assume a toolchain is installed — check with scripts/flutter-preflight.sh and report honestly if it's absent.

Fallback behavior (defaults when details are missing)

Build a small polished MVP and document assumptions: ages 4–8, no-fail; support both orientations, phone-first; Flutter-widgets-only unless the genre needs motion/physics (then Flame); bright high-contrast placeholder vector art; gentle optional SFX with a mute toggle (off if unsure); lightweight local persistence (shared_preferences or a JSON file) for progress only; no networking, accounts, or analytics. State these in the Mini-GDD and handoff.

Reference map

• references/game-development-pipeline.md — end-to-end process & the Mini-GDD step.
• references/flutter-game-architecture.md — modes, pure-Dart core, state management, layout.
• references/flutter-flame-patterns.md — Flame game loop/components/collisions, GameWidget, CustomPainter for widget-only games, input, embedding Flame in Flutter.
• references/game-templates.md — per-template recipes and pitfalls.
• references/asset-pipeline.md — placeholder art, asset bundling, audio, level data (JSON).
• references/accessibility-child-safety.md — Flutter Semantics + Apple Kids & Google Play Families.
• references/testing-and-release.md — dart test/flutter test, build & both-store release.
• references/performance-checklist.md — frame budget, const/RepaintBoundary, Flame perf, jank.
• references/flutter-games-toolkit.md — using the official flutter/games Casual Games Toolkit.
• references/algorithms-for-games.md — pure-Dart, deterministic game algorithms (pathfinding BFS/Dijkstra/A*, match-3, line-clears, maze/proc-gen, scoring, sliding-puzzle solvability).
• references/ui-and-animations.md — game screens (menu/start/win/settings/shop/onboarding), animated buttons & transitions, implicit/explicit/staggered animation, responsive + Material/Cupertino, reduce-motion gating.
• references/production-quality.md — production patterns distilled from Wonderous/flutter samples: structure, go_router navigation, responsive/adaptive, theming, state-at-scale, UX polish.
• references/codegen-and-boilerplate.md — when (and when not) to use build_runner / freezed / json_serializable / auto_route; generated-file policy; boilerplate guidance.
• references/testing-e2e-patrol.md — the full test pyramid incl. Patrol E2E (native dialogs, permissions, lifecycle); complements testing-and-release.md.
• references/common-pitfalls.md — the review-&-generation catalog: the top mistakes that break Dart/Flutter/Flame games, ranked P0–P3, with an error classifier (codes + severity), per-class tripwire/bad→good/AI-rule, a symptom→cause→fix matrix, generation defaults, and a built-in review prompt. Open it first when reviewing or debugging; generate to its defaults. The code-reviewer and code-auditor agents tag findings with its codes.
• references/ci-and-automation.md — safe-automation policy for unattended/long runs: environment preflight, git savepoint/rollback/atomic-commit around destructive steps, build-log triage, and pub get caching. Maps each hazard to its script and the order to run them.
• references/model-routing.md — tiered subagents across models: each of the 14 agents has a tier (heavy/medium/light) that routes it to a model (Opus/Sonnet/Haiku on Claude; the GPT line on Codex). sync-agents.py resolves tier→model:; the coordinator tags each subtask's tier; heavy and light roles run in parallel. Template: assets/parallel-build.workflow.js.

Policies (the rules agents enforce) — references/

• references/package-policy.md — dependency decision order (SDK → official → Flame → mature → DIY) + justification.
• references/quality-policy.md — the production quality bar (layer separation, null-safety, dispose, tests).
• references/monetization-policy.md — ads/IAP/subscriptions with the kids-vs-13+ audience gate.
• references/release-policy.md — App Store + Google Play submission rules and rejection traps.

Checklists (tick-lists a reviewer/agent runs) — checklists/

dart-code-quality, flutter-ui-quality, game-architecture, flame-quality, performance, accessibility, localization, monetization, app-store-release, google-play-release, testing.

Dart mastery (write excellent Dart) — references/dart/

• references/dart/README.md — index + the Dart quality bar (start here).
• references/dart/dart-language-essentials.md, dart-async-isolates.md, dart-api-design.md, flutter-widgets-mastery.md, dart-memory-performance.md, dart-patterns-idioms.md.

Assets (copy & adapt)

assets/gdd-template.md, assets/level-schema-template.json, assets/flame_game_model_template.dart + assets/flame_game_template.dart, assets/tile_game_model_template.dart + assets/flutter_game_widget_template.dart, assets/seeded_random.dart, assets/analysis_options.yaml, assets/review-checklist.md, assets/privacy-checklist.md, assets/parallel-build.workflow.js (tiered multi-model fan-out — see references/model-routing.md).

Scripts

• scripts/sync-skill.sh — mirror canonical skill into .claude/ and .cursor/ (--check for CI).
• scripts/ai-context-pack.py — dependency-free AI context pack generator (--markdown, --json, --project, --no-findings) so agents get repo shape, modes, commands, rules, refs, and findings.
• scripts/task-router.py — token/phrase task-to-workflow router (--markdown, --json, --project) that preserves compound intents and selects project, mode, workflows, references, templates, agents, and required checks.
• scripts/router-eval.py — versioned RU/EN routing eval (evals/task-routing.jsonl): minimum 95% accuracy, 100% critical release/security cases, and full workflow/agent coverage.
• scripts/self-review-loop.py — task-aware closed review loop (--markdown, --json, --project, --strict, --static-only): refreshes context, routes work, runs known safe checks, and reports evidence, skipped commands, actionable findings, and manual device-review gaps. Repository-audit tasks verify every discovered project instead of silently selecting none.
• scripts/discover-projects.sh — shared Dart/Flutter pubspec.yaml discovery for single-project apps and multi-example repos (--all, --dirs, --json).
• scripts/doc-doctor.py — canonical Markdown-link and inline skill-path integrity gate (--json), including backticked references that ordinary link checkers miss.
• scripts/verify-flutter-project.sh — source-preserving project detection, format, analyze, and tests; dependency resolution is explicit (RESOLVE_DEPS=yes) and missing SDK exits unverified (4).
• scripts/scaffold-game-module.py — non-destructive buildable Dart package skeleton for a genre.
• scripts/materialize-template-fixtures.py — creates disposable VM-only, Flutter-widgets, and Flame projects so CI compiles/tests the exact canonical model/renderer pairs.
• scripts/validate-skill.sh — structural and critical CLI contract gate (frontmatter, sync, JSON, documentation integrity, syntax without bytecode writes, black-box safety/routing/schema tests).
• scripts/validate-levels.py — schema-driven level validation against level-schema-template.json; the dependency-free path enforces the same used Draft-07 keywords.
• scripts/dart-doctor.py — project health-check CLI (the analog of swift-doctor / flutter doctor for project quality): environment, architecture, Dart quality, performance, kids-safety, accessibility, assets/licensing, build/tests.
• scripts/design-doctor.py — static UX/a11y/game-design gate: screen map, tap semantics, Reduce Motion, responsive layout, visual states, Flame overlays, kids UX, a11y test hooks.

Safe automation (use in automated / long-running runs) — see references/ci-and-automation.md

• scripts/flutter-preflight.sh — run FIRST: gate the toolchain (--require dart,flutter,android,xcode), git workspace (--git-clean), and project before a build/codegen step. Degrades gracefully (reports MISSING with install hints instead of crashing later). --json for machine output.
• scripts/safe-run.sh — fence a destructive/generative command (build_runner, flutter clean) in a git savepoint: --stash → run → --commit atomic chore(auto): commit on success, or auto rollback (reset --hard + clean -fd) on failure. --triage summarizes a failing log. The net is fail-closed outside a committed git repository, rejects --allow-dirty --commit, and only auto-rolls-back when it can prove no work is lost.
• scripts/triage-log.py — distill a 1000s-line Gradle/Xcode/Dart build log to ~10–25 high-signal lines + a ranked likely-cause list (so a small model gets a clean input, not 2000 lines of noise).
• scripts/pub-get-if-changed.sh — skip pub get when pubspec.lock is unchanged (hash cached in gitignored .dart_tool/); --check-only exits 10 if stale. Turns a slow re-init into a no-op.

Workflow playbooks — workflows/

Step-by-step recipes the agent executes top-to-bottom. Each file is a self-contained guide with decision criteria, concrete commands, code snippets, and common pitfalls:

• create-new-game.md — full session: idea → GDD → scaffold → architecture decision → MVP.
• choose-game-architecture.md — Flutter-widgets vs Flame vs hybrid decision tree with tradeoff table, concrete checklist, and anti-patterns.
• setup-flutter-project.md — flutter create → analysis options → folder layout → CI stub.
• setup-flame-project.md — Flame dep → pubspec → FlameGame skeleton → dt clamping → first component.
• add-game-loop.md — world state, update/render cycle, frame-rate independence, pausing.
• add-level-system.md — JSON schema, LevelRepository, LevelLoader, level-select UI.
• add-animations.md — AnimationController/implicit animations, Flame sprite sheets, reduce-motion gate.
• add-assets-pipeline.md — pubspec.yaml assets declaration, flutter_svg, placeholder shapes, audio.
• add-audio.md — flame_audio/audioplayers, background music + SFX, mute toggle, lifecycle.
• add-state-management.md — ValueNotifier→ Provider → Riverpod progression, game-state binding.
• add-navigation.md — go_router setup, route table, deep-link guards, game-state handoff.
• add-save-system.md — shared_preferences/JSON file persistence, migration, encryption gate.
• write-tests.md — unit (pure Dart), widget, integration/Patrol; seeded RNG; golden tests.
• debug-common-errors.md — capture → triage-log.py → classify by catalog code → fix cause → re-verify. The cheap debug loop for build/runtime/analyzer/jank failures.
• run-performance-audit.md — dart-doctor --only performance → profile-mode on the oldest device → DevTools timeline → kill hot-path alloc / unclamped dt / rebuild-the-world / leaks. Target 60/120 fps.
• prepare-ios-release.md — App Store: bundle id, version+build, icons, Info.plist, signing, flutter build ipa, App Store Connect, privacy labels, Kids Category. No approval guarantee.
• prepare-android-release.md — Google Play: applicationId, versionCode, targetSdk, adaptive icon, upload keystore, flutter build appbundle, Data safety, Families. No approval guarantee.
• add-monetization.md — the audience gate first (kids → no ads/tracking), then model choice; routes to ads/IAP. Keeps billing at the edge, core pure.
• add-ads.md — google_mobile_ads, 13+ only: ATT/CMP consent, non-personalized fallback, non-intrusive placement, SDK isolated behind an interface.
• add-in-app-purchases.md — in_app_purchase: products in both stores, full purchase stream, mandatory restore, server-side verification (or documented gap), parental gate for kids.

Worked examples (both buildable, tested, CI-green)

• examples/memory_match/ — widgets mode: memory match. Pure-Dart core (lib/models/+lib/systems/, no Flutter import, unit-tested) under a thin widget UI; immutable value types, a (state, action) -> state reducer, injected SeededRandom, lifecycle pause, responsive grid, Semantics, kids-safe.
• examples/endless_runner/ — Flame mode: lite endless runner. Pure-Dart core (spawn/physics/ collision rules, no Flame/Flutter import) under a thin FlameGame; clamped dt, clearable seeded spawns, full menu/pause/game-over lifecycle, responsive overlays, frame-rate independence, AABB collision, no per-frame allocation, ValueNotifier HUD.
• CI runs VM-only core tests plus flutter analyze/flutter test on both; the release canary builds Android AAB and unsigned iOS release outputs from disposable platform runners.