From c1906ca7f4b8681dc559eeaf0e293c5059afc74d Mon Sep 17 00:00:00 2001 From: Ulrich Diedrichsen Date: Fri, 30 May 2025 01:39:14 +0200 Subject: [PATCH 1/6] Add comprehensive CLAUDE.md documentation for Claude Code integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This adds essential guidance for future Claude Code instances including: - Available Flutter development commands and testing workflows - High-level architecture overview of the dual physics implementation - Key project structure and dependencies documentation - Testing setup with golden toolkit configuration ๐Ÿค– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..8243987 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,75 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +**Moinsen Physics** is a Flutter-based physics simulation app featuring a Newton's Cradle implementation. The project uniquely demonstrates dual physics approaches: pure Dart calculations and the Forge2D physics engine. + +## Development Commands + +```bash +# Core development +flutter pub get # Install dependencies +flutter run # Run debug mode +flutter run -d android # Run on specific platform +flutter analyze # Code analysis +dart format . # Format code + +# Building +flutter build apk # Android release +flutter build ios # iOS release +flutter build web # Web release + +# Testing +flutter test # Run all tests +flutter test test/screenshot_test.dart --update-goldens # Update golden files +``` + +## Architecture + +### Dual Physics Implementation +The app implements Newton's Cradle using two distinct approaches: + +1. **Pure Dart** (`lib/newton_cradle/plain_dart/`): Custom physics with manual collision detection +2. **Forge2D** (`lib/newton_cradle/forge2d/`): Box2D physics engine integration + +### Key Components +- **Controllers**: Physics simulation logic in `newton_cradle_controller.dart` +- **Game Engine**: Flame-based implementation in `newton_cradle_game.dart` +- **UI Controls**: Simulation parameters in `controls/simulation_controls.dart` +- **Sound System**: Velocity-based audio feedback with platform-specific handling + +### Dependencies +- **Flame + Forge2D**: Game engine and physics +- **Riverpod**: State management +- **Flutter Sound**: Audio with collision-based dynamics +- **Golden Toolkit**: Screenshot testing framework + +## Testing Setup + +### Golden Tests +Comprehensive screenshot testing across multiple device configurations: +- Android: Smartphone, 7" tablet, 10" tablet +- iOS: iPhone 6.5", iPhone 6.9", iPad Pro 12.9" +- Test files: `test/screenshot_test.dart`, goldens in `test/goldens/` + +### Sound Integration +- Disabled for web and test environments +- Asset-based (`assets/sounds/click.wav`) +- Dynamic volume/pitch based on collision physics + +## Code Organization + +### Generated Exports +Uses `_index.dart` files for clean module exports (generated by "Moinsen Flutter" tool). + +### Performance Features +- 60 FPS animation controller +- Efficient collision detection algorithms +- Memory-conscious resource management +- Platform-optimized rendering + +## Git Workflow +- **Main branch**: `develop` +- **Current feature branch**: `feat/game-design` \ No newline at end of file From a77b5d3d2722f3f2c009e32a8125ec5a1ae0f671 Mon Sep 17 00:00:00 2001 From: Ulrich Diedrichsen Date: Fri, 30 May 2025 01:40:36 +0200 Subject: [PATCH 2/6] Refactor animation controller initialization and update pubspec.yaml dependencies --- .../plain_dart/newton_cradle_controller.dart | 30 ++- pubspec.lock | 247 +++++++----------- pubspec.yaml | 24 +- 3 files changed, 129 insertions(+), 172 deletions(-) diff --git a/lib/newton_cradle/plain_dart/newton_cradle_controller.dart b/lib/newton_cradle/plain_dart/newton_cradle_controller.dart index 2b4b832..eea203c 100644 --- a/lib/newton_cradle/plain_dart/newton_cradle_controller.dart +++ b/lib/newton_cradle/plain_dart/newton_cradle_controller.dart @@ -36,13 +36,14 @@ class NewtonCradleController { } void _initializeController() { - animationController = AnimationController( - vsync: vsync, - duration: const Duration(milliseconds: 16), - )..addListener(() { - update(); - onUpdate(); - }); + animationController = + AnimationController( + vsync: vsync, + duration: const Duration(milliseconds: 16), + )..addListener(() { + update(); + onUpdate(); + }); animationController!.repeat(); } @@ -104,10 +105,7 @@ class NewtonCradleController { for (int i = 0; i < controls.numberOfBalls; i++) { final xPos = startX + i * controls.ballRadius * 2.0; - final ballPosition = Offset( - xPos, - originY + controls.ropeLength, - ); + final ballPosition = Offset(xPos, originY + controls.ropeLength); final ball = controls.useRubberBands ? RubberBandBall( @@ -161,12 +159,16 @@ class NewtonCradleController { if (!controls.isSoundEnabled || _soundPlayer == null || !_soundPlayer!.isOpen() || - _soundData == null) return; + _soundData == null) { + return; + } try { final double rate = 1.0 + (velocity * 0.1).clamp(-0.1, 0.1); - final double volume = - (0.1 + 0.9 * (log(1 + velocity) / log(5))).clamp(0.1, 1.0); + final double volume = (0.1 + 0.9 * (log(1 + velocity) / log(5))).clamp( + 0.1, + 1.0, + ); _soundPlayer!.setVolume(volume); _soundPlayer!.setSpeed(rate); diff --git a/pubspec.lock b/pubspec.lock index 30dd635..a054a80 100644 --- a/pubspec.lock +++ b/pubspec.lock @@ -5,23 +5,18 @@ packages: dependency: transitive description: name: _fe_analyzer_shared - sha256: f256b0c0ba6c7577c15e2e4e114755640a875e885099367bf6e012b19314c834 + sha256: e55636ed79578b9abca5fecf9437947798f5ef7456308b5cb85720b793eac92f url: "https://pub.dev" source: hosted - version: "72.0.0" - _macros: - dependency: transitive - description: dart - source: sdk - version: "0.3.2" + version: "82.0.0" analyzer: dependency: transitive description: name: analyzer - sha256: b652861553cd3990d8ed361f7979dc6d7053a9ac8843fa73820ab68ce5410139 + sha256: "904ae5bb474d32c38fb9482e2d925d5454cda04ddd0e55d2e6826bc72f6ba8c0" url: "https://pub.dev" source: hosted - version: "6.7.0" + version: "7.4.5" archive: dependency: transitive description: @@ -42,26 +37,26 @@ packages: dependency: transitive description: name: async - sha256: "947bfcf187f74dbc5e146c9eb9c0f10c9f8b30743e341481c1e2ed3ecc18c20c" + sha256: "758e6d74e971c3e5aceb4110bfd6698efc7f501675bcfe0c775459a8140750eb" url: "https://pub.dev" source: hosted - version: "2.11.0" + version: "2.13.0" boolean_selector: dependency: transitive description: name: boolean_selector - sha256: "6cfb5af12253eaf2b368f07bacc5a80d1301a071c73360d746b7f2e32d762c66" + sha256: "8aab1771e1243a5063b8b0ff68042d67334e3feab9e95b9490f9a6ebf73b42ea" url: "https://pub.dev" source: hosted - version: "2.1.1" + version: "2.1.2" characters: dependency: transitive description: name: characters - sha256: "04a925763edad70e8443c99234dc3328f442e811f1d8fd1a72f1c8ad0f69a605" + sha256: f71061c654a3380576a52b451dd5532377954cf9dbd272a78fc8479606670803 url: "https://pub.dev" source: hosted - version: "1.3.0" + version: "1.4.0" checked_yaml: dependency: transitive description: @@ -70,6 +65,14 @@ packages: url: "https://pub.dev" source: hosted version: "2.0.3" + cli_config: + dependency: transitive + description: + name: cli_config + sha256: ac20a183a07002b700f0c25e61b7ee46b23c309d76ab7b7640a028f18e4d99ec + url: "https://pub.dev" + source: hosted + version: "0.2.0" cli_util: dependency: transitive description: @@ -82,18 +85,18 @@ packages: dependency: transitive description: name: clock - sha256: cb6d7f03e1de671e34607e909a7213e31d7752be4fb66a86d29fe1eb14bfb5cf + sha256: fddb70d9b5277016c77a80201021d40a2247104d9f4aa7bab7157b7e3f05b84b url: "https://pub.dev" source: hosted - version: "1.1.1" + version: "1.1.2" collection: dependency: transitive description: name: collection - sha256: ee67cb0715911d28db6bf4af1026078bd6f0128b07a5f66fb2ed94ec6783c09a + sha256: "2f5709ae4d3d59dd8f7cd309b4e023046b57d8a6c82130785d2b0e5868084e76" url: "https://pub.dev" source: hosted - version: "1.18.0" + version: "1.19.1" convert: dependency: transitive description: @@ -106,10 +109,10 @@ packages: dependency: transitive description: name: coverage - sha256: "88b0fddbe4c92910fefc09cc0248f5e7f0cd23e450ded4c28f16ab8ee8f83268" + sha256: "4b8701e48a58f7712492c9b1f7ba0bb9d525644dd66d023b62e1fc8cdb560c8a" url: "https://pub.dev" source: hosted - version: "1.10.0" + version: "1.14.0" crypto: dependency: transitive description: @@ -122,10 +125,10 @@ packages: dependency: transitive description: name: fake_async - sha256: "511392330127add0b769b75a987850d136345d9227c6b94c96a04cf4a391bf78" + sha256: "5368f224a74523e8d2e7399ea1638b37aecfca824a3cc4dfdf77bf1fa905ac44" url: "https://pub.dev" source: hosted - version: "1.3.1" + version: "1.3.3" ffi: dependency: transitive description: @@ -138,34 +141,26 @@ packages: dependency: transitive description: name: file - sha256: "5fc22d7c25582e38ad9a8515372cd9a93834027aacf1801cf01164dac0ffa08c" + sha256: a3b4f84adafef897088c160faf7dfffb7696046cb13ae90b508c2cbc95d3b8d4 url: "https://pub.dev" source: hosted - version: "7.0.0" - fixnum: - dependency: transitive - description: - name: fixnum - sha256: b6dc7065e46c974bc7c5f143080a6764ec7a4be6da1285ececdc37be96de53be - url: "https://pub.dev" - source: hosted - version: "1.1.1" + version: "7.0.1" flame: dependency: "direct main" description: name: flame - sha256: baafe5c38075b60577db05e0421c12941695b246547d9aca95166def3f29e57f + sha256: "58566686ad9b7e6a3984c50a740fd733e0a5022d48263916f50b3c78e7f14ec0" url: "https://pub.dev" source: hosted - version: "1.21.0" + version: "1.29.0" flame_forge2d: dependency: "direct main" description: name: flame_forge2d - sha256: "12d71ba18ea7707f96a01eb6380bf24691c39817c8c47cf5bf00c21edf5b7401" + sha256: "2de549cd4afece82158daaef78486f023475028c061fa2d330e927f9e6efcaa4" url: "https://pub.dev" source: hosted - version: "0.18.2+1" + version: "0.19.0+2" flutter: dependency: "direct main" description: flutter @@ -180,18 +175,18 @@ packages: dependency: "direct dev" description: name: flutter_launcher_icons - sha256: "619817c4b65b322b5104b6bb6dfe6cda62d9729bd7ad4303ecc8b4e690a67a77" + sha256: bfa04787c85d80ecb3f8777bde5fc10c3de809240c48fa061a2c2bf15ea5211c url: "https://pub.dev" source: hosted - version: "0.14.1" + version: "0.14.3" flutter_lints: dependency: "direct dev" description: name: flutter_lints - sha256: "5398f14efa795ffb7a33e9b6a08798b26a180edac4ad7db3f231e40f82ce11e1" + sha256: "3105dc8492f6183fb076ccf1f351ac3d60564bff92e20bfc4af9cc1651f4e7e1" url: "https://pub.dev" source: hosted - version: "5.0.0" + version: "6.0.0" flutter_localizations: dependency: "direct main" description: flutter @@ -209,26 +204,26 @@ packages: dependency: "direct main" description: name: flutter_sound - sha256: "31f9b2058a152520774f98147adb9f5df3b2e9ee0d5b6a7f4f07bec9feeca4e3" + sha256: ef89477f6e8ce2fa395158ebc4a8b11982e3ada440b4021c06fd97a4e771554b url: "https://pub.dev" source: hosted - version: "9.16.3" + version: "9.28.0" flutter_sound_platform_interface: dependency: transitive description: name: flutter_sound_platform_interface - sha256: "60ce97b065ca12161d501575dfcd49ec0764545a5e9ff9576dc96eb19f189e76" + sha256: "3394d7e664a09796818014ff85a81db0dec397f4c286cbe52f8783886fa5a497" url: "https://pub.dev" source: hosted - version: "9.16.3" + version: "9.28.0" flutter_sound_web: dependency: transitive description: name: flutter_sound_web - sha256: c557aebe181ce1d2261a4cb9e3bb8eada18af30745791a7241e8d00152c5fa06 + sha256: "4e10c94a8574bd93bb8668af59bf76f5312a890bccd3778d73168a7133217dc5" url: "https://pub.dev" source: hosted - version: "9.16.3" + version: "9.28.0" flutter_test: dependency: "direct dev" description: flutter @@ -243,10 +238,10 @@ packages: dependency: transitive description: name: forge2d - sha256: "6aac85f1cb9f7e3720bff5d6884ff2e1bcb74402e6fe271599b7b1f65574f5e2" + sha256: c7d0f84bb75d16af41ab5168676d6df80f32a9890ccaf76857d90fe80bb6e7ff url: "https://pub.dev" source: hosted - version: "0.13.1" + version: "0.14.0" frontend_server_client: dependency: transitive description: @@ -304,10 +299,10 @@ packages: dependency: "direct main" description: name: intl - sha256: d6f56758b7d3014a48af9701c085700aac781a92a87a62b1333b46d8879661cf + sha256: "3df61194eb431efc39c4ceba583b95633a403f46c9fd341e550ce0bfa50e9aa5" url: "https://pub.dev" source: hosted - version: "0.19.0" + version: "0.20.2" io: dependency: transitive description: @@ -336,18 +331,18 @@ packages: dependency: transitive description: name: leak_tracker - sha256: "3f87a60e8c63aecc975dda1ceedbc8f24de75f09e4856ea27daf8958f2f0ce05" + sha256: "6bb818ecbdffe216e81182c2f0714a2e62b593f4a4f13098713ff1685dfb6ab0" url: "https://pub.dev" source: hosted - version: "10.0.5" + version: "10.0.9" leak_tracker_flutter_testing: dependency: transitive description: name: leak_tracker_flutter_testing - sha256: "932549fb305594d82d7183ecd9fa93463e9914e1b67cacc34bc40906594a1806" + sha256: f8b613e7e6a13ec79cfdc0e97638fddb3ab848452eff057653abd3edba760573 url: "https://pub.dev" source: hosted - version: "3.0.5" + version: "3.0.9" leak_tracker_testing: dependency: transitive description: @@ -360,18 +355,18 @@ packages: dependency: transitive description: name: lints - sha256: "3315600f3fb3b135be672bf4a178c55f274bebe368325ae18462c89ac1e3b413" + sha256: a5e2b223cb7c9c8efdc663ef484fdd95bb243bff242ef5b13e26883547fce9a0 url: "https://pub.dev" source: hosted - version: "5.0.0" + version: "6.0.0" logger: dependency: "direct main" description: name: logger - sha256: "697d067c60c20999686a0add96cf6aba723b3aa1f83ecf806a8097231529ec32" + sha256: be4b23575aac7ebf01f225a241eb7f6b5641eeaf43c6a8613510fc2f8cf187d1 url: "https://pub.dev" source: hosted - version: "2.4.0" + version: "2.5.0" logging: dependency: transitive description: @@ -380,22 +375,14 @@ packages: url: "https://pub.dev" source: hosted version: "1.3.0" - macros: - dependency: transitive - description: - name: macros - sha256: "0acaed5d6b7eab89f63350bccd82119e6c602df0f391260d0e32b5e23db79536" - url: "https://pub.dev" - source: hosted - version: "0.1.2-main.4" matcher: dependency: transitive description: name: matcher - sha256: d2323aa2060500f906aa31a895b4030b6da3ebdcc5619d14ce1aada65cd161cb + sha256: dc58c723c3c24bf8d3e2d3ad3f2f9d7bd9cf43ec6feaa64181775e60190153f2 url: "https://pub.dev" source: hosted - version: "0.12.16+1" + version: "0.12.17" material_color_utilities: dependency: transitive description: @@ -408,10 +395,10 @@ packages: dependency: transitive description: name: meta - sha256: bdb68674043280c3428e9ec998512fb681678676b3c54e773629ffe74419f8c7 + sha256: e3641ec5d63ebf0d9b41bd43201a66e3fc79a65db5f61fc181f04cd27aab950c url: "https://pub.dev" source: hosted - version: "1.15.0" + version: "1.16.0" mime: dependency: transitive description: @@ -420,14 +407,6 @@ packages: url: "https://pub.dev" source: hosted version: "2.0.0" - nested: - dependency: transitive - description: - name: nested - sha256: "03bac4c528c64c95c722ec99280375a6f2fc708eec17c7b3f07253b626cd2a20" - url: "https://pub.dev" - source: hosted - version: "1.0.0" node_preamble: dependency: transitive description: @@ -440,10 +419,10 @@ packages: dependency: transitive description: name: ordered_set - sha256: fc861bb51fc863cd3e0718e21768af9586e0d5022b91a0fd4437636456cdb7d0 + sha256: d6c1d053a533e84931a388cbf03f1ad21a0543bf06c7a281859d3ffacd8e15f2 url: "https://pub.dev" source: hosted - version: "6.1.1" + version: "8.0.0" package_config: dependency: transitive description: @@ -456,10 +435,10 @@ packages: dependency: transitive description: name: path - sha256: "087ce49c3f0dc39180befefc60fdb4acd8f8620e5682fe2476afd0b3688bb4af" + sha256: "75cca69d1490965be98c73ceaea117e8a04dd21217b37b292c9ddbec0d955bc5" url: "https://pub.dev" source: hosted - version: "1.9.0" + version: "1.9.1" path_provider: dependency: transitive description: @@ -512,26 +491,26 @@ packages: dependency: "direct main" description: name: permission_handler - sha256: "18bf33f7fefbd812f37e72091a15575e72d5318854877e0e4035a24ac1113ecb" + sha256: "2d070d8684b68efb580a5997eb62f675e8a885ef0be6e754fb9ef489c177470f" url: "https://pub.dev" source: hosted - version: "11.3.1" + version: "12.0.0+1" permission_handler_android: dependency: transitive description: name: permission_handler_android - sha256: "71bbecfee799e65aff7c744761a57e817e73b738fedf62ab7afd5593da21f9f1" + sha256: "1e3bc410ca1bf84662104b100eb126e066cb55791b7451307f9708d4007350e6" url: "https://pub.dev" source: hosted - version: "12.0.13" + version: "13.0.1" permission_handler_apple: dependency: transitive description: name: permission_handler_apple - sha256: e6f6d73b12438ef13e648c4ae56bd106ec60d17e90a59c4545db6781229082a0 + sha256: f000131e755c54cf4d84a5d8bd6e4149e262cc31c5a8b1d698de1ac85fa41023 url: "https://pub.dev" source: hosted - version: "9.4.5" + version: "9.4.7" permission_handler_html: dependency: transitive description: @@ -544,10 +523,10 @@ packages: dependency: transitive description: name: permission_handler_platform_interface - sha256: e9c8eadee926c4532d0305dff94b85bf961f16759c3af791486613152af4b4f9 + sha256: eb99b295153abce5d683cac8c02e22faab63e50679b937fa1bf67d58bb282878 url: "https://pub.dev" source: hosted - version: "4.2.3" + version: "4.3.0" permission_handler_windows: dependency: transitive description: @@ -568,10 +547,10 @@ packages: dependency: transitive description: name: platform - sha256: "9b71283fc13df574056616011fb138fd3b793ea47cc509c189a6c3fa5f8a1a65" + sha256: "5d6b1b0036a5f331ebc77c850ebc8506cbc1e9416c27e59b439f917a902a4984" url: "https://pub.dev" source: hosted - version: "3.1.5" + version: "3.1.6" plugin_platform_interface: dependency: transitive description: @@ -592,18 +571,10 @@ packages: dependency: transitive description: name: process - sha256: "21e54fd2faf1b5bdd5102afd25012184a6793927648ea81eea80552ac9405b32" - url: "https://pub.dev" - source: hosted - version: "5.0.2" - provider: - dependency: transitive - description: - name: provider - sha256: c8a055ee5ce3fd98d6fc872478b03823ffdb448699c6ebdbbc71d59b596fd48c + sha256: "107d8be718f120bbba9dcd1e95e3bd325b1b4a4f07db64154635ba03f2567a0d" url: "https://pub.dev" source: hosted - version: "6.1.2" + version: "5.0.3" pub_semver: dependency: transitive description: @@ -612,14 +583,14 @@ packages: url: "https://pub.dev" source: hosted version: "2.1.4" - recase: + pubspec_parse: dependency: transitive description: - name: recase - sha256: e4eb4ec2dcdee52dcf99cb4ceabaffc631d7424ee55e56f280bc039737f89213 + name: pubspec_parse + sha256: "0560ba233314abbed0a48a2956f7f022cce7c3e1e73df540277da7544cad4082" url: "https://pub.dev" source: hosted - version: "4.1.0" + version: "1.5.0" riverpod: dependency: transitive description: @@ -664,7 +635,7 @@ packages: dependency: transitive description: flutter source: sdk - version: "0.0.99" + version: "0.0.0" source_map_stack_trace: dependency: transitive description: @@ -685,26 +656,18 @@ packages: dependency: transitive description: name: source_span - sha256: "53e943d4206a5e30df338fd4c6e7a077e02254531b138a15aec3bd143c1a8b3c" - url: "https://pub.dev" - source: hosted - version: "1.10.0" - sprintf: - dependency: transitive - description: - name: sprintf - sha256: "1fc9ffe69d4df602376b52949af107d8f5703b77cda567c4d7d86a0693120f23" + sha256: "254ee5351d6cb365c859e20ee823c3bb479bf4a293c22d17a9f1bf144ce86f7c" url: "https://pub.dev" source: hosted - version: "7.0.0" + version: "1.10.1" stack_trace: dependency: transitive description: name: stack_trace - sha256: "73713990125a6d93122541237550ee3352a2d84baad52d375a4cad2eb9b7ce0b" + sha256: "8b27215b45d22309b5cddda1aa2b19bdfec9df0e765f2de506401c071d38d1b1" url: "https://pub.dev" source: hosted - version: "1.11.1" + version: "1.12.1" state_notifier: dependency: transitive description: @@ -717,18 +680,18 @@ packages: dependency: transitive description: name: stream_channel - sha256: ba2aa5d8cc609d96bbb2899c28934f9e1af5cddbd60a827822ea467161eb54e7 + sha256: "969e04c80b8bcdf826f8f16579c7b14d780458bd97f56d107d3950fdbeef059d" url: "https://pub.dev" source: hosted - version: "2.1.2" + version: "2.1.4" string_scanner: dependency: transitive description: name: string_scanner - sha256: "556692adab6cfa87322a115640c11f13cb77b3f076ddcc5d6ae3c20242bedcde" + sha256: "921cd31725b72fe181906c6a94d987c78e3b98c2e205b397ea399d4054872b43" url: "https://pub.dev" source: hosted - version: "1.2.0" + version: "1.4.1" sync_http: dependency: transitive description: @@ -749,34 +712,34 @@ packages: dependency: transitive description: name: term_glyph - sha256: a29248a84fbb7c79282b40b8c72a1209db169a2e0542bce341da992fe1bc7e84 + sha256: "7f554798625ea768a7518313e58f83891c7f5024f88e46e7182a4558850a4b8e" url: "https://pub.dev" source: hosted - version: "1.2.1" + version: "1.2.2" test: dependency: "direct dev" description: name: test - sha256: "7ee44229615f8f642b68120165ae4c2a75fe77ae2065b1e55ae4711f6cf0899e" + sha256: "301b213cd241ca982e9ba50266bd3f5bd1ea33f1455554c5abb85d1be0e2d87e" url: "https://pub.dev" source: hosted - version: "1.25.7" + version: "1.25.15" test_api: dependency: transitive description: name: test_api - sha256: "5b8a98dafc4d5c4c9c72d8b31ab2b23fc13422348d2997120294d3bac86b4ddb" + sha256: fb31f383e2ee25fbbfe06b40fe21e1e458d14080e3c67e7ba0acfde4df4e0bbd url: "https://pub.dev" source: hosted - version: "0.7.2" + version: "0.7.4" test_core: dependency: transitive description: name: test_core - sha256: "55ea5a652e38a1dfb32943a7973f3681a60f872f8c3a05a14664ad54ef9c6696" + sha256: "84d17c3486c8dfdbe5e12a50c8ae176d15e2a771b96909a9442b40173649ccaa" url: "https://pub.dev" source: hosted - version: "0.6.4" + version: "0.6.8" typed_data: dependency: transitive description: @@ -785,14 +748,6 @@ packages: url: "https://pub.dev" source: hosted version: "1.4.0" - uuid: - dependency: transitive - description: - name: uuid - sha256: a5be9ef6618a7ac1e964353ef476418026db906c4facdedaa299b7a2e71690ff - url: "https://pub.dev" - source: hosted - version: "4.5.1" vector_math: dependency: "direct main" description: @@ -805,10 +760,10 @@ packages: dependency: transitive description: name: vm_service - sha256: "5c5f338a667b4c644744b661f309fb8080bb94b18a7e91ef1dbd343bed00ed6d" + sha256: ddfa8d30d89985b96407efce8acbdd124701f96741f2d981ca860662f1c0dc02 url: "https://pub.dev" source: hosted - version: "14.2.5" + version: "15.0.0" watcher: dependency: transitive description: @@ -845,10 +800,10 @@ packages: dependency: transitive description: name: webdriver - sha256: "003d7da9519e1e5f329422b36c4dcdf18d7d2978d1ba099ea4e45ba490ed845e" + sha256: "2f3a14ca026957870cfd9c635b83507e0e51d8091568e90129fbf805aba7cade" url: "https://pub.dev" source: hosted - version: "3.0.3" + version: "3.1.0" webkit_inspection_protocol: dependency: transitive description: @@ -882,5 +837,5 @@ packages: source: hosted version: "3.1.2" sdks: - dart: ">=3.5.0 <4.0.0" - flutter: ">=3.24.0" + dart: "3.8.0" + flutter: ">=3.27.1" diff --git a/pubspec.yaml b/pubspec.yaml index acb4653..cab5909 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,25 +1,25 @@ name: moinsen_physics description: Just a simple physics game -publish_to: none -version: 0.2.0 +repository: https://github.com/moinsen-dev/moinsen_physics +version: 0.3.0 environment: - sdk: ">=3.5.0 <4.0.0" - flutter: ">=3.2.0 <4.0.0" + sdk: 3.8.0 + flutter: 3.3.2 dependencies: flutter: sdk: flutter flutter_localizations: sdk: flutter - flame: ^1.21.0 - flame_forge2d: ^0.18.2+1 - flutter_sound: ^9.16.3 - permission_handler: ^11.3.0 + flame: ^1.29.0 + flame_forge2d: ^0.19.0+2 + flutter_sound: ^9.28.0 + permission_handler: ^12.0.0+1 vector_math: ^2.1.4 flutter_riverpod: ^2.6.1 - intl: ^0.19.0 - logger: ^2.4.0 + intl: ^0.20.2 + logger: ^2.5.0 dev_dependencies: flutter_driver: @@ -27,8 +27,8 @@ dev_dependencies: test: any flutter_test: sdk: flutter - flutter_lints: ^5.0.0 - flutter_launcher_icons: ^0.14.1 + flutter_lints: ^6.0.0 + flutter_launcher_icons: ^0.14.3 golden_toolkit: ^0.15.0 flutter: From 3875695da801ce550c792b8fd4d1cdc09b0367c1 Mon Sep 17 00:00:00 2001 From: Ulrich Diedrichsen Date: Fri, 30 May 2025 01:43:22 +0200 Subject: [PATCH 3/6] Update CLAUDE.md with GitHub workflow and current PR context MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add GitHub Issues and Pull Requests workflow documentation - Include GitHub CLI commands for issue and PR management - Document current work on PR #2 (Gravity Lab transformation) - Specify use of gh tool for setup and completion tracking ๐Ÿค– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8243987..e32ed48 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -70,6 +70,34 @@ Uses `_index.dart` files for clean module exports (generated by "Moinsen Flutter - Memory-conscious resource management - Platform-optimized rendering -## Git Workflow +## Development Workflow + +### GitHub Integration +- **Primary workflow**: GitHub Issues and Pull Requests +- **GitHub CLI**: Use `gh` command for issue and PR management +- **Current work**: Pull Request #2 - "feat: Initial setup for Gravity Lab transformation" + - Transforming Moinsen Physics into Gravity Lab + - Modern Flutter architecture with clean code principles + - Firebase integration for analytics and monetization + +### Git Workflow - **Main branch**: `develop` -- **Current feature branch**: `feat/game-design` \ No newline at end of file +- **Current feature branch**: `feat/game-design` + +### GitHub Commands +```bash +# View current PR +gh pr view 2 + +# Create new issue +gh issue create --title "Feature Title" --body "Description" + +# List issues +gh issue list + +# Create PR from current branch +gh pr create --title "PR Title" --body "Description" + +# Review PR status +gh pr status +``` \ No newline at end of file From 5ba31d068e3bc90bd6cfbf79b86beef6964d4264 Mon Sep 17 00:00:00 2001 From: Ulrich Diedrichsen Date: Fri, 30 May 2025 01:53:26 +0200 Subject: [PATCH 4/6] Update CLAUDE.md with Gravity Lab implementation context MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add feature specification reference and implementation focus - Document current work on PR #2 Gravity Lab transformation - Clarify this is a free game without monetization/Firebase - Include implementation phases and key design principles - Add comprehensive development guidance for team ๐Ÿค– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e32ed48..b5c7220 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -76,9 +76,10 @@ Uses `_index.dart` files for clean module exports (generated by "Moinsen Flutter - **Primary workflow**: GitHub Issues and Pull Requests - **GitHub CLI**: Use `gh` command for issue and PR management - **Current work**: Pull Request #2 - "feat: Initial setup for Gravity Lab transformation" - - Transforming Moinsen Physics into Gravity Lab + - Implementing comprehensive feature specification from `docs/gravity-lab-feature-spec.md` + - Transforming Moinsen Physics into Gravity Lab physics puzzle game - Modern Flutter architecture with clean code principles - - Firebase integration for analytics and monetization + - **FREE GAME**: No monetization, no Firebase, no ads - pure physics puzzle experience ### Git Workflow - **Main branch**: `develop` @@ -100,4 +101,25 @@ gh pr create --title "PR Title" --body "Description" # Review PR status gh pr status -``` \ No newline at end of file +``` + +## Current Implementation Focus + +### Feature Specification +Follow the comprehensive feature spec in `docs/gravity-lab-feature-spec.md` which outlines: +- **Game Concept**: Physics puzzle game with gravity manipulation +- **6 Themed Worlds**: Newton's Lab, Zero-G Station, Aqua Depths, Magnetic Factory, Time Nexus, Quantum Realm +- **Core Mechanics**: 8-directional gravity control, 8 object types, interactive elements +- **Clean Architecture**: Domain/Data/Presentation layers with feature modules +- **Advanced Physics**: Forge2D integration, particle effects, collision systems + +### Implementation Phases +1. **Phase 1 (MVP)**: Core physics engine, 20 tutorial levels, basic UI +2. **Phase 2**: All 5 worlds (100 levels), progression system, visual polish +3. **Phase 3**: Level editor, community features, advanced mechanics + +### Key Design Principles +- **Free Game**: No monetization, ads, or Firebase +- **Physics-First**: Realistic gravity manipulation and object interactions +- **Visual Delight**: Particle effects, smooth animations, modern UI +- **Accessibility**: High contrast options, multiple control schemes \ No newline at end of file From 7a2774dbf874f35df8a65fd19fa62ca7f19f44cf Mon Sep 17 00:00:00 2001 From: Ulrich Diedrichsen Date: Fri, 30 May 2025 01:54:35 +0200 Subject: [PATCH 5/6] Update project configuration and add Gravity Lab feature specification document --- .gitignore | 2 + docs/gravity-lab-feature-spec.md | 684 ++++++++++++++++++ ios/Podfile | 2 +- ios/Podfile.lock | 16 +- .../xcshareddata/xcschemes/Runner.xcscheme | 3 + 5 files changed, 698 insertions(+), 9 deletions(-) create mode 100644 docs/gravity-lab-feature-spec.md diff --git a/.gitignore b/.gitignore index 29a3a50..79c113f 100644 --- a/.gitignore +++ b/.gitignore @@ -5,9 +5,11 @@ *.swp .DS_Store .atom/ +.build/ .buildlog/ .history .svn/ +.swiftpm/ migrate_working_dir/ # IntelliJ related diff --git a/docs/gravity-lab-feature-spec.md b/docs/gravity-lab-feature-spec.md new file mode 100644 index 0000000..e101e41 --- /dev/null +++ b/docs/gravity-lab-feature-spec.md @@ -0,0 +1,684 @@ +# Gravity Lab: Physics Puzzles +## Comprehensive Feature Specification Document + +**Version:** 0.3 +**Date:** May 2024 +**Project:** Moinsen Physics โ†’ Gravity Lab Transformation +**Platform:** iOS, Android, Web (Flutter) + +--- + +## Table of Contents +1. [Executive Summary](#executive-summary) +2. [Game Overview](#game-overview) +3. [Screen Specifications](#screen-specifications) +4. [Gameplay Mechanics](#gameplay-mechanics) +5. [Visual Design Specifications](#visual-design-specifications) +6. [User Interface Design](#user-interface-design) +7. [Physics Systems](#physics-systems) +8. [Progression Systems](#progression-systems) +9. [AI Features](#ai-features) +10. [Monetization Features](#monetization-features) +11. [Technical Specifications](#technical-specifications) +12. [Audio Specifications](#audio-specifications) + +--- + +## 1. Executive Summary + +### Vision Statement +Transform Moinsen Physics into "Gravity Lab" - a premium physics puzzle game that combines intuitive gameplay with cutting-edge AI features, creating an addictive experience that showcases the power of Flutter and modern game design. + +### Core Pillars +- **Intuitive Physics**: Easy to learn, hard to master +- **Visual Delight**: Stunning effects and smooth animations +- **Smart Progression**: AI-driven difficulty and content +- **Social Competition**: Multiplayer and community features +- **Fair Monetization**: Player-friendly business model + +--- + +## 2. Game Overview + +### Concept +Players manipulate gravity and various physics elements to guide objects through increasingly complex puzzles. Each level presents a unique challenge requiring creative thinking and precise timing. + +### Target Audience +- **Primary**: Puzzle game enthusiasts (18-45) +- **Secondary**: Casual mobile gamers +- **Tertiary**: Physics students and educators + +### Unique Selling Points +- First physics puzzle game with AI-generated levels +- Real-time multiplayer physics battles +- "Vibe Coding" - Create levels with natural language +- Adaptive difficulty that learns from player behavior + +--- + +## 3. Screen Specifications + +### 3.1 Splash Screen +**Purpose**: Brand introduction and loading +**Duration**: 2-3 seconds + +**Elements**: +- Moinsen Dev logo (fade in) +- Gravity Lab logo with physics particle effects +- Loading progress bar (styled as liquid filling a beaker) +- Tips/hints at bottom (rotating) +- Version number (bottom right) + +**Transitions**: +- Particle explosion transition to Main Menu +- Preload essential assets during splash + +### 3.2 Main Menu +**Purpose**: Central navigation hub + +**Layout**: +``` +[Profile Avatar] [Settings Icon] + + GRAVITY LAB + [Animated Logo] + + [ PLAY ] + [ CHALLENGES ] + [ CREATE ] + [ LEADERBOARD] + [ SHOP ] + +[Daily Reward] [News] [Friends] +``` + +**Interactive Elements**: +- Floating physics objects in background +- Parallax star field +- Reactive UI (buttons have physics properties) +- Particle effects on hover/tap +- Dynamic lighting based on time of day + +### 3.3 World Selection +**Purpose**: Choose gameplay area/theme + +**Visual Design**: +- Horizontal scrolling galaxy map +- Each world represented as a planet/space station +- Progress shown as orbiting satellites +- Locked worlds shown as mysterious silhouettes + +**Worlds**: +1. **Newton's Laboratory** (Tutorial) - Classic physics +2. **Zero-G Station** - Space/no gravity +3. **Aqua Depths** - Underwater physics +4. **Magnetic Factory** - Electromagnetic puzzles +5. **Time Nexus** - Time manipulation +6. **Quantum Realm** - Probability mechanics + +**Information Displayed**: +- World name and theme +- Completion percentage +- Star rating (1-3 stars per level) +- Best times for speedrunners +- Special achievements +- Current events/challenges + +### 3.4 Level Selection +**Purpose**: Choose specific puzzle within world + +**Layout Type**: Hexagonal grid with path connections +- Completed levels: Bright with star rating +- Current level: Pulsing glow effect +- Locked levels: Darkened with lock icon +- Special levels: Unique borders/effects + +**Preview Window**: +- Mini preview of level layout +- Difficulty indicator (1-5 atoms) +- Par time/moves +- Leaderboard snippet (top 3 + player) +- Power-ups allowed +- AI hint availability + +### 3.5 Gameplay Screen +**Purpose**: Core puzzle-solving interface + +**Layout Zones**: +``` +[Pause] [Timer] [Moves] [Hint] +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ โ”‚ +โ”‚ PLAY AREA โ”‚ +โ”‚ (Physics Simulation) โ”‚ +โ”‚ โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ [Gravity] [Tool1] [Tool2] โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +**HUD Elements**: +- **Top Bar**: + - Pause button + - Timer (for time attack) + - Move counter + - Hint button (AI-powered) + - Objective reminder + +- **Play Area**: + - Grid overlay (optional) + - Physics objects + - Interactive elements + - Particle effects + - Trail visualization + - Force field indicators + +- **Tool Bar**: + - Gravity direction control + - Available tools/modifiers + - Undo/Redo buttons + - Reset level button + +**Interactive Gestures**: +- Tap: Select/activate objects +- Drag: Move elements or adjust gravity +- Pinch: Zoom in/out +- Two-finger rotate: Rotate gravity field +- Long press: Object properties +- Swipe: Quick tool switching + +### 3.6 Level Complete Screen +**Purpose**: Celebrate success and show rewards + +**Animation Sequence**: +1. Physics objects celebrate (confetti physics) +2. Stars appear based on performance +3. Score counter animates up +4. Rewards slide in +5. Next/Replay/Share buttons appear + +**Information Shown**: +- Star rating (with specific criteria) +- Time taken vs par time +- Moves used vs optimal +- Score breakdown +- XP earned +- Unlocked content +- Leaderboard position +- Social sharing options + +### 3.7 Shop Screen +**Purpose**: Monetization and customization + +**Categories**: +- **Remove Ads**: One-time purchase banner +- **Coin Packs**: Various denominations +- **Power-ups**: Consumable items +- **Cosmetics**: Skins, trails, effects +- **Season Pass**: Current season offerings + +**Layout**: Tab-based with preview window +- Featured items carousel +- Category grid +- Item detail view with preview +- Purchase confirmation +- Owned items section + +### 3.8 Level Editor +**Purpose**: User-generated content creation + +**Interface Zones**: +- **Toolbar** (left): Objects, elements, tools +- **Canvas** (center): Build area with grid +- **Properties** (right): Selected object settings +- **Timeline** (bottom): For moving elements + +**Features**: +- Drag-and-drop interface +- Copy/paste functionality +- Test mode toggle +- Save/load templates +- Validation system +- AI assistance for balancing + +### 3.9 Settings Screen +**Purpose**: Game customization and options + +**Categories**: +- **Audio**: Music, SFX, haptics sliders +- **Graphics**: Quality, particles, fps +- **Gameplay**: Hints, grid, tutorials +- **Account**: Profile, sync, logout +- **Language**: 10+ languages +- **Accessibility**: Colorblind modes, contrast + +### 3.10 Profile/Stats Screen +**Purpose**: Player progression and achievements + +**Sections**: +- Avatar and username +- Level/XP progress bar +- Statistics dashboard +- Achievement showcase +- Play style analysis (AI-generated) +- Friends list and comparisons + +--- + +## 4. Gameplay Mechanics + +### 4.1 Core Mechanics + +#### Gravity Manipulation +- **Default**: Standard downward gravity +- **Adjustable**: 8-directional gravity control +- **Variable Strength**: 0% to 200% force +- **Localized Fields**: Area-specific gravity zones +- **Switching**: Real-time or turn-based modes + +#### Object Types +1. **Basic Ball**: Standard physics object +2. **Heavy Cube**: Increased mass, breaks weak platforms +3. **Balloon**: Negative mass, floats up +4. **Sticky Blob**: Adheres to surfaces +5. **Ghost Orb**: Phases through certain materials +6. **Energy Sphere**: Powers mechanisms +7. **Ice Cube**: Slippery, melts over time +8. **Magnetic Ball**: Attracted/repelled by fields + +#### Interactive Elements +1. **Platforms**: + - Static: Immovable + - Moving: Predetermined paths + - Rotating: Continuous or triggered + - Breakable: Limited durability + - Spring: Bounces objects + - Conveyor: Moves objects along surface + +2. **Obstacles**: + - Spikes: Instant failure + - Lasers: Timed hazards + - Black Holes: Gravitational pull + - Force Fields: Blocks certain objects + - Crushers: Moving hazards + - Portals: Teleportation + +3. **Mechanisms**: + - Switches: Activate platforms + - Pressure Plates: Weight-activated + - Logic Gates: Puzzle elements + - Timers: Countdown mechanics + - Collectors: Gather specific objects + - Generators: Create objects + +### 4.2 Advanced Mechanics + +#### Physics Modifiers +- **Time Dilation**: Slow/fast motion zones +- **Density Shift**: Change object mass +- **Phase Shift**: Toggle solid/ghost state +- **Magnetic Fields**: Attraction/repulsion +- **Wind Zones**: Directional force +- **Liquid Areas**: Buoyancy physics +- **Quantum Split**: Objects in multiple states + +#### Combo System +- Chain reactions score multipliers +- Speed bonuses for quick solutions +- Style points for creative solutions +- Perfect runs unlock special rewards + +--- + +## 5. Visual Design Specifications + +### 5.1 Art Style +**Overall Direction**: Clean, modern, scientific aesthetic with playful elements + +**Color Palette**: +- **Primary**: Electric blue (#00A8FF) +- **Secondary**: Plasma purple (#8B5CF6) +- **Accent**: Energy yellow (#FFD93D) +- **Success**: Quantum green (#10B981) +- **Danger**: Radiation red (#EF4444) +- **Neutral**: Lab grey (#6B7280) + +### 5.2 Visual Effects + +#### Particle Systems +1. **Impact Particles**: + - 20-30 particles per collision + - Size: 2-8 pixels + - Lifetime: 0.5-1.5 seconds + - Physics-based movement + +2. **Trail Effects**: + - Continuous emission + - Fade over 2 seconds + - Color based on object type + - Distortion effects for fast objects + +3. **Success Celebrations**: + - 100+ particles + - Firework patterns + - Screen flash (optional) + - Confetti physics + +#### Shader Effects +- **Gravity Distortion**: Warping effect near strong fields +- **Portal Ripples**: Water-like distortion +- **Energy Glow**: Bloom effect on powered objects +- **Heat Haze**: For fire/laser elements +- **Holographic**: For UI elements + +### 5.3 Animation Standards + +#### UI Animations +- **Button Press**: Scale to 95%, return with bounce +- **Screen Transitions**: 0.3s slide with ease-in-out +- **Menu Elements**: Stagger animation, 0.05s delay +- **Loading**: Continuous rotation with pulse +- **Success**: Scale burst from center + +#### Gameplay Animations +- **Object Spawn**: Scale from 0 with rotation +- **Collection**: Spiral into collector +- **Destruction**: Explode into particles +- **Portal Travel**: Squeeze and stretch +- **Victory**: All objects celebrate + +--- + +## 6. User Interface Design + +### 6.1 Design Principles +- **Clarity**: Information hierarchy +- **Consistency**: Unified design language +- **Responsiveness**: Immediate feedback +- **Accessibility**: High contrast options +- **Delight**: Micro-interactions + +### 6.2 Typography +- **Headers**: Orbitron Bold +- **Body**: Roboto Regular +- **Numbers**: Roboto Mono +- **Special**: Custom LCD font for timers + +### 6.3 Iconography +- Line-based icons (2px stroke) +- Consistent 24x24 base grid +- Animated states for all icons +- Color coding for quick recognition + +### 6.4 Responsive Layout +- Support phones (5" to 7") +- Tablet optimization (7" to 13") +- Aspect ratios: 16:9 to 21:9 +- Safe areas for notches +- Landscape/portrait modes + +--- + +## 7. Physics Systems + +### 7.1 Physics Engine Configuration +```dart +class PhysicsConfig { + static const double gravity = 9.81; + static const double airResistance = 0.02; + static const double bounciness = 0.7; + static const double friction = 0.3; + static const int solverIterations = 10; + static const double timeStep = 1/60; +} +``` + +### 7.2 Collision Detection +- Continuous collision detection for fast objects +- Separate layers for different object types +- Trigger zones for non-physical interactions +- Compound colliders for complex shapes + +### 7.3 Performance Optimization +- Object pooling for particles +- LOD system for complex simulations +- Spatial partitioning for collision checks +- Sleep mode for static objects + +--- + +## 8. Progression Systems + +### 8.1 Player Leveling +- **XP Sources**: + - Level completion: 100 XP + - Three stars: +50 XP bonus + - First try: +25 XP bonus + - Speed bonus: Up to +50 XP + - Daily challenges: 200 XP + +- **Level Rewards**: + - Every 5 levels: New avatar frame + - Every 10 levels: Exclusive skin + - Every 25 levels: Premium currency + - Level 100: Prestige option + +### 8.2 Unlock System +- Linear progression within worlds +- Star requirements for world unlocks +- Optional levels with special requirements +- Secret levels with hidden entrances + +### 8.3 Achievement Categories +1. **Progression**: Complete X levels +2. **Skill**: Perfect runs, speed records +3. **Discovery**: Find secrets +4. **Creative**: Level editor milestones +5. **Social**: Multiplayer victories + +--- + +## 9. AI Features + +### 9.1 Dynamic Hint System +```dart +class AIHintEngine { + // Analyzes player's attempts + List playerHistory; + + // Generates contextual hints + Hint generateHint() { + // ML model analyzes failure patterns + // Returns appropriate hint level + // Never spoils the solution + } +} +``` + +### 9.2 Procedural Level Generation +- **Input Parameters**: + - Difficulty rating + - Available elements + - Theme constraints + - Player skill level + +- **Validation Process**: + - AI solves generated level + - Checks multiple solution paths + - Balances difficulty curve + - Ensures fairness + +### 9.3 Adaptive Difficulty +- Monitors completion rates +- Adjusts level parameters +- Provides optional easier variants +- Maintains engagement flow + +### 9.4 AI Opponents +- **Speedster**: Optimizes for time +- **Perfectionist**: Minimal moves +- **Creative**: Unusual solutions +- **Learner**: Adapts to player style + +--- + +## 10. Monetization Features + +### 10.1 Premium Currency +- **Quantum Coins**: Premium currency +- **Energy Points**: Earned through play + +### 10.2 Revenue Streams +1. **Remove Ads**: $2.99 one-time +2. **Coin Packs**: $0.99 - $99.99 +3. **Season Pass**: $4.99/month +4. **Cosmetic Items**: $0.99 - $4.99 +5. **Power-up Packs**: $1.99 - $9.99 + +### 10.3 Ad Integration +- **Rewarded Videos**: + - Extra hints + - Continue after failure + - Double XP for 30 minutes + - Free daily power-up + +- **Interstitials**: + - Every 5 levels (skippable) + - Not during gameplay + - Frequency capping + +### 10.4 Season Pass Content +- 50 tiers of rewards +- Free and premium tracks +- Exclusive skins and effects +- Early access to new worlds +- Monthly refresh + +--- + +## 11. Technical Specifications + +### 11.1 Platform Requirements + +#### Android +- Minimum API: 21 (Android 5.0) +- Target API: 34 (Android 14) +- RAM: 2GB minimum, 4GB recommended +- Storage: 150MB initial, 500MB full + +#### iOS +- Minimum: iOS 12.0 +- Devices: iPhone 6S and newer +- iPad: All models from 2015+ +- Storage: Same as Android + +### 11.2 Performance Targets +- **Frame Rate**: 60 FPS (30 FPS minimum) +- **Load Times**: <3 seconds per level +- **Battery Life**: <10% drain per hour +- **Network**: Playable offline +- **Memory**: <500MB RAM usage + +### 11.3 Backend Services +- **Firebase**: Analytics, crash reporting +- **PlayFab**: Leaderboards, cloud saves +- **RevenueCat**: IAP management +- **Sentry**: Error tracking +- **Cloudflare**: CDN for assets + +### 11.4 Security Measures +- SSL pinning for API calls +- Encrypted local storage +- Anti-cheat for leaderboards +- Purchase validation +- COPPA compliance + +--- + +## 12. Audio Specifications + +### 12.1 Music Tracks +1. **Main Theme**: Upbeat electronic (2:30) +2. **World Themes**: 6 unique tracks (3:00 each) +3. **Victory Fanfare**: Short celebration (0:05) +4. **Shop Music**: Calm ambient (loop) +5. **Editor Music**: Focus/concentration (loop) + +### 12.2 Sound Effects + +#### UI Sounds +- Button tap: Soft click (0.1s) +- Menu transition: Whoosh (0.3s) +- Purchase success: Coin drop (0.5s) +- Error: Subtle buzz (0.2s) + +#### Gameplay Sounds +- Object collision: Material-based +- Gravity switch: Warping effect +- Portal entry/exit: Dimensional shift +- Success: Chimes cascade +- Failure: Deflating sound + +### 12.3 Audio Implementation +- 3D spatial audio for objects +- Dynamic mixing based on action +- Compressed formats for mobile +- Separate volume controls +- Haptic feedback sync + +--- + +## Implementation Priorities + +### Phase 1: MVP (Weeks 1-4) +1. Core physics engine +2. 20 tutorial levels +3. Basic UI/UX +4. Essential sound effects +5. Analytics integration + +### Phase 2: Enhancement (Weeks 5-8) +1. All 5 worlds (100 levels) +2. Progression system +3. Visual polish +4. AI hint system +5. Monetization + +### Phase 3: Social (Weeks 9-12) +1. Level editor +2. Multiplayer modes +3. Leaderboards +4. Season pass +5. Community features + +--- + +## Success Metrics + +### Launch Targets +- **Day 1 Retention**: 50% +- **Day 7 Retention**: 25% +- **Day 30 Retention**: 15% +- **Average Session**: 20 minutes +- **Store Rating**: 4.5+ stars + +### Revenue Targets +- **ARPU**: $1.50 +- **Conversion**: 5% paying users +- **Ad Revenue**: $0.02 per user/day +- **Season Pass**: 2% adoption + +--- + +## Conclusion + +This specification outlines the complete transformation of Moinsen Physics into Gravity Lab. The focus is on creating an engaging, visually stunning, and intelligently designed physics puzzle game that stands out in the mobile gaming market while showcasing advanced Flutter development and AI integration capabilities. + +The modular design allows for iterative development, ensuring we can launch an MVP quickly while building towards the full vision. Each system is designed to enhance player engagement while maintaining fair monetization practices. + +--- + +**Document Version**: 1.0 +**Last Updated**: May 2024 +**Next Review**: Post-MVP Launch +**Approval Status**: Pending \ No newline at end of file diff --git a/ios/Podfile b/ios/Podfile index d97f17e..0736413 100644 --- a/ios/Podfile +++ b/ios/Podfile @@ -1,5 +1,5 @@ # Uncomment this line to define a global platform for your project -# platform :ios, '12.0' +platform :ios, '14.5' # CocoaPods analytics sends network stats synchronously affecting flutter build latency. ENV['COCOAPODS_DISABLE_STATS'] = 'true' diff --git a/ios/Podfile.lock b/ios/Podfile.lock index ec5e2b0..3518bb5 100644 --- a/ios/Podfile.lock +++ b/ios/Podfile.lock @@ -1,9 +1,9 @@ PODS: - Flutter (1.0.0) - - flutter_sound (9.16.3): + - flutter_sound (9.28.0): - Flutter - - flutter_sound_core (= 9.16.3) - - flutter_sound_core (9.16.3) + - flutter_sound_core (= 9.28.0) + - flutter_sound_core (9.28.0) - path_provider_foundation (0.0.1): - Flutter - FlutterMacOS @@ -32,11 +32,11 @@ EXTERNAL SOURCES: SPEC CHECKSUMS: Flutter: e0871f40cf51350855a761d2e70bf5af5b9b5de7 - flutter_sound: d9c7b35b2f19366439a74695d190d9a504a6b4fe - flutter_sound_core: 2c5d7e93183845b53a776d99c4d6ebc2933ec495 - path_provider_foundation: 2b6b4c569c0fb62ec74538f866245ac84301af46 - permission_handler_apple: 9878588469a2b0d0fc1e048d9f43605f92e6cec2 + flutter_sound: b9236a5875299aaa4cef1690afd2f01d52a3f890 + flutter_sound_core: 427465f72d07ab8c3edbe8ffdde709ddacd3763c + path_provider_foundation: 080d55be775b7414fd5a5ef3ac137b97b097e564 + permission_handler_apple: 4ed2196e43d0651e8ff7ca3483a069d469701f2d -PODFILE CHECKSUM: 819463e6a0290f5a72f145ba7cde16e8b6ef0796 +PODFILE CHECKSUM: d713b6b659a24d596f461d32412ab1f8a1a74182 COCOAPODS: 1.16.2 diff --git a/ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme b/ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme index 8e3ca5d..e3773d4 100644 --- a/ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme +++ b/ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme @@ -26,6 +26,7 @@ buildConfiguration = "Debug" selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB" selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB" + customLLDBInitFile = "$(SRCROOT)/Flutter/ephemeral/flutter_lldbinit" shouldUseLaunchSchemeArgsEnv = "YES"> From 84098b3f1a04f6cc01aae87ca9be8474aa83ffb1 Mon Sep 17 00:00:00 2001 From: Ulrich Diedrichsen Date: Sat, 14 Jun 2025 14:05:47 +0200 Subject: [PATCH 6/6] feat: Add comprehensive implementation roadmap for Gravity Lab game development - Introduced detailed implementation roadmap outlining tasks and timelines for transitioning from Newton's Cradle to a full physics puzzle game. - Structured the project into core gameplay, UI implementation, content creation, and testing phases. - Defined technical debt, risk mitigation strategies, and success metrics for project evaluation. docs: Outline next steps after design phase for Gravity Lab - Documented integration actions following PR #2 completion. - Listed completed tasks and current dependencies. - Detailed to-do items based on new design documents, including theme updates, screen implementations, and physics enhancements. docs: Create screen design specifications for Gravity Lab - Developed a visual mockup and detailed UI/UX guide for all screens in the game. - Included layout designs, animation sequences, and interactive elements for each screen. - Established implementation priority guide for core and advanced screens. docs: Establish visual design system for Gravity Lab - Compiled a complete visual design system for Flutter implementation. - Defined color palettes, typography, component library, animation standards, and responsive design guidelines. - Included shader effects and loading states for enhanced visual feedback. --- CLAUDE.md | 227 ++++++---- docs/design/README.md | 144 +++++++ docs/design/gameplay-mechanics-detailed.md | 425 +++++++++++++++++++ docs/design/implementation-roadmap.md | 296 +++++++++++++ docs/design/next-steps.md | 192 +++++++++ docs/design/screen-design-specs.md | 412 ++++++++++++++++++ docs/design/visual-design-system.md | 471 +++++++++++++++++++++ 7 files changed, 2090 insertions(+), 77 deletions(-) create mode 100644 docs/design/README.md create mode 100644 docs/design/gameplay-mechanics-detailed.md create mode 100644 docs/design/implementation-roadmap.md create mode 100644 docs/design/next-steps.md create mode 100644 docs/design/screen-design-specs.md create mode 100644 docs/design/visual-design-system.md diff --git a/CLAUDE.md b/CLAUDE.md index b5c7220..9ad12b9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,19 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -**Moinsen Physics** is a Flutter-based physics simulation app featuring a Newton's Cradle implementation. The project uniquely demonstrates dual physics approaches: pure Dart calculations and the Forge2D physics engine. +**Gravity Lab** (transforming from Moinsen Physics) is a Flutter-based physics puzzle game where players manipulate gravity to solve challenging puzzles. The game features realistic physics simulation using Forge2D, creative level design across 6 themed worlds, and a clean architecture approach. + +## Design Documentation + +Comprehensive design documents are available in `docs/design/`: +- `gravity-lab-feature-spec.md` - Complete game design document +- `ui-ux-design.md` - Visual design, color schemes, and UI patterns +- `level-design-guide.md` - Level creation principles and mechanics +- `tutorial-system-design.md` - Progressive learning system +- `world-themes-design.md` - Detailed world and level progression +- `physics-system-design.md` - Core physics implementation details +- `monetization-strategy.md` - Revenue model and pricing +- `technical-architecture.md` - Clean architecture implementation ## Development Commands @@ -22,104 +34,165 @@ flutter build ios # iOS release flutter build web # Web release # Testing -flutter test # Run all tests +flutter test # Run all tests flutter test test/screenshot_test.dart --update-goldens # Update golden files ``` ## Architecture -### Dual Physics Implementation -The app implements Newton's Cradle using two distinct approaches: +### Clean Architecture Structure +The project follows clean architecture principles with clear separation of concerns: -1. **Pure Dart** (`lib/newton_cradle/plain_dart/`): Custom physics with manual collision detection -2. **Forge2D** (`lib/newton_cradle/forge2d/`): Box2D physics engine integration +``` +lib/ +โ”œโ”€โ”€ core/ # Shared utilities and constants +โ”‚ โ”œโ”€โ”€ physics/ # Physics constants and helpers +โ”‚ โ”œโ”€โ”€ theme/ # App theming and colors +โ”‚ โ””โ”€โ”€ utils/ # Common utilities +โ”œโ”€โ”€ data/ # Data layer +โ”‚ โ”œโ”€โ”€ repositories/ # Data repositories +โ”‚ โ””โ”€โ”€ models/ # Data models +โ”œโ”€โ”€ domain/ # Business logic +โ”‚ โ”œโ”€โ”€ entities/ # Core entities +โ”‚ โ”œโ”€โ”€ repositories/ # Repository interfaces +โ”‚ โ””โ”€โ”€ use_cases/ # Business logic +โ”œโ”€โ”€ presentation/ # UI layer +โ”‚ โ”œโ”€โ”€ screens/ # Screen widgets +โ”‚ โ”œโ”€โ”€ widgets/ # Reusable widgets +โ”‚ โ””โ”€โ”€ providers/ # State management +โ””โ”€โ”€ features/ # Feature modules + โ”œโ”€โ”€ game_engine/ # Flame/Forge2D integration + โ”œโ”€โ”€ level_editor/ # Level creation tools + โ””โ”€โ”€ tutorial/ # Tutorial system +``` ### Key Components -- **Controllers**: Physics simulation logic in `newton_cradle_controller.dart` -- **Game Engine**: Flame-based implementation in `newton_cradle_game.dart` -- **UI Controls**: Simulation parameters in `controls/simulation_controls.dart` -- **Sound System**: Velocity-based audio feedback with platform-specific handling +- **Game Engine**: Flame + Forge2D for physics simulation +- **State Management**: Riverpod for app state +- **Audio System**: Flutter Sound with dynamic collision-based effects +- **Level System**: JSON-based level definitions with physics parameters +- **Visual Effects**: Particle systems and animations ### Dependencies -- **Flame + Forge2D**: Game engine and physics -- **Riverpod**: State management -- **Flutter Sound**: Audio with collision-based dynamics -- **Golden Toolkit**: Screenshot testing framework - -## Testing Setup +- **Game Engine**: `flame` + `flame_forge2d` for physics +- **State**: `flutter_riverpod` for state management +- **Audio**: `flutter_sound` with permission handling +- **Testing**: `golden_toolkit` for visual regression +- **Analytics**: `firebase_analytics` (future implementation) + +## Game Development Guidelines + +### Physics Implementation +- **Forge2D Integration**: Use Box2D physics for realistic simulation +- **Gravity System**: 8-directional gravity with smooth transitions +- **Object Types**: Standard, Heavy, Light, Bouncy, Sticky, Fragile, Magnetic, Portal +- **Performance**: Target 60 FPS with efficient collision detection + +### Level Design +- **Structure**: JSON-based level definitions in `assets/levels/` +- **Progression**: 6 worlds ร— 20 levels = 120 total levels +- **Difficulty**: Progressive difficulty with star-based scoring +- **Testing**: Each level must be completable within time limits + +### Visual Standards +- **Theme**: Modern, clean with physics-inspired aesthetics +- **Colors**: World-specific palettes (see `docs/design/ui-ux-design.md`) +- **Animations**: Smooth transitions, particle effects for interactions +- **Accessibility**: High contrast mode, colorblind-friendly options + +## Testing Strategy + +### Unit Tests +- Physics calculations and gravity mechanics +- Level loading and validation +- Score calculation algorithms + +### Widget Tests +- UI component behavior +- Screen navigation flows +- Control responsiveness ### Golden Tests -Comprehensive screenshot testing across multiple device configurations: -- Android: Smartphone, 7" tablet, 10" tablet -- iOS: iPhone 6.5", iPhone 6.9", iPad Pro 12.9" -- Test files: `test/screenshot_test.dart`, goldens in `test/goldens/` - -### Sound Integration -- Disabled for web and test environments -- Asset-based (`assets/sounds/click.wav`) -- Dynamic volume/pitch based on collision physics - -## Code Organization +- Visual regression across devices: + - Android: Phone, 7" tablet, 10" tablet + - iOS: iPhone 6.5", 6.9", iPad Pro 12.9" +- Run with: `flutter test test/screenshot_test.dart --update-goldens` -### Generated Exports -Uses `_index.dart` files for clean module exports (generated by "Moinsen Flutter" tool). - -### Performance Features -- 60 FPS animation controller -- Efficient collision detection algorithms -- Memory-conscious resource management -- Platform-optimized rendering +### Integration Tests +- Full gameplay flow +- Level completion mechanics +- Save/load functionality ## Development Workflow -### GitHub Integration -- **Primary workflow**: GitHub Issues and Pull Requests -- **GitHub CLI**: Use `gh` command for issue and PR management -- **Current work**: Pull Request #2 - "feat: Initial setup for Gravity Lab transformation" - - Implementing comprehensive feature specification from `docs/gravity-lab-feature-spec.md` - - Transforming Moinsen Physics into Gravity Lab physics puzzle game - - Modern Flutter architecture with clean code principles - - **FREE GAME**: No monetization, no Firebase, no ads - pure physics puzzle experience - ### Git Workflow - **Main branch**: `develop` -- **Current feature branch**: `feat/game-design` +- **Feature branches**: `feat/feature-name` +- **Release branches**: `release/version` +- **Hotfix branches**: `hotfix/issue-name` -### GitHub Commands +### GitHub Integration ```bash -# View current PR -gh pr view 2 - -# Create new issue -gh issue create --title "Feature Title" --body "Description" - -# List issues -gh issue list +# Current work context +gh pr view 2 # View current PR -# Create PR from current branch -gh pr create --title "PR Title" --body "Description" +# Issue management +gh issue create --title "Title" --body "Description" +gh issue list --label "bug" -# Review PR status +# PR workflow +gh pr create --title "Title" --body "Description" gh pr status ``` -## Current Implementation Focus - -### Feature Specification -Follow the comprehensive feature spec in `docs/gravity-lab-feature-spec.md` which outlines: -- **Game Concept**: Physics puzzle game with gravity manipulation -- **6 Themed Worlds**: Newton's Lab, Zero-G Station, Aqua Depths, Magnetic Factory, Time Nexus, Quantum Realm -- **Core Mechanics**: 8-directional gravity control, 8 object types, interactive elements -- **Clean Architecture**: Domain/Data/Presentation layers with feature modules -- **Advanced Physics**: Forge2D integration, particle effects, collision systems - -### Implementation Phases -1. **Phase 1 (MVP)**: Core physics engine, 20 tutorial levels, basic UI -2. **Phase 2**: All 5 worlds (100 levels), progression system, visual polish -3. **Phase 3**: Level editor, community features, advanced mechanics - -### Key Design Principles -- **Free Game**: No monetization, ads, or Firebase -- **Physics-First**: Realistic gravity manipulation and object interactions -- **Visual Delight**: Particle effects, smooth animations, modern UI -- **Accessibility**: High contrast options, multiple control schemes \ No newline at end of file +### Code Standards +- **Exports**: Use `_index.dart` files for clean module exports +- **Naming**: Follow Flutter conventions (lowerCamelCase, UpperCamelCase) +- **Documentation**: Document complex physics calculations +- **Performance**: Profile regularly, optimize draw calls + +## Performance Optimization + +### Key Metrics +- **Target FPS**: 60 on all supported devices +- **Load Time**: < 3 seconds for app start +- **Level Load**: < 500ms per level +- **Memory**: < 150MB runtime usage + +### Optimization Strategies +- Efficient sprite batching +- Object pooling for particles +- Lazy loading of world assets +- Physics body sleeping for inactive objects + +## Monetization Implementation + +### Revenue Streams +- **Ads**: Rewarded videos for hints/retries +- **IAP**: Hint packs, world unlocks, cosmetics +- **Season Pass**: Monthly content updates +- **Remove Ads**: One-time purchase option + +### Implementation Notes +- Use `in_app_purchase` package for IAP +- `google_mobile_ads` for ad integration +- Server validation for purchases +- Offline play capability maintained + +## Current Development Status + +### Completed +- Basic project structure +- Core physics engine setup +- Initial UI framework + +### In Progress (PR #2) +- Clean architecture implementation +- Game engine integration +- Level system foundation + +### Upcoming +- Tutorial system implementation +- First world levels (Newton's Lab) +- Visual polish and effects +- Sound system enhancement \ No newline at end of file diff --git a/docs/design/README.md b/docs/design/README.md new file mode 100644 index 0000000..faa11f4 --- /dev/null +++ b/docs/design/README.md @@ -0,0 +1,144 @@ +# Gravity Lab Design Documentation +## Summary of New Design Documents + +**Created:** May 2024 +**Author:** Ulrich Diedrichsen / Moinsen Dev +**Purpose:** Comprehensive design documentation for Gravity Lab transformation + +--- + +## ๐Ÿ“ New Documents Created + +### 1. **screen-design-specs.md** +- Detailed mockups for all 10 game screens +- ASCII art layouts for visual reference +- Interactive element specifications +- Animation sequences and transitions +- Implementation priority guide + +### 2. **gameplay-mechanics-detailed.md** +- Core gameplay loop definition +- 8 physics object types with properties +- Gravity manipulation system details +- Level design principles +- Scoring and progression systems +- Tutorial and hint systems + +### 3. **visual-design-system.md** +- Complete Flutter design system +- Color palette with hex values +- Typography specifications +- Reusable component library +- Animation standards +- Shader effects for visual polish + +### 4. **implementation-roadmap.md** +- 10-week development timeline +- Migration strategy from Newton's Cradle +- Technical architecture changes +- Testing and launch checklist +- Risk mitigation strategies +- Success metrics + +--- + +## ๐ŸŽฏ Key Design Decisions + +### Game Concept +- **Name**: Gravity Lab: Physics Puzzles +- **Core Mechanic**: 8-directional gravity manipulation +- **Unique Features**: AI-powered hints, procedural levels +- **Target Audience**: Puzzle enthusiasts, casual gamers +- **Monetization**: FREE (no ads, no IAP) + +### Visual Identity +- **Theme**: Clean, scientific, playful +- **Colors**: Electric blue, plasma purple, energy yellow +- **Style**: Modern with particle effects +- **UI**: Material Design 3 inspired +- **Animations**: 60 FPS smooth physics + +### Technical Approach +- **Engine**: Forge2D (already implemented) +- **Architecture**: Feature-based modules +- **State Management**: Riverpod +- **Performance**: Object pooling, LOD +- **Platforms**: Android, iOS, Web + +--- + +## ๐Ÿš€ Next Steps + +1. **Review** all design documents with team +2. **Approve** visual design direction +3. **Prioritize** feature implementation +4. **Begin** Week 1 of roadmap +5. **Create** GitHub issues for tasks + +--- + +## ๐Ÿ“‹ Document Locations + +All design documents are located in: +``` +/Users/udi/work/moinsen/opensource/moinsen_physics/docs/design/ +โ”œโ”€โ”€ screen-design-specs.md +โ”œโ”€โ”€ gameplay-mechanics-detailed.md +โ”œโ”€โ”€ visual-design-system.md +โ””โ”€โ”€ implementation-roadmap.md +``` + +Original feature specification: +``` +/Users/udi/work/moinsen/opensource/moinsen_physics/docs/ +โ””โ”€โ”€ gravity-lab-feature-spec.md +``` + +--- + +## ๐Ÿ’ก Design Highlights + +### Screens (10 Total) +1. Splash Screen - Particle effects +2. Main Menu - Interactive physics +3. World Selection - 6 themed worlds +4. Level Selection - Hexagonal grid +5. Gameplay - Core puzzle interface +6. Victory - Celebration animations +7. Settings - Comprehensive options +8. Profile/Stats - Progress tracking +9. Level Editor - User content +10. Shop - Cosmetics only (FREE game) + +### Physics Objects (8 Types) +1. ๐ŸŸข Basic Ball - Standard physics +2. ๐ŸŸฆ Heavy Cube - Breaks platforms +3. ๐ŸŽˆ Balloon - Negative mass +4. ๐ŸŸฃ Sticky Blob - Adheres to surfaces +5. ๐Ÿ‘ป Ghost Orb - Phase through materials +6. โšก Energy Sphere - Powers mechanisms +7. ๐ŸงŠ Ice Cube - Slippery, melts +8. ๐Ÿงฒ Magnetic Ball - Attraction/repulsion + +### Worlds (6 Themes) +1. Newton's Laboratory - Tutorial +2. Zero-G Station - Space physics +3. Aqua Depths - Underwater +4. Magnetic Factory - Electromagnetic +5. Time Nexus - Time manipulation +6. Quantum Realm - Probability + +--- + +## ๐Ÿ“ Design Philosophy + +The design focuses on creating an engaging, visually stunning physics puzzle game that: +- Builds upon the existing Newton's Cradle foundation +- Showcases Flutter's capabilities +- Provides hours of challenging gameplay +- Remains accessible to all players (FREE) +- Demonstrates Moinsen Dev's expertise + +--- + +**Ready to transform Moinsen Physics into Gravity Lab!** ๐Ÿš€ \ No newline at end of file diff --git a/docs/design/gameplay-mechanics-detailed.md b/docs/design/gameplay-mechanics-detailed.md new file mode 100644 index 0000000..81ba8a2 --- /dev/null +++ b/docs/design/gameplay-mechanics-detailed.md @@ -0,0 +1,425 @@ +# Gravity Lab - Enhanced Gameplay Mechanics +## Detailed Game Design Document + +**Version:** 1.0 +**Date:** May 2024 +**Focus:** Core gameplay loop, physics interactions, and level design + +--- + +## 1. Core Gameplay Loop + +### Basic Flow +``` +Start Level โ†’ Analyze Puzzle โ†’ Plan Solution โ†’ Execute Actions โ†’ + โ†“ โ†“ + โ†“ Success? โ†’ Victory! + โ†“ โ†“ + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ Retry with Learning โ†โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ Failure โ†โ”˜ +``` + +### Player Actions Per Turn +1. **Observe** current state +2. **Adjust** gravity direction (optional) +3. **Activate** special tools (optional) +4. **Release** objects or triggers +5. **Watch** physics simulation +6. **Learn** from result + +--- + +## 2. Gravity Manipulation System + +### Gravity States +``` + โ†‘ (0ยฐ) + โ†– โ†‘ โ†— + โ•ฒ โ”‚ โ•ฑ + โ† โ”โ”โ” โŠ• โ”โ”โ” โ†’ (90ยฐ/270ยฐ) + โ•ฑ โ”‚ โ•ฒ + โ†™ โ†“ โ†˜ + โ†“ (180ยฐ) +``` + +### Gravity Strength Levels +- **Zero-G** (0%): Objects float +- **Low** (25%): Moon gravity +- **Normal** (100%): Earth gravity +- **High** (150%): Heavy gravity +- **Extreme** (200%): Crushing force + +### Advanced Gravity Features +1. **Gravity Wells**: Localized gravity points +2. **Gravity Waves**: Oscillating fields +3. **Gravity Shields**: Null zones +4. **Gravity Streams**: Directional flows + +--- + +## 3. Physics Objects - Detailed Behaviors + +### ๐ŸŸข Basic Ball +```dart +class BasicBall { + mass: 1.0 + bounciness: 0.7 + friction: 0.3 + special: none + + behavior: "Standard physics object" +} +``` + +### ๐ŸŸฆ Heavy Cube +```dart +class HeavyCube { + mass: 5.0 + bounciness: 0.1 + friction: 0.8 + special: "Breaks weak platforms" + + interaction: "Activates heavy switches" +} +``` + +### ๐ŸŽˆ Balloon +```dart +class Balloon { + mass: -0.5 // Negative mass! + bounciness: 0.9 + friction: 0.1 + special: "Always floats up" + + mechanic: "Pops on spikes" +} +``` + +### ๐ŸŸฃ Sticky Blob +```dart +class StickyBlob { + mass: 2.0 + bounciness: 0.0 + friction: 10.0 + special: "Sticks to surfaces" + + usage: "Create bridges, hold objects" +} +``` + +### ๐Ÿ‘ป Ghost Orb +```dart +class GhostOrb { + mass: 0.5 + bounciness: 0.5 + friction: 0.0 + special: "Phases through specific materials" + + phases_through: ["wood", "glass"] + blocked_by: ["metal", "energy"] +} +``` + +### โšก Energy Sphere +```dart +class EnergySphere { + mass: 1.0 + bounciness: 1.0 // Perfect bounce! + friction: 0.0 + special: "Powers mechanisms" + + charge: 100 + discharge_rate: 10/second +} +``` + +### ๐ŸงŠ Ice Cube +```dart +class IceCube { + mass: 0.8 + bounciness: 0.3 + friction: 0.05 // Very slippery! + special: "Melts over time" + + melt_time: 30_seconds + leaves_water: true +} +``` + +### ๐Ÿงฒ Magnetic Ball +```dart +class MagneticBall { + mass: 3.0 + bounciness: 0.4 + friction: 0.5 + special: "Magnetic properties" + + polarity: "north" | "south" + field_strength: 5.0 + attraction_range: 100_pixels +} +``` + +--- + +## 4. Interactive Elements Details + +### Platform Types + +#### Static Platform +- Immovable obstacle +- Can have different materials +- May have special properties + +#### Moving Platform +``` +Path Types: +- Linear: A โ†โ†’ B +- Circular: Rotation +- Custom: Bezier curves +- Triggered: Player activated +``` + +#### Breakable Platform +``` +Durability Levels: +- Weak: 1 hit (any object) +- Medium: 2 hits or heavy object +- Strong: Only heavy objects +- Timed: Breaks after X seconds +``` + +#### Spring Platform +``` +Spring Properties: +- Force: 1x to 5x gravity +- Angle: Fixed or rotating +- Cooldown: Instant or delayed +- Visual: Compression animation +``` + +### Mechanism Types + +#### Switches +``` +Types: +- Toggle: On/Off state +- Hold: Must stay pressed +- Sequence: Specific order +- Timed: Limited activation +``` + +#### Portals +``` +Properties: +- Instant teleport +- Maintains momentum +- Can rotate objects +- Paired or network +``` + +#### Force Fields +``` +Types: +- Barrier: Blocks all +- Selective: Filters objects +- One-way: Directional +- Timed: Periodic on/off +``` + +--- + +## 5. Level Design Principles + +### Difficulty Progression +``` +World 1 (Tutorial): Single mechanic per level +World 2 (Easy): Combine 2 mechanics +World 3 (Medium): Timing elements added +World 4 (Hard): Multiple solutions required +World 5 (Expert): Precision and planning +World 6 (Master): All mechanics combined +``` + +### Level Structure Types + +#### Teaching Levels +- Introduce one new concept +- Safe environment +- Impossible to fail +- Visual hints everywhere + +#### Puzzle Levels +- Multiple objects +- Several steps required +- Red herrings included +- Hidden optimal solutions + +#### Action Levels +- Timing critical +- Moving platforms +- Quick gravity switches +- Reflex challenges + +#### Sandbox Levels +- Many possible solutions +- Extra objects provided +- Creativity rewarded +- No single correct path + +--- + +## 6. Scoring System + +### Base Score Calculation +``` +Base Score = 1000 +- (Time Taken ร— 10) +- (Moves Used ร— 50) ++ (Objects Collected ร— 100) ++ (Perfect Run Bonus: 500) +``` + +### Star Rating Criteria +- โญ Complete level +- โญโญ Under par time OR moves +- โญโญโญ Both under par + +### Leaderboard Categories +1. **Fastest Time** +2. **Fewest Moves** +3. **Highest Score** +4. **Most Creative** (community voted) + +--- + +## 7. Power-ups and Tools + +### Temporary Power-ups +1. **Slow Motion**: 5 seconds of 0.5x speed +2. **Ghost Mode**: Pass through one obstacle +3. **Magnet Boost**: Double magnetic strength +4. **Anti-Gravity**: Reverse all objects +5. **Freeze**: Pause physics for planning + +### Permanent Tools (Unlockable) +1. **Trajectory Preview**: See path before release +2. **Gravity Meter**: Precise strength control +3. **Object Scanner**: View hidden properties +4. **Solution Hint**: AI suggests direction +5. **Checkpoint**: Save mid-level progress + +--- + +## 8. Tutorial System + +### Progressive Disclosure +``` +Level 1: "Tap to change gravity" +Level 2: "Hold to see trajectory" +Level 3: "Some objects have special properties" +Level 4: "Timing matters" +Level 5: "Combine mechanics creatively" +``` + +### Visual Indicators +- Glowing highlights on interactive elements +- Arrow indicators for suggested actions +- Ghost preview of successful path +- Particle trails showing flow + +### Adaptive Hints +- First attempt: No hints +- Second attempt: Subtle visual cue +- Third attempt: Text hint appears +- Fourth+ attempt: Video solution option + +--- + +## 9. Challenge Modes + +### Daily Challenge +- One unique level per day +- Global leaderboard +- Special rewards +- Community solutions shared + +### Speed Run Mode +- Series of 5 levels +- Total time tracked +- No pauses allowed +- Mistakes add time penalty + +### Puzzle Rush +- Endless levels +- Increasing difficulty +- Lives system +- High score tracking + +### Creator Challenge +- Theme announced weekly +- Players create levels +- Community votes +- Winner gets featured + +--- + +## 10. Social Features + +### Ghost Mode +- See other players' solutions +- Race against ghosts +- Filter by friends/global +- Learn new strategies + +### Level Sharing +``` +Share Code Format: XXXX-XXXX-XXXX +- Encodes full level data +- Instant loading +- Rate after playing +- Report inappropriate content +``` + +### Collaborative Mode +- Two players, one level +- Split control (gravity vs objects) +- Requires coordination +- Special co-op achievements + +--- + +## Implementation Notes + +### Physics Engine Settings +```dart +const physicsConfig = { + 'gravity': 9.81, + 'timeStep': 1/60, + 'velocityIterations': 10, + 'positionIterations': 10, + 'maxVelocity': 1000, + 'sleepThreshold': 0.1, +}; +``` + +### Performance Optimizations +- Object pooling for particles +- Culling off-screen physics +- LOD for distant objects +- Simplified collision shapes +- Batch rendering similar objects + +--- + +## Next Steps + +1. Prototype core mechanics in Forge2D +2. Create 5 test levels per world +3. Implement basic scoring +4. Add tutorial overlays +5. Test with focus groups +6. Iterate based on feedback + +--- + +**Remember**: The goal is to create a physics puzzle game that's easy to understand but difficult to master, with enough variety to keep players engaged for hours! \ No newline at end of file diff --git a/docs/design/implementation-roadmap.md b/docs/design/implementation-roadmap.md new file mode 100644 index 0000000..c6a8ce2 --- /dev/null +++ b/docs/design/implementation-roadmap.md @@ -0,0 +1,296 @@ +# Gravity Lab - Implementation Roadmap +## From Newton's Cradle to Physics Puzzle Game + +**Version:** 1.0 +**Date:** May 2024 +**Timeline:** 10 weeks +**Current State:** Newton's Cradle simulation +**Target State:** Full Gravity Lab game + +--- + +## Week 1-2: Foundation & Architecture + +### Refactor Current Structure +``` +Current: Target: +lib/ lib/ +โ”œโ”€โ”€ newton_cradle/ โ†’ โ”œโ”€โ”€ core/ +โ”œโ”€โ”€ utils/ โ”‚ โ”œโ”€โ”€ physics/ +โ””โ”€โ”€ widgets/ โ”‚ โ”œโ”€โ”€ theme/ + โ”‚ โ””โ”€โ”€ utils/ + โ”œโ”€โ”€ features/ + โ”‚ โ”œโ”€โ”€ game/ + โ”‚ โ”œโ”€โ”€ menu/ + โ”‚ โ”œโ”€โ”€ levels/ + โ”‚ โ””โ”€โ”€ editor/ + โ””โ”€โ”€ shared/ + โ””โ”€โ”€ widgets/ +``` + +### Tasks +- [ ] Create new folder structure +- [ ] Extract physics engine to core +- [ ] Implement theme system +- [ ] Setup navigation framework +- [ ] Create basic screens scaffold + +### Code Migration Plan +```dart +// Move from newton_cradle_controller.dart +// To: core/physics/gravity_physics_engine.dart + +class GravityPhysicsEngine { + // Reuse existing Forge2D setup + // Add gravity manipulation + // Add new object types +} +``` + +--- + +## Week 3-4: Core Gameplay + +### Physics System Enhancement +```dart +// Extend current physics with: +class PhysicsObjectFactory { + static Body createBall() { /* existing */ } + static Body createCube() { /* new */ } + static Body createBalloon() { /* new */ } + static Body createSticky() { /* new */ } + // ... more object types +} + +class GravityController { + Vector2 currentGravity = Vector2(0, 9.81); + + void setGravityDirection(double angle) { + currentGravity = Vector2( + sin(angle) * 9.81, + cos(angle) * 9.81, + ); + } +} +``` + +### Level System +```dart +class Level { + final String id; + final List objects; + final List goals; + final Map properties; + + bool checkVictory() { + return goals.every((goal) => goal.isCompleted); + } +} +``` + +### Tasks +- [ ] Implement 8 physics object types +- [ ] Create gravity manipulation system +- [ ] Build level loading system +- [ ] Implement victory conditions +- [ ] Create first 10 tutorial levels + +--- + +## Week 5-6: UI Implementation + +### Screen Priority Order +1. **Splash Screen** (enhance existing) +2. **Main Menu** (new) +3. **Level Selection** (new) +4. **Gameplay HUD** (new) +5. **Victory Screen** (new) +6. **Settings** (new) + +### Reusable Components +```dart +// Extract from existing code and enhance +class PhysicsButton extends StatefulWidget { + // Add physics properties to buttons + // Reuse particle effects +} + +class AnimatedBackground extends StatelessWidget { + // Use existing wave animation + // Add starfield layer +} +``` + +### Tasks +- [ ] Implement all screens from design doc +- [ ] Create reusable UI components +- [ ] Add particle effects system +- [ ] Implement screen transitions +- [ ] Setup sound system + +--- + +## Week 7-8: Content & Polish + +### Level Creation Sprint +```yaml +World 1 - Newton's Laboratory: + - Levels 1-5: Basic gravity (existing mechanics) + - Levels 6-10: Multiple objects + - Levels 11-15: Moving platforms + - Levels 16-20: Combined mechanics + +World 2 - Zero-G Station: + - Levels 21-25: No gravity puzzles + - Levels 26-30: Gravity switches + - ... continue pattern +``` + +### Visual Polish +- [ ] Particle effects for all interactions +- [ ] Smooth animations (60 FPS) +- [ ] Visual feedback for all actions +- [ ] Loading screens between levels +- [ ] Background variations per world + +### Audio Implementation +```dart +// Enhance existing sound system +class AudioManager { + // Reuse click.wav for collisions + // Add new sounds: + // - gravity_switch.wav + // - victory.wav + // - background_music.mp3 +} +``` + +--- + +## Week 9-10: Testing & Launch + +### Testing Plan +1. **Performance Testing** + - Target 60 FPS on mid-range devices + - Memory usage under 200MB + - Load times under 2 seconds + +2. **Gameplay Testing** + - All 60 levels completable + - Difficulty curve validation + - Tutorial effectiveness + +3. **Device Testing** + - Android: API 21+ + - iOS: 12.0+ + - Various screen sizes + +### Launch Checklist +- [ ] Update app metadata +- [ ] Create screenshots +- [ ] Write store description +- [ ] Prepare promotional video +- [ ] Submit to Google Play +- [ ] Submit to App Store + +--- + +## Migration Strategy + +### Preserve Existing Features +```dart +// Keep Newton's Cradle as bonus mode +class BonusMode { + // Original Newton's Cradle + // Accessible from main menu + // "Classic Mode" or "Physics Sandbox" +} +``` + +### Progressive Enhancement +1. Keep existing physics engine +2. Add new features incrementally +3. Test each addition thoroughly +4. Maintain backwards compatibility + +--- + +## Technical Debt to Address + +### From Current Code Review +1. **Sound System**: Already disabled for web - needs proper platform handling +2. **Performance**: Optimize collision detection for multiple objects +3. **State Management**: Migrate to proper game state system +4. **Asset Loading**: Implement proper asset management + +### New Requirements +1. **Save System**: Player progress +2. **Analytics**: Basic gameplay metrics +3. **Error Handling**: Graceful failures +4. **Accessibility**: High contrast mode + +--- + +## Risk Mitigation + +### Identified Risks +1. **Scope Creep**: Stick to FREE game model +2. **Performance**: Start optimization early +3. **Content Creation**: 60 levels is ambitious +4. **Platform Issues**: Test early on both platforms + +### Mitigation Strategies +- MVP with 20 levels first +- Performance budget per frame +- Procedural level generation for variety +- Continuous integration testing + +--- + +## Success Metrics + +### Technical Goals +- [ ] 60 FPS on 90% of devices +- [ ] < 100MB app size +- [ ] < 2s level load time +- [ ] Zero crash rate + +### Gameplay Goals +- [ ] Average session > 10 minutes +- [ ] 50% of players complete World 1 +- [ ] 4.0+ star rating +- [ ] 10k downloads in first month + +--- + +## Daily Development Workflow + +### Morning +1. Review yesterday's progress +2. Check GitHub issues +3. Plan day's tasks +4. Update feature branch + +### Development +1. Implement feature +2. Test on device +3. Commit with clear message +4. Update documentation + +### Evening +1. Push changes +2. Update PR if needed +3. Note tomorrow's tasks +4. Check build status + +--- + +## Conclusion + +This roadmap transforms the existing Newton's Cradle demo into a full-featured physics puzzle game. By building on the solid foundation already in place and following the comprehensive design documents, Gravity Lab will showcase both Flutter's capabilities and innovative physics-based gameplay. + +The FREE game model ensures wide distribution while the quality implementation will establish Moinsen Dev's reputation for excellence in mobile game development. + +--- + +**Next Step**: Begin Week 1 tasks by creating the new folder structure and migrating existing physics code! \ No newline at end of file diff --git a/docs/design/next-steps.md b/docs/design/next-steps.md new file mode 100644 index 0000000..4a55aa0 --- /dev/null +++ b/docs/design/next-steps.md @@ -0,0 +1,192 @@ +# Gravity Lab - Next Steps After Design Phase +## Integration with PR #2 + +**Date:** May 2024 +**Current Status:** PR #2 has foundation, design docs complete +**Next Actions:** Implement design specifications + +--- + +## โœ… Already Completed (PR #2) + +### Structure +- Clean architecture setup โœ“ +- Feature modules created โœ“ +- Dependencies updated โœ“ +- Basic theme system โœ“ + +### Current Dependencies +```yaml +flutter: 3.3.2 +flame: ^1.29.0 +flame_forge2d: ^0.19.0+2 +flutter_riverpod: ^2.6.1 +``` + +--- + +## ๐Ÿ“‹ To Do - Based on New Design Docs + +### 1. Update Theme System +Replace basic theme with comprehensive design system from `visual-design-system.md`: + +```dart +// Replace current basic theme with: +- GravityLabColors class (complete palette) +- GravityLabTextStyles (Orbitron + Roboto) +- GradientStyles for UI elements +- Complete component library +``` + +### 2. Implement Screens +Based on `screen-design-specs.md`, create: + +``` +lib/features/ +โ”œโ”€โ”€ splash/ +โ”‚ โ””โ”€โ”€ presentation/ +โ”‚ โ””โ”€โ”€ screens/ +โ”‚ โ””โ”€โ”€ enhanced_splash_screen.dart +โ”œโ”€โ”€ menu/ +โ”‚ โ””โ”€โ”€ presentation/ +โ”‚ โ””โ”€โ”€ screens/ +โ”‚ โ”œโ”€โ”€ main_menu_screen.dart +โ”‚ โ””โ”€โ”€ settings_screen.dart +โ”œโ”€โ”€ levels/ +โ”‚ โ””โ”€โ”€ presentation/ +โ”‚ โ””โ”€โ”€ screens/ +โ”‚ โ”œโ”€โ”€ world_selection_screen.dart +โ”‚ โ”œโ”€โ”€ level_selection_screen.dart +โ”‚ โ””โ”€โ”€ victory_screen.dart +โ”œโ”€โ”€ game/ +โ”‚ โ””โ”€โ”€ presentation/ +โ”‚ โ””โ”€โ”€ screens/ +โ”‚ โ””โ”€โ”€ gameplay_screen.dart +โ””โ”€โ”€ editor/ + โ””โ”€โ”€ presentation/ + โ””โ”€โ”€ screens/ + โ””โ”€โ”€ level_editor_screen.dart +``` + +### 3. Enhance Physics System +From `gameplay-mechanics-detailed.md`: + +```dart +// Extend existing physics with: +- 8 object types (Ball, Cube, Balloon, etc.) +- Gravity manipulation (8-directional) +- Interactive elements (platforms, portals, etc.) +- Collision system enhancements +``` + +### 4. Create Level System +```dart +// New classes needed: +- Level (with goals, objects, victory conditions) +- LevelLoader (JSON/asset loading) +- LevelProgress (save system) +- World (collection of levels) +``` + +### 5. Add Visual Effects +```dart +// Particle systems: +- StarfieldBackground +- ExplosionEffect +- TrailRenderer +- GlowShader +- DistortionEffect +``` + +--- + +## ๐ŸŽฏ Implementation Order (Following Roadmap) + +### Week 1-2: Foundation Enhancement +1. Update theme system with new design tokens +2. Create reusable UI components +3. Implement navigation structure +4. Setup screen scaffolds + +### Week 3-4: Core Gameplay +1. Migrate Newton's Cradle physics to new system +2. Add 8 physics object types +3. Implement gravity manipulation +4. Create first 10 tutorial levels + +### Week 5-6: UI Polish +1. Implement all screens with animations +2. Add particle effects +3. Create sound system +4. Polish transitions + +### Week 7-8: Content Creation +1. Build 50 more levels (60 total) +2. Create 6 world themes +3. Add progression system +4. Implement achievements + +### Week 9-10: Testing & Launch +1. Performance optimization +2. Device testing +3. Play testing +4. Store submission + +--- + +## ๐Ÿ”ง Specific Tasks for Next PR + +### PR #3: Enhanced Theme & UI Components +``` +Tasks: +- [ ] Add Orbitron and Roboto fonts +- [ ] Implement GravityLabColors +- [ ] Create GravityLabButton component +- [ ] Create GravityLabCard component +- [ ] Setup animation system +- [ ] Create particle effect manager +``` + +### PR #4: Screen Implementation +``` +Tasks: +- [ ] Enhanced splash screen +- [ ] Main menu with physics background +- [ ] World selection carousel +- [ ] Level selection grid +- [ ] Basic gameplay screen +``` + +### PR #5: Physics Enhancement +``` +Tasks: +- [ ] Create PhysicsObjectFactory +- [ ] Implement 8 object types +- [ ] Add gravity controller +- [ ] Create level loading system +- [ ] Implement victory conditions +``` + +--- + +## ๐Ÿ“ Design Resources + +All design specifications are in: +``` +docs/ +โ”œโ”€โ”€ gravity-lab-feature-spec.md (original) +โ””โ”€โ”€ design/ + โ”œโ”€โ”€ README.md (summary) + โ”œโ”€โ”€ screen-design-specs.md + โ”œโ”€โ”€ gameplay-mechanics-detailed.md + โ”œโ”€โ”€ visual-design-system.md + โ””โ”€โ”€ implementation-roadmap.md +``` + +--- + +## ๐Ÿš€ Ready to Continue! + +With the design phase complete and PR #2 providing the foundation, we're ready to implement the exciting features that will transform Moinsen Physics into Gravity Lab! + +Next step: Create PR #3 for the enhanced theme system and UI components. \ No newline at end of file diff --git a/docs/design/screen-design-specs.md b/docs/design/screen-design-specs.md new file mode 100644 index 0000000..60dbd6e --- /dev/null +++ b/docs/design/screen-design-specs.md @@ -0,0 +1,412 @@ +# Gravity Lab - Screen Design Specifications +## Visual Mockups and Detailed UI/UX Guide + +**Version:** 1.0 +**Date:** May 2024 +**Purpose:** Detailed screen-by-screen design guide for implementation + +--- + +## 1. Splash Screen Design + +### Visual Layout +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ โ”‚ +โ”‚ [Moinsen Dev Logo] โ”‚ +โ”‚ (fade in) โ”‚ +โ”‚ โ”‚ +โ”‚ โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ +โ”‚ โ”‚ GRAVITY LAB โ”‚ โ”‚ +โ”‚ โ”‚ โš›๏ธ ๐Ÿงช ๐ŸŒŒ โ”‚ โ”‚ +โ”‚ โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ โ”‚ +โ”‚ โ”‚ +โ”‚ [โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•> ] โ”‚ +โ”‚ Loading Physics... โ”‚ +โ”‚ โ”‚ +โ”‚ ๐Ÿ’ก Tip: Gravity can be โ”‚ +โ”‚ your best friend! โ”‚ +โ”‚ โ”‚ +โ”‚ v0.3.0 โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Animation Sequence +1. **0-0.5s**: Moinsen Dev logo fades in +2. **0.5-1s**: Gravity Lab title appears with particle burst +3. **1-2s**: Loading bar fills with liquid physics animation +4. **2s**: Particle transition to main menu + +### Visual Effects +- Floating particles in background (10-20 particles) +- Subtle gravity distortion effect on logo +- Liquid fill animation for loading bar +- Rotating tips every 3 seconds +- Glow effect on emojis + +--- + +## 2. Main Menu Screen + +### Layout Design +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ [๐Ÿ‘ค] [โš™๏ธ] โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ โ”‚ +โ”‚ โš›๏ธ GRAVITY LAB โš›๏ธ โ”‚ +โ”‚ [Animated Logo Scene] โ”‚ +โ”‚ โ”‚ +โ”‚ โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ +โ”‚ โ”‚ ๐ŸŽฎ PLAY โ”‚ โ”‚ +โ”‚ โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ โ”‚ +โ”‚ โ”‚ +โ”‚ โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ +โ”‚ โ”‚ ๐Ÿ† CHALLENGES โ”‚ โ”‚ +โ”‚ โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ โ”‚ +โ”‚ โ”‚ +โ”‚ โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ +โ”‚ โ”‚ ๐Ÿ”ง CREATE โ”‚ โ”‚ +โ”‚ โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ โ”‚ +โ”‚ โ”‚ +โ”‚ โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ +โ”‚ โ”‚ ๐Ÿ“Š LEADERBOARD โ”‚ โ”‚ +โ”‚ โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ โ”‚ +โ”‚ โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ [๐ŸŽ Daily] [๐Ÿ“ฐ News] [๐Ÿ‘ฅ Friends]โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Interactive Elements +- **Logo Scene**: Mini physics simulation with 5-7 objects +- **Button States**: + - Idle: Soft glow, subtle float animation + - Hover/Touch: Scale to 105%, bright glow + - Press: Scale to 95%, particle burst +- **Background**: Animated star field with parallax +- **Physics Objects**: Float and collide in background + +### Color Scheme +```dart +class MenuColors { + static const background = Color(0xFF0A0E27); + static const buttonPrimary = Color(0xFF00A8FF); + static const buttonSecondary = Color(0xFF8B5CF6); + static const accent = Color(0xFFFFD93D); + static const text = Color(0xFFFFFFFF); +} +``` + +--- + +## 3. World Selection Screen + +### Visual Concept +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ [โ† Back] CHOOSE WORLD [๐Ÿ‘ค] โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ โ”‚ +โ”‚ โ† [Previous World] [Next] โ†’ โ”‚ +โ”‚ โ”‚ +โ”‚ โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ ๐Ÿงช NEWTON'S โ”‚ โ”‚ +โ”‚ โ”‚ LABORATORY โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โญโญโญ 18/20 โ”‚ โ”‚ +โ”‚ โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ โ”‚ +โ”‚ โ”‚ +โ”‚ [๐Ÿ”’] [๐Ÿ”’] [๐Ÿ”’] [๐Ÿ”’] [๐Ÿ”’] [๐Ÿ”’] โ”‚ +โ”‚ 1 2 3 4 5 6 โ”‚ +โ”‚ โ”‚ +โ”‚ โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ +โ”‚ โ”‚ Tutorial World โ”‚ โ”‚ +โ”‚ โ”‚ Learn the basics of gravity โ”‚ โ”‚ +โ”‚ โ”‚ manipulation and physics โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ ๐Ÿ† Best Time: 12:34 โ”‚ โ”‚ +โ”‚ โ”‚ ๐ŸŒŸ Total Stars: 54/60 โ”‚ โ”‚ +โ”‚ โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ โ”‚ +โ”‚ โ”‚ +โ”‚ [ ENTER WORLD ] โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### World Carousel +1. **Newton's Laboratory** ๐Ÿงช - Classic physics +2. **Zero-G Station** ๐Ÿš€ - Space puzzles +3. **Aqua Depths** ๐ŸŒŠ - Underwater physics +4. **Magnetic Factory** ๐Ÿงฒ - Electromagnetic +5. **Time Nexus** โฐ - Time manipulation +6. **Quantum Realm** โš›๏ธ - Probability physics + +### Visual Features +- 3D rotating planet/environment preview +- Particle effects matching world theme +- Progress satellites orbiting the world +- Unlock animation with particle explosion +- Background changes with selected world + +--- + +## 4. Level Selection Grid + +### Layout Pattern +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ [โ† Back] NEWTON'S LABORATORY [?] โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ โ”‚ +โ”‚ 1โญโญโญ 2โญโญโญ 3โญโญโ˜† โ”‚ +โ”‚ โฌข โฌข โฌข โ”‚ +โ”‚ โ”‚ +โ”‚ 4โญโ˜†โ˜† 5โญโญโญ 6โญโญโญ โ”‚ +โ”‚ โฌข โ”โ”โ” โฌข โ”โ”โ” โฌข โ”‚ +โ”‚ | โ”‚ +โ”‚ 7โญโญโ˜† 8โšก 9๐Ÿ”’ โ”‚ +โ”‚ โฌข โ”โ”โ” โฌข โฌข โ”‚ +โ”‚ โ”‚ +โ”‚ 10๐Ÿ”’ 11๐Ÿ”’ 12๐Ÿ”’ โ”‚ +โ”‚ โฌข โฌข โฌข โ”‚ +โ”‚ โ”‚ +โ”‚ โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ +โ”‚ โ”‚ Level 8 - Gravity Wells โ”‚ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” Difficulty: โš›๏ธโš›๏ธโš›๏ธ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Preview โ”‚ Par Time: 45s โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ ... โ”‚ Best: 32s โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ Rank: #142 โ”‚ โ”‚ +โ”‚ โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Level States +- **Completed**: Bright with stars (โญ) +- **Current**: Pulsing glow (โšก) +- **Locked**: Darkened (๐Ÿ”’) +- **Special**: Rainbow border (bonus levels) + +### Preview Window Features +- Minimap of level layout +- Animated preview of solution hint +- Difficulty atoms (1-5) +- Speed run times +- Friend scores comparison + +--- + +## 5. Gameplay Screen Layout + +### Interface Zones +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ [โธ๏ธ] 00:23 | Moves: 5 | [๐Ÿ’ก] [๐Ÿ”„] โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ ๐ŸŸข โ† (Start Object) โ”‚ โ”‚ +โ”‚ โ”‚ | โ”‚ โ”‚ +โ”‚ โ”‚ โ†“ โ”‚ โ”‚ +โ”‚ โ”‚ โ•โ•โ•โ•ชโ•โ•โ•โ•โ•โ•โ• โ”‚ โ”‚ +โ”‚ โ”‚ | โ”‚ โ”‚ +โ”‚ โ”‚ โ†“ โ”‚ โ”‚ +โ”‚ โ”‚ โ–“โ–“โ–“โ–“โ–“โ–“โ–“ โ”‚ โ”‚ +โ”‚ โ”‚ โ†“ โ”‚ โ”‚ +โ”‚ โ”‚ โญ โ† (Goal) โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ [โ†‘] [โ†—] [โ†’] [โ†˜] [โ†“] [โ†™] [โ†]โ”‚ +โ”‚ GRAVITY CONTROLS โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ [๐Ÿงฒ] [๐ŸŒŠ] [โšก] [โ„๏ธ] [๐Ÿ•ณ๏ธ] โ”‚ +โ”‚ SPECIAL TOOLS โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Touch Gestures +- **Tap**: Select/activate object +- **Drag**: Move objects or draw paths +- **Pinch**: Zoom in/out +- **Two-finger rotate**: Rotate gravity +- **Long press**: Object properties +- **Swipe**: Quick gravity change + +### Visual Feedback +- Gravity field lines (subtle) +- Object trajectory preview +- Force indicators +- Collision predictions +- Success path highlighting + +--- + +## 6. Victory Screen + +### Celebration Sequence +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ โ”‚ +โ”‚ LEVEL COMPLETE! โ”‚ +โ”‚ โ”‚ +โ”‚ โญ โญ โญ โ”‚ +โ”‚ โ”‚ +โ”‚ โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ +โ”‚ โ”‚ Time: 00:32 โšกBEST! โ”‚ โ”‚ +โ”‚ โ”‚ Moves: 5/7 โ”‚ โ”‚ +โ”‚ โ”‚ Score: 1,250 โ”‚ โ”‚ +โ”‚ โ”‚ Rank: #42 โ†‘23 โ”‚ โ”‚ +โ”‚ โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ โ”‚ +โ”‚ โ”‚ +โ”‚ ๐Ÿ† NEW ACHIEVEMENT UNLOCKED! โ”‚ +โ”‚ "Speed Demon" - Under par time โ”‚ +โ”‚ โ”‚ +โ”‚ +100 XP +50 โš›๏ธ Atoms โ”‚ +โ”‚ โ”‚ +โ”‚ [๐Ÿ“ค SHARE] [๐Ÿ”„ REPLAY] [โžก๏ธ NEXT] โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Animation Timeline +1. **0-0.5s**: Objects celebrate with physics +2. **0.5-1s**: Stars appear one by one +3. **1-1.5s**: Score counter animates +4. **1.5-2s**: Achievements slide in +5. **2s+**: Buttons appear with bounce + +--- + +## 7. Level Editor Interface + +### Tool Palette +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ [โ† Back] LEVEL EDITOR [Test โ–ถ๏ธ] [๐Ÿ’พ]โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ โ”Œโ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ O โ”‚ โ”‚Propertiesโ”‚ +โ”‚ โ”‚ B โ”‚ โ”‚โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ +โ”‚ โ”‚ J โ”‚ CANVAS AREA โ”‚โ”‚Object: โ”‚โ”‚ +โ”‚ โ”‚ E โ”‚ (Grid Visible) โ”‚โ”‚ Ball โ”‚โ”‚ +โ”‚ โ”‚ C โ”‚ โ”‚โ”‚ โ”‚โ”‚ +โ”‚ โ”‚ T โ”‚ โ”‚โ”‚Mass: 5 โ”‚โ”‚ +โ”‚ โ”‚ S โ”‚ โ”‚โ”‚Size: M โ”‚โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ [โฎ๏ธ][โธ๏ธ][โ–ถ๏ธ][โญ๏ธ] Timeline โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Object Palette +- ๐ŸŸข Basic Ball +- ๐ŸŸฆ Heavy Cube +- ๐ŸŽˆ Balloon +- ๐ŸŸฃ Sticky Blob +- ๐Ÿ‘ป Ghost Orb +- โšก Energy Sphere +- ๐ŸงŠ Ice Cube +- ๐Ÿงฒ Magnetic Ball + +### Editor Features +- Snap-to-grid (toggleable) +- Copy/paste objects +- Undo/redo (Ctrl+Z/Y) +- Test mode instant preview +- AI balance checker +- Solution validator + +--- + +## 8. Settings Screen Design + +### Layout Structure +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ [โ† Back] SETTINGS โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ โ”‚ +โ”‚ ๐Ÿ”Š AUDIO โ”‚ +โ”‚ โ”œโ”€ Music [โ”โ”โ”โ”โ”โ—โ”โ”] 70% โ”‚ +โ”‚ โ”œโ”€ Sound Effects [โ”โ”โ”โ”โ”โ”โ”โ—] 100% โ”‚ +โ”‚ โ””โ”€ Haptics [ON โœ“] โ”‚ +โ”‚ โ”‚ +โ”‚ ๐ŸŽฎ GAMEPLAY โ”‚ +โ”‚ โ”œโ”€ Show Hints [ON โœ“] โ”‚ +โ”‚ โ”œโ”€ Grid Overlay [OFF ] โ”‚ +โ”‚ โ”œโ”€ Trajectories [ON โœ“] โ”‚ +โ”‚ โ””โ”€ Particle Density [Medium โ–ผ] โ”‚ +โ”‚ โ”‚ +โ”‚ ๐Ÿ“ฑ DISPLAY โ”‚ +โ”‚ โ”œโ”€ Quality [High โ–ผ] โ”‚ +โ”‚ โ”œโ”€ FPS Limit [60 FPS โ–ผ] โ”‚ +โ”‚ โ””โ”€ Screen Shake [ON โœ“] โ”‚ +โ”‚ โ”‚ +โ”‚ ๐ŸŒ LANGUAGE [English โ–ผ] โ”‚ +โ”‚ โ”‚ +โ”‚ [๐Ÿ“– CREDITS] [โ“ HELP] [๐Ÿ”„ RESET] โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +--- + +## Implementation Priority Guide + +### Phase 1: Core Screens (Week 1-2) +1. โœ… Splash Screen (simple version) +2. โœ… Main Menu +3. โœ… Basic Gameplay Screen +4. โœ… Settings (minimal) + +### Phase 2: Game Flow (Week 3-4) +1. โณ World Selection +2. โณ Level Selection +3. โณ Victory Screen +4. โณ Tutorial Overlays + +### Phase 3: Advanced (Week 5-6) +1. โณ Level Editor +2. โณ Leaderboards +3. โณ Profile/Stats +4. โณ Social Features + +--- + +## Design Tokens + +### Typography +```dart +class AppTypography { + static const headerLarge = TextStyle( + fontFamily: 'Orbitron', + fontSize: 32, + fontWeight: FontWeight.bold, + ); + + static const headerMedium = TextStyle( + fontFamily: 'Orbitron', + fontSize: 24, + fontWeight: FontWeight.w600, + ); + + static const body = TextStyle( + fontFamily: 'Roboto', + fontSize: 16, + fontWeight: FontWeight.normal, + ); +} +``` + +### Spacing +- Small: 8px +- Medium: 16px +- Large: 24px +- XLarge: 32px + +### Border Radius +- Small: 8px +- Medium: 16px +- Large: 24px +- Full: 999px \ No newline at end of file diff --git a/docs/design/visual-design-system.md b/docs/design/visual-design-system.md new file mode 100644 index 0000000..9dc40bb --- /dev/null +++ b/docs/design/visual-design-system.md @@ -0,0 +1,471 @@ +# Gravity Lab - Visual Design System +## Flutter Implementation Guide + +**Version:** 1.0 +**Date:** May 2024 +**Purpose:** Complete visual design system for Flutter implementation + +--- + +## 1. Color System + +### Primary Palette +```dart +class GravityLabColors { + // Main Brand Colors + static const primaryBlue = Color(0xFF00A8FF); + static const secondaryPurple = Color(0xFF8B5CF6); + static const accentYellow = Color(0xFFFFD93D); + + // UI Colors + static const background = Color(0xFF0A0E27); + static const surface = Color(0xFF1A1F3A); + static const surfaceLight = Color(0xFF2A2F4A); + + // Semantic Colors + static const success = Color(0xFF10B981); + static const warning = Color(0xFFF59E0B); + static const error = Color(0xFFEF4444); + static const info = Color(0xFF3B82F6); + + // Text Colors + static const textPrimary = Color(0xFFFFFFFF); + static const textSecondary = Color(0xFFB8BCC8); + static const textDisabled = Color(0xFF6B7280); + + // Physics Object Colors + static const ballGreen = Color(0xFF4ADE80); + static const cubeBlue = Color(0xFF60A5FA); + static const balloonPink = Color(0xFFF472B6); + static const blobPurple = Color(0xFFC084FC); + static const ghostWhite = Color(0xFFE5E7EB); + static const energyYellow = Color(0xFFFDE047); + static const iceCyan = Color(0xFF67E8F9); + static const magnetRed = Color(0xFFF87171); +} +``` + +### Gradient Definitions +```dart +class GradientStyles { + static const blueGlow = LinearGradient( + colors: [Color(0xFF00A8FF), Color(0xFF0080CC)], + begin: Alignment.topCenter, + end: Alignment.bottomCenter, + ); + + static const purpleGlow = LinearGradient( + colors: [Color(0xFF8B5CF6), Color(0xFF6D28D9)], + ); + + static const spaceBackground = LinearGradient( + colors: [Color(0xFF0A0E27), Color(0xFF1A1F3A), Color(0xFF0A0E27)], + stops: [0.0, 0.5, 1.0], + ); +} +``` + +--- + +## 2. Typography System + +### Font Setup (pubspec.yaml) +```yaml +fonts: + - family: Orbitron + fonts: + - asset: assets/fonts/Orbitron-Regular.ttf + - asset: assets/fonts/Orbitron-Bold.ttf + weight: 700 + - family: Roboto + fonts: + - asset: assets/fonts/Roboto-Regular.ttf + - asset: assets/fonts/Roboto-Medium.ttf + weight: 500 +``` + +### Text Styles +```dart +class GravityLabTextStyles { + static const displayLarge = TextStyle( + fontFamily: 'Orbitron', + fontSize: 56, + fontWeight: FontWeight.bold, + letterSpacing: -1.5, + ); + + static const displayMedium = TextStyle( + fontFamily: 'Orbitron', + fontSize: 45, + fontWeight: FontWeight.bold, + letterSpacing: -0.5, + ); + + static const headlineLarge = TextStyle( + fontFamily: 'Orbitron', + fontSize: 32, + fontWeight: FontWeight.bold, + ); + + static const headlineMedium = TextStyle( + fontFamily: 'Orbitron', + fontSize: 24, + fontWeight: FontWeight.w600, + ); + + static const bodyLarge = TextStyle( + fontFamily: 'Roboto', + fontSize: 18, + fontWeight: FontWeight.normal, + ); + + static const bodyMedium = TextStyle( + fontFamily: 'Roboto', + fontSize: 16, + fontWeight: FontWeight.normal, + ); + + static const labelLarge = TextStyle( + fontFamily: 'Roboto', + fontSize: 14, + fontWeight: FontWeight.w500, + letterSpacing: 0.1, + ); +} +``` + +--- + +## 3. Component Library + +### Primary Button +```dart +class GravityLabButton extends StatelessWidget { + final String text; + final VoidCallback onPressed; + final bool isLoading; + + @override + Widget build(BuildContext context) { + return Container( + height: 56, + decoration: BoxDecoration( + gradient: GradientStyles.blueGlow, + borderRadius: BorderRadius.circular(16), + boxShadow: [ + BoxShadow( + color: GravityLabColors.primaryBlue.withOpacity(0.3), + blurRadius: 12, + offset: Offset(0, 4), + ), + ], + ), + child: Material( + color: Colors.transparent, + child: InkWell( + onTap: isLoading ? null : onPressed, + borderRadius: BorderRadius.circular(16), + child: Center( + child: isLoading + ? CircularProgressIndicator(color: Colors.white) + : Text( + text, + style: GravityLabTextStyles.labelLarge.copyWith( + color: Colors.white, + ), + ), + ), + ), + ), + ); + } +} +``` + +### Card Component +```dart +class GravityLabCard extends StatelessWidget { + final Widget child; + final EdgeInsets? padding; + + @override + Widget build(BuildContext context) { + return Container( + padding: padding ?? EdgeInsets.all(16), + decoration: BoxDecoration( + color: GravityLabColors.surface, + borderRadius: BorderRadius.circular(16), + border: Border.all( + color: GravityLabColors.primaryBlue.withOpacity(0.2), + width: 1, + ), + boxShadow: [ + BoxShadow( + color: Colors.black.withOpacity(0.2), + blurRadius: 8, + offset: Offset(0, 2), + ), + ], + ), + child: child, + ); + } +} +``` + +--- + +## 4. Animation Standards + +### Durations +```dart +class AnimationDurations { + static const instant = Duration(milliseconds: 100); + static const fast = Duration(milliseconds: 200); + static const normal = Duration(milliseconds: 300); + static const slow = Duration(milliseconds: 500); + static const verySlow = Duration(milliseconds: 1000); +} +``` + +### Curves +```dart +class AnimationCurves { + static const easeInOut = Curves.easeInOutCubic; + static const bounce = Curves.bounceOut; + static const elastic = Curves.elasticOut; + static const spring = Curves.fastOutSlowIn; +} +``` + +### Page Transitions +```dart +class GravityLabPageTransition extends PageRouteBuilder { + final Widget page; + + GravityLabPageTransition({required this.page}) + : super( + pageBuilder: (context, animation, secondaryAnimation) => page, + transitionDuration: AnimationDurations.normal, + transitionsBuilder: (context, animation, secondaryAnimation, child) { + const begin = Offset(1.0, 0.0); + const end = Offset.zero; + const curve = Curves.easeInOut; + + var tween = Tween(begin: begin, end: end).chain( + CurveTween(curve: curve), + ); + + var offsetAnimation = animation.drive(tween); + + return SlideTransition( + position: offsetAnimation, + child: child, + ); + }, + ); +} +``` + +--- + +## 5. Particle Effects System + +### Particle Configuration +```dart +class ParticleConfig { + static const starfield = { + 'count': 50, + 'minSize': 1.0, + 'maxSize': 3.0, + 'speed': 0.5, + 'opacity': 0.7, + }; + + static const explosion = { + 'count': 30, + 'minSize': 2.0, + 'maxSize': 6.0, + 'speed': 5.0, + 'lifetime': 1.0, + 'colors': [ + GravityLabColors.accentYellow, + GravityLabColors.primaryBlue, + GravityLabColors.secondaryPurple, + ], + }; + + static const trail = { + 'emissionRate': 10, + 'size': 4.0, + 'lifetime': 0.5, + 'fadeOut': true, + }; +} +``` + +--- + +## 6. Shader Effects + +### Glow Shader +```glsl +// Used for glowing UI elements and energy objects +precision mediump float; +uniform vec2 resolution; +uniform float time; +uniform vec3 color; + +void main() { + vec2 uv = gl_FragCoord.xy / resolution; + float dist = distance(uv, vec2(0.5)); + float glow = 1.0 - smoothstep(0.0, 0.5, dist); + glow = pow(glow, 2.0); + + vec3 finalColor = color * glow; + finalColor += vec3(0.1) * sin(time * 2.0) * glow; + + gl_FragColor = vec4(finalColor, glow); +} +``` + +### Distortion Shader +```glsl +// For gravity wells and portals +uniform sampler2D texture; +uniform vec2 center; +uniform float strength; +uniform float time; + +void main() { + vec2 uv = gl_FragCoord.xy / resolution; + vec2 dir = uv - center; + float dist = length(dir); + + float distortion = sin(dist * 10.0 - time * 3.0) * strength; + distortion *= 1.0 - smoothstep(0.2, 0.5, dist); + + vec2 distortedUV = uv + normalize(dir) * distortion; + gl_FragColor = texture2D(texture, distortedUV); +} +``` + +--- + +## 7. Responsive Design + +### Breakpoints +```dart +class Breakpoints { + static const mobile = 600; + static const tablet = 900; + static const desktop = 1200; +} + +extension ResponsiveExtension on BuildContext { + bool get isMobile => MediaQuery.of(this).size.width < Breakpoints.mobile; + bool get isTablet => MediaQuery.of(this).size.width < Breakpoints.tablet; + bool get isDesktop => MediaQuery.of(this).size.width >= Breakpoints.desktop; +} +``` + +### Adaptive Layouts +```dart +class AdaptiveGrid extends StatelessWidget { + final List children; + + @override + Widget build(BuildContext context) { + return GridView.builder( + gridDelegate: SliverGridDelegateWithFixedCrossAxisCount( + crossAxisCount: context.isMobile ? 2 : context.isTablet ? 3 : 4, + childAspectRatio: 1.0, + crossAxisSpacing: 16, + mainAxisSpacing: 16, + ), + itemCount: children.length, + itemBuilder: (context, index) => children[index], + ); + } +} +``` + +--- + +## 8. Icon System + +### Custom Icons +```dart +class GravityLabIcons { + static const gravity = IconData(0xe800, fontFamily: 'GravityLabIcons'); + static const atom = IconData(0xe801, fontFamily: 'GravityLabIcons'); + static const portal = IconData(0xe802, fontFamily: 'GravityLabIcons'); + static const magnet = IconData(0xe803, fontFamily: 'GravityLabIcons'); + static const energy = IconData(0xe804, fontFamily: 'GravityLabIcons'); +} +``` + +--- + +## 9. Loading States + +### Skeleton Loader +```dart +class SkeletonLoader extends StatelessWidget { + final double width; + final double height; + + @override + Widget build(BuildContext context) { + return Shimmer.fromColors( + baseColor: GravityLabColors.surface, + highlightColor: GravityLabColors.surfaceLight, + child: Container( + width: width, + height: height, + decoration: BoxDecoration( + color: GravityLabColors.surface, + borderRadius: BorderRadius.circular(8), + ), + ), + ); + } +} +``` + +--- + +## 10. Theme Configuration + +### Complete Theme +```dart +class GravityLabTheme { + static ThemeData get theme => ThemeData( + brightness: Brightness.dark, + scaffoldBackgroundColor: GravityLabColors.background, + colorScheme: ColorScheme.dark( + primary: GravityLabColors.primaryBlue, + secondary: GravityLabColors.secondaryPurple, + surface: GravityLabColors.surface, + error: GravityLabColors.error, + ), + appBarTheme: AppBarTheme( + backgroundColor: Colors.transparent, + elevation: 0, + titleTextStyle: GravityLabTextStyles.headlineMedium, + ), + elevatedButtonTheme: ElevatedButtonThemeData( + style: ElevatedButton.styleFrom( + minimumSize: Size(double.infinity, 56), + shape: RoundedRectangleBorder( + borderRadius: BorderRadius.circular(16), + ), + ), + ), + ); +} +``` + +--- + +This design system provides all the visual building blocks needed to implement Gravity Lab's UI in Flutter! \ No newline at end of file