msw-general

MSW General — 基础技能

用于创建 MSW（MapleStory Worlds）的基础技能，整合了共享工具、领域知识、平台规则和文件编写。其他所有 MSW 技能都依赖此技能。

---

核心原则：视觉精致度

MSW 是一个游戏创作平台。目标不是创建一个逻辑勉强可运行的原型，而是打造一款玩家乐于游玩的精致游戏。

因此，无论你创建什么实体——怪物、NPC、塔、物品或背景对象——都要搜索并应用符合其角色和个性的适当资源（精灵图、动画、音效）。不要保留默认精灵图，也不要让 SpriteRUID 留空。

创建实体时的资源应用原则：

1. 创建实体后，使用 msw-search 技能查找合适的精灵图/动画
2. 将找到的资源的 RUID 应用于 SpriteRendererComponent，以便实体能够在视觉上呈现
3. 如果包含战斗，还要设置受击/爆炸特效；如果包含交互，还要设置音效

实现功能 ≠ 完成。 精致的游戏需要搭配合适的资源和视觉呈现。

---

创建 .model 时——先查目录

不要从空文件开始新建 .model。技能本地的 models/ 文件夹中包含经过验证、按类别整理的模板——怪物（ChaseMonster/MoveMonster/StaticMonster）、NPC（StaticNPC）、玩家（Player/DefaultPlayer）、地形（Foothold/Ladder/Rope/Portal）、地图对象（MapObject/SkeletonMapObject/ItemAsset）、粒子（BasicParticle/SpriteParticle/AreaParticle/AnimationPlayer）、声音（Sound/SoundEffect）、瓦片地图容器（TileMap/RectTileMap）、UI（UIButton/UIText/UISprite/UIGroup 等）、外部媒体（WebSprite/YoutubePlayerWorld）。

工作流：先完整阅读 references/model.md（必做——参见下方“模型工作预检——必须”） → 从目录中选择最接近的模板 → 通过 ModelBuilder 加载模板（调用协议：references/builder-protocol.md 核心内容 + references/builder-protocol-model.md）→ 通过构建器替换 3 个标识符（EntryKey、Id、Name）→ 通过构建器自定义 Components/Values/Properties/Children → 保存到 RootDesk/MyDesk/Models/ 下按类型分类的子文件夹中（例如 Models/Monsters/{Name}.model，不要直接放在 MyDesk/ 下）→ refresh。详细目录和构建器流程见 references/model.md §2。

构建器会生成必需的值元数据，因此 Agent 无需阅读或手写 .model 格式的内部细节。

对于怪物，先在 references/animation-state.md §0 中选择一种模式，然后按照 references/monster.md §5 采用推荐路径。

• 模式 A（已验证可用的规范模式——Soldier 参考配置，完整源码内嵌于 references/monster.md §7）：无需模板；从头组装 11 个组件，并使用自定义 script.MyMonsterAI（SoldierAI 风格），而不是 AIChase/AIWander。StateComponent.IsLegacy 保持默认值。
• 模式 B（MonsterCanonical.model）：采用 AIChaseComponent + ActionSheet 流程。必须设置 StateComponent.IsLegacy=false。其他怪物模板（ChaseMonster / MoveMonster / StaticMonster）的 ActionSheet 为空，并使用在模式 B 下会静默失效的默认值（大写键、SortingLayer="Default"、IsLegacy=true）。

**对于任何包含 StateAnimationComponent（怪物/NPC）或 AvatarStateAnimationComponent（玩家）的实体，或任何调用 ChangeState / AddState / SetActionSheet 的 .mlua，也要阅读 references/animation-state.md。**状态机与动画流程、两种模式的区分、默认状态注册规则、[LEA-3005] 的原因，以及 SetActionSheet 与 ChangeState 的语义都在其中（不会在各实体文档中重复说明）。

---

放置多个实体——优先使用模型

如果同一实体将在同一张地图中出现两次或更多次（5 个怪物、10 棵树、3 个传送门，……），请先创建 .model，再通过 modelId 放置每个实例，不要复制粘贴内联 @components。

同一构成的实例数量	选择
1（在单张地图中真正独一无二的装饰）	可以使用内联 @components
≥2	使用 .model + modelId 实例（默认）
运行时生成（SpawnByModelId）	无论数量多少，都必须使用 .model

默认采用这种方式的原因：

• 修改一次，处处生效——更改模型中的 SpriteRUID/HP/ActionSheet，所有实例都会更新。内联副本则需要每次逐一修改 N 个实体。
• .map 差异更小，也更易审查——modelId 实例只包含 Transform 覆盖项；内联副本会让地图中每个实体增加数百行内容。
• 避免偏差——五个内联副本可能在不知不觉中出现差异（一个设置了 IsLegacy: true，另一个却忘了设置 SortingLayer: "MapLayer0"）。模型则确保规范值一致。
• SpawnByModelId 必需——没有已注册的模型 id，动态生成就会失败。

工作流：

1. 在 RootDesk/MyDesk/Models/{Category}/{Name}.model 下创建 .model（参见上文的文件夹规则）。
2. 通过 MapBuilder 放置每个实例（调用协议：references/builder-protocol.md 核心内容 + references/builder-protocol-map.md），以保持 id、路径、componentNames、源信息和每个实例的组件覆盖项同步。
3. 执行 refresh。

详情及内联与 modelId 的对比：references/entity.md "Two-Step Map Editing Workflow"、references/model.md §1。

---

预检读取语义——适用于此技能中每项“必须读取”要求

预检和绝对原则中的“先读取 X”意为：开始工作前，X 必须完整地处于上下文中，而不是“每轮都重新读取 X”。仅当文件在本次会话中从未加载，或因上下文压缩而丢失时，才应完整读取文件（不使用 offset/limit，也不使用 cat/Get-Content）。不要重新读取已完整处于上下文中的文件——要求是文件存在于上下文中；重复读取只会浪费资源。文件的记忆或摘要不等同于文件处于上下文中；之前的轮次加载过该文件，也不能免除本轮确认其仍在上下文中的要求。

---

实体工作预检——必须执行

如果任务以任何方式涉及实体，**必须先读取 references/entity.md。**没有例外。

---

构建器协议预检——MUST

如果任务会创建或修改任何 .map / .model / .ui 文件——无论是直接操作，还是通过编写会生成 / 放置 / 绑定对象的 .mlua 间接操作——必须先将 references/builder-protocol.md（核心）以及任务会修改的每种文件类型对应的构建器文件——references/builder-protocol-map.md（.map）/ references/builder-protocol-model.md（.model）/ references/builder-protocol-ui.md（.ui）——完整载入上下文（参见上文的阅读语义）。没有例外。

该协议是一个统一入口，由共享核心（builder-protocol.md——路由、通用工作流、链式调用约定、第 §0 节预检、第 §4 节跨流程、第 §5 节检查清单）和各构建器文件（builder-protocol-map.md 第 §1 节 / builder-protocol-model.md 第 §2 节 / builder-protocol-ui.md 第 §3 节）组成。只了解一种构建器的协议，然后调用另一种构建器的 .cjs，会绕过该构建器的写入约定（componentNames 同步、Values 的 typeKey 元数据、写入时自动 lint、placeModel 组件镜像、子实体不变量）——三者通过跨流程（模型编写 → 地图放置 → UI 绑定）相互关联，因此跨流程任务必须载入所有匹配的构建器文件。

触发条件（有意设得宽泛——符合任一条件时，载入缺失的协议文件）：

• .map 变更（实体放置、组件修补、图块 / 落脚点检查）
• .model 变更（新建、值 / 组件 / 属性 / 子项编辑）
• .ui 变更（新建、组件 CRUD、绑定注入）
• 调用任何 MapBuilder / ModelBuilder / UIBuilder
• 类似“实体”的任务——怪物 / NPC / 投射物 / 地图对象 / 弹窗 / HUD 等
• 使用 _SpawnService 的任何代码（可生成的模型必须先编写并放置）

领域参考资料（entity.md / model.md / msw-ui-system 设计参考）必须与协议文件同时阅读，不能替代协议文件（领域上下文 + 调用协议，两者缺一不可）。每次触发条件的轮次都要确认这些资料仍在上下文中——只需重新阅读从未载入或因上下文压缩而丢失的内容。

---

模型工作预检——MUST

如果任务以任何方式涉及编写或编辑 .model 文件——包括调用 ModelBuilder（任何 API）、从模板创建新模型、修改现有模型的组件 / 值 / 属性 / 子项 / 事件链接，甚至只做一行调整——必须先将 references/model.md 完整载入上下文（参见上文的阅读语义）。没有例外。

构建器的模板目录、三标识符替换规则（EntryKey / Id / Name）、必需的值元数据、属性 / 子项 / 事件链接 API，以及 RootDesk/MyDesk/Models/ 下按类型划分的保存目录结构，都只记录在 references/model.md 中。不先阅读 references/model.md 就调用构建器，会悄然生成损坏的模型（缺少值元数据、标识符不匹配、保存目录错误、默认值静默失效）。零散阅读模板文件或凭记忆猜测 API 不能替代该文档——每次开始处理 .model 的轮次时，都要确认它仍在上下文中；只有在内容丢失时才重新阅读。

---

地图工作前置检查（进行任何地图工作之前）

开始任何与地图相关的任务之前——实体放置、生成、移动脚本、模型制作、图块编辑等——你必须按顺序完成以下两个步骤：

1. 确认目标地图——其路径（./map/{mapname}.map）、根实体，以及它在层级中的位置。
2. 使用 MapBuilder 将 MapComponent.TileMapMode 读取为数字（调用协议：references/builder-protocol.md 核心内容 + references/builder-protocol-map.md）。在本次会话的后续过程中记住该值。

值	模式	必需的 Body	不匹配 / 缺少 Body 时的运行时日志
0	TileMap（MapleTile，侧视 + Foothold）	RigidbodyComponent	[LEA-3004] MissingComponent : Entity is missing 'RigidbodyComponent'.
1	RectTileMap（RectTile，俯视）	KinematicbodyComponent	[LEA-3004] MissingComponent : Entity is missing 'KinematicbodyComponent'.
2	SideViewRectTileMap（SideViewRectTile，侧视图块）	SideviewbodyComponent	[LEA-3004] MissingComponent : Entity is missing 'SideviewbodyComponent'.

在不知道当前 TileMapMode 的情况下，绝不要开始地图工作。 三种模式在 Body 组件、重力、碰撞和事件堆栈方面完全不同。不匹配几乎不会导致编译时错误——它会表现为静默故障（实体无法移动 / 穿过墙壁 / 不可见），或者出现上述三种 [LEA-3004] MissingComponent 运行时日志之一。每当看到这三条消息中的任意一条时，首先应怀疑 TileMapMode 与实体 Body 不匹配。

推荐合适的模式——开始创建新地图或当前模式明显不符合用户目标时必须执行

每当用户描述他们想要制作的游戏 / 地图时（创建新地图、“制作一款横版卷轴游戏”、“我想要一个俯视角地牢”等），或者你读取当前 .map 后发现其 TileMapMode 不符合用户预期的玩法时，在继续进行任何实体 / 模型 / 脚本工作之前，必须明确向用户推荐合适的 TileMapMode 并解释原因。

以下决策矩阵是权威依据：

用户预期的游戏 / 玩法	推荐	原因
MapleStory 风格的横版卷轴动作 · 跳跃 · 爬梯 · 可自由放置的 Foothold（平台跳跃）	0 MapleTile	侧视 + 重力，使用 FootholdComponent 线段平台——非网格、可自由放置的平台
俯视角 RPG · 迷宫 · 棋盘游戏 · 地牢探索 · Bomberman 风格 · RTS 风格 · 农场模拟	1 RectTile	俯视角四向自由移动、无重力、方形图块网格
基于图块的横版卷轴平台游戏 · Mario 风格的像素动作 · 侧视解谜（方形图块侧视）	2 SideViewRectTile	侧视 + 在图块网格上施加重力（而非可自由放置的 foothold）

流程：

1. 如果用户尚未说明想制作哪类游戏，推荐模式之前先询问（一个简短的问题即可——例如：“这是俯视角，还是横版卷轴（跳跃 / 爬梯）？地形是基于可自由放置的 foothold，还是方形图块网格？”）。
2. 意图明确后，说明推荐方案（模式编号 + 名称 + 一句话理由），以及用户需要的对应 Body / 地图组件（参见 platform.md §4 映射表）。
3. 尽早确定模式选择——之后切换 TileMapMode 会清除地形，必须重新检查每个 Body / 移动脚本，而且可能需要重新绘制所有图块（参见 platform.md §4“切换地图类型时的注意事项”）。

更改 TileMapMode — 由用户在 Maker 中操作，而非 AI 编辑文件

AI 绝不能直接编辑 .map JSON 来切换 MapComponent.TileMapMode。 切换模式需要替换 Tile 组件、重建落脚点、转换瓦片数据格式并重置地形——这些都是 Maker 的内部操作。

引导用户在 Maker 编辑器中完成此操作：

1. 打开 Maker 编辑器的 层级 窗口。
2. 在层级窗口中右键单击目标地图实体。
3. 在上下文菜单中，选择与目标模式对应的“Switch ...”选项（Switch TileMap / RectTileMap / SideViewRectTileMap）。Maker 会执行转换、替换 Tile 组件，并按需重置地形。
4. 用户确认切换完成后，调用 MCP refresh，然后重新读取 MapComponent.TileMapMode 以验证，并根据新模式重新检查每个动态实体的 Body 组件。

AI 在模式更改中的职责：提出建议 → 等待用户在 Maker 层级窗口中右键切换 → refresh → 修复不再匹配的 Body 组件 / 脚本。 绝不要通过编辑文件来写入新的 TileMapMode 值。

上表仅为摘要。模式切换流程、Body 替换后的检查清单，以及 LEA-3004 以外的静默失败症状词典仅见于 references/platform.md §4（映射 + 检查协议 + 切换策略）和 references/troubleshooting.md（完整症状词典）——更改模式 / 替换 Body / 调试静默失败时，必须阅读这些内容。各地图类型的详细模式：platform-maple.md / platform-rect.md / platform-sideview.md。瓦片绘制：references/tile.md。地图工作预检：references/entity.md。

---

平台规则预检 — 当以下任一触发条件成立时，必须执行

如果以下任一触发条件与你的任务匹配，请在编辑代码或提出计划之前Read对应的参考文档。这些触发条件的范围刻意设得很广——不确定时就阅读。SKILL.md 中的“8 条核心规则”仅为摘要；症状→原因→修复表、各地图类型的代码模式、MovementComponent 转换公式以及 SortingLayer/SpriteRUID 详情仅见于参考文档。

触发条件（关键词／情况）	要阅读的文件
跳跃、重力、移动、MoveVelocity、InputSpeed、JumpForce、WalkSpeed、SpeedFactor、foothold、巡逻	对应地图类型的 references/platform-maple.md / references/platform-rect.md / references/platform-sideview.md（全文）以及 references/platform.md §10
spawn / _SpawnService / SpawnByModelId / SpawnByEntity /“召唤怪物”/“运行时创建”	references/platform.md §8 + §8.5
屏幕坐标／相机范围／“是否在屏幕上”／“像素单位”/ OrthographicSize / 世界单位	references/platform.md §5
被遮挡／不可见／“应该渲染在最上层”/ SortingLayer / OrderInLayer / Z 值	references/platform.md §6 + §7
日志中出现 LEA-3004 /“无法移动”/“悬浮在半空中”/“卡在墙里”/“被弹开”/“消失在地图外”/“从 foothold 边缘掉落”	首先阅读 references/troubleshooting.md（全文），然后阅读对应地图类型的 platform-{type}.md §7
LEA-3005 InvalidArgument 'stateName' / StateComponent / StateType / @State / ChangeState / AddState / AddCondition / ActionSheet / SetActionSheet / StateAnimationComponent / AvatarStateAnimationComponent / StateChangeEvent /“动画不变化”/“移动时仍保持站立／空闲状态”/“攻击姿势始终不播放”/“受击动画循环播放”/怪物·NPC·玩家动画状态相关工作	首先阅读 references/animation-state.md（全文），然后阅读 references/monster.md（或对应实体的文档），了解实体级组合方式
shader / material / 轮廓 / 发光 / 模糊 / 像素化 / 彩虹 / 色调 / 灰度 / 暗角 / 屏幕滤镜 / 镜头畸变 / 波浪 / 涟漪 / 扭曲 / 溶解 / 加色 / 混合模式 / 全息影像 / 遮罩 / 后处理 / MaterialID / MaterialId / ChangeMaterial / _MaterialService / .material 文件	完整阅读 references/material.md — 然后通过 mlua_Document_Retriever + mlua_API_Retriever MCP 查询获取着色器目录、属性名称和各组件兼容性信息（请勿凭记忆作答）
新地图设置／新项目／.config／扇区注册／文件夹元数据刷新	references/platform.md §2 + §15
MapleTile（TileMapMode = 0）相关工作 — Foothold、Gravity、WalkSpeed、PredictFootholdEnd	references/platform-maple.md（全文）
RectTile（TileMapMode = 1）相关工作 — SpeedFactor、四方向移动、可移动瓦片、动态瓦片	references/platform-rect.md（全文）
SideViewRectTile（TileMapMode = 2）相关工作 — JumpSpeed/JumpDrag、墙体检测（Normal）、EnableDownJump	references/platform-sideview.md（全文）

如果匹配两个或更多触发条件，请全部阅读。“我已经看过 SKILL.md 中的 8 条核心规则”不能成为跳过参考文档的借口。

8 条核心规则（必须牢记）

1. 如果未对齐 TileMapMode ↔ Body 映射，实体将无法移动（不会报错），或在运行时抛出 [LEA-3004] MissingComponent → references/platform.md §4（如果想按症状排查，请参阅 references/troubleshooting.md）
2. 用户脚本仅能以 .mlua + .codeblock 成对使用——.codeblock 由 Maker Refresh 生成
3. 如果 SpriteRUID 是空字符串，实体将在屏幕上不可见（不会报错）
4. 调用 SpawnByModelId 时，如果未将地图实体（self.Entity.CurrentMap）作为 parent 传入，将导致运行时错误
5. 坐标单位为世界单位（1 单位 = 100 px）。像素值会相差 100 倍
6. Maker 只扫描 RootDesk/——放在 Global/ 中的用户文件将无法被识别
7. 不要修改 .d.mlua 或 .codeblock。
8. 手动编写的入口文件从 Environment/config 获取其 CoreVersion——构建器输出无需处理版本

---

MCP 工具速查表（msw-maker-mcp）

工具	用途
maker_get_current_map	当前地图名称/ID——在会话开始时，确认它们与某个 map/ 文件的名称和根实体 ID 一致（在其他世界中的 Maker 也会返回 ok）
play / stop	进入 / 退出播放模式
refresh	文件更改后同步 Maker（播放期间不可用）
logs / clear_logs	读取 / 清除运行时和构建日志
screenshot	仅在用户明确要求时调用
keyboard_input / mouse_input	在播放模式下模拟输入
maker_execute_script	以编程方式探测运行时——验证期间，优先使用一次探测，而不是一长串输入模拟（msw-scripting §17）

MCP 调用失败 / 出现“​​MCP connection”/“API Key”请求时 → 引导用户查看官方设置文档：https://maplestoryworlds-creators.nexon.com/ko/docs?postId=1368

---

按任务路由——应阅读哪些参考资料

文件	范围	阅读时机
workspace.md	世界实例 / Room / DataStorage、文件夹布局、文件路径、Play 模式、refresh、工作流中途失败恢复	工作区 / 实例 / 模式转换相关工作
platform.md（核心）	8 条核心规则、文件权威性 + 文件夹元数据、.mlua+.codeblock 配对、TileMapMode↔Body 映射 + LEA-3004、坐标系 / 屏幕范围、SortingLayer/OrderInLayer、SpriteRUID、SpawnByModelId 用法 / 初始化顺序、MovementComponent 按地图类型转换 InputSpeed 的公式、ECS、ID 生成、.config、CoreVersion	TileMapMode 映射 / 模式切换 / 生成 / 坐标 / RUID / SortingLayer / .config 和 CoreVersion / 文件夹元数据——所有地图类型通用的规则
platform-maple.md	仅限 MapleTile（TileMapMode = 0）——Foothold 物理、Gravity/WalkSpeed/WalkJump、PredictFootholdEnd、IsOnGround、DownJump、FootholdEnter/LeaveEvent、仅适用于 MapleTile 的故障排查 + 检查清单	横版动作 / 跳跃 / 梯子 / 自由放置 Foothold（MapleStory 风格的平台游戏）
platform-rect.md	仅限 RectTile（TileMapMode = 1）——KinematicbodyComponent、SpeedFactor、自由四向移动、仅视觉效果的跳跃、Movable 瓦片碰撞、ToCellPosition/ToWorldPosition、RectTileEnter/LeaveEvent、动态瓦片（SetTile/BoxFill）、仅适用于 RectTile 的故障排查 + 检查清单	俯视角 RPG / 迷宫 / 棋盘游戏 / 地下城探索 / Bomberman 风格 / RTS / 农场模拟游戏
platform-sideview.md	仅限 SideViewRectTile（TileMapMode = 2）——SideviewbodyComponent、JumpSpeed/JumpDrag、EnableDownJump、墙壁检测（RectTileCollisionBeginEvent + Normal）、GetUnderfootTile、仅适用于 SideView 的故障排查 + 检查清单	基于瓦片的横版平台游戏 / Mario 风格像素动作游戏 / 侧视角解谜游戏
troubleshooting.md	统一症状词典——LEA-3004 表 / “无法移动” / “无法渲染” / “悬在半空” / “卡在墙里” / “从地图上消失” / “从 foothold 边缘掉落” / “偏差 100×” / “在 Maker 中不显示” / “仅客户端同步”及其他静默故障症状→原因→修复统一索引	从症状着手调试——用户报告上述问题或日志中出现 [LEA-3004] 时，先从这里开始
authoring.md	5 种文件类型通用的创作原则（架构一致性、手动编辑风险）	编写任何文件前的入门文档
tile.md	瓦片绘制——Maker UI 领域，仅供 AI 参考	瓦片地图相关工作
builder-protocol.md（核心）+ builder-protocol-map.md / builder-protocol-model.md / builder-protocol-ui.md	.map / .model / .ui 的统一调用协议——核心：路由、通用工作流、串联契约、§0 前置检查、§4 跨流程、§5 检查清单；各 Builder 文件：MapBuilder §1 / ModelBuilder §2 / UIBuilder §3 API、覆盖缺口、绑定注入	每次修改 .map / .model / .ui 时，上下文中都必须包含核心文件 + 与被修改类型匹配的文件（Builder Protocol 前置检查）
entity.md	.map 实体领域——Scope、RUID、TileMapMode 前置检查、modelId 与内联模式的判断规则、坐标 / foothold / 相机、运行时验证	.map 编辑 / 实体放置（调用协议请与 builder-protocol.md 核心文件 + builder-protocol-map.md 一起阅读）
model.md	.model 创作领域——何时创建、模板目录、组件组合、脚本组件生命周期	编写 / 编辑 .model（调用协议请与 builder-protocol.md 核心文件 + builder-protocol-model.md 一起阅读）
monster.md	怪物规范组件、小写 ActionSheet 键、必需的 IsLegacy / SortingLayer 覆盖项、AI 选择、HP / 重生、生成位置	创作怪物模型
animation-state.md	StateComponent 默认值与自动注册、状态变更流水线、SetActionSheet 与 ChangeState、StateType 编写（仅服务器端，ParentComponent.Entity）、StateAnimationComponent（怪物 / NPC）与 AvatarStateAnimationComponent（玩家）的区别、[LEA-3005] 常见问题	怪物、NPC 或玩家的任何状态 / 动画问题——实体动画与行为不匹配时，先阅读此文档
material.md	.material 文件结构、着色器类别索引（10+ 类别）、通过 .model / .map / 运行时 ChangeMaterial 在渲染器组件上应用 MaterialID、_MaterialService:ChangeMaterialProperty（ClientOnly），以及由 MCP 驱动的查询流程（mlua_Document_Retriever / mlua_API_Retriever），以此替代对各着色器目录的死记硬背	任何着色器 / 材质 / 视觉效果相关工作——描边、发光、模糊、暗角、彩虹、全息图、混合模式、后期处理、受击闪光、屏幕滤镜等
msw-ui-system 技能（通过 Skill 工具调用）	**UI 唯一入口。**设计判断（坐标 / 锚点 / 轴心、UIGroup/CanvasGroup、组件选择）+ 组件属性 / 方法 / 事件 API + 枚举值 + 布局方案 + mlua 运行时模式（弹窗 / toast / HP / 网格 / 拖拽）+ Runtime UI 注意事项 + UUID 绑定 + .ui CJS UIBuilder 调用协议（面板 / 文本 / 精灵 / 按钮 / 滑块 / 滚动区域 / 脚本 / 组 / 遮罩 / 网格 / Avatar / 触控 / 骨骼 / 粒子、锚点预设、组件添加 / 替换 / 修补 / 移除、写入时自动 lint）	任何 UI 相关任务 / 创建或编辑 .ui 文件——优先阅读
msw-ui-system/references/templates 文件	按复杂度划分的 UI 结构模式模板（简单弹窗、最小 HUD、多标签页、商店 / 购买流程），附有 .ui + .mlua 示例及按钮处理程序模式	添加新的 UI 组 / 弹窗 / HUD、构建按钮处理程序结构或选择 UI 布局模式时（在阅读 msw-ui-system 后直接阅读）
dataset.md	UserDataSet / LocaleDataSet 运行时、.userdataset + .csv 配对、_LocalizationService 仅限客户端、serveronly	数据集 / i18n / 翻译

---

绝对原则（适用于每项任务）

0. 如果任务涉及实体，请先阅读 references/entity.md。没有例外。 0-bis. 如果用户的请求提到了任何 UI 元素（弹出窗口、HUD、按钮、Toast、面板、对话框、菜单、标签页、布局、屏幕、条形指示器／量表、槽位）或涉及编写／编辑 .ui 文件，则在向用户提出任何计划、选项或问题之前：
   1. 先通过 Skill 工具调用 msw-ui-system——这是唯一的 UI 入口（在一个技能中统一提供设计判断、组件 API、枚举、布局方案、运行时模式、UUID 绑定和构建器调用协议）。
   2. 所有 .ui 修改都必须通过 msw-ui-system 的 UIBuilder 进行——不得直接编辑原始 JSON 或使用 grep。也要通过 UIBuilder 的读取端 API 来读取现有 .ui 文件。（调用协议：核心内容见 references/builder-protocol.md + 第 3 节见 references/builder-protocol-ui.md §3。）
   3. （可选）如果需要 UI 模式模板（简单弹出窗口、精简 HUD、多标签页、商店流程），可直接对 msw-ui-system/references/templates/ 下的文件使用 Read／Glob（templates.md + style-N-*/ + ruid-map.md + Popupbutton.mlua）。 没有例外。 0-ter. 如果任务将创建、修改、重命名或删除任何 .mlua 文件——包括新建脚本、编辑现有脚本、添加／移除 Component／@Logic／@Event／@State／@BTNode、连接生命周期方法（OnBeginPlay／OnUpdate／……），甚至是一行的小修复——则你必须先完整 Read msw-scripting/SKILL.md 和 msw-scripting/references/verify-checklist.md（不得使用 offset／limit，不得使用 cat／Get-Content）。阅读 msw-general 加上零散的 .d.mlua 文件不能替代此要求。即使上一轮已经加载过 msw-scripting，本轮开始时也必须重新确认。触发条件有意设得很宽泛：只要本轮有任何可能涉及 .mlua，就视为触发。没有例外，不得以“我已经知道”为由，也不得凭记忆走捷径。 0-quater. 如果任务涉及生成、移动、跳跃／重力、坐标放置、图层／顺序调试、MapleTile／RectTile／SideViewRectTile 专属逻辑，或你观察到任何静默失败症状（[LEA-3004] 日志、“无法移动”、“无法渲染”、“悬浮在空中”、“卡在墙里”、“从地图上消失”、“从落脚平台边缘掉下去”、“偏差 100×”、“在 Maker 中不显示”、“仅客户端同步”），则必须先将对应的 references/platform*.md／references/troubleshooting.md 完整置于上下文中（若尚未读取，则使用 Read——参见“Preflight read semantics”）。此外，如果症状与动画／状态有关（[LEA-3005] 日志、'stateName' is not a valid argument、动画与行为不匹配、移动时卡在站立／待机片段、攻击姿势始终不播放、受击动画循环、自定义状态始终没有动画，或涉及 StateComponent／StateType／ChangeState／AddState／ActionSheet／SetActionSheet／StateAnimationComponent），则必须在任何代码或模型编辑前，先将 references/animation-state.md完整置于上下文中。本 SKILL.md 中的 8 条核心规则仅为摘要——症状→原因→修复表、各地图类型的代码模式（Foothold 巡逻／RectTile 四向移动／SideView 墙体检测）、MovementComponent 的 InputSpeed 转换公式、SpriteRUID、SortingLayer／OrderInLayer 详情、SpawnByModelId 初始化顺序、文件夹元数据刷新策略以及 CoreVersion 策略都只在参考资料中。触发条件有意设得很宽泛：只要本轮有任何可能涉及这些领域，就视为触发。对于对应的 Read 目标，请遵循上文“Platform Rules Preflight — MUST”部分中的触发表。没有例外，不得以“我已从 8 条核心规则中了解”为由，也不得凭记忆走捷径。
1. 视觉润色——切勿让 SpriteRUID 留空。使用 msw-search 查找资源。
2. 内容文件变更后执行 refresh，以便 Maker 载入变更（如果处于游戏模式，请先 stop）。仅更改文件夹时无需立即刷新。
3. 切勿修改 Environment/*.d.mlua——API 定义为只读。
4. 切勿手动创建 .codeblock——Maker 会通过 refresh 从 .mlua 生成该文件。刷新时也会根据实际文件夹生成文件夹元数据。
5. 不要在 Global/ 中创建新的用户文件——Maker 无法识别这些文件。用户文件应放在 RootDesk/MyDesk/ 下。
6. 结构化文件优先使用构建器，调用手册只有一个统一入口——由共享核心和各构建器文件组成——.model／.ui 只能使用构建器；.map 优先使用构建器。三种构建器——MapBuilder／ModelBuilder／UIBuilder——的调用协议统一汇总在 references/builder-protocol.md（核心）以及各构建器文件（builder-protocol-map.md／builder-protocol-model.md／builder-protocol-ui.md）中。每次修改 .map／.model／.ui 时，核心内容和与被修改类型匹配的文件都必须置于上下文中（参见 Builder Protocol Preflight）。只有在各构建器文件中明确列出的覆盖缺口区域，才允许直接编辑原始 JSON——范围必须最小，并执行 refresh 和日志验证。
7. 实体引用绑定（Entity／EntityRef 属性）——AI 直接注入 UUID 字符串。不要让用户在 Maker 中拖入。
8. **仅当用户明确要求时才调用 screenshot。**任务完成后绝不自动调用。
9. 如果工作流中途某一步失败，停止后续步骤——先修复根本原因。
10. **两个或以上就创建模型。**当同一实体组合在地图中放置 ≥2 次时，先创建 .model，再通过 modelId 实例化。仅当实体确实只出现一次时，才使用内联 @components。
11. **模型必须放在类型子文件夹中。**将新 .model 文件保存在 RootDesk/MyDesk/Models/ 下的类别子文件夹中（例如 Models/Monsters/、Models/NPCs/、Models/Terrain/、Models/MapObjects/、Models/Particles/、Models/UI/）——绝不可直接放在 MyDesk/ 或 Models/ 下。如果所需子文件夹不存在，只创建文件夹；Maker Refresh 稍后会生成文件夹元数据（参见 references/platform.md §2）。
12. 翻译仅在客户端进行。_LocalizationService 和 Translator 方法（GetText／GetTextFormat）均为 ClientOnly。对于服务器发起的本地化消息，应通过 RPC 发送键，再由客户端解析。
13. 跨平台工具选择——探索工作区时不要使用 shell，改用工具。所有工作区文件／文件夹探索、读取和搜索都使用 Glob／Read／Grep 工具。Bash 命令（如 ls／dir／Get-ChildItem／gci／cat／type／Get-Content／gc／head／tail／find／where／grep／findstr／Select-String）禁止用于工作区探索——这些命令在 Windows（PowerShell／Git Bash）和 macOS（bash／zsh）之间无法兼容，因为 shell／路径处理方式不同（特别是在 bash 中，像 D:\path\foo 这样的路径，其反斜杠会被当作转义字符消耗，最终变成 D:pathfoo）。Bash 仅用于运行实际的 shell 程序（git／npm／MCP／构建脚本），即便如此也要：(a) 优先使用相对于工作区的路径；(b) 如果必须使用绝对路径，则使用正斜杠并加双引号（"D:/path/to/map/"，切勿传入 D:\... 格式）；(c) 仅使用 POSIX 命令（ls／mv／cp／rm）。如果看到类似 ls: cannot access 'D:path...': No such file or directory 的错误，请立即停止，并改用 Glob／Read 重试。
14. **.model 文件只能使用构建器——使用构建器前必须先阅读 references/model.md（领域知识）、references/builder-protocol.md 核心内容以及 references/builder-protocol-model.md（调用协议）。**不得直接检查或编辑 .model JSON。使用 ModelBuilder 前，必须将所有这些文档完整置于上下文中（遵循上述读取规则）——“Model Work Preflight”和“Builder Protocol Preflight”都适用。只有将它们一起阅读，才能确保标识符／值元数据／属性／子项／事件链接的一致性。
15. **.map 文件优先使用构建器。**对于 MapBuilder 所支持的检查和修改操作，应使用 MapBuilder，以确保实体 ID、路径、组件名称、来源元数据和模型实例镜像保持一致。如果 MapBuilder 明确不支持所需操作，则对 .map 进行尽可能小的直接编辑，然后执行 refresh 并验证。完整 API／require 路径／各操作模式／覆盖缺口／false 返回值处理／跨流程：references/builder-protocol-map.md §1 + references/builder-protocol.md §4（同时参阅 references/entity.md 了解领域背景）。