القائمة
Red Alert 3 地图脚本、WorldBuilder、Lua 4.0、脚本加载顺序、地编伴侣 Ra3MapUtils。 在编写或修改 RA3 地图 Lua、配置脚本加载顺序、区分 Lua4 与 Lua5 语法、或对照引擎 API 时使用。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
使用 C# 批量编辑 Red Alert 3 地图（Ra3MapSharp / Dreamness.RA3.Map.Facade），并通过 Ra3MapUtils 地编伴侣直接执行 C#（HTTP 与 MCP）。 当用户需要地图自动化改图、地形纹理处理、单位/路径点/玩家/队伍调整、脚本 JSON 导入导出、或查询 C# 地图库 API 时使用。 Use when users ask for RA3 map editing in C#, map automation scripts, map data import/export, or running C# via companion MCP/HTTP.
Validates Red Alert 3 map Lua 4.0 script syntax and retrieves error details by calling the Ra3MapUtils local HTTP API. Use when checking .lua map scripts, Lua4 syntax, RA3 triggers/scripts, or when the user asks to verify Lua4 against the running Ra3MapUtils service.
Detects whether the Ra3MapUtils desktop app (地编伴侣) is running by calling its local HTTP companion-presence endpoint. Use when the user asks if 地编伴侣 or Ra3MapUtils is running, alive, up, reachable, or before relying on other localhost:30033 APIs.
استنادا إلى تصنيف SOC المهني
| name | ra3_map_lua4_skill |
| description | Red Alert 3 地图脚本、WorldBuilder、Lua 4.0、脚本加载顺序、地编伴侣 Ra3MapUtils。 在编写或修改 RA3 地图 Lua、配置脚本加载顺序、区分 Lua4 与 Lua5 语法、或对照引擎 API 时使用。 |
指导 Agent 为 红色警戒 3 地图编写符合 Lua 4.0 的脚本。
RA3CoronaMapLuaLib 与已有地图 Lua，勿编造 API。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）。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
如果需求中的目录不存在或目录为空, 则这是一个全新的项目.
当项目是全新创建时，先把最小可运行骨架搭好，再写业务逻辑。推荐顺序：
lua/ 目录, 作为lua项目的根目录。标准目录布局, 建立整个项目结构.debug_lua目录, 用于存放debug的临时lua文件.在同一目录内：先执行该目录下的 .lua 文件，再进入子目录递归同样规则。
一个子目录整棵子树执行完毕后，才会执行下一个兄弟子目录（深度优先、子目录之间顺序由工具/配置决定时以工具为准）。
只运行9_update/update.lua
first_of_all.luafirst_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
地图侧封装库位于工作区内的 RA3CoronaMapLuaLib/（相对路径：以当前打开的工作区根目录为基准，例如 RA3CoronaMapLuaLib/lib/...）。分享本 skill 时，说明「在用户仓库中位于工作区根下的 RA3CoronaMapLuaLib」，勿写 n:\... 等本机路径。
创建/操作单位时，优先查 unit.md。
SKILL.md 保留原则与全局约束。unit.md 提供 Unit 的高频操作、最小示例、以及查源码边界规则。在 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 |
| 何时优先选它 | 你要“改数值强度” | 你要“改行为限制/规则判定” | 你要“改视觉或模型条件表现” |
常见坑（务必避免）：
add_modifier 用帧，add_model_state 用秒。AttributeModifierEnum/StatusEnum/ModelStateEnum，避免硬编码字符串拼错。实操模板与同一单位叠加三者的示例，见 unit.md 的 BUFF / Status / ModelState 快速决策 小节。
处理引擎事件（单位创建/死亡、按钮点击、键盘鼠标等）或需要自定义领域事件时，优先查 event_sys.md。
RA3CoronaMapLuaLib/lib/event_sys/EventSys.luatake_over_engine_event、subscribe / unsubscribe、emitsubscribe(原始类型) 回调中 emit("自定义类型", ...) ，再 subscribe 自定义类型写纯业务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）。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 上的方法（见下节）。
不支持
不支持
序列表用 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 的自引用形式。
RA3CoronaMapLuaLib/（相对工作区根目录；枚举、封装、命名习惯）。special_workspace/ 下示例）的 Lua 作为可运行参考。TODO，或明确拒绝编造 API；不要虚构函数签名或引擎行为。如果需要通过埋点的方式来获取运行时的状况, 可以使用lua库中的logger来埋点, 不要使用任何io函数.
完成必要埋点后, 可以让用户重新导入lua工程, 并重启游戏, 把相关埋点日志复制给你, 进行进一步的分析.
你可以直接访问游戏的运行环境, 并执行代码, 获取返回值/输出内容, 或询问用户游戏中发生了什么变化.
还有控制游戏时间, 暂停/加速/单帧调试的功能.
你可以在项目中的debug_lua文件夹中保存用来调试的lua文件.
详情参考本skill中的reference/suggest/debug.md
编辑器内 **/*.lua 的 Lua4 约束见 .cursor/rules/ra3-lua-rule.mdc，与本文档保持一致。