How jingunsnack/ghost-survivors works
Project Type and Purpose
• This is a client‐side, single-page browser game (“Ghost Survivors”) implemented in Rust and compiled to WebAssembly. There is no traditional server or backend API; everything runs in the user’s browser.
• The HTML/JS in the wasm/ folder bootstraps the Wasm module and handles any browser‐specific concerns (e.g., audio context restart).
High‐Level File‐Structure Analysis
• Top‐level:
• Cargo.toml/Cargo.lock defines Rust dependencies and build settings.
• .github/workflows holds CI pipelines (build, test, release).
• assets/models contains 3D assets (GLB models for player, enemies).
• wasm/index.html and accompanying JS glue for browser startup.
• src/ modules roughly map to the game’s subsystems:
• main.rs – entry point & game‐loop initialization.
• camera.rs, earth.rs, waveform.rs – rendering and visual effects.
• enemy/ – enemy‐type definitions (Dragon, Ghost, Knight).
• weapon/ – bullet & orbit‐weapon implementations.
• player.rs, score.rs, menu.rs, gameover.rs – UI, game state, and scoring logic.
Key Components
a. Browser Host Layer
• HTML Canvas & DOM (from wasm/index.html)
• JS Glue (restart-audio-context.js)
b. WebAssembly Module
• Rust‐to‐Wasm binary (produced by Cargo + wasm-bindgen)
• Submodules:
• Game Loop & Scheduler (main.rs)
• Input Handler (implicit in main loop)
• Rendering Engine (camera.rs, earth.rs, waveform.rs)
• Entity System (player, enemies, weapons)
• UI Manager (menu.rs, gameover.rs, score.rs)
• Asset Loader (models in assets/models)
• Audio Manager (waveform & audio context restart)
c. External/Build Infrastructure
• GitHub Actions CI (ci.yaml, release.yaml)
• Crates.io & Cargo Build Toolchain
Relationships and Data Flows
• User Input → Browser Event Loop → Wasm Input Handler
• Input Handler → Game Loop (update phase)
• Game Loop → Entity System Updates → Collision/Physics & Score updates
• Asset Loader & Audio Manager supply textures, models, and sound data to Renderer
• UI Manager overlays menus, scores, and game‐over screens on top of the Canvas
Architectural Patterns and Principles
• Modular separation: each major concern (rendering, entities, UI, audio) lives in its own Rust module folder.
• Single responsibility: e.g., enemy/ only contains enemy logic, weapon/ only handles projectile logic.
• Minimal coupling between modules—interaction mediated through the main game‐loop scheduler.
• Canvas & Event Loop (Browser)
• JS Audio Restart Script
• Wasm Entry Point (main.rs)
• Game Loop Scheduler
• Subsystems:
• Camera & Scene (camera.rs, earth.rs)
• Waveform/Audio (waveform.rs)
• Entity Manager: Player (player.rs), Enemies (enemy/*.rs), Weapons (weapon/*.rs)
• UI Manager: Menu (menu.rs), Score (score.rs), Game Over (gameover.rs)
• Asset Repository (GLB models)
• CI/CD (GitHub Actions)