Architecture — MeshWorld

Generation Pipeline

From Config to Cached Scene

world.json_{Seed · grid size · zones · style}

WorldMap_{Assigns ZoneType + RegionType per (x,y) coordinate}

ChunkPipeline_{Cache hit? → return cached XML}

LuaGeneratorRegistry_{try lua.zone.<region> first}

LuaSandbox → LuaRuntime (Lua 5.4 + sol2)_{Sandboxed: no io/os/debug/require}

C++ Fallback_{get_generator(zone, region) → 20 generators}

Mc3SceneBuilder_{addBox · addCylinder · addPlane · addGround · addInstance}

MC3Validator_{XML · metadata · bounds · material names}

ChunkCache_{cache/chunks/x_y.mc3.xml}

MC3 XML output_{MeshCraft viewer · MCB compiler · WorldRenderer}

Pipeline notes

Cache-first: ChunkPipeline checks the disk cache before doing any work. If cache/chunks/x_y.mc3.xml exists and is newer than the world config, generation is skipped entirely.

Lua-first: The registry is checked before the C++ fallback. A Lua file with a matching M.id overrides the C++ generator with zero configuration.

Validation gate: Only validated chunks are written to cache. Invalid generator output is discarded — the cache can never contain corrupted data.

The WorldStreamer sits above this pipeline. It calls ChunkPipeline::generate() for chunks entering the load radius and drops the Mc3Document from memory when chunks leave the radius.

C++ API

Key Classes

Class	Header	Description
`ChunkPipeline`	`ChunkPipeline.hpp`	Orchestrates the full generation flow: Lua-first → C++ fallback → validate → cache. Main entry point for chunk generation.
`Mc3SceneBuilder`	`Mc3SceneBuilder.hpp`	Safe builder API for constructing MC3 scenes: `addBox`, `addCylinder`, `addPlane`, `addGround`, `addInstance`, `setMetadata`.
`LuaGeneratorRegistry`	`LuaGeneratorRegistry.hpp`	Maps generator ID strings to Lua source. Scans `generators/lua/` at startup. Auto-discovers all `.lua` files.
`LuaSandbox`	`LuaSandbox.hpp`	Executes a single Lua generator safely. Blocks `io`, `os`, `debug`, `require`. Provides only the scene API and safe standard libraries.
`LuaRuntime`	`LuaRuntime.hpp`	Wraps sol2 + Lua 5.4. Manages the Lua state, binds the `scene` and `ctx` objects, and calls `M.generate(ctx, scene)`.
`TaxonomyRegistry`	`TaxonomyRegistry.hpp`	Loads `data/taxonomy/taxonomy.json`. Provides a node hierarchy (world → zone → block → building → room → object).
`ContainmentRuleRegistry`	`ContainmentRuleRegistry.hpp`	Loads `data/taxonomy/containment.json`. LOD-aware rules: which parent node can contain which child node at which detail level.
`MaterialRegistry`	`MaterialRegistry.hpp`	~100 built-in materials. Provides `resolve_color(name)` and validation of material name strings.
`MC3Validator`	`MC3Validator.hpp`	Validates MC3 XML: well-formed, metadata presence, bounds check, material name lookup. Returns `ValidationResult{valid, errors}`.
`SqliteContentPack`	`SqliteContentPack.hpp`	Writes and reads `.sqlite` content packs. Tables: generators, taxonomy, materials, styles.
`WorldMap`	`WorldMap.hpp`	Builds the zone/region assignment grid from the world config JSON. Provides `zone_at(x,y)` and `region_at(x,y)`.
`WorldStreamer`	`WorldStreamer.hpp`	Tracks player position in chunk-space, maintains a load radius, emits LOADED/UNLOADED callbacks as the player moves.
`WorldRenderer`	`WorldRenderer.hpp`	Wraps WorldStreamer + optional Mc3Renderer. `update()` drives streaming; `render()` draws loaded chunks.
`Mc3MeshBuilder`	`Mc3MeshBuilder.hpp`	CPU tessellator. Parses MC3 XML, converts box/cylinder/plane primitives to triangle meshes. Resolves material colours from registry.
`Mc3Renderer`	`Mc3Renderer.hpp`	First-person renderer. Wraps MeshCraft SceneRenderer. Guarded by `MESH_WORLD_HAS_RENDERER` — excluded from the core library.
`FPCamera`	`Mc3Renderer.hpp`	First-person camera: position (vec3), yaw, pitch, fov_y, near_z, far_z, aspect. Produces view + projection matrices.
`MainMenu`	`MainMenu.hpp`	In-app main menu system used by MeshWorldApp. Handles ESC → menu transitions.
`ChunkCache`	`ChunkCache.hpp`	File-based cache. Keys: `(x, y)` → `cache/chunks/x_y.mc3.xml`. Has/Put/Get operations.
`StyleRegistry`	`StyleRegistry.hpp`	Maps style name strings (e.g. `central_europe_small_city`) to style parameter sets used by generators.

Naming Convention

Generator IDs

Every generator has a unique string ID following a structured naming convention.

convention

Lua generators:
lua.<category>.<name>.<variant>

C++ generators:
cpp.chunk.<region>

Examples:
lua.object.chair.simple
lua.zone.park
lua.building.simple_house.standard
lua.room.kitchen.standard
cpp.chunk.river_bank
cpp.chunk.apartment_block

The category maps to the subdirectory under generators/lua/: zone, object, building, room. The variant allows multiple versions of the same conceptual generator (simple, detailed, ruined, etc.).

World Config

world.json Format

json

{
  "name": "demo_city",
  "seed": 42,
  "style": "central_europe_small_city",
  "grid_w": 20,
  "grid_h": 20,
  "chunk_size_m": 64,
  "zones": [
    {
      "type": "city",
      "x_min": 0, "x_max": 18,
      "y_min": 0, "y_max": 18,
      "region_default": "small_house_block",
      "regions": [
        {
          "x_min": 9, "x_max": 10,
          "y_min": 9, "y_max": 10,
          "type": "square"
        }
      ]
    }
  ]
}

Field	Description
`seed`	Global seed. Chunks derive their variation from `seed + x31 + y37`.
`style`	Style name resolved by StyleRegistry — affects material choices and proportions.
`grid_w/h`	World size in chunks. 20×20 = 400 chunks = 1280m × 1280m at 64m chunk size.
`chunk_size_m`	Side length of each chunk in metres (default 64).
`regions`	Sub-zones within a zone that override the `region_default` for specific coordinate ranges.

Data Format

MC3 XML Format

MC3 (MeshCraft 3) is the XML scene format used by the MeshCraft ecosystem. Each chunk is stored as one MC3 file containing:

A <mc3> root element with version attribute
A <metadata> block (generator ID, version, language, generation parameters)
A flat list of primitives: <box>, <cylinder>, <plane>, <ground>
Each primitive has an ID, position, size/radius, material, and optional rotation (ry)

MC3 files can be compiled to MCB (binary) format by the MeshCraft toolchain using MeshWorldExport --mcb.

xml — sample mc3 output (excerpt)

<?xml version="1.0"?>
<mc3 version="1.0">

  <metadata>
    <generator
      id="lua.zone.park"
      version="0.1.0"
      language="lua"/>
    <chunk x="2" y="9" size_m="64"/>
  </metadata>

  <ground material="grass"/>

  <cylinder id="fountain_basin"
    x="32" y="0" z="32"
    radius="1.8" height="0.4"
    material="stone_wall"/>

  <box id="bench_n_seat"
    x="32" y="0.46" z="26"
    w="1.55" h="0.04" d="0.35"
    material="wood_bench"
    ry="0"/>

</mc3>

Repository

Directory Layout

filesystem

mesh-world/
  apps/mesh-world-app/  — standalone 3D viewer
  cache/chunks/         — generated MC3 XML cache
  data/taxonomy/        — taxonomy.json + containment.json
  docs/                 — design documents
  examples/             — world.json demo config
  generators/lua/       — Lua generators
    zone/               — park.lua, forest.lua, road.lua…
    object/             — bench.lua, tree.lua, lamp.lua…
    building/           — simple_house.lua
    room/               — kitchen.lua
  include/              — C++ public headers
  src/                  — C++ sources
    generators/         — 20 C++ chunk generators
    materials/          — built-in material definitions
    styles/             — built-in style definitions
    tools/              — CLI tool main() functions
  tests/                — GTest suite (119 tests)
  vendor/               — googletest, nlohmann/json
  CMakeLists.txt
  plan.md               — task list T001–T255+

Test Coverage

The GTest suite covers all major subsystems. 119 tests pass with zero compiler warnings on every CI push.

Subsystem	Coverage highlights
ChunkPipeline	Cache hit/miss, validation failure, Lua override detection
LuaSandbox	Sandbox isolation, all scene API calls, error propagation
MaterialRegistry	All ~100 materials register, unknown name → error
MC3Validator	Well-formed XML, missing metadata, out-of-bounds, bad material
WorldStreamer	3×3 area around origin loads on update()
Mc3MeshBuilder	Park chunk XML → non-empty mesh list (6 tests)
TaxonomyRegistry	Node hierarchy loads, parent/child lookups
ContainmentRuleRegistry	LOD rule lookup, out-of-range LOD
SqliteContentPack	Round-trip: pack → read back → match

Dependencies

External Libraries

Lua 5.4.7

Embedded scripting language. Auto-downloaded by CMake FetchContent at configure time. No system package needed.

MIT

sol2 3.3.0

Header-only C++17 binding library for Lua. Makes binding C++ objects to Lua clean and type-safe. FetchContent.

MIT

SQLite 3

System package (libsqlite3-dev). Used for content pack storage and loading.

Public Domain

nlohmann/json

Header-only JSON parser used for world.json, taxonomy.json, and containment.json. Vendored.

MIT

GoogleTest

GTest + GMock test framework. Vendored. Used by the 119-test suite.

BSD-3-Clause

tinyxml2

Lightweight XML parser. Used by MC3Validator and Mc3MeshBuilder to parse chunk scene files.

zlib

Viewer-only dependencies (MeshWorldApp only): SDL3, OpenGL, MeshCraft, CNA, EasyGL, SharpRuntime. These are separate sibling repositories and are not required to build the core library or CLI tools.