# 123samueld/wfc_terrain_generator architecture

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

- Interactive diagram: https://gitdiagram.com/123samueld/wfc_terrain_generator
- Repository: https://github.com/123samueld/wfc_terrain_generator

## Overview

1. **Overall shape**
   - This is a **client-side browser application**: `index.html` + `index.css` + a set of ES modules under `JS/`, with all visual content loaded from the `Assets/` tree.
   - The repo is organized more like a **map editor / terrain generation tool** than a traditional app server. A local web server is required so modules and image assets can be fetched correctly.

2. **Bootstrapping and runtime flow**
   - `JS/Initialise.js` and `JS/Main.js` appear to form the startup path.
   - The likely flow is: initialize state and resources → wire input and menus → enter a main update/render loop.
   - `JS/Simulation.js` probably owns per-frame world updates, while `JS/Rendering.js` turns the current state into visible output.

3. **Central application state**
   - `JS/GameState.js` is the main shared model for the editor/world.
   - Supporting modules like `JS/Options.js`, `JS/Input.js`, and `JS/HotkeyManager.js` feed user intent into that state.
   - `JS/TerrainTile.js` likely represents the atomic world unit used throughout editing, generation, rendering, and pathfinding.

4. **Editor interaction layer**
   - `JS/BuildMenu.js` and `JS/MenuItems.js` define the build-time UI for choosing terrain, buildings, roads, and other placeable elements.
   - `JS/FilePathRouter.js` likely abstracts asset lookup so menus and render code can resolve the correct icon/sprite paths from the nested asset directories.
   - User actions are centered around selecting a tool/tile, previewing placement, and committing changes into `GameState`.

5. **Input and control boundaries**
   - `JS/Input.js` handles mouse/keyboard events.
   - `JS/HotkeyManager.js` maps shortcuts like the build-menu toggle and camera movement into higher-level actions.
   - This is a clean boundary between raw browser events and editor commands, which keeps rendering and world logic separate from device handling.

6. **Rendering and visual composition**
   - `JS/Rendering.js` is the presentation layer for the editor.
   - The asset tree shows two major visual domains:
     - `Assets/Terrain_Tile_Sprites/` for the actual map tiles, split into **Cartesian** and **Isometric** variants.
     - `Assets/Nested_Menu_Icons/` for UI icons used by the build/generate/save menus.
   - The renderer likely combines world tiles, previews, overlays, and menu UI into one canvas-based or DOM-based output.

7. **Terrain generation subsystem**
   - The `JS/TerrainGenerator/` folder is a self-contained procedural generation pipeline based on **Wave Function Collapse (WFC)**.
   - Key pieces:
     - `WFC.js` for the core collapse/propagation logic
     - `WFCRules.js` for adjacency/constraint rules
     - `WFC_Initialization.js` for setting up a generation run
     - `GenerationState.js` for tracking progress and candidates
     - `GenerationProcessVisualiser.js` and `TerrainStateDisplay*.js` for step-by-step visualization
     - `SuperpositionLookupTableManager.js` plus `SuperpositionLookupTable.csv` for precomputed constraint lookup data
   - This subsystem feeds generated terrain back into the shared world state rather than owning the whole app.

8. **Pathfinding subsystem**
   - `JS/Pathfinding/` is a separate algorithmic boundary, with `AStar.js`, `WaveFrontPropagation.js`, and `Heuristics.js`.
   - `PathfindingManager.js` likely coordinates algorithm choice and exposes a simpler interface to the rest of the app.
   - Architecturally, this looks prepared for future gameplay AI and movement systems, but it is distinct from the editor and generation pipeline.

9. **Data and control flow across subsystems**
   - Primary editing flow: user input → menu/tool selection → placement/edit operations → update `GameState`/terrain grid → render.
   - Generation flow: menu action → WFC initialization → constraint propagation/collapse → generation-state visualization → commit generated terrain.
   - Pathfinding flow: world/grid data from `GameState` or terrain structures → route computation → results returned to simulation or future AI systems.

10. **Domain model and world content**
   - The assets and menu structure reveal the content model: **buildings, roads, train tracks, flora, landscape, water, bridges**.
   - Terrain tiles are represented in both **map-editor icon form** and **world-sprite form**, which suggests the editor uses one visual layer for tool selection and another for actual terrain display.
   - Water and bridge assets indicate terrain connectivity/adjacency is important, which fits the WFC and pathfinding systems.

11. **Performance and instrumentation**
   - `JS/ProfilingTools.js` and `PerformanceEnhancements.md` indicate explicit attention to runtime cost, likely because WFC, rendering, and pathfinding can all be expensive in-browser.
   - This suggests the architecture expects iterative tuning rather than a fixed, production-hardened engine.

12. **Boundary to the future game pipeline**
   - The README makes it clear this repo is Phase 1 of a larger pipeline.
   - Current architecture is centered on **content authoring and procedural terrain**, with placeholders for later systems such as graphics-heavy gameplay, AI, and multiplayer.
   - So an architecture diagram should show this repo as a **frontend world-editor/generator core** that will later feed a broader game engine stack.

Main entry points: [`JS/Rendering.js`](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Rendering.js) (Rendering), [`JS/Initialise.js`](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Initialise.js) (Initialise), [`JS/Simulation.js`](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Simulation.js) (Simulation), [`JS/GameState.js`](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/GameState.js) (Game state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core App"]
  node_index_html["index.html<br/>entry page<br/>[index.html]"]
  node_index_css["index.css<br/>styles<br/>[index.css]"]
  node_initialise["Initialise<br/>bootstrap<br/>[Initialise.js]"]
  node_main["Main loop<br/>runtime loop<br/>[Main.js]"]
  node_game_state[("Game state<br/>shared model<br/>[GameState.js]")]
  node_input["Input<br/>browser events<br/>[Input.js]"]
  node_hotkeys["Hotkeys<br/>shortcut mapping<br/>[HotkeyManager.js]"]
  node_options["Options<br/>settings<br/>[Options.js]"]
  node_build_menu["Build menu<br/>editor UI<br/>[BuildMenu.js]"]
  node_menu_items["Menu items<br/>catalog<br/>[MenuItems.js]"]
  node_file_router["Path router<br/>asset resolver<br/>[FilePathRouter.js]"]
  node_rendering["Rendering<br/>presentation<br/>[Rendering.js]"]
  node_simulation["Simulation<br/>world update<br/>[Simulation.js]"]
  node_terrain_tile["Terrain tile<br/>domain object<br/>[TerrainTile.js]"]
end

subgraph group_gen["Terrain Generation"]
  node_wfc["WFC<br/>collapse engine<br/>[WFC.js]"]
  node_wfc_init["WFC init<br/>generation setup"]
  node_wfcrules["WFC rules<br/>constraints<br/>[WFCRules.js]"]
  node_gen_state[("Gen state<br/>progress model<br/>[GenerationState.js]")]
  node_gen_vis["Gen visualiser<br/>process UI"]
  node_terrain_display["Terrain display<br/>visual debug"]
  node_terrain_items["Terrain items<br/>render items"]
  node_lookup_mgr["Lookup table<br/>precompute cache"]
  node_lookup_csv["Lookup CSV<br/>data table"]
end

subgraph group_path["Pathfinding"]
  node_path_mgr["Path manager<br/>algorithm facade"]
  node_astar["A*<br/>path algorithm<br/>[AStar.js]"]
  node_wavefront["Wavefront<br/>path algorithm"]
  node_heuristics["Heuristics<br/>cost helpers<br/>[Heuristics.js]"]
end

subgraph group_assets["Assets"]
  node_assets_menu[("Menu icons<br/>ui assets")]
  node_assets_tiles[("Tile sprites<br/>world assets")]
end

node_index_html -->|"loads"| node_initialise
node_index_html -->|"styles"| node_index_css
node_initialise -->|"creates"| node_game_state
node_initialise -->|"reads"| node_options
node_initialise -->|"wires"| node_build_menu
node_initialise -->|"starts"| node_rendering
node_main -->|"ticks"| node_simulation
node_main -->|"draws"| node_rendering
node_input -->|"routes"| node_hotkeys
node_hotkeys -->|"toggles"| node_build_menu
node_hotkeys -->|"commands"| node_simulation
node_input -->|"edits"| node_game_state
node_build_menu -->|"lists"| node_menu_items
node_menu_items -->|"resolves"| node_file_router
node_rendering -->|"reads"| node_game_state
node_rendering -->|"uses"| node_assets_tiles
node_rendering -->|"uses"| node_assets_menu
node_simulation -->|"updates"| node_terrain_tile
node_simulation -->|"queries"| node_path_mgr
node_wfc_init -->|"creates"| node_gen_state
node_wfc_init -->|"configures"| node_wfcrules
node_wfc -->|"mutates"| node_gen_state
node_wfc -->|"checks"| node_wfcrules
node_lookup_mgr -->|"loads"| node_lookup_csv
node_gen_vis -->|"visualizes"| node_gen_state
node_terrain_display -->|"renders"| node_terrain_items
node_wfc -->|"shows"| node_terrain_display
node_path_mgr -->|"selects"| node_astar
node_path_mgr -->|"selects"| node_wavefront
node_astar -->|"uses"| node_heuristics
node_wavefront -->|"traverses"| node_terrain_tile
node_rendering -->|"overlays"| node_build_menu
node_game_state -->|"contains"| node_terrain_tile

click node_index_html "https://github.com/123samueld/wfc_terrain_generator/blob/main/index.html"
click node_index_css "https://github.com/123samueld/wfc_terrain_generator/blob/main/index.css"
click node_initialise "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Initialise.js"
click node_main "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Main.js"
click node_game_state "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/GameState.js"
click node_input "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Input.js"
click node_hotkeys "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/HotkeyManager.js"
click node_options "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Options.js"
click node_build_menu "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/BuildMenu.js"
click node_menu_items "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/MenuItems.js"
click node_file_router "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/FilePathRouter.js"
click node_rendering "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Rendering.js"
click node_simulation "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Simulation.js"
click node_terrain_tile "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainTile.js"
click node_wfc "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/WFC.js"
click node_wfc_init "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/WFC_Initialization.js"
click node_wfcrules "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/WFCRules.js"
click node_gen_state "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/GenerationState.js"
click node_gen_vis "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/GenerationProcessVisualiser.js"
click node_terrain_display "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/TerrainStateDisplay.js"
click node_terrain_items "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/TerrainStateDisplayItems.js"
click node_lookup_mgr "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/SuperpositionLookupTableManager.js"
click node_lookup_csv "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/SuperpositionLookupTable.csv"
click node_path_mgr "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Pathfinding/PathfindingManager.js"
click node_astar "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Pathfinding/AStar.js"
click node_wavefront "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Pathfinding/WaveFrontPropagation.js"
click node_heuristics "https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Pathfinding/Heuristics.js"
click node_assets_menu "https://github.com/123samueld/wfc_terrain_generator/tree/main/Assets/Nested_Menu_Icons"
click node_assets_tiles "https://github.com/123samueld/wfc_terrain_generator/tree/main/Assets/Terrain_Tile_Sprites"

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_index_html,node_index_css,node_initialise,node_main,node_game_state,node_input,node_hotkeys,node_options,node_build_menu,node_menu_items,node_file_router,node_rendering,node_simulation,node_terrain_tile toneBlue
class node_wfc,node_wfc_init,node_wfcrules,node_gen_state,node_gen_vis,node_terrain_display,node_terrain_items,node_lookup_mgr,node_lookup_csv toneAmber
class node_path_mgr,node_astar,node_wavefront,node_heuristics toneMint
class node_assets_menu,node_assets_tiles toneRose
```

## Components

### Core App

Browser app bootstrap, shared state, input, menus, rendering, and simulation.

- [index.html](https://github.com/123samueld/wfc_terrain_generator/blob/main/index.html): entry page · Browser entry point that loads the app shell and modules. · `index.html`
- [index.css](https://github.com/123samueld/wfc_terrain_generator/blob/main/index.css): styles · Global styling for the browser UI. · `index.css`
- [Initialise](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Initialise.js): bootstrap · Sets up application state and startup wiring. · `JS/Initialise.js`
- [Main loop](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Main.js): runtime loop · Coordinates the ongoing application cycle. · `JS/Main.js`
- [Game state](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/GameState.js): shared model · Central world/editor state used across subsystems. · `JS/GameState.js`
- [Input](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Input.js): browser events · Translates mouse and keyboard events into app actions. · `JS/Input.js`
- [Hotkeys](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/HotkeyManager.js): shortcut mapping · Maps keyboard shortcuts to higher-level commands. · `JS/HotkeyManager.js`
- [Options](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Options.js): settings · Application configuration and user-adjustable settings. · `JS/Options.js`
- [Build menu](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/BuildMenu.js): editor UI · Tool and placement menu for map editing. · `JS/BuildMenu.js`
- [Menu items](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/MenuItems.js): catalog · Defines selectable build, generate, and save menu content. · `JS/MenuItems.js`
- [Path router](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/FilePathRouter.js): asset resolver · Resolves nested asset paths for menus and rendering. · `JS/FilePathRouter.js`
- [Rendering](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Rendering.js): presentation · Draws world tiles, overlays, previews, and menus. · `JS/Rendering.js`
- [Simulation](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Simulation.js): world update · Runs per-frame world logic and state updates. · `JS/Simulation.js`
- [Terrain tile](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainTile.js): domain object · Atomic map unit shared by editing, generation, rendering, and pathfinding. · `JS/TerrainTile.js`

### Terrain Generation

Wave Function Collapse pipeline and its visualization helpers.

- [WFC](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/WFC.js): collapse engine · Core wave function collapse constraint propagation and selection. · `JS/TerrainGenerator/WFC.js`
- [WFC init](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/WFC_Initialization.js): generation setup · Prepares a generation run and initial state. · `JS/TerrainGenerator/WFC_Initialization.js`
- [WFC rules](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/WFCRules.js): constraints · Adjacency and compatibility rules for terrain generation. · `JS/TerrainGenerator/WFCRules.js`
- [Gen state](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/GenerationState.js): progress model · Tracks generation progress, candidates, and collapse state. · `JS/TerrainGenerator/GenerationState.js`
- [Gen visualiser](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/GenerationProcessVisualiser.js): process UI · Shows generation progress step by step. · `JS/TerrainGenerator/GenerationProcessVisualiser.js`
- [Terrain display](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/TerrainStateDisplay.js): visual debug · Displays intermediate terrain states during generation. · `JS/TerrainGenerator/TerrainStateDisplay.js`
- [Terrain items](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/TerrainStateDisplayItems.js): render items · Building blocks used by the terrain-state display. · `JS/TerrainGenerator/TerrainStateDisplayItems.js`
- [Lookup table](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/SuperpositionLookupTableManager.js): precompute cache · Loads and manages superposition lookup data. · `JS/TerrainGenerator/SuperpositionLookupTableManager.js`
- [Lookup CSV](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/TerrainGenerator/SuperpositionLookupTable.csv): data table · Precomputed constraint lookup data for generation. · `JS/TerrainGenerator/SuperpositionLookupTable.csv`

### Pathfinding

Grid navigation algorithms and orchestration.

- [Path manager](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Pathfinding/PathfindingManager.js): algorithm facade · Coordinates pathfinding algorithm selection and requests. · `JS/Pathfinding/PathfindingManager.js`
- [A*](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Pathfinding/AStar.js): path algorithm · Heuristic shortest-path search on the world grid. · `JS/Pathfinding/AStar.js`
- [Wavefront](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Pathfinding/WaveFrontPropagation.js): path algorithm · Grid propagation approach for distance or reachability. · `JS/Pathfinding/WaveFrontPropagation.js`
- [Heuristics](https://github.com/123samueld/wfc_terrain_generator/blob/main/JS/Pathfinding/Heuristics.js): cost helpers · Distance and scoring functions used by pathfinding. · `JS/Pathfinding/Heuristics.js`

### Assets

Visual resources for menus and terrain tiles.

- [Menu icons](https://github.com/123samueld/wfc_terrain_generator/tree/main/Assets/Nested_Menu_Icons): ui assets · Nested icon assets for build, generate, and save menus. · `Assets/Nested_Menu_Icons`
- [Tile sprites](https://github.com/123samueld/wfc_terrain_generator/tree/main/Assets/Terrain_Tile_Sprites): world assets · Terrain and map sprites for the editor and renderer. · `Assets/Terrain_Tile_Sprites`

## Connections

- index.html → Initialise: loads · Bootstraps the app through the startup module.
- index.html → index.css: styles · Applies global browser styling.
- Initialise → Game state: creates · Initial setup builds the shared state model.
- Initialise → Options: reads · Startup configuration is applied during initialization.
- Initialise → Build menu: wires · Initializes the editor UI and controls.
- Initialise → Rendering: starts · Hands off to the presentation layer after setup.
- Main loop → Simulation: ticks · Main loop advances simulation each frame.
- Main loop → Rendering: draws · Main loop requests frame rendering.
- Input → Hotkeys: routes · Raw events are mapped to shortcut commands.
- Hotkeys → Build menu: toggles · Keyboard actions control editor menus and modes.
- Hotkeys → Simulation: commands · Shortcuts can trigger world actions and updates.
- Input → Game state: edits · Pointer and keyboard input affect the shared world state.
- Build menu → Menu items: lists · The build menu is populated from item definitions.
- Menu items → Path router: resolves · Item definitions point to nested icon/sprite locations.
- Rendering → Game state: reads · Renderer consumes the current world and editor state.
- Rendering → Tile sprites: uses · World visuals come from the terrain sprite library.
- Rendering → Menu icons: uses · UI drawing uses nested menu icons.
- Simulation → Terrain tile: updates · Simulation operates on terrain units and grid cells.
- Simulation → Path manager: queries · Simulation can request route calculations.
- WFC init → Gen state: creates · Generation setup initializes progress tracking.
- WFC init → WFC rules: configures · Initialization applies adjacency constraints.
- WFC → Gen state: mutates · Collapse and propagation update generation progress.
- WFC → WFC rules: checks · Core engine validates choices against rules.
- Lookup table → Lookup CSV: loads · Precomputed lookup data is sourced from CSV.
- Gen visualiser → Gen state: visualizes · Process UI reflects generation progress.
- Terrain display → Terrain items: renders · Debug display uses structured terrain-state items.
- WFC → Terrain display: shows · Generation steps can be surfaced in the visual display.
- Path manager → A*: selects · Manager delegates to A* when appropriate.
- Path manager → Wavefront: selects · Manager can also delegate to wavefront propagation.
- A* → Heuristics: uses · A* depends on heuristic scoring.
- Wavefront → Terrain tile: traverses · Path computation runs over terrain cells.
- Rendering → Build menu: overlays · Menu UI is composed into the presentation layer.
- Game state → Terrain tile: contains · The shared model stores terrain grid data.