How matteocrielesi/f1-projectgame works
1. This is a Flutter-based, client-only F1 arcade game with no backend service in the repository. The same Dart codebase targets Web, Android, Windows, macOS, Linux, and iOS, with platform shells generated by Flutter around the shared app logic.
2. The app entry and navigation flow appear to be main.dart → splash/boot UI (splash_page.dart) → a pre-game/menu screen (game_page_0.dart) → the main play screen (lib/game/screens/game_screen.dart). The README confirms the main documented experience is the Challenge mode.
3. The central runtime boundary is the game controller layer in lib/game/controllers/game_controller.dart. This is likely the orchestrator that owns game state, selected circuit, vehicle state, lap timing, race progression, and restart/retry behavior.
4. The domain model is split into Car and Circuit under lib/game/models/. These objects represent the core game entities that the controller and physics layer operate on, rather than being UI-only state.
5. Track content is data-driven from JSON assets under assets/circuiti/track/. Each circuit has its own track file, which suggests geometry/layout is loaded at runtime instead of being hardcoded. The mask folder likely supports track boundaries or collision/driveable-area detection.
6. Motion and interaction rules are isolated in lib/game/utils/physics.dart. This is the gameplay math layer: acceleration, braking, steering, timing, and probably simple collision or off-track handling. start_lights.dart suggests a pre-race countdown subsystem that gates when the player can start moving.
7. Presentation is concentrated in lib/game/screens/ and lib/game/widgets/. game_screen.dart is the main play surface, while game_controls.dart provides the touch/keyboard controls that feed player input into the controller. The UI is therefore a thin layer over the game state.
8. Persistence is abstracted through lib/game/saves/game_records.dart with separate platform implementations: game_records_impl_io.dart and game_records_impl_web.dart. This is an important architectural boundary because record storage is platform-specific, likely using local file/system storage on desktop/mobile and browser storage on Web.
9. The asset model is broad and game-specific: assets/logos, assets/macchine, assets/piloti, and the circuit JSONs. That indicates the game is content-rich and visually branded, with the gameplay logic separate from the visual/theme assets.
10. Platform directories (android, ios, macos, linux, windows, web) are mostly standard Flutter wrappers, but the repo also includes web-specific static files like web/index.html, web/manifest.json, and splash assets. These define the browser packaging and PWA surface for the Web build.
11. CI/CD is a first-class operational subsystem in .github/workflows/. The repository automatically builds and publishes Android APKs, Windows EXEs, and web builds to GitHub Pages; tagged releases on main produce release artifacts, while pushes to main deploy the web build.
12. The scripts/increment_version.* files support release/version automation, matching the workflow-driven release process. In architecture terms, versioning is treated as part of the delivery pipeline rather than a manual packaging step.
13. Tests exist but are minimal in scope (test/widget_test.dart, plus default platform test scaffolding). The repository’s main architectural emphasis is on gameplay logic, asset-driven track content, and multi-platform distribution rather than a large test or service layer.
Main entry points: game_controller.dart Game controller · main.dart Main · workflows Workflows · game_screen.dart Game screen
Components 23
Shared app
Flutter app logic shared across all targets.
Gameplay engine
Game state, rules, models, and runtime flow.
- Game screen · Main gameplay surface and in-race presentation.
lib/game/screens/game_screen.dart - Game controller · Owns race state, progression, retries, and selected circuit.
lib/game/controllers/game_controller.dart - Physics · Motion, steering, timing, and gameplay math.
lib/game/utils/physics.dart - Start lights · Pre-race start gate and launch timing.
lib/start_lights.dart - Controls · Touch and keyboard input surface for the player.
lib/game/widgets/game_controls.dart - Car · Vehicle state and attributes used by the controller and physics.
lib/game/models/car.dart - Circuit · Track selection and circuit metadata.
lib/game/models/circuit.dart - Game records · Abstraction for saving and loading records.
lib/game/saves/game_records.dart - Records IO · Platform persistence implementation for desktop/mobile.
lib/game/saves/game_records_impl_io.dart - Records web · Browser persistence implementation for Web.
lib/game/saves/game_records_impl_web.dart
Content
Asset-driven track and visual data.
- Track JSON · Circuit geometry and layout definitions loaded at runtime.
assets/circuiti/track - Visual assets · Branded cars, drivers, logos, and related game art.
assets
Delivery
Build, release, and version automation.
- Workflows · Build, release, and deployment automation.
.github/workflows - Versioning · Automated version bumping for releases and builds.
scripts/increment_version.py
Platform shells
Generated wrappers and platform entry points.
- Android shell · Android host project and launcher entry point.
android - iOS shell · iOS host project and launcher entry point.
ios - macOS shell · macOS host project and launcher entry point.
macos - Linux shell · Linux host project and launcher entry point.
linux - Windows shell · Windows host project and launcher entry point.
windows - Web shell · Web entry page, manifest, and splash packaging.
web
Connections 24
- Main → Splash: boots · Application starts in the splash flow.
- Splash → Game menu: navigates · Boot screen transitions into pre-game selection.
- Game menu → Game screen: starts game · Challenge flow enters the main play screen.
- Game screen → Game controller: drives · Gameplay UI is orchestrated by the controller.
- Controls → Game controller: inputs · Player input feeds race state and movement decisions.
- Game controller → Physics: uses · Controller applies gameplay motion and timing rules.
- Game controller → Start lights: gates · Race launch is gated by countdown state.
- Game controller → Car: owns · Controller tracks the active vehicle state.
- Game controller → Circuit: selects · Controller manages the chosen circuit and track.
- Game controller → Game records: persists · Controller reads and writes race records.
- Game records → Records IO: implements · Native persistence backend.
- Game records → Records web: implements · Web persistence backend.
- Circuit → Track JSON: loads · Circuits are data-driven from JSON track files.
- Game screen → Visual assets: renders · Gameplay and branding rely on game assets.
- Android shell → Main: hosts · Android wrapper launches the shared Dart app.
- iOS shell → Main: hosts · iOS wrapper launches the shared Dart app.
- macOS shell → Main: hosts · macOS wrapper launches the shared Dart app.
- Linux shell → Main: hosts · Linux wrapper launches the shared Dart app.
- Windows shell → Main: hosts · Windows wrapper launches the shared Dart app.
- Web shell → Main: hosts · Web packaging launches the shared Dart app.
- Workflows → Android shell: builds · CI produces Android artifacts.
- Workflows → Windows shell: builds · CI produces Windows artifacts.
- Workflows → Web shell: deploys · CI publishes web builds to Pages.
- Versioning → Workflows: supports · Version bumping is part of the release pipeline.