# kinncj/mindcraft architecture

> Architecture diagram of the GitHub repository kinncj/mindcraft, 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/kinncj/mindcraft
- Repository: https://github.com/kinncj/mindcraft

## Overview

MindCraft is a browser-only, kid-friendly creative voxel game. A player uses the on-screen controls to explore an infinite world, place and shape blocks, and interact with creatures; the game engine handles simulation and rendering while the game store saves world state locally. The README also documents building tools, crafting, dress-up, vehicles, weather, and villager-driven construction. Some subsystems are represented from documented capabilities and the source index; unsampled implementation details and their internal links are not assumed.

Main entry points: [`src/engine/core/Engine.ts`](https://github.com/kinncj/mindcraft/blob/main/src/engine/core/Engine.ts) (Game engine), [`src/game/gameStore.ts`](https://github.com/kinncj/mindcraft/blob/main/src/game/gameStore.ts) (Game state), [`src/storage/worldStore.ts`](https://github.com/kinncj/mindcraft/blob/main/src/storage/worldStore.ts) (World persistence), [`src/engine/world/ChunkManager.ts`](https://github.com/kinncj/mindcraft/blob/main/src/engine/world/ChunkManager.ts) (Chunk streaming)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Game interface"]
  node_app["Game interface<br/>[App.tsx]"]
  node_canvas["Game canvas<br/>[GameCanvas.tsx]"]
  node_store["Game state<br/>[gameStore.ts]"]
  node_menu["World menu<br/>[MenuPanel.tsx]"]
end

subgraph group_simulation["World simulation"]
  node_engine["Game engine<br/>[Engine.ts]"]
  node_entities["Creatures and player<br/>[EntitySystem.ts]"]
  node_avatar["Player physics<br/>[PlayerAvatar.ts]"]
end

subgraph group_worlddata["Voxel world"]
  node_blocks["Block definitions<br/>[blocks.ts]"]
  node_world["Voxel world<br/>[VoxelWorld.ts]"]
  node_chunk["World chunks<br/>[Chunk.ts]"]
  node_streaming["Chunk streaming<br/>[ChunkManager.ts]"]
  node_generation["Terrain generation"]
  node_lighting["Voxel lighting<br/>[LightEngine.ts]"]
  node_meshing["Chunk meshing<br/>[ChunkMesher.ts]"]
end

subgraph group_features["Creative features"]
  node_chat["Villager chat<br/>[ChatAgent.ts]"]
  node_tools["Creative tools<br/>[buildTools.ts]"]
end

subgraph group_persistence["Local persistence"]
  node_worldstore["World persistence<br/>[worldStore.ts]"]
  node_database[("Browser database<br/>[db.ts]")]
  node_codec["Chunk codec<br/>[chunkCodec.ts]"]
  node_settings["World settings"]
  node_export["World import and export<br/>[exportWorld.ts]"]
  node_import["Import validation"]
end

node_player(("Player"))

node_player -->|"uses"| node_app
node_app -->|"shows"| node_canvas
node_app -->|"reads state"| node_store
node_app -->|"shows"| node_menu
node_menu -->|"updates"| node_store
node_store -->|"accesses"| node_engine
node_store -->|"saves worlds"| node_worldstore
node_store -->|"exports worlds"| node_export
node_store -->|"validates imports"| node_import
node_engine -->|"runs"| node_entities
node_engine -->|"runs"| node_avatar
node_engine -->|"uses"| node_chat
node_engine -.->|"manages"| node_world
node_engine -->|"resolves blocks"| node_blocks
node_engine -.->|"provides tools"| node_tools
node_streaming -->|"requests terrain"| node_generation
node_streaming -->|"creates"| node_chunk
node_streaming -->|"requests meshes"| node_meshing
node_streaming -->|"uses lighting"| node_lighting
node_meshing -->|"reads"| node_chunk
node_meshing -->|"reads definitions"| node_blocks
node_world -->|"stores blocks"| node_chunk
node_lighting -->|"reads blocks"| node_world
node_worldstore -->|"reads and writes"| node_database
node_worldstore -->|"encodes chunks"| node_codec
node_worldstore -->|"loads chunks"| node_chunk
node_worldstore -->|"uses defaults"| node_settings
node_export -->|"reads worlds"| node_database
node_import -->|"prepares world data"| node_worldstore
node_player -.->|"builds with"| node_tools
node_player -.->|"requests builds"| node_chat

click node_app "https://github.com/kinncj/mindcraft/blob/main/src/app/App.tsx"
click node_canvas "https://github.com/kinncj/mindcraft/blob/main/src/game/GameCanvas.tsx"
click node_store "https://github.com/kinncj/mindcraft/blob/main/src/game/gameStore.ts"
click node_menu "https://github.com/kinncj/mindcraft/blob/main/src/components/MenuPanel.tsx"
click node_engine "https://github.com/kinncj/mindcraft/blob/main/src/engine/core/Engine.ts"
click node_entities "https://github.com/kinncj/mindcraft/blob/main/src/engine/entities/EntitySystem.ts"
click node_avatar "https://github.com/kinncj/mindcraft/blob/main/src/engine/entities/PlayerAvatar.ts"
click node_chat "https://github.com/kinncj/mindcraft/blob/main/src/engine/chat/ChatAgent.ts"
click node_tools "https://github.com/kinncj/mindcraft/blob/main/src/engine/tools/buildTools.ts"
click node_blocks "https://github.com/kinncj/mindcraft/blob/main/src/engine/blocks/blocks.ts"
click node_world "https://github.com/kinncj/mindcraft/blob/main/src/engine/world/VoxelWorld.ts"
click node_chunk "https://github.com/kinncj/mindcraft/blob/main/src/engine/world/Chunk.ts"
click node_streaming "https://github.com/kinncj/mindcraft/blob/main/src/engine/world/ChunkManager.ts"
click node_generation "https://github.com/kinncj/mindcraft/blob/main/src/engine/world/generation/InfiniteGenerator.ts"
click node_lighting "https://github.com/kinncj/mindcraft/blob/main/src/engine/lighting/LightEngine.ts"
click node_meshing "https://github.com/kinncj/mindcraft/blob/main/src/engine/render/ChunkMesher.ts"
click node_worldstore "https://github.com/kinncj/mindcraft/blob/main/src/storage/worldStore.ts"
click node_database "https://github.com/kinncj/mindcraft/blob/main/src/storage/db.ts"
click node_codec "https://github.com/kinncj/mindcraft/blob/main/src/storage/chunkCodec.ts"
click node_settings "https://github.com/kinncj/mindcraft/blob/main/src/storage/settingsRepository.ts"
click node_export "https://github.com/kinncj/mindcraft/blob/main/src/importExport/exportWorld.ts"
click node_import "https://github.com/kinncj/mindcraft/blob/main/src/importExport/validateWorldImport.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_app,node_canvas,node_store,node_menu toneBlue
class node_engine,node_entities,node_avatar toneAmber
class node_blocks,node_world,node_chunk,node_streaming,node_generation,node_lighting,node_meshing toneMint
class node_chat,node_tools toneRose
class node_worldstore,node_database,node_codec,node_settings,node_export,node_import,node_player toneIndigo
```

## Components

### Game interface

- [Game interface](https://github.com/kinncj/mindcraft/blob/main/src/app/App.tsx): `src/app/App.tsx`
- [Game canvas](https://github.com/kinncj/mindcraft/blob/main/src/game/GameCanvas.tsx): `src/game/GameCanvas.tsx`
- [Game state](https://github.com/kinncj/mindcraft/blob/main/src/game/gameStore.ts): `src/game/gameStore.ts`
- [World menu](https://github.com/kinncj/mindcraft/blob/main/src/components/MenuPanel.tsx): `src/components/MenuPanel.tsx`

### World simulation

- [Game engine](https://github.com/kinncj/mindcraft/blob/main/src/engine/core/Engine.ts): `src/engine/core/Engine.ts`
- [Creatures and player](https://github.com/kinncj/mindcraft/blob/main/src/engine/entities/EntitySystem.ts): `src/engine/entities/EntitySystem.ts`
- [Player physics](https://github.com/kinncj/mindcraft/blob/main/src/engine/entities/PlayerAvatar.ts): `src/engine/entities/PlayerAvatar.ts`

### Voxel world

- [Block definitions](https://github.com/kinncj/mindcraft/blob/main/src/engine/blocks/blocks.ts): `src/engine/blocks/blocks.ts`
- [Voxel world](https://github.com/kinncj/mindcraft/blob/main/src/engine/world/VoxelWorld.ts): `src/engine/world/VoxelWorld.ts`
- [World chunks](https://github.com/kinncj/mindcraft/blob/main/src/engine/world/Chunk.ts): `src/engine/world/Chunk.ts`
- [Chunk streaming](https://github.com/kinncj/mindcraft/blob/main/src/engine/world/ChunkManager.ts): `src/engine/world/ChunkManager.ts`
- [Terrain generation](https://github.com/kinncj/mindcraft/blob/main/src/engine/world/generation/InfiniteGenerator.ts): `src/engine/world/generation/InfiniteGenerator.ts`
- [Voxel lighting](https://github.com/kinncj/mindcraft/blob/main/src/engine/lighting/LightEngine.ts): `src/engine/lighting/LightEngine.ts`
- [Chunk meshing](https://github.com/kinncj/mindcraft/blob/main/src/engine/render/ChunkMesher.ts): `src/engine/render/ChunkMesher.ts`

### Creative features

- [Villager chat](https://github.com/kinncj/mindcraft/blob/main/src/engine/chat/ChatAgent.ts): `src/engine/chat/ChatAgent.ts`
- [Creative tools](https://github.com/kinncj/mindcraft/blob/main/src/engine/tools/buildTools.ts): `src/engine/tools/buildTools.ts`

### Local persistence

- [World persistence](https://github.com/kinncj/mindcraft/blob/main/src/storage/worldStore.ts): `src/storage/worldStore.ts`
- [Browser database](https://github.com/kinncj/mindcraft/blob/main/src/storage/db.ts): `src/storage/db.ts`
- [Chunk codec](https://github.com/kinncj/mindcraft/blob/main/src/storage/chunkCodec.ts): `src/storage/chunkCodec.ts`
- [World settings](https://github.com/kinncj/mindcraft/blob/main/src/storage/settingsRepository.ts): `src/storage/settingsRepository.ts`
- [World import and export](https://github.com/kinncj/mindcraft/blob/main/src/importExport/exportWorld.ts): `src/importExport/exportWorld.ts`
- [Import validation](https://github.com/kinncj/mindcraft/blob/main/src/importExport/validateWorldImport.ts): `src/importExport/validateWorldImport.ts`

### Other components

- **Player**

## Connections

- Player → Game interface: uses
- Game interface → Game canvas: shows (evidence: `src/app/App.tsx`)
- Game interface → Game state: reads state (evidence: `src/app/App.tsx`)
- Game interface → World menu: shows (evidence: `src/app/App.tsx`)
- World menu → Game state: updates (evidence: `src/components/MenuPanel.tsx`)
- Game state → Game engine: accesses (evidence: `src/game/gameStore.ts`)
- Game state → World persistence: saves worlds (evidence: `src/game/gameStore.ts`)
- Game state → World import and export: exports worlds (evidence: `src/game/gameStore.ts`)
- Game state → Import validation: validates imports (evidence: `src/game/gameStore.ts`)
- Game engine → Creatures and player: runs (evidence: `src/engine/core/Engine.ts`)
- Game engine → Player physics: runs (evidence: `src/engine/core/Engine.ts`)
- Game engine → Villager chat: uses (evidence: `src/engine/core/Engine.ts`)
- Game engine → Voxel world: manages (evidence: `src/engine/core/Engine.ts`)
- Game engine → Block definitions: resolves blocks (evidence: `src/engine/core/Engine.ts`)
- Game engine → Creative tools: provides tools (evidence: `src/engine/core/Engine.ts`)
- Chunk streaming → Terrain generation: requests terrain (evidence: `src/engine/world/ChunkManager.ts`)
- Chunk streaming → World chunks: creates (evidence: `src/engine/world/ChunkManager.ts`)
- Chunk streaming → Chunk meshing: requests meshes (evidence: `src/engine/world/ChunkManager.ts`)
- Chunk streaming → Voxel lighting: uses lighting (evidence: `src/engine/world/ChunkManager.ts`)
- Chunk meshing → World chunks: reads (evidence: `src/engine/render/ChunkMesher.ts`)
- Chunk meshing → Block definitions: reads definitions (evidence: `src/engine/render/ChunkMesher.ts`)
- Voxel world → World chunks: stores blocks (evidence: `src/engine/world/VoxelWorld.ts`)
- Voxel lighting → Voxel world: reads blocks (evidence: `src/engine/lighting/LightEngine.ts`)
- World persistence → Browser database: reads and writes (evidence: `src/storage/worldStore.ts`)
- World persistence → Chunk codec: encodes chunks (evidence: `src/storage/worldStore.ts`)
- World persistence → World chunks: loads chunks (evidence: `src/storage/worldStore.ts`)
- World persistence → World settings: uses defaults (evidence: `src/storage/worldStore.ts`)
- World import and export → Browser database: reads worlds (evidence: `src/importExport/exportWorld.ts`)
- Import validation → World persistence: prepares world data (evidence: `src/importExport/validateWorldImport.ts`)
- Player → Creative tools: builds with
- Player → Villager chat: requests builds