星火 2.0 开发文档

主题

AI 开发文档 ​

这里包含了 WasiCore 框架中 AI 相关功能的开发文档、Skill，以及 SCE Editor MCP 的接入说明。

AI 如何帮助不同起点的用户 ​

以用户想完成的游戏为目标，按功能选择现成玩法系统、GameGraph 或 UI 能力。经验影响解释方式，不决定实现路线；零基础用户先完成可玩的目标，无需先学习架构。有地图编辑器或 Unity / Urho 经验的用户可选读理解星火。

选型与跨层扩展使用架构 skill，具体接口查GameCore 与 GameGraph 桥接。保留合适的项目结构和用户需要的图形化编辑入口；不要因为引入底层能力就要求重建整个项目。

MCP 接入文档 ​

先按开发入口规则选择宿主：用户已打开目标项目的可视化编辑器时优先复用，除非用户主动要求隔离；没有已打开的 GUI 或用户要求隔离时，AI 独立开发优先 Headless；图形交互使用 GUI；客户端局部表现使用纯客户端预览。Headless 单客户端调试可打开游戏窗口并使用 Runtime MCP 和截图，多客户端编排使用完整编辑器。

  • 无头编辑器指南 - Windows 控制台宿主、登录复用与主动换号、玩家配置同步、单客户端调试和发布及历史操作恢复

  • SCE Editor MCP 接入指南 - 如何把 SCE Editor 以 stdio / WebSocket / HTTP 方式接入 Cursor 或其他 AI 工具

  • 创作者中心远程 MCP 接入 - 不打开编辑器即可用项目限定的短期授权读取作者后台配置、下载项目日志与管理内测邀请码

  • SCE Editor MCP 工具速查 - 数据编辑器、触发器编辑器、UI 编辑器自动化、调试/Runtime、HTTP helper 与测试工具总览

  • TapTap Maker MCP 接入说明 - 已有 Maker 测试资格的用户，如何安装 Maker MCP 并把生成资产导入 WasiCore 项目

  • 用 AI 创建第一个游戏 - 从安装根命令创建项目、生成 AI 指引，再通过项目辅助入口完成单客户端连服

AI Rules (rules/) ​

  • 数编 MCP 工作流 - AI 区分类型与条目，并通过 data_* / gamedata_* / ui_* 安全修改 GameData 的标准流程
  • 触发器 MCP 工作流 - AI 通过 trigger_* 操作触发器、Validator 与 MCP Host 的标准流程

AI Skills (skills/) ​

每个 Skill 目录都包含精简版 SKILL.md（<500 行，适合 AI Agent 直接消费）；复杂主题可额外包含完整版 reference.md。

  • 首次上手：创建并运行第一个游戏 - 从已有完整安装创建项目、设备授权、恢复未完成准备，到第一次单客户端连服验收；说明官方资源前提与清理边界

  • 创作者中心远程 MCP - 单项目短期授权、项目配置、客户端附件与游戏局脚本日志读取，以及内测邀请码的权限边界

  • WasiCore 框架开发指南 - 编译配置、技术约束、常见陷阱、坐标系统、自定义托管程序集

  • SCE 数据编辑器 Skill - 触发编辑器图形化自定义类型、纯代码特性边界、data_* / gamedata_* / ui_* MCP、JSON、$id 与 link 路径

  • SCE 编辑器项目与场景生命周期 MCP - 通过 editor_* MCP 打开、切换、重载项目和场景，处理 ready 状态、未保存策略、测试场景创建/删除与 DataManager 持久化

  • 离散瓦片地形 MCP - 通过 terrain_* MCP 编辑地表、TileSet、高度、台阶、水域、裂缝、视野遮挡、手绘碰撞、道路与装饰物，并完成保存重开验收

  • 冲锋遇静态碰撞停止 - 使用 LaunchMissile 复用施法者，配置 Surface2D 静态碰撞掩码、场景烘焙与停止收尾

  • 场景氛围 MCP - 查询并编辑当前 .lightgroup 的环境光、雾、主光方向、贴图、反射与后处理，支持预览、撤销/重做及显式保存

  • 离散瓦片地形自定义纹理 - 沿用 config_v1、TextureStyle、纹理数组和地形 Material，为项目配置、校验或排查自定义地表纹理

  • CloudData 云数据 - 云存档、货币、背包、首轮存档加载、ServiceNotInitialized / FailedToSend 排查，以及 CloudData ready + UserId ready 启动时序

  • 随进随出模式与开放局 - 创作者中心随进随出配置、模式 key 分池、版本升级时的匹配池隔离、后台自动匹配容量、地图玩家槽位和 OpenGameRef 定向加入

  • 同用户游戏局切换清理 - 同一用户切换到同游戏其他游戏局前，旧局提交 CloudData、释放用户级资源、处理 Player 可空和幂等收尾

  • 商店与支付 - GameSystemUI 商店、星火币商品、自定义商店 UI、底层支付 API、购买失败和上线检查

  • 敏感词过滤 - 聊天、昵称、公会名、留言和跨服玩家文本的服务端过滤；明确 ServerChannel 只负责传输且不会自动审核载荷

  • OperationMail 运营邮件 - 服务端查询运营后台全服邮件/个人邮件，配合 CloudData 自存已读、领取、红点状态；不用于玩家互发邮件

  • 游戏架构路线选择 - 区分 SCE Unit/技能系统、直接 GameGraph SceneGraph、Canvas/GameUI 绘制路线，以及 Surface2D / Volumetric3D 空间模型

  • 动态 SCE 场景副本 - 运行时复制已有 SCE 场景素材，为玩家或房间创建隔离实例；覆盖默认镜头同步、加载时序和预放置对象边界

  • SCE Unit/技能系统游戏开发指南 - 单位数据定义、属性系统、移动寻路、生命值、跨端通信；目录名保留 3d-unit-game，但不要把它理解为所有 3D 游戏的唯一入口

  • 角色跨场景迁移 - 原英雄与库存随行、玩家视图切换、主控恢复、客户端副本就绪和失败恢复的双端验收

  • 服务端权威 3D 物理 - 服务端模拟 3D 刚体、GameGraph 发布图、按玩家同步 transform、客户端本地表现分层

  • 射击游戏权威与瞄准同步 - 顶视角/TPS/FPS 输入上行、独立身体/瞄准姿态、本机预测、远端平滑与角度阈值

  • 服务端预烘焙模型碰撞 - 为运行时创建的复杂静态或动态模型生成服务端三角网格 / 凸包 cooked collision，并按枚举结果加载和排错

  • GameGraph 材质与 RenderPath 排查 - 材质类型选择、MaterialVertexColor 固定透明模式、MaterialFlatLambert / MaterialWater / MaterialCustom 用法，以及通过 Runtime MCP material.probe / scenegraph.materials 对照 RenderDoc 排查不可见物体

  • 项目自定义 Shader - 项目 GLSL 与 Technique XML、变体/平台清单、Editor MCP 编译，以及从日志提取缺失 Shader 变体

  • GameGraph 透明背景画中画 - 使用普通 PIP 对照构建透明附加 Viewport，选择带 alpha 的 RTT 格式，并通过纯客户端截图验证最终合成

  • 单位换模与表现重建 - ModelSwap 后恢复默认 Actor 与装备表现，以及同步外观属性、GameGraph 模型子树和 Socket 迁移

  • GameGraph 附加模型挂载 - 自动挂载模型表现的下钻接口：显式选择 Prefab 主骨骼宿主，管理附加模型挂载、换装、解除和可选宿主网格裁剪

  • SCE 场景内置节点、地形与环境 - 通过 Scene.TryGetTerrainController() / Scene.TryGetWeatherController() / Scene.TryGetLightingController() 运行时访问 SCE 场景内置节点；同时识别地形编辑器“氛围”对应的 atmosphere/*.lightgroup XML，并按持久化资产或临时运行时效果选择正确路线

  • 客户端设置 - 通过 ClientSettings.Graphics / Audio / Preferences 调整画质、帧率、音频和项目自定义本地偏好

  • 客户端环境能力 - 通过 ClientEnvironment 打开 QQ 群等允许链接、读写剪贴板、读取 / 切换 CultureInfo 本地化语言、查看网络、电量和只读诊断快照

  • 直接 SceneGraph 小游戏/预览 - 不使用 Unit/技能系统、直接创建 GameGraph SceneGraph / Node 的客户端本地 3D 小游戏、场景内 2D/Spine 表现、材质/模型 probe、本地物理和 GameSystemUI 输入事件模式

  • GameGraph 二维渲染路径与颜色 - 二维主视图的 RenderPath、Bloom/色调映射、sRGB/Gamma、PIE 与独立窗口颜色一致性，附 XML 与视口生命周期样例

  • Canvas / CanvasAnimated 游戏开发指南 - 设计分辨率、Canvas 绘图 API、碰撞检测、游戏循环；目录名保留 canvas-2d-game，但 Canvas 可与 SCE 场景、Unit 和 GameGraph 混用

  • 移动端 Canvas 性能调优 - Canvas/CanvasAnimated 移动端帧耗时、发热、framebuffer/底层绘制缓冲压力与分辨率调优

  • 旧客户端专用的图片缓存预算 - 旧客户端 Canvas 图片中途批量变白时的临时规避、内存代价、验证和撤除条件

  • 游戏起手模板选择 - 从 code_sample 选择最小匹配起点，覆盖 Canvas 绘制、SCE Unit/技能系统、直接 GameGraph、联机混合同步等原型路线

  • 预览与验收闭环 - 复用会话、选择 Headless / GUI 连服调试或纯客户端预览、截图、UI snapshot 与运行时日志检查

  • 官方资源选择 - 通过 docs/resources 选择角色、模型、动画、特效、声音、图标和 UI 图片，避免编造资源路径

  • 云资源目录与明文导出 - 通过 Editor MCP 搜索、下载和批量导出官方云资源，并用真实 .effect / prefab 文件作为 AI 手写项目资源的样例

  • 部署环境与运行时环境 - 区分 alpha / production 部署环境和 debug / test / formal 运行时环境，覆盖数据隔离、内测/正式发布、新功能到线上节奏和自定义云端资源同步

  • TapTap Maker 资产生成 - 已有 TapTap Maker 测试资格的用户，通过 Maker MCP 生成图片、模型、视频、音乐等资产并按 WasiCore 资源路径导入项目

  • 流式布局 UI API - 尺寸、间距、对齐、Flexbox、响应式布局、图集 JSON 与图片子区域、Loading 页面和启动遮罩

  • ScreenViewport 分辨率适配 - 窗口/屏幕尺寸变化、横竖屏、设备像素比、安全区、Surface 重建和旧客户端兼容

  • Widget、血条与飘字 - 轻量 Widget、单位血条、飘字、StatusBarCustom、属性绑定和运行时 handle API

  • UI 编辑器自动化 MCP - AI 通过 uiauthoring_* 操作 UI Authoring：启动真实 UI 编辑器 PIE、读取 hierarchy、选择控件、切换 Edit/Interact、打开/关闭 Workbench 并清理 session

  • GameUI 自定义字体 - Label.Font / Input.Font 字体 family、ref/fontref.txt、字体路径和 fallback 排查

  • Label 富文本与链接 - b/i/u/color/br/link 标签、嵌套样式、Label.OnLinkClicked 和 LinkId 路由

  • 2D 动画与序列帧选型 - 区分 GameUI Sprites、AnimatedImageSource + CanvasAnimated 与 GameGraph AnimatedSprite2D 的最佳适用场景

  • 编辑器插件开发指南 - C# 插件系统，自动暴露 MCP 工具供 AI 调用

  • SCE 触发器编辑器 MCP - trigger_* 工具、Validator，以及通过 Class 属性定义图形化数编分类/类型

  • SCE DebugTools MCP - 调试启动与清理、build_* 编译诊断/日志/取消、Humanoid 动画烘焙，以及通过 runtime_call_tool 检查运行中客户端并执行 ui.* / input.* 自动化

  • 技能试验场 - 调试专用真实主控/技能实例、全量目录、表现/Sequence 参数与草稿回写；核心双端链路已验证

  • SCE 编辑器包修复 - 通过独立 WinUI/CLI 工具诊断并安全重置 editor_bcd、global_default、gamesparkcore、gamesystemui、lib_game_options、wasicoresdk；只使用 editor-*.spark.xd.com 编辑器渠道，并可识别和清理 e.* 异常下载源、处理 VERSION.JSON 与 _m 历史缓存

  • Editor 生命周期 MCP - editor_open_project / editor_reload_project / editor_open_scene / editor_reload_scene / editor_create_scene / editor_delete_scene 的异步操作协议、ready 状态和安全边界

  • Runtime MCP 多人目标路由 - 多 Gameplay 调试时发现、选择并固定 Runtime 目标，处理 runtime_target_ambiguous / runtime_target_not_found，以及区分 Runtime 路由和进程级输入边界

  • 纯客户端调试启动 Skill - AI 使用项目内启动脚本或 docs/.client-only-debug.json 以 -client_only 启动 UI、GameGraph、本地工具测试

  • Runtime 粒子 Builder - AI 用 C# 运行时构造 GameGraph 粒子，配置 sprite / mesh / beam / ribbon 发射器，使用能力 10 的确定性回放，并在 Debug 模式下导出 .effect

  • PowerShell 7 环境诊断 - 检查用户机器的 PowerShell 版本；当 Windows PowerShell 5.1 导致 UTF-8 中文输出乱码时，建议并协助安装 PowerShell 7

  • 运行期行为问题排查 - 用事件 + System.Environment.StackTrace 反向定位"谁改了状态/谁取消了指令/谁结束了 buff"；适用于 AI 不动、技能中途取消、buff 提前消失等动态行为异常问题

  • 响应配置与目标排查 - 反伤、自疗、死亡复活中的主动方/被动方、Host/Owner，以及原效果链与响应附加效果链的 Caster/Target

  • 1.0 → 2.0 项目迁移指南 - 把星火 1.0(ts2lua) 项目迁移到 2.0(C#)：给定 1.0 工程目录的确定性迁移工作流、1.0→2.0 映射表、1.0 工件解读（.ini/trigger_module_main*.ts/lua_declare.d.ts/场景）、以及"必须手补"清单

AI Tools (tools/) ​

  • Ensure-PowerShell7.ps1 - 检查当前 PowerShell 与 pwsh 可用性，必要时通过 -Install 调用 winget 安装 PowerShell 7
  • Start-SceClientOnlyDebug.ps1 - 读取项目 docs/.client-only-debug.json 并启动纯客户端调试；项目打开后会生成 ai/tools/Start-SceClientOnlyDebug.ps1 作为优先入口
  • Invoke-SceMcp.ps1 - Trigger/Data 兼容入口；探测或启动 TriggerMcpHost 并执行单次 trigger_* / data_* / gamedata_* 调用
  • Invoke-SceEditorMcp.ps1 - 共享版本化完整 Editor MCP HTTP 客户端的薄入口；当 AI 客户端没有直接暴露编辑器 MCP 工具时，用它连接已通过 --mcp-port 打开的完整编辑器、发现 schema、调用 editor_get_context / debug_* / runtime_* / uiauthoring_*，并拒绝把 TriggerMcpHost 当成完整编辑器使用
  • Invoke-SceRuntimeMcp.ps1 - 共享版本化 Runtime MCP fallback 的薄入口；仅当当前 AI 工具环境没有暴露编辑器 MCP runtime_call_tool 或需要诊断转发故障时使用
  • SCEPackageRepair.Cli.exe - 独立包修复 CLI；使用 list/diagnose 获取结构化诊断，使用 sources 检查并用 remove-sources --apply 清理 e.* 异常下载源，使用 reset --dry-run 预览并在明确授权后用 --apply 重置受控包，使用 prune 回收 _m 历史版本

快速开始 ​

如果您是第一次使用 AI 工具开发 WasiCore 游戏，建议按以下顺序阅读：

  1. 用 AI 创建第一个游戏与首次上手 Skill - 从已有安装创建项目并完成首次连服；使用 GUI 创建项目时参阅快速开始
  2. PowerShell 7 环境诊断 - 按需诊断 Windows 终端编码；首次上手不要求安装 PowerShell 7 或系统 .NET SDK
  3. 星火 2.0 发布、调试与 AI 辅助开发流程 - 项目跑起来后理解发布/内测/TapTap 状态、AI/MCP 开发闭环和调试路线选择
  4. WasiCore 框架开发指南 - 必读：编译配置、技术约束
  5. SCE Editor MCP 接入指南 - 需要让 AI 直接操作编辑器时先看
  6. SCE Editor MCP 工具速查 - 确认有哪些 data_* / trigger_* / debug_* / uiauthoring_* / Runtime 工具可用
  7. 离散瓦片地形 MCP - 需要 AI 通过 Editor MCP 创作或验证离散瓦片地形时先看
  8. SCE DebugTools MCP - 需要从编辑器 MCP 启动/关闭普通调试或不编译调试，并检查运行时客户端时先看
  9. Runtime MCP 多人目标路由 - 多 Gameplay 调试时先发现并固定目标，再进行 Runtime 工具检查或写入
  10. 纯客户端调试启动 Skill - 需要让 AI 直接启动客户端验证 UI / GameGraph / 本地工具时先看
  11. GameGraph 材质与 RenderPath 排查 - GameGraph 物体不可见、材质不对或 RenderDoc/pass 对不上时先看
  12. 直接 SceneGraph 小游戏/预览 - 需要做不使用 Unit/技能系统的单人 3D 小游戏、场景内 2D/Spine 表现、材质/模型 probe 或本地物理原型时先看
  13. Runtime 粒子 Builder - 需要 AI 代码生成 GameGraph 粒子特效时先看
  14. SCE 数据编辑器 Skill - 任务涉及自定义数编类型、editor/data、data_* MCP、$id / $inherit / link 路径时先看
  15. CloudData 云数据 - 任务涉及云存档、货币、背包、首轮存档加载或云数据失败排查时先看
  16. 同用户游戏局切换清理 - 同一用户切换到同游戏其他游戏局前，需要旧局保存 CloudData 或释放用户级资源时先看
  17. 商店与支付 - 实现 GameSystemUI 商店、星火币商品、自定义商店 UI 或排查购买失败时先看
  18. 常驻游戏局 - 玩家全部离线后仍需运行服务端逻辑，或设计跨游戏局协调时先看
  19. 敏感词过滤 - 开发聊天、昵称、UGC 或 ServerChannel 跨服聊天时先看
  20. OperationMail 运营邮件 - 查询运营后台全服邮件/个人邮件，或设计 CloudData 已读/领取状态时先看
  21. 游戏架构路线选择 - 用户只说“2D/3D 游戏”、不确定是否用 Unit/技能系统、GameGraph、Canvas 或 SpaceModel 时先看
  22. 游戏起手模板选择 - 新建游戏或大原型时先选最小起点
  23. 官方资源选择 - 需要角色、模型、动画、特效、声音、图标、UI 图片时先看
  24. 部署环境与运行时环境 - 区分部署环境和运行时环境、从外网迁线上、规划新功能上线时间，或自定义云资源缺失时先看
  25. TapTap Maker 资产生成 - 已有 Maker 资格且需要自定义图片、模型、视频或音乐时先看
  26. SCE Unit/技能系统游戏开发指南 - 开发 Unit、技能、AI、HP、SCE 场景单位玩法时必读
  27. 服务端权威 3D 物理 - 开发非 Unit 的服务端权威 3D 物理物件时必读
  28. 服务端预烘焙模型碰撞 - 服务端需要复杂模型精确碰撞、生成 collision bake 产物或排查加载失败时先看
  29. Canvas / CanvasAnimated 游戏开发指南 - 开发全屏 Canvas 绘制游戏或 Canvas 表现层时必读
  30. 移动端 Canvas 性能调优 - Canvas/CanvasAnimated 在手机上帧耗时高、发热或 framebuffer/底层绘制缓冲压力大时先看
  31. 流式布局 UI API - 构建 UI 界面、配置图集子区域、Loading 页面或启动遮罩时必读
  32. ScreenViewport 分辨率适配 - 处理分辨率变化、旋转、安全区或 Surface 重建时先看
  33. Widget、血条与飘字 - 配置或运行时修改单位血条、飘字、轻量场景标记时先看
  34. UI 编辑器自动化 MCP - 需要 AI 打开 UI 编辑器、读取 GameUI hierarchy、选择控件或验证 Workbench 生命周期时先看
  35. GameUI 自定义字体 - 设置 Label.Font、Input.Font 或排查字体不生效时先看
  36. Label 富文本与链接 - 在 Label 中使用样式、换行和局部链接，或处理 OnLinkClicked 时先看
  37. 2D 动画与序列帧选型 - 需要序列帧、sprite sheet、UI 动画、Canvas 帧动画或 3D 场景里的 Spriter / Spine 时先看
  38. 预览与验收闭环 - 完成可见行为、UI、GameGraph、粒子或玩法改动后用于运行验证
  39. 旧客户端专用的图片缓存预算 - 旧客户端 Canvas 图片在游玩或切地图后批量变白、且暂时无法升级客户端时先看

相关文档 ​

贡献指南 ​

添加新的 AI Skill 时：

  • 在 skills/ 下创建新目录，包含 SKILL.md（精简版，<500 行）和可选的 reference.md（详细版）
  • SKILL.md 需包含 YAML frontmatter（name + description）
  • 若 Skill 依赖 MCP 或额外运行环境，请在 docs/ai/ 下补一页接入文档并更新本 README