# josephliao542211/ggstudio architecture

> Architecture diagram of the GitHub repository josephliao542211/ggstudio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/josephliao542211/ggstudio
- Repository: https://github.com/josephliao542211/ggstudio

## Overview

#### Repository Scope
GGStudio is a multi-project game-development repository. It contains three independent HTML5 game projects, shared licensed art/audio sources, and GLB conversion/rigging toolchains. Binary source assets are expected through Git LFS. Root guidance: `README.md`, `docs/README.md`, `vercel.json`.

#### Product Entry Points
Each game is separately buildable/runnable, with its own Vite/TypeScript configuration and browser entry:
- **Subway**, an endless-runner project: `Subway/index.html`, `Subway/src/main.ts`, `Subway/src/game/Game.ts`.
- **Comfy Zoo**, a zoo-management/simulation game: `comfy-zoo/index.html`, `comfy-zoo/src/main.ts`, `comfy-zoo/src/core/Game.ts`.
- **Zombie Motorworks**, a vehicle-building survival game: `zombie-motorworks/index.html`, `zombie-motorworks/src/app/main.ts`, `zombie-motorworks/src/app/App.ts`.

Each project owns its runtime code, public assets, package manifest, and Vite configuration; they should be treated as deployment/build boundaries.

#### Asset Production and Shared Sources
Raw or reusable source assets are centralized rather than duplicated in game code:
- `Shared/` contains third-party source packs, audio, fonts, UI art, and multiple source formats.
- `saved/` retains raw/generated GLBs used as pipeline inputs, e.g. `saved/models/gunslinger-source.glb`.
- `glb-pipeline/pipeline.mjs` transforms textured GLB assets into optimized pixel-art/runtime assets, with Blender/Python stages in `glb-pipeline/blender_voxelize.py` and `glb-pipeline/optimize.mjs`.
- `glb-rigger/rig.mjs` applies declarative rigid-part animation hierarchies from files such as `glb-rigger/gunslinger.rig.json`.

The asset boundary is explicit: games consume runtime-ready artifacts from their `public/assets` directories, while `Shared/` and `saved/` are production inputs.

#### Comfy Zoo Architecture
Comfy Zoo is organized around a core game context and event-driven simulation:
- Core lifecycle, persistence, assets, and spatial queries: `comfy-zoo/src/core/Game.ts`, `comfy-zoo/src/core/GameContext.ts`, `comfy-zoo/src/core/SaveSystem.ts`.
- Data-driven content defines animals, shelters, resources, balance, and quests: `comfy-zoo/src/data/animals.json`, `comfy-zoo/src/data/balance.json`, `comfy-zoo/src/data/quests.json`.
- World generation and placement use tile/grid abstractions: `comfy-zoo/src/world/WorldGen.ts`, `comfy-zoo/src/world/TileGrid.ts`.
- Simulation systems update spawning, hunger, economy, construction, capture, and progression: `comfy-zoo/src/systems/SpawnSystem.ts`, `comfy-zoo/src/systems/HungerSystem.ts`, `comfy-zoo/src/systems/EconomySystem.ts`.
- UI consumes game state through dedicated HUD/menu modules: `comfy-zoo/src/ui/index.ts`, `comfy-zoo/src/ui/HUD.ts`.

Platform adapters isolate host integration for CrazyGames, Devvit, playable ads, and local development: `comfy-zoo/src/platform/PlatformAdapter.ts`, `comfy-zoo/src/platform/CrazyGamesAdapter.ts`.

#### Subway Architecture
Subway is a real-time endless-runner loop coordinated by a central game controller:
- `Subway/src/game/Game.ts` drives input, track/lane movement, collision handling, entities, and effects.
- Procedural/run progression is separated into reusable systems: `Subway/src/systems/Spawner.ts`, `Subway/src/systems/DifficultyDirector.ts`, `Subway/src/systems/ScoreManager.ts`.
- Player, chaser, obstacles, and track are distinct gameplay units: `Subway/src/game/entities/PlayerAvatar.ts`, `Subway/src/game/entities/ChasingImposter.ts`, `Subway/src/game/Track.ts`.
- Platform lifecycle and host SDK calls are abstracted behind providers: `Subway/src/platform/PlatformSDK.ts`, `Subway/src/platform/providers/CrazyGamesProvider.ts`, `Subway/src/platform/providers/PokiProvider.ts`.

#### Zombie Motorworks Architecture
Zombie Motorworks has a clear build-to-combat control flow:
1. The app/title layer manages launch, profiles, saves, badges, leaderboards, and CrazyGames access: `zombie-motorworks/src/app/App.ts`, `zombie-motorworks/src/app/profileStore.ts`, `zombie-motorworks/src/app/crazyGamesSdk.ts`.
2. The editor converts grid-based part placement into a vehicle blueprint: `zombie-motorworks/src/editor/EditorMode.ts`, `zombie-motorworks/src/core/blueprint.ts`, `zombie-motorworks/src/core/placement.ts`.
3. Runtime assembly turns blueprints into driveable combat vehicles: `zombie-motorworks/src/runtime/assembler.ts`, `zombie-motorworks/src/runtime/vehicle.ts`, `zombie-motorworks/src/runtime/weapons.ts`.
4. Survival mode runs arenas, waves, zombie AI, combat effects, and camera/UI: `zombie-motorworks/src/survival/SurvivalMode.ts`, `zombie-motorworks/src/survival/WaveManager.ts`, `zombie-motorworks/src/survival/zombies/ZombieSystem.ts`.
5. Core rules remain mostly pure/data-oriented—parts, economy, damage, progression, serialization, and wave models: `zombie-motorworks/src/core/parts.ts`, `zombie-motorworks/src/core/economy.ts`, `zombie-motorworks/src/core/runSave.ts`.

Main entry points: [`glb-pipeline/pipeline.mjs`](https://github.com/josephliao542211/ggstudio/blob/main/glb-pipeline/pipeline.mjs) (GLB optimization pipeline), [`comfy-zoo/src/core/GameContext.ts`](https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/core/GameContext.ts) (Game context), [`Subway/src/game/Game.ts`](https://github.com/josephliao542211/ggstudio/blob/main/Subway/src/game/Game.ts) (Game controller), [`zombie-motorworks/src/editor/EditorMode.ts`](https://github.com/josephliao542211/ggstudio/blob/main/zombie-motorworks/src/editor/EditorMode.ts) (Vehicle editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_assets["Asset Production"]
  node_shared_assets["Shared source packs<br/>asset sources"]
  node_saved_glbs["Saved GLB inputs<br/>model sources"]
  node_glb_pipeline{{"GLB optimization pipeline<br/>asset pipeline<br/>[pipeline.mjs]"}}
  node_glb_voxelizer["Blender voxelizer<br/>Blender/Python stage"]
  node_glb_rigger{{"GLB rigger<br/>rigging tool<br/>[rig.mjs]"}}
end

subgraph group_subway["Subway"]
  node_subway_entry["Browser entry<br/>Vite entry<br/>[main.ts]"]
  node_subway_game["Game controller<br/>runtime loop<br/>[Game.ts]"]
  node_subway_run_systems["Run progression<br/>gameplay systems<br/>[Spawner.ts]"]
  node_subway_entities["Runner world units<br/>entities and track<br/>[PlayerAvatar.ts]"]
  node_subway_platform["Platform providers<br/>host integration<br/>[PlatformSDK.ts]"]
  node_subway_assets["Runtime assets<br/>public assets"]
end

subgraph group_zoo["Comfy Zoo"]
  node_zoo_entry["Browser entry<br/>Vite entry<br/>[main.ts]"]
  node_zoo_game_context["Game context<br/>core lifecycle<br/>[GameContext.ts]"]
  node_zoo_content["Game content<br/>data definitions<br/>[animals.json]"]
  node_zoo_world["Generated tile world<br/>world model<br/>[WorldGen.ts]"]
  node_zoo_simulation["Simulation systems<br/>event-driven systems<br/>[SpawnSystem.ts]"]
  node_zoo_ui["HUD and menus<br/>UI layer<br/>[index.ts]"]
  node_zoo_platform["Platform adapter<br/>host integration<br/>[PlatformAdapter.ts]"]
  node_zoo_assets["Runtime assets<br/>public assets"]
end

subgraph group_motorworks["Zombie Motorworks"]
  node_motor_entry["Browser entry<br/>Vite entry<br/>[main.ts]"]
  node_motor_app["App and profile layer<br/>application shell<br/>[App.ts]"]
  node_motor_editor["Vehicle editor<br/>build mode<br/>[EditorMode.ts]"]
  node_motor_rules["Core rules<br/>data-oriented domain<br/>[parts.ts]"]
  node_motor_assembly["Vehicle assembly<br/>runtime assembly<br/>[assembler.ts]"]
  node_motor_survival["Survival mode<br/>combat runtime<br/>[SurvivalMode.ts]"]
  node_motor_assets["Runtime assets<br/>public assets"]
end

node_shared_assets -->|"source material"| node_glb_pipeline
node_saved_glbs -->|"GLB input"| node_glb_pipeline
node_glb_voxelizer -->|"voxelization stage"| node_glb_pipeline
node_glb_pipeline -->|"optimized models"| node_glb_rigger
node_glb_pipeline -.->|"runtime artifacts"| node_subway_assets
node_glb_pipeline -.->|"runtime artifacts"| node_zoo_assets
node_glb_pipeline -.->|"runtime artifacts"| node_motor_assets
node_subway_entry -->|"starts"| node_subway_game
node_subway_game -->|"updates"| node_subway_run_systems
node_subway_game -->|"controls"| node_subway_entities
node_subway_game -->|"host lifecycle"| node_subway_platform
node_subway_assets -->|"loads"| node_subway_game
node_zoo_entry -->|"starts"| node_zoo_game_context
node_zoo_game_context -->|"loads"| node_zoo_content
node_zoo_game_context -->|"builds"| node_zoo_world
node_zoo_game_context -->|"runs"| node_zoo_simulation
node_zoo_simulation -->|"state updates"| node_zoo_ui
node_zoo_game_context -->|"host integration"| node_zoo_platform
node_zoo_assets -->|"loads"| node_zoo_game_context
node_motor_entry -->|"starts"| node_motor_app
node_motor_app -->|"opens build mode"| node_motor_editor
node_motor_editor -->|"uses placement and parts"| node_motor_rules
node_motor_editor -->|"produces blueprint"| node_motor_assembly
node_motor_assembly -->|"vehicle to combat"| node_motor_survival
node_motor_rules -->|"rules and saves"| node_motor_survival
node_motor_assets -->|"loads"| node_motor_app

click node_glb_pipeline "https://github.com/josephliao542211/ggstudio/blob/main/glb-pipeline/pipeline.mjs"
click node_glb_voxelizer "https://github.com/josephliao542211/ggstudio/blob/main/glb-pipeline/blender_voxelize.py"
click node_glb_rigger "https://github.com/josephliao542211/ggstudio/blob/main/glb-rigger/rig.mjs"
click node_subway_entry "https://github.com/josephliao542211/ggstudio/blob/main/Subway/src/main.ts"
click node_subway_game "https://github.com/josephliao542211/ggstudio/blob/main/Subway/src/game/Game.ts"
click node_subway_run_systems "https://github.com/josephliao542211/ggstudio/blob/main/Subway/src/systems/Spawner.ts"
click node_subway_entities "https://github.com/josephliao542211/ggstudio/blob/main/Subway/src/game/entities/PlayerAvatar.ts"
click node_subway_platform "https://github.com/josephliao542211/ggstudio/blob/main/Subway/src/platform/PlatformSDK.ts"
click node_subway_assets "https://github.com/josephliao542211/ggstudio/tree/main/Subway/public/assets"
click node_zoo_entry "https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/main.ts"
click node_zoo_game_context "https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/core/GameContext.ts"
click node_zoo_content "https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/data/animals.json"
click node_zoo_world "https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/world/WorldGen.ts"
click node_zoo_simulation "https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/systems/SpawnSystem.ts"
click node_zoo_ui "https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/ui/index.ts"
click node_zoo_platform "https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/platform/PlatformAdapter.ts"
click node_zoo_assets "https://github.com/josephliao542211/ggstudio/tree/main/comfy-zoo/public/assets"
click node_motor_entry "https://github.com/josephliao542211/ggstudio/blob/main/zombie-motorworks/src/app/main.ts"
click node_motor_app "https://github.com/josephliao542211/ggstudio/blob/main/zombie-motorworks/src/app/App.ts"
click node_motor_editor "https://github.com/josephliao542211/ggstudio/blob/main/zombie-motorworks/src/editor/EditorMode.ts"
click node_motor_rules "https://github.com/josephliao542211/ggstudio/blob/main/zombie-motorworks/src/core/parts.ts"
click node_motor_assembly "https://github.com/josephliao542211/ggstudio/blob/main/zombie-motorworks/src/runtime/assembler.ts"
click node_motor_survival "https://github.com/josephliao542211/ggstudio/blob/main/zombie-motorworks/src/survival/SurvivalMode.ts"
click node_motor_assets "https://github.com/josephliao542211/ggstudio/tree/main/zombie-motorworks/public/assets"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_shared_assets,node_saved_glbs,node_glb_pipeline,node_glb_voxelizer,node_glb_rigger toneBlue
class node_subway_entry,node_subway_game,node_subway_run_systems,node_subway_entities,node_subway_platform,node_subway_assets toneAmber
class node_zoo_entry,node_zoo_game_context,node_zoo_content,node_zoo_world,node_zoo_simulation,node_zoo_ui,node_zoo_platform,node_zoo_assets toneMint
class node_motor_entry,node_motor_app,node_motor_editor,node_motor_rules,node_motor_assembly,node_motor_survival,node_motor_assets toneRose
```

## Components

### Asset Production

Shared source assets are transformed into game-ready artifacts.

- **Shared source packs**: asset sources · Licensed art, audio, fonts, and UI source material.
- **Saved GLB inputs**: model sources · Raw and generated GLB pipeline inputs.
- [GLB optimization pipeline](https://github.com/josephliao542211/ggstudio/blob/main/glb-pipeline/pipeline.mjs): asset pipeline · Voxelizes and optimizes textured GLBs for runtime use. · `glb-pipeline/pipeline.mjs`
- [Blender voxelizer](https://github.com/josephliao542211/ggstudio/blob/main/glb-pipeline/blender_voxelize.py): Blender/Python stage · `glb-pipeline/blender_voxelize.py`
- [GLB rigger](https://github.com/josephliao542211/ggstudio/blob/main/glb-rigger/rig.mjs): rigging tool · Applies declarative rigid-part animation hierarchies. · `glb-rigger/rig.mjs`

### Subway

Independent endless-runner build and runtime.

- [Browser entry](https://github.com/josephliao542211/ggstudio/blob/main/Subway/src/main.ts): Vite entry · `Subway/src/main.ts`
- [Game controller](https://github.com/josephliao542211/ggstudio/blob/main/Subway/src/game/Game.ts): runtime loop · Coordinates input, movement, collisions, entities, and effects. · `Subway/src/game/Game.ts`
- [Run progression](https://github.com/josephliao542211/ggstudio/blob/main/Subway/src/systems/Spawner.ts): gameplay systems · Spawning, difficulty, and scoring systems. · `Subway/src/systems/Spawner.ts`
- [Runner world units](https://github.com/josephliao542211/ggstudio/blob/main/Subway/src/game/entities/PlayerAvatar.ts): entities and track · Player, chaser, obstacles, and track. · `Subway/src/game/entities/PlayerAvatar.ts`
- [Platform providers](https://github.com/josephliao542211/ggstudio/blob/main/Subway/src/platform/PlatformSDK.ts): host integration · Abstracts CrazyGames and Poki SDK lifecycles. · `Subway/src/platform/PlatformSDK.ts`
- [Runtime assets](https://github.com/josephliao542211/ggstudio/tree/main/Subway/public/assets): public assets · `Subway/public/assets`

### Comfy Zoo

Independent simulation-game build and runtime.

- [Browser entry](https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/main.ts): Vite entry · `comfy-zoo/src/main.ts`
- [Game context](https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/core/GameContext.ts): core lifecycle · Owns lifecycle, persistence, assets, and spatial queries. · `comfy-zoo/src/core/GameContext.ts`
- [Game content](https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/data/animals.json): data definitions · Animals, balance, and quest definitions. · `comfy-zoo/src/data/animals.json`
- [Generated tile world](https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/world/WorldGen.ts): world model · Tile-grid generation and placement. · `comfy-zoo/src/world/WorldGen.ts`
- [Simulation systems](https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/systems/SpawnSystem.ts): event-driven systems · Spawning, hunger, and economy updates. · `comfy-zoo/src/systems/SpawnSystem.ts`
- [HUD and menus](https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/ui/index.ts): UI layer · `comfy-zoo/src/ui/index.ts`
- [Platform adapter](https://github.com/josephliao542211/ggstudio/blob/main/comfy-zoo/src/platform/PlatformAdapter.ts): host integration · Adapts CrazyGames, Devvit, playable ads, and local hosts. · `comfy-zoo/src/platform/PlatformAdapter.ts`
- [Runtime assets](https://github.com/josephliao542211/ggstudio/tree/main/comfy-zoo/public/assets): public assets · `comfy-zoo/public/assets`

### Zombie Motorworks

Independent build-to-combat game runtime.

- [Browser entry](https://github.com/josephliao542211/ggstudio/blob/main/zombie-motorworks/src/app/main.ts): Vite entry · `zombie-motorworks/src/app/main.ts`
- [App and profile layer](https://github.com/josephliao542211/ggstudio/blob/main/zombie-motorworks/src/app/App.ts): application shell · Launch, profiles, saves, badges, leaderboards, and host access. · `zombie-motorworks/src/app/App.ts`
- [Vehicle editor](https://github.com/josephliao542211/ggstudio/blob/main/zombie-motorworks/src/editor/EditorMode.ts): build mode · Converts grid placement into vehicle blueprints. · `zombie-motorworks/src/editor/EditorMode.ts`
- [Core rules](https://github.com/josephliao542211/ggstudio/blob/main/zombie-motorworks/src/core/parts.ts): data-oriented domain · Parts, economy, damage, progression, and serialization. · `zombie-motorworks/src/core/parts.ts`
- [Vehicle assembly](https://github.com/josephliao542211/ggstudio/blob/main/zombie-motorworks/src/runtime/assembler.ts): runtime assembly · Builds driveable combat vehicles from blueprints. · `zombie-motorworks/src/runtime/assembler.ts`
- [Survival mode](https://github.com/josephliao542211/ggstudio/blob/main/zombie-motorworks/src/survival/SurvivalMode.ts): combat runtime · Runs arenas, waves, zombie AI, combat, camera, and UI. · `zombie-motorworks/src/survival/SurvivalMode.ts`
- [Runtime assets](https://github.com/josephliao542211/ggstudio/tree/main/zombie-motorworks/public/assets): public assets · `zombie-motorworks/public/assets`

## Connections

- Shared source packs → GLB optimization pipeline: source material
- Saved GLB inputs → GLB optimization pipeline: GLB input
- Blender voxelizer → GLB optimization pipeline: voxelization stage
- GLB optimization pipeline → GLB rigger: optimized models
- GLB optimization pipeline → Runtime assets: runtime artifacts
- GLB optimization pipeline → Runtime assets: runtime artifacts
- GLB optimization pipeline → Runtime assets: runtime artifacts
- Browser entry → Game controller: starts
- Game controller → Run progression: updates
- Game controller → Runner world units: controls
- Game controller → Platform providers: host lifecycle
- Runtime assets → Game controller: loads
- Browser entry → Game context: starts
- Game context → Game content: loads
- Game context → Generated tile world: builds
- Game context → Simulation systems: runs
- Simulation systems → HUD and menus: state updates
- Game context → Platform adapter: host integration
- Runtime assets → Game context: loads
- Browser entry → App and profile layer: starts
- App and profile layer → Vehicle editor: opens build mode
- Vehicle editor → Core rules: uses placement and parts
- Vehicle editor → Vehicle assembly: produces blueprint
- Vehicle assembly → Survival mode: vehicle to combat
- Core rules → Survival mode: rules and saves
- Runtime assets → App and profile layer: loads