星火 1.0(ts2lua) → 2.0(C#/WasiCore) 项目迁移作业手册

把一个星火编辑器 1.0（TypeScript→Lua，简称 ts2lua）项目迁移到星火编辑器 2.0（C#、WasiCore 框架）。 本 Skill 是给 AI 助手执行迁移用的作业手册：确定性步骤 + 映射表 + 工件解读 + 手补清单。 偏概念的"老用户上手"读物见 资深用户指南，本 Skill 与它互补、不重复。

> 详细映射表、分系统迁移配方、工程解剖在同目录 reference.md。本文是入口与流程层。

何时使用

• 用户给出一个 1.0 项目目录，要求迁移/移植到 2.0。
• 需要把 1.0 的数据编辑器配置（.ini）、触发器逻辑（trigger_module_main*.ts）、公式（trigger_validator*.ts）、场景、UI 搬到 2.0。
• 需要判断"哪些能自动迁、哪些必须手补、哪些 2.0 暂不支持"。

不适用：纯新建 2.0 项目（直接看 资深用户指南 00 与 wasicore-dev）。

重要前提与免责（先读，必须如实转达用户）

1. AI 辅助迁移无法 100%。 1.0 与 2.0 的 API 可比拟但有差异——类型名不同、字段有出入、部分机制被重新设计。总会有需要人工补齐和校验的地方，不要承诺"一键完整迁移"。
2. 必须先拿到 1.0 工程目录的绝对路径，再开始。迁移目标最好也先让用户在 2.0 编辑器里新建一个空项目（game_entry 模板）：用编辑器新建更稳——项目 ID 和 src/WasiCoreSDK.props 里指向下载版 SDK 的路径都会在编辑器打开项目时才更新。AI 助手虽然也能直接从 map_templates 复制一份 game_entry，但那样既要手改 project/ 里的项目 ID，SDK 路径也得等编辑器打开项目后才指得对，非必要不建议。
3. 2.0 文档全、1.0 文档弱。 2.0 这边有完整的文档、API 声明、schema 与 skill；1.0 那边主要靠工程内的 lua_declare.d.ts 和 tsconfig.json 望文生义（见下"如何发现 1.0 的 API"）。
4. 优先读 TS 源码。 触发器/公式有同名 .ts 时，以它为迁移基准，跳过重复生成的 .lua；同时清点独立手写 TS 模块。为追踪入口可只读检查 main.lua 的 require；没有 TS 对应的手写 Lua、场景预放置和 UI 配置仍需按实际格式读取。旧 INI 中未显式填写或经过继承的字段，可只读对照 script/obj/、ui/script/obj/ 的生成 Lua 核对有效值；这些文件不作为目标工程的维护源。

前置阅读（都在 SDK 内）：资深用户指南 INDEX → 核心差异 → wasicore-dev（编译/约束/坐标）。涉及数据用 data-editor，涉及触发器用 trigger-editor-mcp。

迁移工作流

> 原则：先记录迁移约定，再跑通一条代表性流程，随后按已验证的语义批量迁移。以下按工作类型组织，不要求搬完全部数据后才处理逻辑、资源和 UI。

迁移约定与规则来源

复用用户已明确的要求，记录本次范围：玩法复刻还是还要承接旧账号/存档，配置是否需保留数编编辑能力，逻辑使用普通 C# 还是需要可视化触发器。未发布项目明确无需旧存档兼容时，不额外制作转换器；只迁移局部功能时，验收也按该范围设计。

区分原版规则（附源配置/调用链）、用户主动改动（附决定）与临时技术边界（附原因、影响和解除条件）。缺失实现或工具缺陷不能直接变成玩法限制，临时容量上限也不能充当原版平衡数值。具体台账见 quality-gates.md。

故障测试项目复刻还需记录 测试条件对照：保留与故障相关的资源、时序和实例条件，说明自动轮播、替代模板等测试辅助带来的差异。“未复现”只适用于已记录的版本、环境和操作。

第 0 步：侦察 1.0 工程

确认这是 1.0 工程（签名：根目录有 editor/、script/、ui/script/、scene/、各处 tsconfig.json 与成对的 .ts/.lua）。然后清点规模：

• editor/table/entry_data/ 下有哪些数据编辑器类型目录（unit/ buff/ spell/ effect/ actor/ item/ model/ ...）、各有多少条目。
• script/（服务端）和 ui/script/（客户端）的 trigger_module_main*.ts、trigger_validator*.ts 及独立手写模块；从初始化/导入链确认实际入口，不能只按生成文件名收集。
• scene/ 下有几个场景文件夹。
• editor/table/entry_data/const_config.ini（常量/可附加枚举/单位属性/伤害类型）、ui_data.ini、libs.json（依赖库）。
• res/、ui/image/、ui/spine/ 或 ui/Spine/ 下的项目私有资源规模、目录大小写和同名文件冲突风险。

输出一份"工程清单 + 迁移工作量评估"给用户。详细工件含义见 reference.md 第一节。

第 1 步：建 2.0 目标骨架

让用户用 2.0 编辑器新建一个 game_entry（空白）模板项目作为迁移目标（理由见 资深用户指南 00）。2.0 工程是 src/（C# 双端单源）+ editor/data/（GameData JSON）+ scene/。没有 1.0 的 script/、ui/script/ 双文件夹——双端逻辑用 #if SERVER / #if CLIENT 写在同一份 src/ 代码里。

第 2 步：选迁移策略（每个子系统各自判断）

先沿用用户已选的作者方式；未指定时，按子系统选择以下路线：

• A. 配置直迁：1.0 .ini → 2.0 editor/data/*.json（或用 data-editor MCP 写入）。保真度高，但 1.0 ini 把公式 json 内嵌进去、很繁琐，token 成本高。
• B. 结果代码化：直接把 1.0 生成的 .ts（script/ui\script）翻译成 2.0 C#（GameData 用代码定义、触发器用 Trigger<T>）。2.0 支持纯代码开发，通常 token 更省、更贴合当前 AI 工具。

经验：允许普通 C# 时，逻辑/触发器优先走 B；需数编维护的数据走 A，需可视化维护的逻辑使用触发编辑器。具体决策树见 reference.md 第四节。

先跑通代表性流程，再批量展开

按本次范围选择能覆盖主要风险的一条流程。例如带存档的生存游戏可先完成：出生/读档或新建存档 → 移动战斗 → 拾取/制作 → 保存 → 退出重进。先准备这条流程必需的场景、依赖、资源和最小 UI；纯技能或 UI 迁移则选对应的可操作流程。

抽取有代表性的非默认字段，核对源意图 → 保存并重新读取的配置 → 生成投影 → 运行时有效值，通过后再迁同类条目。生成代码只用于诊断，不手改；发现系统性丢字段时暂停受影响的批次，记录问题所在边界，独立工作可继续。高风险语义见 reference.md 4.9。

第 3 步：迁数据（数据编辑器）

1.0 editor/table/entry_data/<type>/ 的每个条目 → 2.0 对应 GameData<Type>。类型名会变（unit→GameDataUnit、spell→GameDataAbility、effect→GameDataEffect*…，全表见下）。 做法见 reference.md 4.1。涉及 JSON/$id/link 路径用 data-editor；理解 2.0 数编系统看 GameDataSystem。

首次创建某种目标节点前，通过 gamedata_list_types / gamedata_get_type_schema 或目标 SDK 声明确认可实例化类型的完整名称和引用类型，不能按相邻类型的命名空间推测 $type。每个数据批次执行全量保存生成并检查 generationWarningCount、diagnostics 和 GDATA001；迁移引入的字段省略必须修正后才可通过该批次验收，见 生成诊断门槛。

第 4 步：迁触发器与逻辑代码

以 script/（服务端）和 ui/script/（客户端）中实际可达的触发器及手写模块为基准，翻译成 2.0 C#：事件订阅用 Game.Subscribe<TEvent>(...) / new Trigger<TEvent>(...)（见 01-核心差异 与 TriggerSystem）。客户端专属逻辑包 #if CLIENT，服务端专属包 #if SERVER。 配方见 reference.md 4.2。

第 5 步：迁公式 / Validator

1.0 数编公式值（ini 里内嵌的触发器 json）生成的是 trigger_validator*.ts。2.0 改为数据字段直接引用触发器函数 / C# 委托（如 Value = ctx => ...）。#if SERVER/#if CLIENT 放置规则必须遵守 GameData 公式字段赋值位置。 配方见 reference.md 4.3。

第 6 步：迁场景 / 地形 + 项目资源 + UI + 清点手补

• 场景/地形：1.0 与 2.0 基础场景资产文件同格式，可直接复制（见 reference.md 4.4）。1.0 没有 Volumetric3D 场景，因此默认迁移不需要生成 3D 场景产物；只需按目标工程的大小写约定整理文件、用 2.0 编辑器打开确认场景入口，并把 scene/<名>/area_save.lua、unit_save.lua 的区域/预放置物体信息重新写进 GameDataScene。只有用户明确把目标场景升级为 Volumetric3D 时，才另行按 3DSceneSetup 生成 3D 场景产物。
• 项目资源：优先把 1.0 工程的 res/ 按原相对路径整体合并复制到 2.0 目标项目；旧项目的地形、模型、材质、粒子、音频或其他场景文件可能通过这些相对路径间接依赖它。不要只复制被当前代码直接搜到的文件，也不要覆盖目标项目的同名资源而不记录冲突。把 1.0 的 ui/image/、ui/spine/（若旧工程使用大写 ui/Spine/，保留源目录大小写）及其 .atlas / .skel / 贴图等配套文件一并复制，随后按 2.0 路径规则检查代码是否去掉 ui/ 前缀；详见 ResourcePathGuide。
• UI：1.0 ui/script + link_node（事件响应在客户端 ui/src/gui/ui_response/，生成于 ui/script/gui/ui_response/）→ 2.0 UI 代码、GameData 模板或 UI Authoring。2.0 UI 编辑器 / UI Authoring 已进入工具链，但仍是早期能力，覆盖范围与 1.0 不等价；复杂交互和最终行为必须走普通客户端运行时验证。代码创建的控件仍需主动 AddToVisualTree()/AddToRoot()（1.0 默认挂）。当迁移的是完整页面或菜单界面时，优先用 UI.Page() 作为页面根容器；滚动内容放在 Page 内部的滚动容器里，而不是继续把 Panel().FullScreen() 当主路径。见 03-UI系统、ui-authoring-mcp、ui-layout-api、reference.md 4.7。
• 清点并明确告知用户"必须手补"项（坐标系、暂不支持的机制等，见末节）。

每搬完一块，按 wasicore-dev 编译 Server-Debug + Client-Debug 验证。

迁移质量门槛（每个纵切都要满足）

迁移状态按以下顺序记录，不能用前一状态替代后一状态：

source-mapped -> skeleton -> compiled -> runtime-smoke-passed -> accepted

每个纵切至少确认：

• 1.0 数据、入口、调用链和失败/清理分支；
• 2.0 实际运行入口，而非只有 GameData 定义；
• Server-Debug 与 Client-Debug 串行编译；
• 若迁移了项目私有表现资源，Client-Resource 也通过；项目 res/ 检查随项目封装，需统计的云资源检查 ref/objref.txt，并在客户端核对关键模型、粒子、音频和动画；
• 一个真实场景中的服务端行为和客户端表现；
• 结构化日志、截图或用户验收证据；
• 未支持、资源缺失、平台依赖和必须手补项。

保持以下边界清晰：

数据迁移 != 运行逻辑迁移 != 客户端表现迁移
编译通过 != 运行通过 != 用户验收通过

按需加载 quality-gates.md，获取状态字段、可达性审计、持久化/资源/UI 检查和集中验收格式；不要在每个项目迁移时把全部参考规则复制进本 Skill。 涉及存档时，读取其持久化节并覆盖正常退出、断线、提交结果未收到时的恢复；维护每个功能唯一的当前状态，证据使用可随项目移交的相对路径。

迁移单位或技能时，额外遵守以下表现门槛：

• 资源路径存在不等于资源依赖完整；
• 服务端创建成功不等于客户端表现可见；
• GameDataUnit 的客户端表现定义不能整体放入 #if SERVER；
• Model、Animation、Actor、Particle、Material、Socket 需分别检查；
• 首次播放成功不等于重复触发、关闭重开后仍正常；
• 至少保留一次客户端截图或用户实机确认。

1.0 工件速查表

1.0 工件	是什么	对应 2.0	详见
editor/table/entry_data/<type>/	数据编辑器配置（.ini）	editor/data/.../GameData<Type>/*.json	reference 4.1
editor/table/entry_data/const_config.ini	常量 / 可附加枚举 / 单位属性 / 伤害类型	可扩展枚举 + GameDataUnitProperty + GameDataDamageType	reference 4.5
script/trigger_module_main*.ts	触发器编辑器生成的服务端逻辑	src/ 中 C# Trigger<T> / Subscribe	reference 4.2
ui/script/trigger_module_main*.ts	触发器生成的客户端逻辑	src/ + #if CLIENT	reference 4.2
script|ui/script/trigger_validator*.ts	数编公式值生成的校验/公式函数	数据字段引用的触发器函数 / C# 委托	reference 4.3
script|ui/script/obj/**	数编配置生成的（lua）数据	不直接迁；以 .ini 或代码为基准	reference 4.1
script|ui/script/lua_declare.d.ts	1.0 API + _OBJ_ 自定义数编类型声明	查 1.0 API 的主要入口	"如何发现 1.0 的 API"
scene/<名>/*.dat .acmap area_save.lua	地形/场景资产 + 预放置	资产直接复制 + 写入 GameDataScene	reference 4.4
table/mapinfo.ini（旧称 map.info，如有）	全局玩法/场景配置	GameDataGameplay + GameDataScene	reference 3.3
同名 TS 生成的 .lua、*.lua.map、*.diagnostic、tstl.log	重复构建产物	不作为翻译源；入口/手写 Lua/场景配置另查	reference 第一节

1.0→2.0 快速映射（精简版，全表见 reference 第三节）

目录：editor/table/entry_data/ → editor/data/.../；script/ + ui/script/（双文件夹）→ src/（双端单源 + #if）；lua_declare.d.ts → 生成的 src/DataGenerated/ScopeData.cs；trigger_validator*.ts → C# 公式委托 / Validator；tsconfig.json → src/*.csproj。

官方数编类型名：unit→GameDataUnit、spell→GameDataAbility、effect→GameDataEffect*、buff→GameDataBuff、actor→GameDataActor、item→GameDataItem、model→GameDataModel。字段大致可比拟，但有差异（例：2.0 技能动画不再填在技能表里，改指向独立 GameDataAnimation）。

如何发现 1.0 的 API（数据来源，全在用户本机）

1.0 没有 2.0 那样完善的 docs，但有两处可"望文生义"：

1. 工程内 script/lua_declare.d.ts（服务端）和 ui/script/lua_declare.d.ts（客户端）：含基础枚举 + 该项目的自定义数编类型声明，通常以 _OBJ_ / _OBJ__ 开头。
2. 基础 API：读工程 tsconfig.json 的 typeRoots/types，会指向用户本机 1.0 编辑器 Update 目录下的 global_default 基础声明——服务端在 .../global_default/script/lua_declare.d.ts，客户端在 .../global_default/ui/script/lua_declare.d.ts。这是 1.0 官方 API 的总声明，类比 2.0 的 API 参考，只是没那么完善。

把它当作 1.0 的"API 文档"来查类型/字段。详见 reference.md 第二节。

坐标系（别盲目换算）

2.0 默认镜头相对 1.0 旋转了 90°（默认：1.0 X 上/Y 右/原点左下；2.0 X 右/Y 下/原点左上），目的只是统一 2D/3D 游戏的坐标规律，并非强制——可把场景镜头配回 1.0 朝向。

迁移建议：不要去"换算"坐标数据。 地形资产与场景/预放置坐标是整体复制、彼此一致的；若把刷怪点/区域/路径按 90° 换算却不转地形，反而对不上（要换算就得连地形一起转，得不偿失）。直接保持数据原样，需要时把镜头配成 1.0 朝向即可。

真正要复查的是代码里硬编码的方向假设（如"屏幕上方=某轴正向"、UI↔场景手动换算），按你选定的镜头朝向核对；纯数据不用动。坐标语义见 COORDINATE_SYSTEM_GUIDE 与 01-核心差异·坐标。

各子系统怎么迁（指针）

子系统	配方	2.0 参考（SDK 内）
数据编辑器（数据条目）	reference 4.1	data-editor、GameDataSystem、UnitSystem、AbilitySystem、EffectSystem
触发器/逻辑	reference 4.2	TriggerSystem、trigger-editor-mcp、DualEndEventSystem
公式/Validator	reference 4.3	GameDataFormulaPlacement
场景/地形	reference 4.4	SceneSystem、SceneVisionSystem
单位属性/可扩展枚举/伤害类型	reference 4.5	UnitPropertySystem、EnumExtension、02-高级功能
动画	reference 4.6	ModelAnimationSystem
UI	reference 4.7	03-UI系统、ui-layout-api、canvas-2d-game

已知不支持 / 必须手补（如实告知用户）

• 场景拼接功能：1.0 的"场景拼接"在 2.0 暂未加入（这类 1.0 项目极少；官方今后会加）。遇到请提示用户暂不支持。
• 小地图：2.0 暂无与 1.0 等价的完整内置小地图工作流；可按项目需要使用单位/Actor 的 MiniMapIcon 或 Canvas 自行补表现。见 04-限制、canvas-2d-game。
• 部分小卡片机制：可能尚未覆盖（商城已支持）；未覆盖的先用代码/API 实现。
• 捏人动画重定向：仍需在编辑器手动执行生成。常见单位→技能动画链可被资源统计自动收集，但静态分析不保证覆盖所有代码结构；关键动画可继续显式配置 GameDataModel.HumanoidSourceAnimations（≈ 1.0 的“额外加载动画”）作为保险，见 04-限制。
• UI 编辑器 / UI Authoring 覆盖不完整：可用 UI Authoring、GameData 模板或代码三法，但复杂交互仍需手工和运行时验收（见上）。
• 坐标系：2.0 默认镜头转了 90°，但可配回 1.0 朝向；迁移时别换算坐标数据，只复查代码里的方向假设（见上节）。
• 通用提醒：API 字段差异、被重设计的机制（可附加枚举→可扩展枚举/GameDataUnitProperty 等）必有手补；每块迁完都要编译 + 实际运行验证（wasicore-dev、GameCompletenessChecklist）。

更多详细信息

• 完整迁移配方与映射表 → reference.md
• 质量门槛与验收字段 → quality-gates.md
• 概念读物 → 资深用户指南（00 上手 / 01 核心差异 / 02 高级 / 03 UI / 04 限制）
• 编译与框架约束 → wasicore-dev；发布/调试流程 → Editor2PublishAndAiWorkflow