# samadipour/snack-hole-game architecture

> Architecture diagram of the GitHub repository samadipour/snack-hole-game, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samadipour/snack-hole-game
- Repository: https://github.com/samadipour/snack-hole-game

## Overview

Snack Hole is a browser game: players steer a growing hole through timed rounds or a relaxed Tour, swallow props to grow and earn cash, then spend or prestige to advance. The runtime centers on the game controller and World simulation, with procedural maps, economy/save state, rendering, audio, and UI supporting that loop. The README also documents trophies, collection, abilities, helper holes, and offline play. Balance simulation is a substantial companion subsystem; its sampled files show simulated rounds and whole-playthrough evaluation. Some UI and runtime connections are based on the source index, not inspected implementation excerpts.

Main entry points: [`src/game.ts`](https://github.com/samadipour/snack-hole-game/blob/main/src/game.ts) (Game Controller), [`balance/lib/progress.ts`](https://github.com/samadipour/snack-hole-game/blob/main/balance/lib/progress.ts) (Playthrough Evaluator), [`balance/lib/round.ts`](https://github.com/samadipour/snack-hole-game/blob/main/balance/lib/round.ts) (Simulated Rounds), [`src/core/world.ts`](https://github.com/samadipour/snack-hole-game/blob/main/src/core/world.ts) (World Simulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Game Runtime"]
  node_controller["Game Controller<br/>[game.ts]"]
  node_pwa["Offline Install<br/>[pwa.ts]"]
end

subgraph group_world["World And Progression"]
  node_worldsim["World Simulation<br/>[world.ts]"]
  node_rounds["Timed Rounds<br/>[round.ts]"]
  node_tour["Casual Tour<br/>[tour.ts]"]
  node_mapdispatch["Map Selection<br/>[index.ts]"]
  node_mapbuilder["Map Builder<br/>[builder.ts]"]
  node_mapsets["Map Variants"]
  node_economy["Economy And Prestige<br/>[economy.ts]"]
  node_save["Save Data<br/>[save.ts]"]
  node_achievements["Trophies<br/>[achievements.ts]"]
  node_persistence["Local Persistence<br/>[persistence.ts]"]
end

subgraph group_presentation["Player Experience"]
  node_input["Input Controls<br/>[input.ts]"]
  node_renderer["3D Renderer<br/>[scene.ts]"]
  node_props["Prop Geometry<br/>[props.ts]"]
  node_hud["Round HUD<br/>[hud.ts]"]
  node_hub["Hub And Shop<br/>[tabs.ts]"]
  node_dialogs["Menus And Dialogs<br/>[dialogs.ts]"]
  node_audio["Sound And Music<br/>[audio.ts]"]
end

subgraph group_balance["Balance Simulation"]
  node_balance_round["Simulated Rounds<br/>[round.ts]"]
  node_bots["Player Bots<br/>[bots.ts]"]
  node_progress["Playthrough Evaluator<br/>[progress.ts]"]
  node_balance_model["Round Model<br/>[model.ts]"]
  node_balance_params["Tuning Parameters<br/>[params.ts]"]
  node_balance_report["Balance Reports<br/>[report.ts]"]
end

node_player(("Player"))

node_player -->|"steers"| node_input
node_input -.->|"sends controls"| node_controller
node_controller -->|"creates and updates"| node_worldsim
node_controller -->|"generates maps"| node_mapdispatch
node_mapdispatch -->|"uses builder"| node_mapbuilder
node_mapdispatch -->|"dispatches maps"| node_mapsets
node_controller -->|"runs rounds"| node_rounds
node_controller -->|"runs Tour"| node_tour
node_worldsim -->|"uses formulas"| node_economy
node_rounds -->|"uses simulation"| node_worldsim
node_tour -->|"uses round logic"| node_rounds
node_controller -->|"applies progression"| node_economy
node_controller -->|"serializes progress"| node_save
node_controller -->|"loads and saves"| node_persistence
node_controller -->|"checks trophies"| node_achievements
node_controller -->|"sets world"| node_renderer
node_renderer -->|"uses geometry"| node_props
node_controller -.->|"configures HUD"| node_hud
node_controller -.->|"shows hub"| node_hub
node_controller -->|"checks modal state"| node_dialogs
node_controller -->|"unlocks audio"| node_audio
node_controller -.->|"initializes PWA"| node_pwa
node_balance_round -->|"drives simulated players"| node_bots
node_balance_round -->|"simulates rounds"| node_worldsim
node_progress -->|"runs direct rounds"| node_balance_round
node_progress -->|"samples predictions"| node_balance_model
node_progress -->|"applies tuning"| node_balance_params
node_balance_model -->|"uses parameter set"| node_balance_params
node_balance_report -->|"evaluates playthroughs"| node_progress
node_balance_report -->|"uses round results"| node_balance_round

click node_controller "https://github.com/samadipour/snack-hole-game/blob/main/src/game.ts"
click node_input "https://github.com/samadipour/snack-hole-game/blob/main/src/ui/input.ts"
click node_worldsim "https://github.com/samadipour/snack-hole-game/blob/main/src/core/world.ts"
click node_rounds "https://github.com/samadipour/snack-hole-game/blob/main/src/core/round.ts"
click node_tour "https://github.com/samadipour/snack-hole-game/blob/main/src/core/tour.ts"
click node_mapdispatch "https://github.com/samadipour/snack-hole-game/blob/main/src/core/mapgen/index.ts"
click node_mapbuilder "https://github.com/samadipour/snack-hole-game/blob/main/src/core/mapgen/builder.ts"
click node_mapsets "https://github.com/samadipour/snack-hole-game/tree/main/src/core/mapgen"
click node_economy "https://github.com/samadipour/snack-hole-game/blob/main/src/core/economy.ts"
click node_save "https://github.com/samadipour/snack-hole-game/blob/main/src/core/save.ts"
click node_achievements "https://github.com/samadipour/snack-hole-game/blob/main/src/core/achievements.ts"
click node_persistence "https://github.com/samadipour/snack-hole-game/blob/main/src/persistence.ts"
click node_renderer "https://github.com/samadipour/snack-hole-game/blob/main/src/render/scene.ts"
click node_props "https://github.com/samadipour/snack-hole-game/blob/main/src/render/props.ts"
click node_hud "https://github.com/samadipour/snack-hole-game/blob/main/src/ui/hud.ts"
click node_hub "https://github.com/samadipour/snack-hole-game/blob/main/src/ui/tabs.ts"
click node_dialogs "https://github.com/samadipour/snack-hole-game/blob/main/src/ui/dialogs.ts"
click node_audio "https://github.com/samadipour/snack-hole-game/blob/main/src/audio/audio.ts"
click node_pwa "https://github.com/samadipour/snack-hole-game/blob/main/src/pwa.ts"
click node_balance_round "https://github.com/samadipour/snack-hole-game/blob/main/balance/lib/round.ts"
click node_bots "https://github.com/samadipour/snack-hole-game/blob/main/balance/lib/bots.ts"
click node_progress "https://github.com/samadipour/snack-hole-game/blob/main/balance/lib/progress.ts"
click node_balance_model "https://github.com/samadipour/snack-hole-game/blob/main/balance/lib/model.ts"
click node_balance_params "https://github.com/samadipour/snack-hole-game/blob/main/balance/lib/params.ts"
click node_balance_report "https://github.com/samadipour/snack-hole-game/blob/main/balance/report.ts"

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_controller,node_pwa toneBlue
class node_worldsim,node_rounds,node_tour,node_mapdispatch,node_mapbuilder,node_mapsets,node_economy,node_save,node_achievements,node_persistence toneAmber
class node_input,node_renderer,node_props,node_hud,node_hub,node_dialogs,node_audio toneMint
class node_balance_round,node_bots,node_progress,node_balance_model,node_balance_params,node_balance_report toneRose
class node_player toneIndigo
```

## Components

### Game Runtime

- [Game Controller](https://github.com/samadipour/snack-hole-game/blob/main/src/game.ts): `src/game.ts`
- [Offline Install](https://github.com/samadipour/snack-hole-game/blob/main/src/pwa.ts): `src/pwa.ts`

### World And Progression

- [World Simulation](https://github.com/samadipour/snack-hole-game/blob/main/src/core/world.ts): `src/core/world.ts`
- [Timed Rounds](https://github.com/samadipour/snack-hole-game/blob/main/src/core/round.ts): `src/core/round.ts`
- [Casual Tour](https://github.com/samadipour/snack-hole-game/blob/main/src/core/tour.ts): `src/core/tour.ts`
- [Map Selection](https://github.com/samadipour/snack-hole-game/blob/main/src/core/mapgen/index.ts): `src/core/mapgen/index.ts`
- [Map Builder](https://github.com/samadipour/snack-hole-game/blob/main/src/core/mapgen/builder.ts): `src/core/mapgen/builder.ts`
- [Map Variants](https://github.com/samadipour/snack-hole-game/tree/main/src/core/mapgen): `src/core/mapgen`
- [Economy And Prestige](https://github.com/samadipour/snack-hole-game/blob/main/src/core/economy.ts): `src/core/economy.ts`
- [Save Data](https://github.com/samadipour/snack-hole-game/blob/main/src/core/save.ts): `src/core/save.ts`
- [Trophies](https://github.com/samadipour/snack-hole-game/blob/main/src/core/achievements.ts): `src/core/achievements.ts`
- [Local Persistence](https://github.com/samadipour/snack-hole-game/blob/main/src/persistence.ts): `src/persistence.ts`

### Player Experience

- [Input Controls](https://github.com/samadipour/snack-hole-game/blob/main/src/ui/input.ts): `src/ui/input.ts`
- [3D Renderer](https://github.com/samadipour/snack-hole-game/blob/main/src/render/scene.ts): `src/render/scene.ts`
- [Prop Geometry](https://github.com/samadipour/snack-hole-game/blob/main/src/render/props.ts): `src/render/props.ts`
- [Round HUD](https://github.com/samadipour/snack-hole-game/blob/main/src/ui/hud.ts): `src/ui/hud.ts`
- [Hub And Shop](https://github.com/samadipour/snack-hole-game/blob/main/src/ui/tabs.ts): `src/ui/tabs.ts`
- [Menus And Dialogs](https://github.com/samadipour/snack-hole-game/blob/main/src/ui/dialogs.ts): `src/ui/dialogs.ts`
- [Sound And Music](https://github.com/samadipour/snack-hole-game/blob/main/src/audio/audio.ts): `src/audio/audio.ts`

### Balance Simulation

- [Simulated Rounds](https://github.com/samadipour/snack-hole-game/blob/main/balance/lib/round.ts): `balance/lib/round.ts`
- [Player Bots](https://github.com/samadipour/snack-hole-game/blob/main/balance/lib/bots.ts): `balance/lib/bots.ts`
- [Playthrough Evaluator](https://github.com/samadipour/snack-hole-game/blob/main/balance/lib/progress.ts): `balance/lib/progress.ts`
- [Round Model](https://github.com/samadipour/snack-hole-game/blob/main/balance/lib/model.ts): `balance/lib/model.ts`
- [Tuning Parameters](https://github.com/samadipour/snack-hole-game/blob/main/balance/lib/params.ts): `balance/lib/params.ts`
- [Balance Reports](https://github.com/samadipour/snack-hole-game/blob/main/balance/report.ts): `balance/report.ts`

### Other components

- **Player**

## Connections

- Player → Input Controls: steers
- Input Controls → Game Controller: sends controls (evidence: `src/game.ts`)
- Game Controller → World Simulation: creates and updates (evidence: `src/game.ts`)
- Game Controller → Map Selection: generates maps (evidence: `src/game.ts`)
- Map Selection → Map Builder: uses builder (evidence: `src/core/mapgen/index.ts`)
- Map Selection → Map Variants: dispatches maps (evidence: `src/core/mapgen/index.ts`)
- Game Controller → Timed Rounds: runs rounds (evidence: `src/game.ts`)
- Game Controller → Casual Tour: runs Tour (evidence: `src/game.ts`)
- World Simulation → Economy And Prestige: uses formulas (evidence: `src/core/world.ts`)
- Timed Rounds → World Simulation: uses simulation (evidence: `src/core/round.ts`)
- Casual Tour → Timed Rounds: uses round logic (evidence: `src/core/tour.ts`)
- Game Controller → Economy And Prestige: applies progression (evidence: `src/game.ts`)
- Game Controller → Save Data: serializes progress (evidence: `src/game.ts`)
- Game Controller → Local Persistence: loads and saves (evidence: `src/game.ts`)
- Game Controller → Trophies: checks trophies (evidence: `src/game.ts`)
- Game Controller → 3D Renderer: sets world (evidence: `src/game.ts`)
- 3D Renderer → Prop Geometry: uses geometry (evidence: `src/render/scene.ts`)
- Game Controller → Round HUD: configures HUD (evidence: `src/game.ts`)
- Game Controller → Hub And Shop: shows hub (evidence: `src/game.ts`)
- Game Controller → Menus And Dialogs: checks modal state (evidence: `src/game.ts`)
- Game Controller → Sound And Music: unlocks audio (evidence: `src/game.ts`)
- Game Controller → Offline Install: initializes PWA
- Simulated Rounds → Player Bots: drives simulated players (evidence: `balance/lib/round.ts`)
- Simulated Rounds → World Simulation: simulates rounds (evidence: `balance/lib/round.ts`)
- Playthrough Evaluator → Simulated Rounds: runs direct rounds (evidence: `balance/lib/progress.ts`)
- Playthrough Evaluator → Round Model: samples predictions (evidence: `balance/lib/progress.ts`)
- Playthrough Evaluator → Tuning Parameters: applies tuning (evidence: `balance/lib/progress.ts`)
- Round Model → Tuning Parameters: uses parameter set (evidence: `balance/lib/model.ts`)
- Balance Reports → Playthrough Evaluator: evaluates playthroughs (evidence: `balance/report.ts`)
- Balance Reports → Simulated Rounds: uses round results (evidence: `balance/report.ts`)