跳转至
来源: 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 内容待修订： 本页仍含已移除的 v5 接口或旧运行时示例，不可作为当前 Lua 开发依据。请使用 Platform v1 入门。

地图与程序化生成技术手册 (Map & Mapgen Manual)

本手册详细介绍 Cataclysm: Cleanwater Bomb (CCB) 的三维立体空间模型、滑动窗口地图缓存以及纯 Lua 程序化地块生成（Mapgen）技术。

1. 三维空间与地图分层网格

CCB 采用三维立体网格坐标系统：

  1. 三维坐标向量 Tripoint(x, y, z)：
  2. $x, y$：水平面网格（东/南/西/北方向）。
  3. $z$：竖直高度层级。0 代表地面地表层，负数（-1, -2...）代表地下避难所与矿井，正数（1, 2...）代表高楼天台与屋顶。
  4. Submap 单元：基础地图数据以 $12 \times 12 \times 1$ 格为一个 Submap 单元。
  5. Mapgen 标准地块：标准单地块生成器以 $24 \times 24$ 格（$2 \times 2$ 个 Submap）为单位进行建筑填充。
  6. 滑动视口缓存 (map)：引擎在玩家周围维持一个 $11 \times 11$ 个 Submap 的活跃区域，实现无缝边界移动。

2. 地形 (Terrain) 与家具 (Furniture) 物理规则

  • 地形 (Terrain)：构成地面的永久结构（如土地、混凝土墙、深水、悬崖）。
  • 家具 (Furniture)：位于地形上方的可移动/可破坏物件（如桌子、储物货架、床、发电机、路障）。
  • 碰撞与视线穿透规则：
  • t_wall（实体墙）：阻挡移动、阻挡视线、阻挡流体。
  • t_window（玻璃窗）：阻挡移动、允许视线与光线穿透。
  • f_rack_metal（金属货架）：阻挡移动、允许视线穿透、提供物品堆叠容器。

3. Mapgen 生成器与上下文 API (MapgenContext)

context:set_terrain(x, y, terrain_id)

设置指定网格坐标的地形。

参数 (Parameters): * x, y (integer, 必填): 本地网格坐标 ($0 \sim 23$)。 * terrain_id (string, 必填): 目标地形标识符（如 "t_concrete_floor", "t_wall_metal"）。

context:set_furniture(x, y, furniture_id)

在指定网格坐标放置家具。

context:spawn_loot(x, y, loot_config)

在指定位置生成战利品池。

参数 (Parameters): * loot_config (table, 必填): 包含 group（掉落物组 ID）、count（生成数量区间 {min, max}）与 chance（生成概率 $0.0 \sim 1.0$）。

4. 实战：纯 Lua 蓝图矩阵绘制示例

-- 绘制包含安全门、床铺与物资货架的避难所前哨
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
})