# warshoow/game-engine architecture

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

- Interactive diagram: https://gitdiagram.com/warshoow/game-engine
- Repository: https://github.com/warshoow/game-engine
- Video tour (about a minute): https://gitdiagram.com/warshoow/game-engine/video

## Overview

This is a Bevy voxel game backed by a hand-written Rust voxel core. The main player workflow is: generate and stream terrain around the player, render chunks, then move, target blocks, and edit them; inventory, dropped items, crafting, and data-defined block behavior extend that loop. Content loading, generated textures, lighting, liquids, and persistence are distinct capabilities. The README documents several subsystems whose implementation details were not sampled; their paths and links are shown only where supported by the tree or documentation.

Main entry points: [`src/main.rs`](https://github.com/warshoow/game-engine/blob/master/src/main.rs) (Bevy application), [`src/interact.rs`](https://github.com/warshoow/game-engine/blob/master/src/interact.rs) (Block interaction), [`crates/voxel_core/src/world.rs`](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/world.rs) (World and chunks), [`src/inventory.rs`](https://github.com/warshoow/game-engine/blob/master/src/inventory.rs) (Inventory and crafting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_game["Bevy game"]
  node_stream["Chunk streaming<br/>[streaming.rs]"]
  node_ui["Game UI<br/>[ui.rs]"]
  node_engine["Bevy application<br/>[main.rs]"]
end

subgraph group_world["Voxel world core"]
  node_terrain["Terrain generation<br/>[worldgen.rs]"]
  node_world["World and chunks<br/>[world.rs]"]
  node_chunk["Palette chunks<br/>[chunk.rs]"]
  node_mesh["Greedy meshing<br/>[mesher.rs]"]
  node_light["Block lighting<br/>[light.rs]"]
  node_liquid["Liquid simulation<br/>[liquids.rs]"]
  node_raycast["Voxel raycast<br/>[raycast.rs]"]
  node_rules["Block rules<br/>[rules.rs]"]
  node_ticks["Block ticks<br/>[ticks.rs]"]
  node_physics["Collision physics<br/>[physics.rs]"]
  node_crafting["Recipe logic<br/>[crafting.rs]"]
  node_core_save["World serialization<br/>[save.rs]"]
end

subgraph group_play["Player gameplay"]
  node_player["FPS controller<br/>[player.rs]"]
  node_interact["Block interaction<br/>[interact.rs]"]
  node_inventory["Inventory and crafting<br/>[inventory.rs]"]
  node_items["Dropped items<br/>[items.rs]"]
end

subgraph group_content["Content and persistence"]
  node_registry["Content registry<br/>[registry.rs]"]
  node_content["Content loading<br/>[content.rs]"]
  node_texgen["Generated textures<br/>[texgen.rs]"]
  node_save["Save system<br/>[save.rs]"]
  node_generator["Generated blocks<br/>[generate.rs]"]
end

node_claude(("Claude CLI"))
node_disk[("Save files")]

node_engine -->|"starts"| node_stream
node_engine -->|"registers"| node_player
node_engine -->|"registers"| node_interact
node_engine -->|"registers"| node_inventory
node_engine -->|"registers"| node_items
node_engine -->|"loads"| node_content
node_engine -->|"loads"| node_save
node_engine -->|"registers"| node_ui
node_engine -->|"registers"| node_generator
node_stream -->|"generates chunks"| node_terrain
node_stream -->|"reads edits"| node_save
node_stream -->|"loads chunks"| node_world
node_world -->|"stores voxels"| node_chunk
node_world -->|"owns content"| node_registry
node_terrain -->|"generates"| node_chunk
node_terrain -->|"resolves blocks"| node_registry
node_mesh -->|"reads voxels"| node_chunk
node_mesh -->|"reads light"| node_light
node_mesh -->|"meshes liquids"| node_liquid
node_light -->|"updates lighting"| node_world
node_liquid -->|"updates voxels"| node_world
node_content -->|"loads data"| node_registry
node_registry -->|"generates textures"| node_texgen
node_player -->|"simulates movement"| node_physics
node_interact -->|"targets blocks"| node_raycast
node_interact -->|"edits blocks"| node_world
node_interact -->|"fires rules"| node_rules
node_interact -->|"advances ticks"| node_ticks
node_interact -->|"reads held item"| node_inventory
node_interact -->|"drops items"| node_items
node_rules -->|"checks world"| node_world
node_ticks -->|"evaluates rules"| node_rules
node_inventory -->|"checks recipes"| node_crafting
node_items -->|"adds pickups"| node_inventory
node_inventory -->|"shows menus"| node_ui
node_generator -->|"requests entry"| node_claude
node_generator -->|"validates blocks"| node_registry
node_save -->|"saves world"| node_core_save
node_core_save -->|"writes state"| node_disk
node_save -->|"persists player"| node_disk

click node_player "https://github.com/warshoow/game-engine/blob/master/src/player.rs"
click node_stream "https://github.com/warshoow/game-engine/blob/master/src/streaming.rs"
click node_terrain "https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/worldgen.rs"
click node_world "https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/world.rs"
click node_chunk "https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/chunk.rs"
click node_mesh "https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/mesher.rs"
click node_light "https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/light.rs"
click node_liquid "https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/liquids.rs"
click node_registry "https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/registry.rs"
click node_content "https://github.com/warshoow/game-engine/blob/master/src/content.rs"
click node_texgen "https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/texgen.rs"
click node_interact "https://github.com/warshoow/game-engine/blob/master/src/interact.rs"
click node_raycast "https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/raycast.rs"
click node_rules "https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/rules.rs"
click node_ticks "https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/ticks.rs"
click node_physics "https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/physics.rs"
click node_inventory "https://github.com/warshoow/game-engine/blob/master/src/inventory.rs"
click node_crafting "https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/crafting.rs"
click node_items "https://github.com/warshoow/game-engine/blob/master/src/items.rs"
click node_ui "https://github.com/warshoow/game-engine/blob/master/src/ui.rs"
click node_save "https://github.com/warshoow/game-engine/blob/master/src/save.rs"
click node_core_save "https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/save.rs"
click node_generator "https://github.com/warshoow/game-engine/blob/master/src/generate.rs"
click node_engine "https://github.com/warshoow/game-engine/blob/master/src/main.rs"

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_stream,node_ui,node_engine toneBlue
class node_terrain,node_world,node_chunk,node_mesh,node_light,node_liquid,node_raycast,node_rules,node_ticks,node_physics,node_crafting,node_core_save,node_disk toneAmber
class node_player,node_interact,node_inventory,node_items toneMint
class node_registry,node_content,node_texgen,node_save,node_generator toneRose
class node_claude toneIndigo
```

## Components

### Bevy game

- [Chunk streaming](https://github.com/warshoow/game-engine/blob/master/src/streaming.rs): `src/streaming.rs`
- [Game UI](https://github.com/warshoow/game-engine/blob/master/src/ui.rs): `src/ui.rs`
- [Bevy application](https://github.com/warshoow/game-engine/blob/master/src/main.rs): `src/main.rs`

### Voxel world core

- [Terrain generation](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/worldgen.rs): `crates/voxel_core/src/worldgen.rs`
- [World and chunks](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/world.rs): `crates/voxel_core/src/world.rs`
- [Palette chunks](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/chunk.rs): `crates/voxel_core/src/chunk.rs`
- [Greedy meshing](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/mesher.rs): `crates/voxel_core/src/mesher.rs`
- [Block lighting](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/light.rs): `crates/voxel_core/src/light.rs`
- [Liquid simulation](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/liquids.rs): `crates/voxel_core/src/liquids.rs`
- [Voxel raycast](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/raycast.rs): `crates/voxel_core/src/raycast.rs`
- [Block rules](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/rules.rs): `crates/voxel_core/src/rules.rs`
- [Block ticks](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/ticks.rs): `crates/voxel_core/src/ticks.rs`
- [Collision physics](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/physics.rs): `crates/voxel_core/src/physics.rs`
- [Recipe logic](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/crafting.rs): `crates/voxel_core/src/crafting.rs`
- [World serialization](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/save.rs): `crates/voxel_core/src/save.rs`

### Player gameplay

- [FPS controller](https://github.com/warshoow/game-engine/blob/master/src/player.rs): `src/player.rs`
- [Block interaction](https://github.com/warshoow/game-engine/blob/master/src/interact.rs): `src/interact.rs`
- [Inventory and crafting](https://github.com/warshoow/game-engine/blob/master/src/inventory.rs): `src/inventory.rs`
- [Dropped items](https://github.com/warshoow/game-engine/blob/master/src/items.rs): `src/items.rs`

### Content and persistence

- [Content registry](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/registry.rs): `crates/voxel_core/src/registry.rs`
- [Content loading](https://github.com/warshoow/game-engine/blob/master/src/content.rs): `src/content.rs`
- [Generated textures](https://github.com/warshoow/game-engine/blob/master/crates/voxel_core/src/texgen.rs): `crates/voxel_core/src/texgen.rs`
- [Save system](https://github.com/warshoow/game-engine/blob/master/src/save.rs): `src/save.rs`
- [Generated blocks](https://github.com/warshoow/game-engine/blob/master/src/generate.rs): `src/generate.rs`

### Other components

- **Claude CLI**
- **Save files**

## Connections

- Bevy application → Chunk streaming: starts (evidence: `src/main.rs`)
- Bevy application → FPS controller: registers (evidence: `src/main.rs`)
- Bevy application → Block interaction: registers (evidence: `src/main.rs`)
- Bevy application → Inventory and crafting: registers (evidence: `src/main.rs`)
- Bevy application → Dropped items: registers (evidence: `src/main.rs`)
- Bevy application → Content loading: loads (evidence: `src/main.rs`)
- Bevy application → Save system: loads (evidence: `src/main.rs`)
- Bevy application → Game UI: registers (evidence: `src/main.rs`)
- Bevy application → Generated blocks: registers (evidence: `src/main.rs`)
- Chunk streaming → Terrain generation: generates chunks (evidence: `README.md`)
- Chunk streaming → Save system: reads edits (evidence: `README.md`)
- Chunk streaming → World and chunks: loads chunks (evidence: `README.md`)
- World and chunks → Palette chunks: stores voxels (evidence: `crates/voxel_core/src/world.rs`)
- World and chunks → Content registry: owns content (evidence: `crates/voxel_core/src/world.rs`)
- Terrain generation → Palette chunks: generates (evidence: `crates/voxel_core/src/worldgen.rs`)
- Terrain generation → Content registry: resolves blocks (evidence: `crates/voxel_core/src/worldgen.rs`)
- Greedy meshing → Palette chunks: reads voxels (evidence: `crates/voxel_core/src/mesher.rs`)
- Greedy meshing → Block lighting: reads light (evidence: `crates/voxel_core/src/mesher.rs`)
- Greedy meshing → Liquid simulation: meshes liquids (evidence: `crates/voxel_core/src/mesher.rs`)
- Block lighting → World and chunks: updates lighting (evidence: `crates/voxel_core/src/light.rs`)
- Liquid simulation → World and chunks: updates voxels (evidence: `crates/voxel_core/src/liquids.rs`)
- Content loading → Content registry: loads data (evidence: `README.md`)
- Content registry → Generated textures: generates textures (evidence: `crates/voxel_core/src/registry.rs`)
- FPS controller → Collision physics: simulates movement (evidence: `src/player.rs`)
- Block interaction → Voxel raycast: targets blocks (evidence: `README.md`)
- Block interaction → World and chunks: edits blocks (evidence: `src/interact.rs`)
- Block interaction → Block rules: fires rules (evidence: `src/interact.rs`)
- Block interaction → Block ticks: advances ticks (evidence: `src/interact.rs`)
- Block interaction → Inventory and crafting: reads held item (evidence: `src/interact.rs`)
- Block interaction → Dropped items: drops items (evidence: `src/interact.rs`)
- Block rules → World and chunks: checks world (evidence: `crates/voxel_core/src/rules.rs`)
- Block ticks → Block rules: evaluates rules (evidence: `crates/voxel_core/src/ticks.rs`)
- Inventory and crafting → Recipe logic: checks recipes (evidence: `crates/voxel_core/src/crafting.rs`)
- Dropped items → Inventory and crafting: adds pickups (evidence: `src/items.rs`)
- Inventory and crafting → Game UI: shows menus (evidence: `src/inventory.rs`)
- Generated blocks → Claude CLI: requests entry (evidence: `README.md`)
- Generated blocks → Content registry: validates blocks (evidence: `README.md`)
- Save system → World serialization: saves world (evidence: `README.md`)
- World serialization → Save files: writes state (evidence: `README.md`)
- Save system → Save files: persists player (evidence: `README.md`)