# redblobgames/mapgen2 architecture

> Architecture diagram of the GitHub repository redblobgames/mapgen2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/redblobgames/mapgen2
- Repository: https://github.com/redblobgames/mapgen2

## Overview

##### Project Type and Purpose
- This is an open-source JavaScript library (with demo UI code) for procedural polygonal map generation.
- Core algorithms: point distribution, mesh construction (Voronoi/Delaunay), dual‐mesh augmentation, elevation/rivers/biomes assignment.

##### File Structure Analysis
- Top-level:
- dual-mesh/ — standalone TypeScript package for constructing and augmenting meshes
- .js, biomes.js, moisture.js, rivers.js, water.js — modules implementing WorldMap data generation
- build.sh, package.json, pnpm-lock.yaml — build and dependency config
- dual-mesh subpackage:
- create.ts, index.ts — APIs to generate boundary points and wrap Delaunator output into TriangleMesh
- dist/ — compiled JavaScript/TypeScript declarations
- tests.js, tsconfig.json, package.json — standalone build/test config

##### README Insights
- Core data structures:
- Mesh (struct-of-arrays) for connectivity (points, edges, triangles, cells)
- WorldMap for map attributes (elevation, rivers, biomes)
- Extensibility points:
- Custom point generators (jittered grid, Poisson disc)
- Plug-in noise functions (SimplexNoise or user-provided)
- Seeded RNG (makeRandInt / makeRandFloat)
- Execution pipeline spelled out in sample code.

a. Main Components
– Input Generators: boundary-point generator, Poisson-disc sampler
– Mesh Engine: Delaunator (external) → dual-mesh (TriangleMesh)
– WorldMap Generator: elevation, drainage, rivers, biome assignment modules
– Data Structures: Mesh, WorldMap
– External Libraries: SimplexNoise, Delaunator, poisson-disk-sampling, prng module
b. Relationships & Data Flow
1. Input Generators produce point set
2. Delaunator consumes points → raw triangles
3. dual-mesh augments triangles with ghost cells and builds connectivity
4. WorldMap consumes Mesh + noise + RNG → populates r_elevation, r_water, r_biome, lines_s arrays
5. Rendering module reads WorldMap → draws polygons/triangles on HTML canvas/SVG
c. Architectural Patterns / Principles
– Pipeline architecture: discrete steps chained (point gen → mesh → map gen → render)
– Modular design: dual-mesh packaged separately for reuse
– Struct-of-arrays for performance and cache locality
– Open-closed for extensibility (swap noise, RNG, point source)
d. Key Technologies & Libraries
– JavaScript/TypeScript
– Delaunator for triangulation
– dual-mesh library for Voronoi connectivity
– SimplexNoise for heightmap noise
– Poisson-disk sampling for point distribution
– @redblobgames/prng for seeded randomness

## Diagram (Mermaid)

```mermaid
graph TB
    %% Input Generators
    subgraph "Input Generators"
        IG1["Boundary Point Generator"]:::core
        IG2["Poisson-disc Sampler"]:::core
    end

    %% Mesh Engine & dual-mesh package
    subgraph "Mesh Engine"
        Delaunator["Delaunator"]:::external
        subgraph "dual-mesh Package"
            DMcreate["create.ts"]:::core
            DMindex["index.ts"]:::core
            subgraph "dist"
                DMdist1["index.js"]:::core
                DMdist2["create.js"]:::core
            end
            DMpkgjson["package.json"]:::config
            DMtsconfig["tsconfig.json"]:::config
            DMtests["tests.js"]:::config
        end
    end

    %% WorldMap Generator
    subgraph "WorldMap Generator"
        MapOrch["Map Orchestrator (map.js)"]:::core
        Elev["Elevation Module (elevation.js)"]:::core
        Rivers["River Module (rivers.js)"]:::core
        Moisture["Moisture Module (moisture.js)"]:::core
        Water["Water Bodies Module (water.js)"]:::core
        Biomes["Biome Module (biomes.js)"]:::core
    end

    %% Utilities
    subgraph "Utilities"
        RNG["Seeded RNG (util.js)"]:::util
        Colormap["Color Mapping (colormap.js)"]:::util
    end

    %% Rendering/UI
    subgraph "Rendering/UI"
        Draw["Draw Utilities (draw.js)"]:::ui
        Embed["Demo HTML (embed.html)"]:::ui
    end

    %% External Libraries
    subgraph "External Libraries"
        SimplexNoise["SimplexNoise"]:::external
        PoissonLib["poisson-disk-sampling"]:::external
    end

    %% Package Config & Build
    subgraph "Config & Build"
        BuildSh["build.sh"]:::config
        RootPkg["package.json"]:::config
        Lockfile["pnpm-lock.yaml"]:::config
    end

    %% Data Flow
    IG1 -->|points| Delaunator
    IG2 -->|points| Delaunator
    Delaunator -->|raw triangles| DMcreate
    DMcreate --> DMindex
    DMindex --> MapOrch

    MapOrch -->|invokes| Elev
    MapOrch -->|invokes| Rivers
    MapOrch -->|invokes| Moisture
    MapOrch -->|invokes| Water
    MapOrch -->|invokes| Biomes

    MapOrch -->|WorldMap data| Draw
    Draw -->|renders| Embed

    %% Extension Points (dashed)
    SimplexNoise -.-> Elev
    RNG -.-> MapOrch
    RNG -.-> Elev
    RNG -.-> Rivers
    PoissonLib -.-> IG2
    Colormap -.-> Draw

    %% Click Events
    click IG1 "https://github.com/redblobgames/mapgen2/blob/master/dual-mesh/create.ts"
    click DMcreate "https://github.com/redblobgames/mapgen2/blob/master/dual-mesh/create.ts"
    click DMindex "https://github.com/redblobgames/mapgen2/blob/master/dual-mesh/index.ts"
    click DMdist1 "https://github.com/redblobgames/mapgen2/blob/master/dual-mesh/dist/index.js"
    click DMdist2 "https://github.com/redblobgames/mapgen2/blob/master/dual-mesh/dist/create.js"
    click MapOrch "https://github.com/redblobgames/mapgen2/blob/master/map.js"
    click Elev "https://github.com/redblobgames/mapgen2/blob/master/elevation.js"
    click Rivers "https://github.com/redblobgames/mapgen2/blob/master/rivers.js"
    click Moisture "https://github.com/redblobgames/mapgen2/blob/master/moisture.js"
    click Water "https://github.com/redblobgames/mapgen2/blob/master/water.js"
    click Biomes "https://github.com/redblobgames/mapgen2/blob/master/biomes.js"
    click Draw "https://github.com/redblobgames/mapgen2/blob/master/draw.js"
    click Embed "https://github.com/redblobgames/mapgen2/blob/master/embed.html"
    click RNG "https://github.com/redblobgames/mapgen2/blob/master/util.js"
    click Colormap "https://github.com/redblobgames/mapgen2/blob/master/colormap.js"
    click BuildSh "https://github.com/redblobgames/mapgen2/blob/master/build.sh"
    click RootPkg "https://github.com/redblobgames/mapgen2/blob/master/package.json"
    click Lockfile "https://github.com/redblobgames/mapgen2/blob/master/pnpm-lock.yaml"
    click DMpkgjson "https://github.com/redblobgames/mapgen2/blob/master/dual-mesh/package.json"
    click DMtsconfig "https://github.com/redblobgames/mapgen2/blob/master/dual-mesh/tsconfig.json"
    click DMtests "https://github.com/redblobgames/mapgen2/blob/master/dual-mesh/tests.js"

    %% Styles
    classDef core fill:#cce5ff,stroke:#3399ff,stroke-width:2px
    classDef ui fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px,stroke-dasharray: 5 5
    classDef util fill:#fff3cd,stroke:#ffecb5,stroke-width:2px
    classDef config fill:#f8d7da,stroke:#f5c6cb,stroke-width:2px,stroke-dasharray: 2 2
```
