Crate Architecture Reference #

This document describes the Cargo Workspace subcrate structure of the akius project. Reorganized under the Rust 2024 edition, this multi-crate layout isolates core game rules and physics from Bevy rendering systems, facilitating headless simulation/training while preserving a single source of truth.

---

1. Directory Structure #

akius/
├── Cargo.toml                  # Workspace root configuration
├── Cargo.lock                  # Shared workspace lockfile
├── index.html                  # Main entry page (targets akius_game)
├── assets/                     # Shared game assets (audio, fonts, textures, shaders)
│
├── akius_core/                 # 1. CORE SIMULATION LIBRARY
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs              # AppState, Score, Sphere, checking & reset systems
│       ├── core_math.rs        # Radii math, scoring logic, queue random weights
│       └── physics_rules.rs    # Rapier3D physics systems, collision/merge rules
│
├── akius_game/                 # 2. PLAYABLE BEVY GAME FRONTEND
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs             # Bevy app bootstrap, setup camera/lighting
│       ├── launcher.rs         # Launcher aiming, mouse, touch input systems
│       ├── visuals.rs          # Shaders, camera, lighting, effects, high scores
│       ├── hud.rs              # UI layouts & responsive stacking
│       └── utils.rs            # Change-detection visibility helper
│
└── akius_train/                # 3. HEADLESS ML ENVIRONMENT & BINDINGS
    ├── Cargo.toml
    └── src/
        └── main.rs             # Headless training loop/Gymnasium bindings

---

2. Crate Responsibilities #

akius_core (Core Library) #

• Goal: Runs the headless game state machine and physics simulation as fast as possible.
• Dependencies: Compiles Bevy without default features (default-features = false). It pulls in only core ECS features (bevy_app, bevy_ecs, bevy_state, bevy_log). It has no dependency on graphics windowing, rendering, UI, or audio libs.
• Key Components:
  • core_math: Target scoring math, sphere radius calculations ($R(n) = 0.5 \times 1.21^{n-1}$), and dispenser random weights.
  • physics_rules: Physics configuration (density, friction, restitution, locked axes) and merge/collision detection logic using Bevy Rapier 3D.
  • Game resources (Score, ActiveOrder, DispenserQueue, ActiveFulfillment).

akius_game (Playable Frontend) #

• Goal: Displays the game interface, handles user inputs, and plays audio.
• Dependencies: Bevy with full rendering, windowing, UI, and audio features (bevy_render, bevy_ui, bevy_audio, etc.) + bevy_mesh, and depends on akius_core.
• Key Components:
  • launcher: Aiming guide lines, keyboard movement, screen-to-world raycasting, and obstruction checks.
  • visuals: Color palettes, outer shells, particle systems, CRT post-processing, and local storage high score writes.
  • hud: UI rendering, layout responsiveness, orientations stacking, and buttons/labels sizing.

akius_train (Machine Learning Target) #

• Goal: Headless simulation runner and Python Gymnasium wrapper entry point.
• Dependencies: Depends on akius_core (and optional PyO3 dependencies for Python bindings). Bypasses all akius_game code.

---

3. Configuration & Compilation Details #

Rust Edition #

All crates in the workspace use the Rust 2024 edition.

The Bevy Sphere Namespace Collision #

Because Bevy 0.15+ introduces a built-in 3D primitive called bevy::prelude::Sphere, any code importing bevy::prelude::* will shadow our game's custom Sphere component.

• Solution: In all game files, our custom Sphere component is explicitly imported after the Bevy prelude:

  use bevy::prelude::*;
  use akius_core::Sphere; // Explicitly override the primitive Sphere
  

---

4. Test Suite Division #

Tests are distributed based on dependency constraints to avoid circular reference issues:

akius_core Tests (14 Tests) #

Validates core mechanics, math, and physics logic in isolation:

• Math & Scoring (test_radius_scaling, test_scoring_math, test_weighted_dispenser_distribution)
• Rules & Fulfilment (test_order_fulfillment, test_loss_condition_recoil, test_loss_condition_fallen_y, test_loss_condition_grace_period, test_restart_from_game_over)
• Physics Attributes (test_sphere_spawn_physics_attributes, test_dampen_rebound_velocity, test_spill_spheres, test_double_merge_safety, test_collision_midpoint_merge, test_merge_momentum_conservation)

akius_game Tests (13 Tests) #

Validates inputs, HUD behaviors, and rendering updates:

• Inputs & Cooldowns (test_raycast_cursor_plane_intersection, test_launch_spawn_and_impulse, test_merge_cooldown_blocking, test_launch_cooldown_blocking, test_touch_start_origin_filter, test_preview_obstruction_detection)
• UI & Render settings (test_in_game_over_or_win_state, test_crt_screen_position_inverts_shader_curve, test_crt_screen_position_pulls_toward_center, test_label_projection, test_auto_degrade_fires_on_sustained_slowness, test_auto_degrade_ignores_healthy_and_spiky_frames)
• Leak checks (test_entity_count_soak - checks visuals/labels cleanups)

---

5. Deployment / Trunk Integration #

To deploy the game to GitHub Pages or Itch.io:

1. The index.html file at the root points Trunk to the subcrate's manifest:

   <link data-trunk rel="rust" href="akius_game/Cargo.toml" />
   

2. Build the project using Trunk from the workspace root:

   trunk build --release
   

3. Zip or deploy the /dist directory. The compiled WebAssembly output (akius_game.wasm) will contain both akius_game and its statically linked akius_core library dependency.