-
Notifications
You must be signed in to change notification settings - Fork 7.8k
Dependencies in pubspec.yaml as commented out caused many errors. These are uncommented in the.yaml file, #2765
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
spakkan
wants to merge
3
commits into
flutter:main
Choose a base branch
from
spakkan:Game_Template_Study
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,132 @@ | ||
| # Copilot Instructions for Flutter Game Template | ||
|
|
||
| ## Project Overview | ||
| This is a mobile game template built with Flutter showcasing a complete starter game with navigation, audio, state management, and optional integrations (ads, in-app purchases, games services, Firebase Crashlytics). The template is intentionally low-level on state management to avoid complexity while remaining extensible. | ||
|
|
||
| ## Architecture & Key Components | ||
|
|
||
| ### Feature-First Organization (`lib/src/`) | ||
| Code is organized by feature, not by layer. Each feature directory is semi-independent: | ||
| - `audio/` - Music and sound effects (via `audioplayers` package) | ||
| - `player_progress/` - Game progress tracking with persistence abstraction | ||
| - `settings/` - User preferences (muted, music, sound, player name) | ||
| - `app_lifecycle/` - Lifecycle event monitoring via `WidgetsBindingObserver` | ||
| - `main_menu/`, `level_selection/`, `play_session/`, `win_game/` - Screen features | ||
| - `ads/`, `games_services/`, `in_app_purchase/` - Optional integrations (disabled by default) | ||
| - `style/` - Palette, responsive layout, custom transitions | ||
|
|
||
| ### State Management Pattern | ||
| Uses **Provider** with a low-level, intentional approach: | ||
| - **ChangeNotifier** for mutable state (`PlayerProgress`, `SettingsController`, `AudioController`) | ||
| - **ValueNotifier** for simple reactive properties (settings values, lifecycle state) | ||
| - **MultiProvider** setup in `main.dart` with explicit dependency ordering | ||
| - Key insight: `AudioController` depends on `SettingsController` via `ProxyProvider2` for reactive attachment | ||
| - No code generation; manually attach listeners using `attachSettings()` and `attachLifecycleNotifier()` patterns | ||
|
|
||
| ### Persistence Abstraction | ||
| All persistent data uses dependency-injected interfaces: | ||
| - `PlayerProgressPersistence` (injected in `PlayerProgress`) | ||
| - `SettingsPersistence` (injected in `SettingsController`) | ||
| - Default implementation: `LocalStoragePlayerProgressPersistence`, `LocalStorageSettingsPersistence` | ||
| - This allows easy testing or swapping implementations (e.g., Firebase, cloud sync) | ||
|
|
||
| ### Navigation | ||
| Uses **GoRouter** (v16.0.0+) with nested route structure in `main.dart`: | ||
| - Routes are statically defined in `MyApp._router` | ||
| - Transitions use custom `buildMyTransition<void>()` helper from `src/style/my_transition.dart` | ||
| - Parameters passed via `state.pathParameters` (e.g., level number in `/play/session/:level`) | ||
| - Extra data passed via `state.extra` and validated with guards (e.g., win screen redirect) | ||
|
|
||
| ### Audio Integration | ||
| `AudioController` is a facade over `audioplayers` package: | ||
| - Manages a music player + pool of SFX players (configurable polyphony, default 2) | ||
| - Automatically shuffles playlist and handles lifecycle pauses | ||
| - Pauses audio when app goes to background; resumes on foreground | ||
| - Settings-aware: respects muted, musicOn, soundsOn toggles | ||
| - Use `audioController.playSfx(SfxType.buttonTap)` to play sound effects | ||
|
|
||
| ### Optional Integrations (Commented By Default) | ||
| In `main.dart`, integrations are **commented out and must be explicitly enabled**: | ||
| - **Firebase Crashlytics**: Uncomment imports and initialize block; requires `firebase_options.dart` | ||
| - **Google Mobile Ads**: Uncomment `AdsController` initialization; requires `google_mobile_ads` package | ||
| - **Games Services**: Uncomment `GamesServicesController` initialization | ||
| - **In-App Purchase**: Uncomment `InAppPurchaseController` initialization | ||
| - All integrations use platform guards: `!kIsWeb && (Platform.isIOS || Platform.isAndroid)` | ||
|
|
||
| ## Development Workflows | ||
|
|
||
| ### Running the App | ||
| ```bash | ||
| # Default (emulator/simulator/physical device) | ||
| flutter run | ||
|
|
||
| # Desktop (faster iteration, no emulator needed) | ||
| flutter run -d macOS # or -d linux / -d windows | ||
|
|
||
| # Web (useful for demos) | ||
| flutter run -d web | ||
| ``` | ||
|
|
||
| ### Building for Production | ||
| ```bash | ||
| # iOS | ||
| flutter build ipa && open build/ios/archive/Runner.xcarchive | ||
|
|
||
| # Android | ||
| flutter build appbundle && open build/app/outputs/bundle/release | ||
|
|
||
| # Web (requires 'peanut' package) | ||
| flutter pub global run peanut --web-renderer canvaskit --extra-args "--base-href=/repo_name/" && git push origin --set-upstream gh-pages | ||
| ``` | ||
|
|
||
| ### Analysis & Linting | ||
| Uses `flutter_lints` with minimal overrides (prefer_const_constructors and prefer_single_quotes disabled for early development). Check with: | ||
| ```bash | ||
| flutter analyze | ||
| ``` | ||
|
|
||
| ## Code Patterns & Conventions | ||
|
|
||
| ### Logging | ||
| Uses `package:logging` with dev.log: | ||
| ```dart | ||
| static final _log = Logger('ClassName'); | ||
| _log.info('message'); | ||
| _log.warning('warning'); | ||
| ``` | ||
|
|
||
| ### Responsive UI | ||
| Custom `ResponsiveScreen` widget in `src/style/responsive_screen.dart` provides `mainAreaProminence` and layout areas. Use for adaptive layouts across mobile/tablet/desktop. | ||
|
|
||
| ### Snack Bar Feedback | ||
| Custom `showSnackBar()` in `src/style/snack_bar.dart`. Use a global `scaffoldMessengerKey` passed to `MaterialApp.router`. | ||
|
|
||
| ### Palette & Theme | ||
| Centralized `Palette` provider in `src/style/palette.dart`. Inject via `context.watch<Palette>()`. Avoids hardcoding colors. | ||
|
|
||
| ### Game Levels | ||
| Game levels defined in `src/level_selection/levels.dart` as a list. Reference by level number in routing. | ||
|
|
||
| ### Screen State Management | ||
| Screens are typically StatelessWidget that watch providers. Mutable interactions go through provider controllers: | ||
| ```dart | ||
| final audioController = context.watch<AudioController>(); | ||
| audioController.playSfx(SfxType.buttonTap); | ||
| ``` | ||
|
|
||
| ## Dependencies Overview | ||
| - **go_router** (v16.0.0): Navigation and routing | ||
| - **provider** (v6.0.2): State management | ||
| - **audioplayers** (v6.0.0): Audio playback | ||
| - **shared_preferences**: Local persistence (via abstraction) | ||
| - **logging**: Structured logging to dart:developer | ||
| - Optional: firebase_core, firebase_crashlytics, google_mobile_ads, games_services, in_app_purchase | ||
|
|
||
| ## Critical Notes for Contributors | ||
| 1. **Persistence is abstracted**: Always use the persistence interface, not SharedPreferences directly | ||
| 2. **Controllers manage their own initialization**: Check `initialize()` methods and async setup requirements | ||
| 3. **Lifecycle matters**: Audio and ads controllers must respect app lifecycle state | ||
| 4. **Platform-specific code**: Use `kIsWeb` and platform checks (`Platform.isIOS`, etc.) for platform-specific logic | ||
| 5. **No code generation**: Template intentionally avoids build_runner for simplicity; can be added if needed | ||
| 6. **Settings require explicit toggle**: Integrations are commented out; uncomment and enable explicitly when needed | ||
| 7. **Router validation**: Use `redirect` guards on sensitive routes (e.g., win screen requires score extra data) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
3 changes: 3 additions & 0 deletions
3
game_template/lib/services/crash_reporting/crash_reporting.dart
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| abstract class CrashReporting { | ||
| void recordError(Object error, StackTrace stackTrace); | ||
| } |
8 changes: 8 additions & 0 deletions
8
game_template/lib/services/crash_reporting/crash_reporting_desktop.dart
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| import 'crash_reporting.dart'; | ||
|
|
||
| class CrashReportingImpl implements CrashReporting { | ||
| @override | ||
| void recordError(Object error, StackTrace stackTrace) { | ||
| // no-op on Windows / macOS / Linux | ||
| } | ||
| } |
5 changes: 5 additions & 0 deletions
5
game_template/lib/services/crash_reporting/crash_reporting_impl.dart
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| // lib/services/crash_reporting/crash_reporting_impl.dart | ||
|
|
||
| export 'crash_reporting_desktop.dart' | ||
| if (dart.library.android) 'crash_reporting_mobile.dart' | ||
| if (dart.library.ios) 'crash_reporting_mobile.dart'; |
9 changes: 9 additions & 0 deletions
9
game_template/lib/services/crash_reporting/crash_reporting_mobile.dart
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| import 'package:firebase_crashlytics/firebase_crashlytics.dart'; | ||
| import 'crash_reporting.dart'; | ||
|
|
||
| class CrashReportingImpl implements CrashReporting { | ||
| @override | ||
| void recordError(Object error, StackTrace stackTrace) { | ||
| FirebaseCrashlytics.instance.recordError(error, stackTrace); | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This should not be added to this repository