ra3-map-lua4-skill

name	ra3_map_lua4_skill
description	Red Alert 3 地图脚本、WorldBuilder、Lua 4.0、脚本加载顺序、地编伴侣 Ra3MapUtils。 在编写或修改 RA3 地图 Lua、配置脚本加载顺序、区分 Lua4 与 Lua5 语法、或对照引擎 API 时使用。

ra3_map_lua4_skill

指导 Agent 为 红色警戒 3 地图编写符合 Lua 4.0 的脚本。

快速检查清单

• 语法按 Lua 4，不要用 Lua 5；不确定处查本仓库 RA3CoronaMapLuaLib 与已有地图 Lua，勿编造 API。
• 校验语法前可先通过 skill ra3-maputils-companion-http 确认 http://127.0.0.1:30033 为地编伴侣；再用 ra3-lua4-syntax-http 调用 POST /api/lua4/syntax/code 或 /api/lua4/syntax/file（filePath 可与 workingDirectory 组合为相对路径，见该 skill）。
• 路径说明一律相对 用户当前工作区根目录（或地图工程根目录），不写死本机绝对路径。

RA3 地图 Lua 项目结构

标准目录布局

map_project/
├── map.str                     # RA3地图的配置文件
├── debug_lua                   # 存放用于debug的lua4脚本, 不会被放到地图中
├── lua/
    ├── first_of_all.lua        # 最先执行的逻辑, 初始化整体项目的一些配置, 定义整个项目的变量table
    ├── 1_funcs/                # 一些共用的函数
    │   └── xxx_func.lua        
    ├── 2_config/               # 读取或定义配置项
    │   └── xxx_config.lua
    ├── 3_special_unit/         # 如果有必要的话, 定义特殊的单位, 被抽象成`类`
    │   ├── xxx_1/              # 定义一个类
    │   └── xxx_2/              # 定义一个类
    ├── [...]_xxx/              # 如果有必要的话, 定义各种逻辑
    │   └── xxx.lua
    ├── 8_init/                 # 初始化
    │   ├── xxx_init.lua        # 定义某个部分的初始化逻辑
    │   └── init.lua            # 统一进行初始化
    └── 9_update/               # 主循环
        ├── loop.lua            # 主循环逻辑，定义一次即可
        └── update.lua          # 每帧入口，内部调用 loop

新项目初始化流程（先骨架后逻辑）

如果需求中的目录不存在或目录为空, 则这是一个全新的项目.
当项目是全新创建时，先把最小可运行骨架搭好，再写业务逻辑。推荐顺序：

1. 创建 lua/ 目录, 作为lua项目的根目录。
2. 参考标准目录布局, 建立整个项目结构.
3. 需要提示用户, 在地编伴侣中将9_update/update.lua配置成每帧调用
4. 创建debug_lua目录, 用于存放debug的临时lua文件.

lua文件的执行顺序

第一帧

在同一目录内：先执行该目录下的 .lua 文件，再进入子目录递归同样规则。
一个子目录整棵子树执行完毕后，才会执行下一个兄弟子目录（深度优先、子目录之间顺序由工具/配置决定时以工具为准）。

其他帧

只运行9_update/update.lua

项目编程规范和建议

first_of_all.lua

first_of_all.lua中定义了整个项目的配置

-- first_of_all.lua 的示例
logger.setup(LoggerLevelEnum.DEBUG, {LoggerTargetEnum.DEBUG_LOG_FILE})

MyLua = {
    _meta = {
        tags = {
            railway_station_tag = newtag(),
            train_tag = newtag()
        }
    }
    config = {},
    funcs = {}
}

2_config目录

2_config目录负责定义配置数据, 或从map.str文件中解析并读取配置, 详情参考本skill中的reference/suggest/config.md

3_special_unit目录

3_special_unit 中实现玩法侧的「类」：常用 newtag + settag + settagmethod("index", ...)，使实例支持 obj:method()，与库内 UnitHelper.build_unit、StateMachine.new 同构；也可仅用 table + 函数（见该文档）。细则与目录拆分见 reference/suggest/special_unit.md。

8_init目录

8_init目录负责项目的初始化工作, 详情参考本skill中的reference/suggest/init.md

map.str文件

map.str文件是地图的配置文件, 详情参考本skill中的reference/suggest/map.str.md

lua库参考

地图侧封装库位于工作区内的 RA3CoronaMapLuaLib/（相对路径：以当前打开的工作区根目录为基准，例如 RA3CoronaMapLuaLib/lib/...）。分享本 skill 时，说明「在用户仓库中位于工作区根下的 RA3CoronaMapLuaLib」，勿写 n:\... 等本机路径。

Unit 参考入口

创建/操作单位时，优先查 unit.md。

• SKILL.md 保留原则与全局约束。
• unit.md 提供 Unit 的高频操作、最小示例、以及查源码边界规则。

buff/status/modelstate 对照与选型

在 RA3 地图 Lua4 中，这三者都常用，但职责不同。优先按下表选型，避免混用导致行为难排查。

维度	buff（AttributeModifier）	status（Object Status）	modelstate（ModelCondition）
定位	属性修改器（偏数值层）	物体状态位（偏规则/逻辑层）	模型条件（偏表现层）
典型用途	加减攻击、防御、速度、射程等属性	不可攻击、不可选中、不可移动、逻辑标记	隐藏 UI、展开/收起相关表现、模型条件切换
核心 API	u:add_modifier / u:remove_modifier	u:add_status / u:remove_status / u:is_has_status	u:add_model_state / u:remove_model_state / u:is_has_model_state
时长单位	frame_cnt（帧）	状态位开关（通常无单独时长参数）	duration_seconds（秒）
查询/移除方式	移除：remove_modifier	查询：is_has_status，移除：remove_status	查询：is_has_model_state，移除：remove_model_state
何时优先选它	你要“改数值强度”	你要“改行为限制/规则判定”	你要“改视觉或模型条件表现”

常见坑（务必避免）：

• 帧 vs 秒不要混淆：add_modifier 用帧，add_model_state 用秒。
• status 可当纯标记：部分状态更多用于逻辑分流，不一定直接改变数值。
• 优先用 Enum：优先写 AttributeModifierEnum/StatusEnum/ModelStateEnum，避免硬编码字符串拼错。

实操模板与同一单位叠加三者的示例，见 unit.md 的 BUFF / Status / ModelState 快速决策 小节。

EventSys 事件系统参考入口

处理引擎事件（单位创建/死亡、按钮点击、键盘鼠标等）或需要自定义领域事件时，优先查 event_sys.md。

• 源码：RA3CoronaMapLuaLib/lib/event_sys/EventSys.lua
• 核心 API：take_over_engine_event、subscribe / unsubscribe、emit
• 领域事件推荐模式：在 subscribe(原始类型) 回调中 emit("自定义类型", ...) ，再 subscribe 自定义类型写纯业务

Lua 4 编程规范（相对 Lua 5）

• 使用 Lua 4 语法与语义，不要按 Lua 5 书写。
• 语法校验：优先确认地编伴侣 HTTP 可用（skill ra3-maputils-companion-http），再遵循 ra3-lua4-syntax-http，对 http://127.0.0.1:30033 使用 POST /api/lua4/syntax/code（源码）或 POST /api/lua4/syntax/file（磁盘路径；可与 workingDirectory 配合使用相对路径，见该 skill）。

常见错误与正解

metatable

Lua 4 没有 Lua 5 的 metatable。需要「实例 + 方法」时，用引擎的 tag：newtag、settag、settagmethod（通常配合 "index" 把查找转到类表）。完整步骤与 3_special_unit 目录约定见 reference/suggest/special_unit.md；库内参照 RA3CoronaMapLuaLib/lib/helper/UnitHelper.lua（build_unit）、lib/object/StateMachine.lua（StateMachine.new）。

local function

不支持。可写成 local f; f = function() ... end 等形式（与项目现有风格一致）。

闭包与上值

Lua 4 用 %name 访问外层局部；尽量少用闭包，复杂自调用优先用 table 上的方法（见下节）。

coroutine

不支持

ipairs(t)

不支持
序列表用 getn(t) + 数值 for，例如：for i = 1, getn(list) do local x = list[i] ... end

函数自调用写法（递归/重入）

若函数体内需要再次调用自身，优先把函数定义在 table 字段上，减少 Lua4 局部自引用带来的不确定性。

推荐写法：

MyModule = {}

function MyModule.tick(ctx)
    if ctx ~= nil and ctx.need_next then
        MyModule.tick(ctx.next_ctx)
    end
end

不推荐把此类逻辑写成依赖局部 upvalue 的自引用形式。

查 API 与不确定内容时的顺序

1. 工作区内的 RA3CoronaMapLuaLib/（相对工作区根目录；枚举、封装、命名习惯）。
2. 同一工作区下已有地图工程（如 special_workspace/ 下示例）的 Lua 作为可运行参考。
3. 地编伴侣 / 项目约定的 MCP 或 HTTP 文档接口（在已启动且可连上的前提下）。
4. 仍无法确认：在代码中留白并写 TODO，或明确拒绝编造 API；不要虚构函数签名或引擎行为。

DEBUG 指南

日志埋点

如果需要通过埋点的方式来获取运行时的状况, 可以使用lua库中的logger来埋点, 不要使用任何io函数.
完成必要埋点后, 可以让用户重新导入lua工程, 并重启游戏, 把相关埋点日志复制给你, 进行进一步的分析.

在游戏环境中执行lua代码

你可以直接访问游戏的运行环境, 并执行代码, 获取返回值/输出内容, 或询问用户游戏中发生了什么变化.
还有控制游戏时间, 暂停/加速/单帧调试的功能.
你可以在项目中的debug_lua文件夹中保存用来调试的lua文件.
详情参考本skill中的reference/suggest/debug.md

与 Cursor 规则的关系

编辑器内 **/*.lua 的 Lua4 约束见 .cursor/rules/ra3-lua-rule.mdc，与本文档保持一致。