# jingunsnack/ghost-survivors architecture

> Architecture diagram of the GitHub repository jingunsnack/ghost-survivors, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jingunsnack/ghost-survivors
- Repository: https://github.com/jingunsnack/ghost-survivors

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser Host Layer"
        BH_CANVAS("HTML Canvas & DOM"):::clientHost
        BH_JS("JS Audio Restart Script"):::clientHost
    end

    subgraph "WebAssembly Module"
        direction TB
        WASM_ENTRY("Entry Point & Game Loop Scheduler\n(src/main.rs)"):::wasmEngine
        subgraph "Rendering Engine"
            direction TB
            R_CAM("Camera & Scene\n(src/camera.rs, src/earth.rs)"):::wasmEngine
            R_WAVE("Waveform/Audio\n(src/waveform.rs)"):::wasmEngine
        end
        subgraph "Entity System"
            direction TB
            E_PLAYER("Player Logic\n(src/player.rs)"):::wasmEngine
            subgraph "Enemy Types"
                direction TB
                E_DRAGON("Dragon\n(src/enemy/dragon.rs)"):::wasmEngine
                E_GHOST("Ghost\n(src/enemy/ghost.rs)"):::wasmEngine
                E_KNIGHT("Knight\n(src/enemy/knight.rs)"):::wasmEngine
                E_ENEMY_MOD("mod\n(src/enemy/mod.rs)"):::wasmEngine
            end
            subgraph "Weapons"
                direction TB
                W_BULLET("Bullet\n(src/weapon/bullet.rs)"):::wasmEngine
                W_ORBIT("Orbit\n(src/weapon/orbit.rs)"):::wasmEngine
                W_WEAP_MOD("mod\n(src/weapon/mod.rs)"):::wasmEngine
            end
        end
        subgraph "UI Manager"
            direction TB
            UI_MENU("Main Menu\n(src/menu.rs)"):::wasmEngine
            UI_SCORE("Score Display\n(src/score.rs)"):::wasmEngine
            UI_GAMEOVER("Game Over Screen\n(src/gameover.rs)"):::wasmEngine
        end
    end

    subgraph "Assets Repository"
        direction TB
        ASSET_DRAGON("dragon.glb"):::assets
        ASSET_GHOST("ghost.glb"):::assets
        ASSET_KNIGHT("knight.glb"):::assets
        ASSET_PLAYER("player.glb"):::assets
    end

    subgraph "CI/CD Pipeline"
        direction TB
        CI_CI("CI\n(.github/workflows/ci.yaml)"):::ci
        CI_REL("Release\n(.github/workflows/release.yaml)"):::ci
        CFG("Cargo.toml / Cargo.lock"):::ci
    end

    BH_CANVAS -->|"user input/events"| WASM_ENTRY
    BH_JS -->|"audio context restart"| R_WAVE
    WASM_ENTRY -->|"update phase"| E_PLAYER
    WASM_ENTRY -->|"update phase"| E_ENEMY_MOD
    WASM_ENTRY -->|"update phase"| W_WEAP_MOD
    WASM_ENTRY -->|"update phase"| UI_MENU
    WASM_ENTRY -->|"update phase"| UI_SCORE
    WASM_ENTRY -->|"update phase"| UI_GAMEOVER
    WASM_ENTRY -->|"render call"| R_CAM
    WASM_ENTRY -->|"audio update"| R_WAVE

    R_CAM -->|"model data fetch"| ASSET_DRAGON
    R_CAM -->|"model data fetch"| ASSET_GHOST
    R_CAM -->|"model data fetch"| ASSET_KNIGHT
    R_CAM -->|"model data fetch"| ASSET_PLAYER

    CFG -->|"builds via Cargo"| WASM_ENTRY
    CI_CI -->|"runs build/test"| CFG
    CI_REL -->|"pack and release"| CFG

    click BH_CANVAS "https://github.com/jingunsnack/ghost-survivors/blob/main/wasm/index.html"
    click BH_JS "https://github.com/jingunsnack/ghost-survivors/blob/main/wasm/restart-audio-context.js"
    click WASM_ENTRY "https://github.com/jingunsnack/ghost-survivors/blob/main/src/main.rs"
    click R_CAM "https://github.com/jingunsnack/ghost-survivors/blob/main/src/camera.rs"
    click R_CAM "https://github.com/jingunsnack/ghost-survivors/blob/main/src/earth.rs"
    click R_WAVE "https://github.com/jingunsnack/ghost-survivors/blob/main/src/waveform.rs"
    click E_PLAYER "https://github.com/jingunsnack/ghost-survivors/blob/main/src/player.rs"
    click E_DRAGON "https://github.com/jingunsnack/ghost-survivors/blob/main/src/enemy/dragon.rs"
    click E_GHOST "https://github.com/jingunsnack/ghost-survivors/blob/main/src/enemy/ghost.rs"
    click E_KNIGHT "https://github.com/jingunsnack/ghost-survivors/blob/main/src/enemy/knight.rs"
    click E_ENEMY_MOD "https://github.com/jingunsnack/ghost-survivors/blob/main/src/enemy/mod.rs"
    click W_BULLET "https://github.com/jingunsnack/ghost-survivors/blob/main/src/weapon/bullet.rs"
    click W_ORBIT "https://github.com/jingunsnack/ghost-survivors/blob/main/src/weapon/orbit.rs"
    click W_WEAP_MOD "https://github.com/jingunsnack/ghost-survivors/blob/main/src/weapon/mod.rs"
    click UI_MENU "https://github.com/jingunsnack/ghost-survivors/blob/main/src/menu.rs"
    click UI_SCORE "https://github.com/jingunsnack/ghost-survivors/blob/main/src/score.rs"
    click UI_GAMEOVER "https://github.com/jingunsnack/ghost-survivors/blob/main/src/gameover.rs"
    click ASSET_DRAGON "https://github.com/jingunsnack/ghost-survivors/blob/main/assets/models/dragon.glb"
    click ASSET_GHOST "https://github.com/jingunsnack/ghost-survivors/blob/main/assets/models/ghost.glb"
    click ASSET_KNIGHT "https://github.com/jingunsnack/ghost-survivors/blob/main/assets/models/knight.glb"
    click ASSET_PLAYER "https://github.com/jingunsnack/ghost-survivors/blob/main/assets/models/player.glb"
    click CFG "https://github.com/jingunsnack/ghost-survivors/blob/main/Cargo.toml"
    click CFG "https://github.com/jingunsnack/ghost-survivors/blob/main/Cargo.lock"
    click CI_CI "https://github.com/jingunsnack/ghost-survivors/blob/main/.github/workflows/ci.yaml"
    click CI_REL "https://github.com/jingunsnack/ghost-survivors/blob/main/.github/workflows/release.yaml"

    classDef clientHost fill:#D0E8FF,stroke:#000
    classDef wasmEngine fill:#D0FFD0,stroke:#000
    classDef assets fill:#FFD8A8,stroke:#000
    classDef ci fill:#E0E0E0,stroke:#000
```
