Sources: data/lua/README.md data/lua/manifest.schema.json data/lua/types/ccb_api_v5.d.lua data/lua/reference/ccb_public_api_v5.json data/lua/reference/ccb_public_api_v5_coverage.json tools/lua_api/README.md commit d32b9cc880a8 api-contract

Lua sections need revision: This page contains removed v5 APIs or old runtime examples. Do not use its Lua examples for current development. Start with Platform v1.

Map & Mapgen Manual¶

This manual explains the 3D coordinate system, sliding map cache architecture, and pure-Lua procedural map generation (Mapgen) in Cataclysm: Cleanwater Bomb (CCB).

1. 3D Spatial Grid & Submap Units¶

Tripoint(x, y, z):
$x, y$: Horizontal Cartesian coordinates.
$z$: Elevation index (0 for ground, negative for subterranean vaults, positive for multi-story towers).
Submap Chunk: $12 \times 12 \times 1$ tiles per chunk.
Mapgen Standard Grid: $24 \times 24$ tiles per standard overmap terrain tile.
Sliding Viewport Cache: The active memory maintains an $11 \times 11$ submap sliding window around the player.

2. Terrain & Furniture Rules¶

Terrain: Fixed structural ground geometry (concrete floor, reinforced wall, deep water).
Furniture: Placed on top of terrain (beds, generators, metal racks, consoles).

3. MapgenContext APIs¶

`context:set_terrain(x, y, terrain_id)`¶

Sets the base terrain type at local coordinate $(x, y)$.

`context:set_furniture(x, y, furniture_id)`¶

Places a furniture piece at local coordinate $(x, y)$.

`context:spawn_loot(x, y, loot_config)`¶

Spawns loot from a defined item group with probability and count constraints.

4. Blueprint Matrix Layout Example¶

local blueprint = {
    "########################",
    "#........|.............#",
    "#..B.....|.............#",
    "#--------+-------------#",
    "#......................#",
    "#..r........GG.........#",
    "#......................#",
    "########################"
}

local legend = {
    ["#"] = { terrain = "t_reinforced_wall" },
    ["."] = { terrain = "t_concrete_floor" },
    ["+"] = { terrain = "t_door_c" },
    ["-"] = { terrain = "t_wall_glass" },
    ["|"] = { terrain = "t_wall_glass" },
    ["B"] = { terrain = "t_concrete_floor", furniture = "f_bed" },
    ["r"] = { terrain = "t_concrete_floor", furniture = "f_rack_metal" },
    ["G"] = { terrain = "t_concrete_floor", furniture = "f_generator" }
}

game.mapgen.register({
    id = "ccb_outpost_bunker",
    om_terrain = "ccb_outpost",
    generate = function(context)
        context:draw_matrix(0, 0, blueprint, legend)
    end
})