How 123samueld/wfc_terrain_generator works
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: Rendering.js Rendering · Initialise.js Initialise · Simulation.js Simulation · GameState.js Game state
Components 29
Core App
Browser app bootstrap, shared state, input, menus, rendering, and simulation.
- index.html · Browser entry point that loads the app shell and modules.
index.html - index.css · Global styling for the browser UI.
index.css - Initialise · Sets up application state and startup wiring.
JS/Initialise.js - Main loop · Coordinates the ongoing application cycle.
JS/Main.js - Game state · Central world/editor state used across subsystems.
JS/GameState.js - Input · Translates mouse and keyboard events into app actions.
JS/Input.js - Hotkeys · Maps keyboard shortcuts to higher-level commands.
JS/HotkeyManager.js - Options · Application configuration and user-adjustable settings.
JS/Options.js - Build menu · Tool and placement menu for map editing.
JS/BuildMenu.js - Menu items · Defines selectable build, generate, and save menu content.
JS/MenuItems.js - Path router · Resolves nested asset paths for menus and rendering.
JS/FilePathRouter.js - Rendering · Draws world tiles, overlays, previews, and menus.
JS/Rendering.js - Simulation · Runs per-frame world logic and state updates.
JS/Simulation.js - Terrain tile · Atomic map unit shared by editing, generation, rendering, and pathfinding.
JS/TerrainTile.js
Terrain Generation
Wave Function Collapse pipeline and its visualization helpers.
- WFC · Core wave function collapse constraint propagation and selection.
JS/TerrainGenerator/WFC.js - WFC init · Prepares a generation run and initial state.
JS/TerrainGenerator/WFC_Initialization.js - WFC rules · Adjacency and compatibility rules for terrain generation.
JS/TerrainGenerator/WFCRules.js - Gen state · Tracks generation progress, candidates, and collapse state.
JS/TerrainGenerator/GenerationState.js - Gen visualiser · Shows generation progress step by step.
JS/TerrainGenerator/GenerationProcessVisualiser.js - Terrain display · Displays intermediate terrain states during generation.
JS/TerrainGenerator/TerrainStateDisplay.js - Terrain items · Building blocks used by the terrain-state display.
JS/TerrainGenerator/TerrainStateDisplayItems.js - Lookup table · Loads and manages superposition lookup data.
JS/TerrainGenerator/SuperpositionLookupTableManager.js - Lookup CSV · Precomputed constraint lookup data for generation.
JS/TerrainGenerator/SuperpositionLookupTable.csv
Pathfinding
Grid navigation algorithms and orchestration.
- Path manager · Coordinates pathfinding algorithm selection and requests.
JS/Pathfinding/PathfindingManager.js - A* · Heuristic shortest-path search on the world grid.
JS/Pathfinding/AStar.js - Wavefront · Grid propagation approach for distance or reachability.
JS/Pathfinding/WaveFrontPropagation.js - Heuristics · Distance and scoring functions used by pathfinding.
JS/Pathfinding/Heuristics.js
Assets
Visual resources for menus and terrain tiles.
- Menu icons · Nested icon assets for build, generate, and save menus.
Assets/Nested_Menu_Icons - Tile sprites · Terrain and map sprites for the editor and renderer.
Assets/Terrain_Tile_Sprites
Connections 33
- 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.