C++ 引擎底层 Native 绑定与 Lua 导出指南 (Engine Native Binding Guide)¶

本指南面向 CCB 引擎与核心子系统开发者，详尽说明如何为游戏底层的 C++ 类、方法与数据结构添加 Sol2 原生绑定，并将其安全地导出给 CCB Lua 0.1 运行时的完整标准化流程。

1. 架构原则与安全模型¶

在 CCB 引擎中，C++ 到 Lua 的导出必须遵循以下 3 大铁律： 1. 代际安全句柄（Generation-Safe Handles）： - 严禁将裸 C++ 对象指针直接裸露给 Lua 长期持有。 - 所有动态生命周期实体（如 Character*、item*、monster*）必须包装在 game_handle 中，在每次解引用时校验 runtime_generation 和 world_generation，防止悬垂指针崩溃。 2. 零拷贝内存直连（Zero-Copy Direct In-Memory Invocation）： - C++ 与 Lua 之间通过 Sol2 / Lua-C 虚拟机栈进行参数传递，禁止任何 JSON 字符串中转。 3. 100% 契约覆盖率与静态类型保证： - 每一个新导出的 C++ 符号必须在 data/lua/types/ccb_api_v5.d.lua 中提供完整的 LuaLS 类型注解，并通过 check_coverage.py 门禁。

2. 步骤一：在 C++ 中编写原生绑定¶

假设我们在 C++ 中新增了一个天气雷达系统 weather_radar，需要导出查询强对流风暴的方法：

// src/catalua_ui_weather.cpp
#include "weather.h"
#include "catalua_platform_content.h"
#include <sol/sol.hpp>

namespace catalua {

// 1. 实现安全包装函数 (包含句柄与边界检查)
sol::table get_storm_forecast(
    lua_State *lua,
    const game_handle &target_pos,
    const int forecast_hours )
{
    sol::state_view state( lua );

    // 权限检查: 确保调用方具备天气读取权限
    require_capability( state, "game.read", "game.weather.get_storm_forecast" );

    // 调用底层 C++ 引擎方法 (纯内存直连)
    const weather_forecast forecast = weather_manager::forecast_at( target_pos.pos(), forecast_hours );

    // 构造返回给 Lua 的表结构
    sol::table result = state.create_table();
    result["has_storm"] = forecast.has_storm;
    result["intensity"] = forecast.intensity;
    result["wind_speed"] = forecast.wind_speed;
    result["predicted_turn"] = forecast.predicted_turn;

    return result;
}

// 2. 注册到 Lua 命名空间
void register_weather_bindings( sol::state_view &lua ) {
    sol::table weather_ns = lua["game"]["weather"].get_or_create<sol::table>();

    weather_ns["get_storm_forecast"] = &get_storm_forecast;
}

} // namespace catalua

3. 步骤二：编写 LuaLS 类型声明 (`.d.lua`)¶

在 data/lua/types/ccb_api_v5.d.lua 中添加对应的 IDE 类型提示：

---@class WeatherForecast
---@field has_storm boolean 是否存在暴风雨
---@field intensity number 风暴强度指数 (0.0 ~ 1.0)
---@field wind_speed number 预测风速 (km/h)
---@field predicted_turn integer 预测降临的回合数

---查询指定坐标未来数小时的风暴气象预报
---@param target_pos Tripoint 目标三维网格坐标
---@param forecast_hours integer 预报展望小时数
---@return WeatherForecast 预报结构体
function game.weather.get_storm_forecast(target_pos, forecast_hours) end

4. 步骤三：自动生成契约清单与覆盖率验证¶

在终端中执行本地契约同步工具：

# 1. 重新扫描 C++ 导出清单
python3 tools/lua_api/generate_ccb_inventory.py

# 2. 重新生成公共 API 契约与覆盖率
python3 tools/lua_api/generate_public_contract.py

# 3. 运行 100% 覆盖率验证与单测 (CI 门禁)
python3 tools/lua_api/check_coverage.py --require-complete
python3 tools/lua_api/check_luals_declarations.py
python3 -m unittest discover -s tools/lua_api -p 'test_*.py'

若全部通过，新导出的 C++ 方法即正式成为 CCB Lua 0.1 的一等公民，并在文档站重新构建时自动生成漂亮的 API 参考手册！

C++ 引擎底层 Native 绑定与 Lua 导出指南 (Engine Native Binding Guide)¶

1. 架构原则与安全模型¶

2. 步骤一：在 C++ 中编写原生绑定¶

3. 步骤二：编写 LuaLS 类型声明 (.d.lua)¶

4. 步骤三：自动生成契约清单与覆盖率验证¶

3. 步骤二：编写 LuaLS 类型声明 (`.d.lua`)¶