From 3019eeffd41a50b60df244b4e168866e758463bb Mon Sep 17 00:00:00 2001 From: spakkan Date: Mon, 22 Dec 2025 18:45:12 +0300 Subject: [PATCH] Dependencies in pubspec.yaml as commented out caused many errors. These are uncommented in the.yaml file, - flutter pub get - flutter pub outdated - flutter pub upgrade --major versions - flutter pub upgrade commands are run in order to download the necessary packages into the project folder. --- .../pubspec.yaml | 2 +- .../flutter_module_using_plugin/pubspec.yaml | 2 +- animations/pubspec.yaml | 2 +- compass_app/app/pubspec.yaml | 4 +- deeplink_store_example/pubspec.yaml | 2 +- desktop_photo_search/fluent_ui/pubspec.yaml | 2 +- desktop_photo_search/material/pubspec.yaml | 2 +- form_app/pubspec.yaml | 2 +- game_template/.github/copilot-instructions.md | 132 ++++++++++++++++++ game_template/lib/main.dart | 4 +- game_template/pubspec.yaml | 6 +- game_template/windows/flutter/CMakeLists.txt | 7 +- .../windows/runner/flutter_window.cpp | 5 + navigation_and_routing/pubspec.yaml | 2 +- pedometer/example/pubspec.yaml | 2 +- pedometer/pubspec.yaml | 6 +- place_tracker/pubspec.yaml | 2 +- platform_channels/pubspec.yaml | 2 +- provider_shopper/pubspec.yaml | 2 +- simplistic_calculator/pubspec.yaml | 2 +- testing_app/pubspec.yaml | 2 +- 21 files changed, 167 insertions(+), 25 deletions(-) create mode 100644 game_template/.github/copilot-instructions.md diff --git a/add_to_app/android_view/flutter_module_using_plugin_android_view/pubspec.yaml b/add_to_app/android_view/flutter_module_using_plugin_android_view/pubspec.yaml index 4f6067a9287..b605c2832ac 100644 --- a/add_to_app/android_view/flutter_module_using_plugin_android_view/pubspec.yaml +++ b/add_to_app/android_view/flutter_module_using_plugin_android_view/pubspec.yaml @@ -11,7 +11,7 @@ dependencies: sdk: flutter provider: ^6.1.5 url_launcher: ^6.3.2 - sensors_plus: ^6.1.1 + sensors_plus: ^7.0.0 dev_dependencies: analysis_defaults: diff --git a/add_to_app/plugin/flutter_module_using_plugin/pubspec.yaml b/add_to_app/plugin/flutter_module_using_plugin/pubspec.yaml index db1e2d84e8f..0660bab7e10 100644 --- a/add_to_app/plugin/flutter_module_using_plugin/pubspec.yaml +++ b/add_to_app/plugin/flutter_module_using_plugin/pubspec.yaml @@ -11,7 +11,7 @@ dependencies: sdk: flutter provider: ^6.0.2 url_launcher: ^6.0.20 - sensors_plus: ^6.1.1 + sensors_plus: ^7.0.0 dev_dependencies: analysis_defaults: diff --git a/animations/pubspec.yaml b/animations/pubspec.yaml index b20928bd1c1..0d2152b119b 100644 --- a/animations/pubspec.yaml +++ b/animations/pubspec.yaml @@ -11,7 +11,7 @@ dependencies: flutter: sdk: flutter flutter_animate: ^4.1.0 - go_router: ^16.0.0 + go_router: ^17.0.1 window_size: # plugin is not yet part of the flutter framework git: url: https://github.com/google/flutter-desktop-embedding.git diff --git a/compass_app/app/pubspec.yaml b/compass_app/app/pubspec.yaml index cbdd3ff056f..fedfeb56cd1 100644 --- a/compass_app/app/pubspec.yaml +++ b/compass_app/app/pubspec.yaml @@ -16,13 +16,13 @@ dependencies: sdk: flutter flutter_svg: ^2.0.16 freezed_annotation: ^3.0.0 - go_router: ^16.0.0 + go_router: ^17.0.1 google_fonts: ^6.2.1 intl: any json_annotation: ^4.9.0 logging: ^1.3.0 provider: ^6.1.2 - share_plus: ^10.1.3 + share_plus: ^12.0.1 shared_preferences: ^2.3.5 dev_dependencies: diff --git a/deeplink_store_example/pubspec.yaml b/deeplink_store_example/pubspec.yaml index 398a213960d..16c64d547f8 100644 --- a/deeplink_store_example/pubspec.yaml +++ b/deeplink_store_example/pubspec.yaml @@ -38,7 +38,7 @@ dependencies: # Use with the CupertinoIcons class for iOS style icons. cupertino_icons: ^1.0.2 shrine_images: ^2.0.2 - go_router: ^16.0.0 + go_router: ^17.0.1 dev_dependencies: analysis_defaults: diff --git a/desktop_photo_search/fluent_ui/pubspec.yaml b/desktop_photo_search/fluent_ui/pubspec.yaml index 9863e8bc6b6..70afe58ac57 100644 --- a/desktop_photo_search/fluent_ui/pubspec.yaml +++ b/desktop_photo_search/fluent_ui/pubspec.yaml @@ -35,7 +35,7 @@ dev_dependencies: analysis_defaults: path: ../../analysis_defaults async: ^2.11.0 - build: ^3.0.0 + build: ^4.0.3 build_runner: ^2.4.6 built_value_generator: ^8.6.1 flutter_test: diff --git a/desktop_photo_search/material/pubspec.yaml b/desktop_photo_search/material/pubspec.yaml index 5a46a857e53..69bd8265f23 100644 --- a/desktop_photo_search/material/pubspec.yaml +++ b/desktop_photo_search/material/pubspec.yaml @@ -34,7 +34,7 @@ dev_dependencies: analysis_defaults: path: ../../analysis_defaults async: ^2.11.0 - build: ^3.0.0 + build: ^4.0.3 build_runner: ^2.4.6 built_value_generator: ^8.6.1 flutter_test: diff --git a/form_app/pubspec.yaml b/form_app/pubspec.yaml index 69dc8aef83f..2b770c34d63 100644 --- a/form_app/pubspec.yaml +++ b/form_app/pubspec.yaml @@ -19,7 +19,7 @@ dependencies: git: url: https://github.com/google/flutter-desktop-embedding.git path: plugins/window_size - go_router: ^16.0.0 + go_router: ^17.0.1 dev_dependencies: analysis_defaults: diff --git a/game_template/.github/copilot-instructions.md b/game_template/.github/copilot-instructions.md new file mode 100644 index 00000000000..175d3f5517e --- /dev/null +++ b/game_template/.github/copilot-instructions.md @@ -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()` 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()`. 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.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) diff --git a/game_template/lib/main.dart b/game_template/lib/main.dart index b2e30e9c88e..f80a1e16027 100644 --- a/game_template/lib/main.dart +++ b/game_template/lib/main.dart @@ -63,11 +63,11 @@ Future main() async { // await Firebase.initializeApp( // options: DefaultFirebaseOptions.currentPlatform, // ); - // + // FlutterError.onError = (errorDetails) { // FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails); // }; - // + // // Pass all uncaught asynchronous errors // // that aren't handled by the Flutter framework to Crashlytics. // PlatformDispatcher.instance.onError = (error, stack) { diff --git a/game_template/pubspec.yaml b/game_template/pubspec.yaml index e4cc187c521..970806ce10a 100644 --- a/game_template/pubspec.yaml +++ b/game_template/pubspec.yaml @@ -15,7 +15,7 @@ dependencies: sdk: flutter audioplayers: ^6.0.0 cupertino_icons: ^1.0.2 - go_router: ^16.0.0 + go_router: ^17.0.1 logging: ^1.1.0 provider: ^6.0.2 shared_preferences: ^2.0.13 @@ -25,8 +25,8 @@ dependencies: # that references the dependency. firebase_core: ^4.0.0 # Needed for Crashlytics below firebase_crashlytics: ^5.0.0 # Error reporting - games_services: ^4.0.0 # Achievements and leaderboards - google_mobile_ads: ^6.0.0 # Ads + games_services: ^5.0.0 # Achievements and leaderboards + google_mobile_ads: ^7.0.0 # Ads in_app_purchase: ^3.0.1 # In-app purchases dev_dependencies: diff --git a/game_template/windows/flutter/CMakeLists.txt b/game_template/windows/flutter/CMakeLists.txt index 930d2071a32..903f4899d6f 100644 --- a/game_template/windows/flutter/CMakeLists.txt +++ b/game_template/windows/flutter/CMakeLists.txt @@ -10,6 +10,11 @@ include(${EPHEMERAL_DIR}/generated_config.cmake) # https://github.com/flutter/flutter/issues/57146. set(WRAPPER_ROOT "${EPHEMERAL_DIR}/cpp_client_wrapper") +# Set fallback configurations for older versions of the flutter tool. +if (NOT DEFINED FLUTTER_TARGET_PLATFORM) + set(FLUTTER_TARGET_PLATFORM "windows-x64") +endif() + # === Flutter Library === set(FLUTTER_LIBRARY "${EPHEMERAL_DIR}/flutter_windows.dll") @@ -92,7 +97,7 @@ add_custom_command( COMMAND ${CMAKE_COMMAND} -E env ${FLUTTER_TOOL_ENVIRONMENT} "${FLUTTER_ROOT}/packages/flutter_tools/bin/tool_backend.bat" - windows-x64 $ + ${FLUTTER_TARGET_PLATFORM} $ VERBATIM ) add_custom_target(flutter_assemble DEPENDS diff --git a/game_template/windows/runner/flutter_window.cpp b/game_template/windows/runner/flutter_window.cpp index b25e363efa4..955ee3038f9 100644 --- a/game_template/windows/runner/flutter_window.cpp +++ b/game_template/windows/runner/flutter_window.cpp @@ -31,6 +31,11 @@ bool FlutterWindow::OnCreate() { this->Show(); }); + // Flutter can complete the first frame before the "show window" callback is + // registered. The following call ensures a frame is pending to ensure the + // window is shown. It is a no-op if the first frame hasn't completed yet. + flutter_controller_->ForceRedraw(); + return true; } diff --git a/navigation_and_routing/pubspec.yaml b/navigation_and_routing/pubspec.yaml index 19617657d31..21a4d2977ce 100644 --- a/navigation_and_routing/pubspec.yaml +++ b/navigation_and_routing/pubspec.yaml @@ -12,7 +12,7 @@ dependencies: cupertino_icons: ^1.0.2 flutter: sdk: flutter - go_router: ^16.0.0 + go_router: ^17.0.1 url_launcher: ^6.1.1 window_size: git: diff --git a/pedometer/example/pubspec.yaml b/pedometer/example/pubspec.yaml index b9157f05fae..371cfcfbcf7 100644 --- a/pedometer/example/pubspec.yaml +++ b/pedometer/example/pubspec.yaml @@ -44,7 +44,7 @@ dependencies: ffi: ^2.1.2 intl: ^0.20.0 - jni: ^0.14.2 + jni: ^0.15.2 fl_chart: ^1.0.0 dev_dependencies: diff --git a/pedometer/pubspec.yaml b/pedometer/pubspec.yaml index 5dfa80d0f3c..3d86d3d0745 100644 --- a/pedometer/pubspec.yaml +++ b/pedometer/pubspec.yaml @@ -11,14 +11,14 @@ dependencies: flutter: sdk: flutter plugin_platform_interface: ^2.1.8 - jni: ^0.14.2 + jni: ^0.15.2 ffi: ^2.1.2 dev_dependencies: analysis_defaults: path: ../analysis_defaults - ffigen: ^19.1.0 - jnigen: ^0.14.2 + ffigen: ^20.1.1 + jnigen: ^0.15.0 flutter_test: sdk: flutter flutter_lints: ^6.0.0 diff --git a/place_tracker/pubspec.yaml b/place_tracker/pubspec.yaml index 3bdda822fde..21419b31003 100644 --- a/place_tracker/pubspec.yaml +++ b/place_tracker/pubspec.yaml @@ -13,7 +13,7 @@ dependencies: google_maps_flutter: ^2.2.0 provider: ^6.0.2 uuid: ^4.0.0 - go_router: ^16.0.0 + go_router: ^17.0.1 dev_dependencies: analysis_defaults: diff --git a/platform_channels/pubspec.yaml b/platform_channels/pubspec.yaml index 7ebe27e07b1..e3734edf798 100644 --- a/platform_channels/pubspec.yaml +++ b/platform_channels/pubspec.yaml @@ -10,7 +10,7 @@ dependencies: flutter: sdk: flutter cupertino_icons: ^1.0.3 - go_router: ^16.0.0 + go_router: ^17.0.1 dev_dependencies: analysis_defaults: diff --git a/provider_shopper/pubspec.yaml b/provider_shopper/pubspec.yaml index 2c8524c97df..f540b6c309e 100644 --- a/provider_shopper/pubspec.yaml +++ b/provider_shopper/pubspec.yaml @@ -10,7 +10,7 @@ environment: dependencies: flutter: sdk: flutter - go_router: ^16.0.0 + go_router: ^17.0.1 provider: ^6.0.2 window_size: git: diff --git a/simplistic_calculator/pubspec.yaml b/simplistic_calculator/pubspec.yaml index 2f59b1b5d3c..c722982b55b 100644 --- a/simplistic_calculator/pubspec.yaml +++ b/simplistic_calculator/pubspec.yaml @@ -15,7 +15,7 @@ dependencies: flutter: sdk: flutter flutter_layout_grid: ^2.0.1 - flutter_riverpod: ^2.0.2 + flutter_riverpod: ^3.0.3 math_expressions: ^2.7.0 window_size: git: diff --git a/testing_app/pubspec.yaml b/testing_app/pubspec.yaml index 3d0b1357b34..c220b7463f3 100644 --- a/testing_app/pubspec.yaml +++ b/testing_app/pubspec.yaml @@ -11,7 +11,7 @@ dependencies: sdk: flutter cupertino_icons: ^1.0.3 provider: ^6.0.2 - go_router: ^16.0.0 + go_router: ^17.0.1 dev_dependencies: analysis_defaults: