# fluidtag/voxel-engine architecture

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

- Interactive diagram: https://gitdiagram.com/fluidtag/voxel-engine
- Repository: https://github.com/fluidtag/voxel-engine

## Overview

This is a Java voxel game: the player moves through a procedurally generated world, interacts with blocks and inventory, and sees the result rendered in a window. The visible runtime path starts in App, which creates the world, camera, engine, and player and advances ticks; World coordinates chunk work, while Engine and its render/UI helpers present the scene. The map retains distinct terrain, decoration, lighting, meshing, gameplay, and graphics responsibilities. Some subsystem links rely on SOURCE INDEX references or are omitted where the excerpts do not establish who invokes whom.

Main entry points: [`src/main/java/com/szymc/voxel_engine/App.java`](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/App.java) (Game application), [`src/main/java/com/szymc/voxel_engine/World.java`](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/World.java) (World and chunk scheduling), [`src/main/java/com/szymc/voxel_engine/Engine.java`](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Engine.java) (Game engine), [`src/main/java/com/szymc/voxel_engine/PlayerCharacter.java`](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/PlayerCharacter.java) (Player character)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gameplay["Player gameplay"]
  node_player["Player character"]
  node_items["Dropped items<br/>[EntityItem.java]"]
  node_blocktypes["Block definitions<br/>[Blocks.java]"]
  node_inventory["Inventory and crafting<br/>[Engine.java]"]
end

subgraph group_worldgen["World generation"]
  node_biomes["Biome registry<br/>[BiomeRegistry.java]"]
  node_noise["Noise functions<br/>[FastNoiseLite.java]"]
  node_terrain["Terrain generation<br/>[TerrainTask.java]"]
  node_decoration["Terrain decoration"]
end

subgraph group_chunks["Chunk processing"]
  node_column["Chunk columns<br/>[ChunkColumn.java]"]
  node_section["Chunk sections and palette<br/>[ChunkSection.java]"]
  node_lighting["Chunk lighting<br/>[LightingTask.java]"]
  node_meshing["Greedy meshing<br/>[GreedyMesher.java]"]
  node_meshworker["Mesh task<br/>[MeshTask.java]"]
end

subgraph group_graphics["Rendering and UI"]
  node_mesh["GPU mesh<br/>[Mesh.java]"]
  node_textures["Textures and game data<br/>[Texture.java]"]
  node_shaders["Shader programs<br/>[Shader.java]"]
  node_worldshader["World shader<br/>[WorldShader.java]"]
  node_entityshader["Entity shader<br/>[EntityShader.java]"]
  node_ui["UI renderer<br/>[UIRenderer.java]"]
  node_debug["Debug display<br/>[DebugManager.java]"]
end

subgraph group_runtime["Runtime coordination"]
  node_world["World and chunk scheduling<br/>[World.java]"]
  node_camera["Camera<br/>[Camera.java]"]
  node_engine["Game engine<br/>[Engine.java]"]
  node_window["Window<br/>[Window.java]"]
  node_app["Game application<br/>[App.java]"]
end

node_user(("Player"))

node_user -->|"starts"| node_app
node_app -->|"creates"| node_world
node_app -->|"creates"| node_camera
node_app -->|"creates"| node_window
node_app -->|"creates"| node_engine
node_app -->|"creates"| node_player
node_app -->|"ticks"| node_world
node_app -->|"updates"| node_items
node_app -->|"initializes"| node_biomes
node_world -->|"schedules"| node_terrain
node_world -->|"schedules"| node_decoration
node_world -.->|"schedules"| node_lighting
node_world -.->|"schedules"| node_meshworker
node_terrain -->|"samples"| node_noise
node_terrain -->|"selects"| node_biomes
node_terrain -->|"generates"| node_column
node_decoration -->|"decorates"| node_column
node_world -->|"manages"| node_column
node_column -->|"contains data"| node_section
node_meshworker -->|"requests mesh data"| node_meshing
node_meshing -->|"reads blocks"| node_section
node_section -->|"generates mesh data"| node_meshing
node_world -.->|"serves world queries"| node_player
node_player -->|"reads view"| node_camera
node_player -->|"requests interactions"| node_engine
node_player -->|"edits blocks"| node_column
node_engine -->|"manages"| node_inventory
node_engine -->|"renders world"| node_worldshader
node_engine -->|"renders entities"| node_entityshader
node_engine -->|"updates display"| node_debug
node_engine -->|"renders interface"| node_ui
node_worldshader -->|"extends"| node_shaders
node_entityshader -->|"extends"| node_shaders
node_worldshader -->|"uses"| node_textures
node_entityshader -->|"uses"| node_textures
node_ui -->|"uses"| node_textures
node_ui -->|"uses"| node_shaders
node_textures -.->|"loads definitions"| node_blocktypes
node_meshworker -.->|"creates GPU mesh"| node_mesh
node_engine -.->|"draws meshes"| node_mesh

click node_player "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/PlayerCharacter.java"
click node_items "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/EntityItem.java"
click node_blocktypes "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Blocks.java"
click node_inventory "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Engine.java"
click node_biomes "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/BiomeRegistry.java"
click node_noise "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/FastNoiseLite.java"
click node_terrain "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/TerrainTask.java"
click node_decoration "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/DecorationTask.java"
click node_world "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/World.java"
click node_column "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/ChunkColumn.java"
click node_section "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/ChunkSection.java"
click node_lighting "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/LightingTask.java"
click node_meshing "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/GreedyMesher.java"
click node_meshworker "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/MeshTask.java"
click node_mesh "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Mesh.java"
click node_camera "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Camera.java"
click node_engine "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Engine.java"
click node_window "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Window.java"
click node_app "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/App.java"
click node_textures "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Texture.java"
click node_shaders "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/localShaders/Shader.java"
click node_worldshader "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/localShaders/WorldShader.java"
click node_entityshader "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/localShaders/EntityShader.java"
click node_ui "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/UIRenderer.java"
click node_debug "https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/DebugManager.java"

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_player,node_items,node_blocktypes,node_inventory toneBlue
class node_biomes,node_noise,node_terrain,node_decoration toneAmber
class node_column,node_section,node_lighting,node_meshing,node_meshworker toneMint
class node_mesh,node_textures,node_shaders,node_worldshader,node_entityshader,node_ui,node_debug toneRose
class node_world,node_camera,node_engine,node_window,node_app,node_user toneIndigo
```

## Components

### Player gameplay

- [Player character](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/PlayerCharacter.java): `src/main/java/com/szymc/voxel_engine/PlayerCharacter.java`
- [Dropped items](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/EntityItem.java): `src/main/java/com/szymc/voxel_engine/EntityItem.java`
- [Block definitions](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Blocks.java): `src/main/java/com/szymc/voxel_engine/Blocks.java`
- [Inventory and crafting](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Engine.java): `src/main/java/com/szymc/voxel_engine/Engine.java`

### World generation

- [Biome registry](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/BiomeRegistry.java): `src/main/java/com/szymc/voxel_engine/BiomeRegistry.java`
- [Noise functions](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/FastNoiseLite.java): `src/main/java/com/szymc/voxel_engine/FastNoiseLite.java`
- [Terrain generation](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/TerrainTask.java): `src/main/java/com/szymc/voxel_engine/TerrainTask.java`
- [Terrain decoration](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/DecorationTask.java): `src/main/java/com/szymc/voxel_engine/DecorationTask.java`

### Chunk processing

- [Chunk columns](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/ChunkColumn.java): `src/main/java/com/szymc/voxel_engine/ChunkColumn.java`
- [Chunk sections and palette](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/ChunkSection.java): `src/main/java/com/szymc/voxel_engine/ChunkSection.java`
- [Chunk lighting](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/LightingTask.java): `src/main/java/com/szymc/voxel_engine/LightingTask.java`
- [Greedy meshing](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/GreedyMesher.java): `src/main/java/com/szymc/voxel_engine/GreedyMesher.java`
- [Mesh task](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/MeshTask.java): `src/main/java/com/szymc/voxel_engine/MeshTask.java`

### Rendering and UI

- [GPU mesh](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Mesh.java): `src/main/java/com/szymc/voxel_engine/Mesh.java`
- [Textures and game data](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Texture.java): `src/main/java/com/szymc/voxel_engine/Texture.java`
- [Shader programs](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/localShaders/Shader.java): `src/main/java/com/szymc/localShaders/Shader.java`
- [World shader](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/localShaders/WorldShader.java): `src/main/java/com/szymc/localShaders/WorldShader.java`
- [Entity shader](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/localShaders/EntityShader.java): `src/main/java/com/szymc/localShaders/EntityShader.java`
- [UI renderer](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/UIRenderer.java): `src/main/java/com/szymc/voxel_engine/UIRenderer.java`
- [Debug display](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/DebugManager.java): `src/main/java/com/szymc/voxel_engine/DebugManager.java`

### Runtime coordination

- [World and chunk scheduling](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/World.java): `src/main/java/com/szymc/voxel_engine/World.java`
- [Camera](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Camera.java): `src/main/java/com/szymc/voxel_engine/Camera.java`
- [Game engine](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Engine.java): `src/main/java/com/szymc/voxel_engine/Engine.java`
- [Window](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/Window.java): `src/main/java/com/szymc/voxel_engine/Window.java`
- [Game application](https://github.com/fluidtag/voxel-engine/blob/main/src/main/java/com/szymc/voxel_engine/App.java): `src/main/java/com/szymc/voxel_engine/App.java`

### Other components

- **Player**

## Connections

- Player → Game application: starts (evidence: `src/main/java/com/szymc/voxel_engine/App.java`)
- Game application → World and chunk scheduling: creates (evidence: `src/main/java/com/szymc/voxel_engine/App.java`)
- Game application → Camera: creates (evidence: `src/main/java/com/szymc/voxel_engine/App.java`)
- Game application → Window: creates (evidence: `src/main/java/com/szymc/voxel_engine/App.java`)
- Game application → Game engine: creates (evidence: `src/main/java/com/szymc/voxel_engine/App.java`)
- Game application → Player character: creates (evidence: `src/main/java/com/szymc/voxel_engine/App.java`)
- Game application → World and chunk scheduling: ticks (evidence: `src/main/java/com/szymc/voxel_engine/App.java`)
- Game application → Dropped items: updates (evidence: `src/main/java/com/szymc/voxel_engine/App.java`)
- Game application → Biome registry: initializes (evidence: `src/main/java/com/szymc/voxel_engine/App.java`)
- World and chunk scheduling → Terrain generation: schedules (evidence: `src/main/java/com/szymc/voxel_engine/World.java`)
- World and chunk scheduling → Terrain decoration: schedules (evidence: `src/main/java/com/szymc/voxel_engine/World.java`)
- World and chunk scheduling → Chunk lighting: schedules (evidence: `src/main/java/com/szymc/voxel_engine/World.java`)
- World and chunk scheduling → Mesh task: schedules (evidence: `src/main/java/com/szymc/voxel_engine/World.java`)
- Terrain generation → Noise functions: samples (evidence: `src/main/java/com/szymc/voxel_engine/TerrainTask.java`)
- Terrain generation → Biome registry: selects (evidence: `src/main/java/com/szymc/voxel_engine/TerrainTask.java`)
- Terrain generation → Chunk columns: generates (evidence: `src/main/java/com/szymc/voxel_engine/TerrainTask.java`)
- Terrain decoration → Chunk columns: decorates (evidence: `src/main/java/com/szymc/voxel_engine/DecorationTask.java`)
- World and chunk scheduling → Chunk columns: manages (evidence: `src/main/java/com/szymc/voxel_engine/World.java`)
- Chunk columns → Chunk sections and palette: contains data (evidence: `src/main/java/com/szymc/voxel_engine/ChunkColumn.java`)
- Mesh task → Greedy meshing: requests mesh data (evidence: `src/main/java/com/szymc/voxel_engine/MeshTask.java`)
- Greedy meshing → Chunk sections and palette: reads blocks (evidence: `src/main/java/com/szymc/voxel_engine/GreedyMesher.java`)
- Chunk sections and palette → Greedy meshing: generates mesh data (evidence: `src/main/java/com/szymc/voxel_engine/ChunkSection.java`)
- World and chunk scheduling → Player character: serves world queries (evidence: `src/main/java/com/szymc/voxel_engine/PlayerCharacter.java`)
- Player character → Camera: reads view (evidence: `src/main/java/com/szymc/voxel_engine/PlayerCharacter.java`)
- Player character → Game engine: requests interactions (evidence: `src/main/java/com/szymc/voxel_engine/PlayerCharacter.java`)
- Player character → Chunk columns: edits blocks (evidence: `src/main/java/com/szymc/voxel_engine/PlayerCharacter.java`)
- Game engine → Inventory and crafting: manages (evidence: `src/main/java/com/szymc/voxel_engine/Engine.java`)
- Game engine → World shader: renders world (evidence: `src/main/java/com/szymc/voxel_engine/Engine.java`)
- Game engine → Entity shader: renders entities (evidence: `src/main/java/com/szymc/voxel_engine/Engine.java`)
- Game engine → Debug display: updates display (evidence: `src/main/java/com/szymc/voxel_engine/Engine.java`)
- Game engine → UI renderer: renders interface (evidence: `src/main/java/com/szymc/voxel_engine/Engine.java`)
- World shader → Shader programs: extends (evidence: `src/main/java/com/szymc/localShaders/WorldShader.java`)
- Entity shader → Shader programs: extends (evidence: `src/main/java/com/szymc/localShaders/EntityShader.java`)
- World shader → Textures and game data: uses (evidence: `src/main/java/com/szymc/localShaders/WorldShader.java`)
- Entity shader → Textures and game data: uses (evidence: `src/main/java/com/szymc/localShaders/EntityShader.java`)
- UI renderer → Textures and game data: uses (evidence: `src/main/java/com/szymc/voxel_engine/UIRenderer.java`)
- UI renderer → Shader programs: uses (evidence: `src/main/java/com/szymc/voxel_engine/UIRenderer.java`)
- Textures and game data → Block definitions: loads definitions (evidence: `src/main/java/com/szymc/voxel_engine/Engine.java`)
- Mesh task → GPU mesh: creates GPU mesh
- Game engine → GPU mesh: draws meshes
