# plasma4/depthwell architecture

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

- Interactive diagram: https://gitdiagram.com/plasma4/depthwell
- Repository: https://github.com/plasma4/depthwell
- Video tour (about a minute): https://gitdiagram.com/plasma4/depthwell/video

## Overview

Depthwell is a browser-based procedural mining game. The player supplies keyboard and pointer input; the browser runtime runs the game loop and WebGPU presentation, while Zig/WASM implements game state and world behavior. The README documents mining, inventory, crafting and smelting, portal-driven depth changes, procedural worlds, debug controls, and saves. The excerpts show the browser/WASM setup and save-worker protocol, but most Zig implementation is unsampled, so internal gameplay links are omitted where their callers cannot be verified.

Main entry points: [`src/saveManager.ts`](https://github.com/plasma4/depthwell/blob/main/src/saveManager.ts) (Save Manager), [`src/engine.ts`](https://github.com/plasma4/depthwell/blob/main/src/engine.ts) (Browser Engine), [`src/engineMaker.ts`](https://github.com/plasma4/depthwell/blob/main/src/engineMaker.ts) (Engine Setup), [`zig/state/procedural.zig`](https://github.com/plasma4/depthwell/blob/main/zig/state/procedural.zig) (Procedural World)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Browser Runtime"]
  node_game_loop["Game Loop<br/>[main.ts]"]
  node_input["Input Handling<br/>[inputManager.ts]"]
  node_engine_setup["Engine Setup<br/>[engineMaker.ts]"]
  node_engine["Browser Engine<br/>[engine.ts]"]
  node_wasm_api["WASM Interface<br/>[enums.ts]"]
  node_render["WebGPU Rendering<br/>[engine.ts]"]
  node_shader["Game Shader<br/>[shader.wgsl]"]
end

subgraph group_world["World and Progression"]
  node_seed["Seed Generation<br/>[seeding.ts]"]
  node_world_generation["Procedural World<br/>[procedural.zig]"]
  node_world_state["World State<br/>[world.zig]"]
  node_depth_progression["Portal Depths<br/>[portal.zig]"]
end

subgraph group_gameplay["Gameplay Systems"]
  node_player_state["Player State<br/>[player.zig]"]
  node_mining["Mining<br/>[mining.zig]"]
  node_inventory["Inventory<br/>[inventory.zig]"]
  node_menus["Crafting and Smelting"]
  node_game_tick["Game Simulation<br/>[tick.zig]"]
end

subgraph group_persistence["Persistence"]
  node_save_manager["Save Manager<br/>[saveManager.ts]"]
  node_save_worker["Emergency Save Worker<br/>[saveWorker.ts]"]
  node_world_save["World Save State<br/>[save.zig]"]
  node_opfs[("Browser OPFS")]
end

node_player(("Player"))

node_player -->|"plays"| node_game_loop
node_game_loop -->|"runs ticks"| node_engine
node_engine_setup -->|"creates"| node_engine
node_engine_setup -->|"initializes"| node_save_manager
node_engine -->|"uses bindings"| node_wasm_api
node_engine_setup -->|"loads shader"| node_shader
node_engine -->|"renders game"| node_render
node_player -->|"provides keys"| node_input
node_player -->|"mines blocks"| node_mining
node_player -->|"selects items"| node_inventory
node_player -->|"uses interactables"| node_menus
node_world_generation -.->|"generates world"| node_world_state
node_seed -.->|"seeds maps"| node_world_generation
node_player_state -.->|"changes depth"| node_depth_progression
node_depth_progression -->|"inherits materials"| node_world_generation
node_game_tick -.->|"advances state"| node_player_state
node_player -->|"uses portals"| node_depth_progression
node_save_manager -.->|"serializes state"| node_world_save
node_save_manager -->|"sends emergency saves"| node_save_worker
node_save_worker -->|"writes emergency slot"| node_opfs
node_save_manager -->|"stores saves"| node_opfs

click node_game_loop "https://github.com/plasma4/depthwell/blob/main/src/main.ts"
click node_input "https://github.com/plasma4/depthwell/blob/main/src/inputManager.ts"
click node_engine_setup "https://github.com/plasma4/depthwell/blob/main/src/engineMaker.ts"
click node_engine "https://github.com/plasma4/depthwell/blob/main/src/engine.ts"
click node_wasm_api "https://github.com/plasma4/depthwell/blob/main/src/enums.ts"
click node_render "https://github.com/plasma4/depthwell/blob/main/src/engine.ts"
click node_shader "https://github.com/plasma4/depthwell/blob/main/src/shader.wgsl"
click node_seed "https://github.com/plasma4/depthwell/blob/main/src/seeding.ts"
click node_world_generation "https://github.com/plasma4/depthwell/blob/main/zig/state/procedural.zig"
click node_world_state "https://github.com/plasma4/depthwell/blob/main/zig/state/world.zig"
click node_depth_progression "https://github.com/plasma4/depthwell/blob/main/zig/state/portal.zig"
click node_player_state "https://github.com/plasma4/depthwell/blob/main/zig/state/player.zig"
click node_mining "https://github.com/plasma4/depthwell/blob/main/zig/input/mining.zig"
click node_inventory "https://github.com/plasma4/depthwell/blob/main/zig/input/inventory.zig"
click node_menus "https://github.com/plasma4/depthwell/tree/main/zig/menus"
click node_game_tick "https://github.com/plasma4/depthwell/blob/main/zig/state/tick.zig"
click node_save_manager "https://github.com/plasma4/depthwell/blob/main/src/saveManager.ts"
click node_save_worker "https://github.com/plasma4/depthwell/blob/main/src/saveWorker.ts"
click node_world_save "https://github.com/plasma4/depthwell/blob/main/zig/state/save.zig"

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_game_loop,node_input,node_engine_setup,node_engine,node_wasm_api,node_render,node_shader toneBlue
class node_seed,node_world_generation,node_world_state,node_depth_progression toneAmber
class node_player_state,node_mining,node_inventory,node_menus,node_game_tick toneMint
class node_save_manager,node_save_worker,node_world_save,node_opfs toneRose
class node_player toneIndigo
```

## Components

### Browser Runtime

- [Game Loop](https://github.com/plasma4/depthwell/blob/main/src/main.ts): `src/main.ts`
- [Input Handling](https://github.com/plasma4/depthwell/blob/main/src/inputManager.ts): `src/inputManager.ts`
- [Engine Setup](https://github.com/plasma4/depthwell/blob/main/src/engineMaker.ts): `src/engineMaker.ts`
- [Browser Engine](https://github.com/plasma4/depthwell/blob/main/src/engine.ts): `src/engine.ts`
- [WASM Interface](https://github.com/plasma4/depthwell/blob/main/src/enums.ts): `src/enums.ts`
- [WebGPU Rendering](https://github.com/plasma4/depthwell/blob/main/src/engine.ts): `src/engine.ts`
- [Game Shader](https://github.com/plasma4/depthwell/blob/main/src/shader.wgsl): `src/shader.wgsl`

### World and Progression

- [Seed Generation](https://github.com/plasma4/depthwell/blob/main/src/seeding.ts): `src/seeding.ts`
- [Procedural World](https://github.com/plasma4/depthwell/blob/main/zig/state/procedural.zig): `zig/state/procedural.zig`
- [World State](https://github.com/plasma4/depthwell/blob/main/zig/state/world.zig): `zig/state/world.zig`
- [Portal Depths](https://github.com/plasma4/depthwell/blob/main/zig/state/portal.zig): `zig/state/portal.zig`

### Gameplay Systems

- [Player State](https://github.com/plasma4/depthwell/blob/main/zig/state/player.zig): `zig/state/player.zig`
- [Mining](https://github.com/plasma4/depthwell/blob/main/zig/input/mining.zig): `zig/input/mining.zig`
- [Inventory](https://github.com/plasma4/depthwell/blob/main/zig/input/inventory.zig): `zig/input/inventory.zig`
- [Crafting and Smelting](https://github.com/plasma4/depthwell/tree/main/zig/menus): `zig/menus`
- [Game Simulation](https://github.com/plasma4/depthwell/blob/main/zig/state/tick.zig): `zig/state/tick.zig`

### Persistence

- [Save Manager](https://github.com/plasma4/depthwell/blob/main/src/saveManager.ts): `src/saveManager.ts`
- [Emergency Save Worker](https://github.com/plasma4/depthwell/blob/main/src/saveWorker.ts): `src/saveWorker.ts`
- [World Save State](https://github.com/plasma4/depthwell/blob/main/zig/state/save.zig): `zig/state/save.zig`
- **Browser OPFS**

### Other components

- **Player**

## Connections

- Player → Game Loop: plays (evidence: `README.md`)
- Game Loop → Browser Engine: runs ticks (evidence: `src/main.ts`)
- Engine Setup → Browser Engine: creates (evidence: `src/engineMaker.ts`)
- Engine Setup → Save Manager: initializes (evidence: `src/engineMaker.ts`)
- Browser Engine → WASM Interface: uses bindings (evidence: `src/engine.ts`)
- Engine Setup → Game Shader: loads shader (evidence: `src/engineMaker.ts`)
- Browser Engine → WebGPU Rendering: renders game (evidence: `README.md`)
- Player → Input Handling: provides keys (evidence: `README.md`)
- Player → Mining: mines blocks (evidence: `README.md`)
- Player → Inventory: selects items (evidence: `README.md`)
- Player → Crafting and Smelting: uses interactables (evidence: `README.md`)
- Procedural World → World State: generates world
- Seed Generation → Procedural World: seeds maps
- Player State → Portal Depths: changes depth
- Portal Depths → Procedural World: inherits materials (evidence: `README.md`)
- Game Simulation → Player State: advances state
- Player → Portal Depths: uses portals (evidence: `README.md`)
- Save Manager → World Save State: serializes state
- Save Manager → Emergency Save Worker: sends emergency saves (evidence: `src/saveManager.ts`)
- Emergency Save Worker → Browser OPFS: writes emergency slot (evidence: `src/saveWorker.ts`)
- Save Manager → Browser OPFS: stores saves (evidence: `src/saveManager.ts`)