■ Open Source · MIT License · C++23

Procedural 3D World
Generator & Explorer

MeshWorld generates infinite 3D city and landscape chunks from a simple JSON config. Script new content in Lua, explore in real time, pack everything into portable SQLite bundles.

Get Started View on GitHub Explore Features

C++ Generators

Lua Generators

119

Tests Passing

~100

Built-in Materials

Compiler Warnings

API Keys Required

World Map Preview

20 × 20 Demo City Layout

MeshWorldMap — examples/world.json (20×20 chunks, 64m each)

   0         1         1
   0123456789012345678 9
 0 HHHHHHHHHHHHHHHHHHHR
 1 HHRRRRRRRRRRRRRRHHHR
 2 HHRHHHHHHHHHHHHRHHR
 3 HHRHHPPPPPPPPHHRHHR
 4 HHRHHPPPPPPPPHHRHHR
 5 HHRHHHHHHHHHHHHRHHR
 6 HHRAAAAAARRAAAARHHR
 7 HHRRRRRRRRRRRRRRHHHR
 8 HHRHHRAAAAAARRHHR
 9 HHRHHRHHQQHHRRHHR
10 HHRHHRHHQQHHRRHHR
11 HHRRRRRRRRRRRRRRHHHR

Legend: H=SmallHouseBlock  A=ApartmentBlock  P=Park  Q=Square  R=Road

Core Capabilities

Everything You Need to Build Worlds

From JSON config to rendered 3D scene — MeshWorld handles the full pipeline.

■

Procedural Generation

20 built-in C++ chunk generators covering cities, forests, mountains, deserts, oceans, rivers, caves and more. Deterministic from a seed value.

◆

Lua Scripting

Write generators in Lua 5.4 with full access to the scene-builder API. Drop a file in generators/lua/ — it's auto-discovered at startup.

▲

Real-time Exploration

MeshWorldApp streams and renders chunks around the player using SDL3 + OpenGL. WASD movement, mouse look, live chunk loading.

▬

CLI Toolset

Five CLI tools: MeshWorld, MeshWorldMap, MeshWorldExport, MeshWorldMaterials, MeshWorldPack. Export 400 chunks with a single command.

◉

Content Packs

Pack all generators, taxonomy, and materials into a single portable SQLite file. Distribute, version, and swap content bundles independently.

■

Material Registry

~100 built-in procedural materials covering stone, wood, metal, glass, foliage, soil, water and more — each with RGB, roughness, and license metadata.

Architecture

The Generation Pipeline

Every chunk passes through a validated, cached, dual-language pipeline.

world.json_{World config — seed, grid size, zones, style}

WorldMap_{Assigns ZoneType + RegionType to each (x,y) chunk coordinate}

ChunkPipeline_{Checks disk cache first — skips generation if chunk exists}

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

LuaSandbox → LuaRuntime (Lua 5.4 + sol2)

C++ Fallback_{get_generator(zone, region)}

20 built-in chunk generators

MC3Validator_{Validates XML structure, metadata, bounds, material names}

ChunkCache_{Stores validated MC3 XML to disk (cache/chunks/)}

MC3 XML Output_{Load in MeshCraft viewer · compile to MCB binary}

Full Architecture Docs

Quick Start

Up and Running in Minutes

Build, generate a world, and explore — three commands.

bash

# Clone both repos side-by-side
git clone https://github.com/openeggbert/mesh-craft
git clone https://github.com/openeggbert/mesh-world
cd mesh-world

# Configure + build (Lua/sol2 auto-downloaded)
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

# Run tests
cd build && ctest --output-on-failure

# Generate demo world (20×20 chunks)
./build/MeshWorldExport examples/world.json output/

# ASCII zone map
./build/MeshWorldMap examples/world.json

# Launch interactive 3D viewer
./apps/mesh-world-app/build/MeshWorldApp

Write a Lua generator in minutes

lua — generators/lua/zone/my_zone.lua

local M = {}
M.id = "lua.zone.my_zone"

function M.generate(ctx, scene)
  -- ctx: variation, chunk_x, chunk_y, style, zone, region
  scene:addGround("grass")
  scene:addBox("shed", {
    position = {10, 1.5, 10},
    size     = {4, 3, 4},
    material = "plaster_white"
  })
  scene:addCylinder("lamp", {
    position = {20, 0, 20},
    radius = 0.06, height = 4.5,
    material = "metal_lamp"
  })
  scene:setMetadata({
    generator = {id=M.id, version="0.1.0", language="lua"}
  })
end

return M

Drop the file in generators/lua/zone/ and it's picked up automatically on next run.

Full Lua API Reference

Free. Open Source. No Strings.

MIT license. No credits. No billing. No subscription. No marketplace. No API keys committed.

Get Started View Roadmap Ecosystem

Procedural 3D World Generator & Explorer