# wiktorbor/minecraft-procedural-settlement-generation-project architecture

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

- Interactive diagram: https://gitdiagram.com/wiktorbor/minecraft-procedural-settlement-generation-project
- Repository: https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project

## Overview

GDMC Settlement Generator procedurally turns a Minecraft build area into a medieval settlement: it analyzes terrain, plans districts, roads, and plots, builds biome-aware structures, and flushes accumulated blocks to the world. The main runtime orchestrator is SettlementGenerator; the README documents its stages and the single-buffer write strategy. The graph preserves major documented capabilities, including district MDP assignment, connector paths, and perimeter defenses. Some subsystem links are supported by the README rather than inspected implementation; unsampled source is not assumed to have been read.

Main entry points: [`generators/settlement_generator.py`](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/generators/settlement_generator.py) (Generation pipeline), [`planning/settlement_planner.py`](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/planning/settlement_planner.py) (Settlement planner), [`structures/orchestrators`](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/tree/main/structures/orchestrators) (Structure builders), [`main.py`](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/main.py) (Entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_main["Entry point<br/>[main.py]"]
  node_generator["Generation pipeline"]
end

subgraph group_analysis_planning["Analysis and planning"]
  node_world_analysis["Terrain analysis<br/>[world_analysis.py]"]
  node_district_mdp["District type MDP<br/>[district_mdp.py]"]
  node_settlement_planner["Settlement planner"]
  node_district_planner["District planner"]
  node_road_planner["Road planner<br/>[road_planner.py]"]
  node_road_placer["Road placement<br/>[road_placer.py]"]
  node_plot_planner["Plot planner<br/>[plot_planner.py]"]
end

subgraph group_settlement_data["Settlement state and data"]
  node_analysis_results["Analysis results"]
  node_build_area["Build area<br/>[build_area.py]"]
  node_config["Generation config<br/>[configurations.py]"]
  node_entities["Settlement entities"]
  node_state["Settlement state"]
end

subgraph group_construction["Structure construction"]
  node_palette["Biome palettes<br/>[palette_system.py]"]
  node_selector["Structure selector"]
  node_builders["Structure builders"]
  node_build_context["Build context<br/>[build_context.py]"]
end

subgraph group_world_io["World interface"]
  node_terraforming["Terrain modification<br/>[terraforming.py]"]
  node_block_buffer[("Block buffer<br/>[block_buffer.py]")]
  node_structure_placer["World block writer"]
end

node_minecraft(("Minecraft world"))

node_minecraft -->|"provides world"| node_main
node_main -->|"starts generation"| node_generator
node_generator -->|"analyzes terrain"| node_world_analysis
node_world_analysis -.->|"produces maps"| node_analysis_results
node_generator -->|"plans settlement"| node_settlement_planner
node_settlement_planner -->|"plans districts"| node_district_planner
node_district_planner -->|"assigns types"| node_district_mdp
node_settlement_planner -->|"plans roads"| node_road_planner
node_generator -->|"places roads"| node_road_placer
node_settlement_planner -->|"plans plots"| node_plot_planner
node_generator -.->|"updates state"| node_state
node_generator -->|"creates markers"| node_entities
node_generator -.->|"selects materials"| node_palette
node_generator -->|"selects buildings"| node_selector
node_selector -->|"dispatches builds"| node_builders
node_builders -.->|"builds through"| node_build_context
node_build_context -->|"records blocks"| node_block_buffer
node_generator -->|"levels terrain"| node_terraforming
node_generator -->|"accumulates blocks"| node_block_buffer
node_generator -->|"flushes buffer"| node_structure_placer
node_structure_placer -->|"writes blocks"| node_minecraft
node_generator -->|"adds connectors"| node_state
node_generator -->|"builds fortification"| node_builders

click node_main "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/main.py"
click node_generator "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/generators/settlement_generator.py"
click node_world_analysis "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/analysis/world_analysis.py"
click node_district_mdp "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/ai/district_mdp.py"
click node_settlement_planner "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/planning/settlement_planner.py"
click node_district_planner "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/planning/settlement/district_planner.py"
click node_road_planner "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/planning/infrastructure/road_planner.py"
click node_road_placer "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/planning/infrastructure/road_placer.py"
click node_plot_planner "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/planning/settlement/plot_planner.py"
click node_analysis_results "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/data/analysis_results.py"
click node_build_area "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/data/build_area.py"
click node_config "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/data/configurations.py"
click node_entities "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/data/settlement_entities.py"
click node_state "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/data/settlement_state.py"
click node_palette "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/palette/palette_system.py"
click node_selector "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/structures/structure_selector.py"
click node_builders "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/tree/main/structures/orchestrators"
click node_build_context "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/structures/base/build_context.py"
click node_terraforming "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/world_interface/terraforming.py"
click node_block_buffer "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/world_interface/block_buffer.py"
click node_structure_placer "https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/world_interface/structure_placer.py"

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_main,node_generator toneBlue
class node_world_analysis,node_district_mdp,node_settlement_planner,node_district_planner,node_road_planner,node_road_placer,node_plot_planner toneAmber
class node_analysis_results,node_build_area,node_config,node_entities,node_state toneMint
class node_palette,node_selector,node_builders,node_build_context toneRose
class node_terraforming,node_block_buffer,node_structure_placer,node_minecraft toneIndigo
```

## Components

### Runtime orchestration

- [Entry point](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/main.py): `main.py`
- [Generation pipeline](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/generators/settlement_generator.py): `generators/settlement_generator.py`

### Analysis and planning

- [Terrain analysis](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/analysis/world_analysis.py): `analysis/world_analysis.py`
- [District type MDP](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/ai/district_mdp.py): `ai/district_mdp.py`
- [Settlement planner](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/planning/settlement_planner.py): `planning/settlement_planner.py`
- [District planner](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/planning/settlement/district_planner.py): `planning/settlement/district_planner.py`
- [Road planner](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/planning/infrastructure/road_planner.py): `planning/infrastructure/road_planner.py`
- [Road placement](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/planning/infrastructure/road_placer.py): `planning/infrastructure/road_placer.py`
- [Plot planner](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/planning/settlement/plot_planner.py): `planning/settlement/plot_planner.py`

### Settlement state and data

- [Analysis results](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/data/analysis_results.py): `data/analysis_results.py`
- [Build area](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/data/build_area.py): `data/build_area.py`
- [Generation config](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/data/configurations.py): `data/configurations.py`
- [Settlement entities](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/data/settlement_entities.py): `data/settlement_entities.py`
- [Settlement state](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/data/settlement_state.py): `data/settlement_state.py`

### Structure construction

- [Biome palettes](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/palette/palette_system.py): `palette/palette_system.py`
- [Structure selector](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/structures/structure_selector.py): `structures/structure_selector.py`
- [Structure builders](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/tree/main/structures/orchestrators): `structures/orchestrators`
- [Build context](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/structures/base/build_context.py): `structures/base/build_context.py`

### World interface

- [Terrain modification](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/world_interface/terraforming.py): `world_interface/terraforming.py`
- [Block buffer](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/world_interface/block_buffer.py): `world_interface/block_buffer.py`
- [World block writer](https://github.com/wiktorbor/minecraft-procedural-settlement-generation-project/blob/main/world_interface/structure_placer.py): `world_interface/structure_placer.py`

### Other components

- **Minecraft world**

## Connections

- Minecraft world → Entry point: provides world
- Entry point → Generation pipeline: starts generation
- Generation pipeline → Terrain analysis: analyzes terrain (evidence: `generators/settlement_generator.py`)
- Terrain analysis → Analysis results: produces maps
- Generation pipeline → Settlement planner: plans settlement (evidence: `generators/settlement_generator.py`)
- Settlement planner → District planner: plans districts (evidence: `planning/settlement_planner.py`)
- District planner → District type MDP: assigns types (evidence: `planning/settlement/district_planner.py`)
- Settlement planner → Road planner: plans roads (evidence: `planning/settlement_planner.py`)
- Generation pipeline → Road placement: places roads (evidence: `generators/settlement_generator.py`)
- Settlement planner → Plot planner: plans plots (evidence: `planning/settlement_planner.py`)
- Generation pipeline → Settlement state: updates state (evidence: `generators/settlement_generator.py`)
- Generation pipeline → Settlement entities: creates markers (evidence: `generators/settlement_generator.py`)
- Generation pipeline → Biome palettes: selects materials (evidence: `generators/settlement_generator.py`)
- Generation pipeline → Structure selector: selects buildings (evidence: `generators/settlement_generator.py`)
- Structure selector → Structure builders: dispatches builds (evidence: `structures/structure_selector.py`)
- Structure builders → Build context: builds through (evidence: `structures/orchestrators/fortification.py`)
- Build context → Block buffer: records blocks (evidence: `structures/base/build_context.py`)
- Generation pipeline → Terrain modification: levels terrain (evidence: `generators/settlement_generator.py`)
- Generation pipeline → Block buffer: accumulates blocks (evidence: `generators/settlement_generator.py`)
- Generation pipeline → World block writer: flushes buffer (evidence: `generators/settlement_generator.py`)
- World block writer → Minecraft world: writes blocks
- Generation pipeline → Settlement state: adds connectors (evidence: `generators/settlement_generator.py`)
- Generation pipeline → Structure builders: builds fortification (evidence: `generators/settlement_generator.py`)
