星火 2.0 开发文档

主题

用 AI 创建第一个游戏 ​

从安装好的星火 2.0 线上编辑器开始，让 AI 创建项目、读取项目规则，再完成第一次连接服务器的运行。无需先通过 GUI 创建或打开项目，也无需克隆 SDK 仓库。

在线阅读（星火 2.0 文档站）：<https://doc-sce.taptap.cn/guides/AiQuickStart.html>。

新作者默认使用线上版编辑器（production 渠道）。只有需要提前验证尚未进入线上的新能力，或按官方安排做外网测试时，才使用外网编辑器（alpha 外网公开测试渠道）。外网与线上的环境差异、项目迁移和数据隔离见部署环境与运行时环境指南；新项目不需要先从外网开始。

如果更习惯图形界面，按快速开始在 GUI 安装、登录并新建项目。两条路线最终都落在同一个 WasiCore 项目、同一套双端编译和日志规则上；切换入口前先保存、结束正在进行的调试，并正常关闭原宿主。

本流程适用于安装根目录包含 sce.cmd 和 AI_START_HERE.md 的 Windows 完整编辑器包。线上编辑器安装包包含这些入口；先运行 sce.cmd init --help 核对当前安装支持的命令。没有该入口时，先通过正式更新流程更新编辑器，或先用快速开始的 GUI 路线创建项目。

部署渠道和 API 版本是两件事：线上版/外网版决定更新渠道，1.0/2.0 决定编辑器 API 版本。Headless 只使用 API 2000 或更高；线上版安装也可能默认停在 1.0（API 13），不能把下载线上包等同于已经进入 2.0。如果已经用 1.0 打开过图形编辑器，按快速开始的版本选择步骤切到 2.0；Headless 本身不会替你改 GUI 选择。

当前无头入口依赖完整编辑器安装和已下载的官方资源：该安装需要先通过图形编辑器完成官方资源下载，游戏项目可以尚未创建。如果还没有用这个安装打开过图形编辑器，先启动一次；出现“编辑器版本选择”时选 2.0 实验版本 和 API 2000，再等待官方资源下载完成；否则 init 之后可能缺少场景、地形或模型资源。init 会准备 SDK、模板、构建依赖、默认 regular 字体及关键运行包；场景、地形、模型等官方素材仍使用已下载的资源。

只准备两个位置 ​

找到编辑器安装目录和新游戏的保存位置。可以在编辑器快捷方式的属性中查看安装位置。新项目目录应尚不存在，其父目录可以是空目录；项目无需放在编辑器安装目录下。

不要求配置全局 PATH、安装系统 .NET SDK 或 PowerShell 7。项目构建使用安装资源中的 .NET SDK，首次准备会联网下载当前渠道和 API 对应的 SDK、模板及依赖。设备授权优先使用命令回执中的完整授权链接或二维码完成；TapTap 只有基础链接和当前短码时按无头编辑器指南的规则拼接，不要让用户在裸设备页手填；有效的安装账号可直接复用。

安装根目录的 sce-installation.json 记录安装渠道和安装 API；它不等同于 GUI 当前选择的编辑器版本。需要确认 GUI 版本时以“设置 → 编辑器版本”为准；不要为了绕过初始化问题手工修改渠道或 API 记录。

建议用户和 AI 助手安装并优先使用 PowerShell 7（pwsh），减少中文日志和 UTF-8 输出乱码；未安装也可使用系统自带的 Windows PowerShell 5.1 继续。检测和安装方法见 PowerShell 7 环境诊断 Skill。

交给 AI 执行 ​

在 AI 工具中打开游戏将要保存的父目录，把下面的提示交给它，替换两个路径和文案：

text
编辑器安装目录是 D:/Apps/星火编辑器（线上编辑器）。
请在 D:/Games/FirstGame 创建一个星火 2.0 游戏。先查看安装的模板目录，选择最接近目标的现有官方模板；如果只是首次链路检查或没有更合适的模板，用 game_entry。
目标是做一个极小的可玩玩法：屏幕显示可点击目标和 0/10 分数；每次点击客户端向服务端发送一次命中；服务端按玩家累加本局分数并在 10 分时判定胜利；客户端显示服务端返回的分数和胜利结果；提供重开按钮，重开后服务端分数和结果清零。
先读取安装根目录的 AI_START_HERE.md，并查看 sce.cmd init --help。
通过 sce.cmd init 创建项目（按上一步选择 --template）；需要设备授权时向我展示完整公开链接和到期时间（TapTap 基础链接 + 当前短码按[无头编辑器指南](HeadlessEditor.md)拼接），等待授权结果。如果安装缺少 API 2000 或无头入口，停止并说明原因，不要用 1.0 继续。
初始化成功后，以新项目为工作目录，读取 AGENTS.md 和 docs/sdk/ai/skills/sce-first-game/SKILL.md，查询当前 Headless 工具能力，再开始修改。
先用项目自带示例完成一次链路检查（使用 game_entry 时按 E，服务端日志应出现 Hello,world!），再实现上面的小玩法。
客户端只负责输入和显示，不要用客户端分数作为权威结果。优先复用现有官方模板/组件和项目已有的触发器、双端事件、GameSystemUI / GameUI 能力，保持本轮目标小，避免无关重构；不新建私有框架。
完成后编译 Server-Debug 和 Client-Debug，启动一局真实连服调试，验证初始 0 分、点击计分一致、10 分胜利、重开清零并能再次得分，给出构建结果、画面截图和双端日志路径。
最后停止本轮调试并确认清理；不要发布游戏。

提示里同时给出模板选择、目标、权威端、双端构建、真实运行证据和停止条件，避免 AI 直接重写项目。AI 在项目出现之前读取安装根指引，项目出现之后读取项目内规则。账号秘密无需提供给 AI；命令使用编辑器本身的登录流程。

也可以自己创建 ​

在 PowerShell 中执行：

powershell
$Sce = Join-Path 'D:/Apps/星火编辑器' 'sce.cmd'
& $Sce init 'D:/Games/FirstGame'

默认使用安装记录的渠道、API 和 game_entry 模板。线上版安装默认使用线上渠道；需要外网能力时再显式选择，并先读部署环境与运行时环境指南。不要为了完成初始化把线上项目改成外网渠道。安装存在多个候选而无法确定时，按诊断显式指定 --channel 或 --api-version。模板可用 --template <模板目录名> 选择，以本安装的模板目录为准。

无头入口要求 API 2000 或更高，仅支持星火 2.0 及后续版本；它使用安装中的 2.0 入口，不会沿用 GUI 保存的 1.0 默认。安装根必须实际包含 API 2000 的版本目录，缺失时先用 GUI 版本选择或更新取得；显式指定旧 API 或打开 1.0 项目会报告不支持。

命令分别报告项目创建、环境准备、AI 上下文和项目就绪状态。只有最终 success: true 且 ready: true 才完成初始化。init 完成后不会自行启动游戏；接着让 AI 打开新项目根目录。

项目生成之后 ​

项目包含 SDK 绑定、文档、AGENTS.md / CLAUDE.md、AI Skills 与辅助工具。第一次创建或运行时，让 AI 先读首次上手 Skill，再调用项目辅助入口。该 Skill 会随初始化复制到 .codex/skills/sce-first-game/ 和 .cursor/skills/sce-first-game/，串起创建、授权、连服验收和失败恢复：

powershell
Set-Location 'D:/Games/FirstGame'
& ./ai/tools/Invoke-SceHeadlessMcp.ps1 -Project . -Action tools -Login
& ./ai/tools/Invoke-SceHeadlessMcp.ps1 -Project . -Action call -Tool headless_get_capabilities
& ./ai/tools/Invoke-SceHeadlessMcp.ps1 -Project . -Action call -Tool headless_get_project_state

辅助入口会核对项目、安装和 API，复用匹配的宿主，或启动本轮管理的宿主。先调用 headless_get_capabilities 和 headless_get_project_state，确认宿主身份、项目和实际工具 schema；返回降级或依赖错误时先处理，不要直接开始构建。查询实际 schema 后再填写构建、调试和数据编辑参数。宿主提供 HTTP/WebSocket，自定义 HTTP 调用由辅助脚本处理；它没有 stdio 传输。

已经在 GUI 中打开同一项目时，复用 GUI 完成工作，或保存并关闭该项目后再交接给 Headless。项目占用冲突会报告 project_owned_by_other_host；不要据此关闭不属于本轮的编辑器进程。

更新编辑器二进制前，先保存并正常关闭该安装的 GUI 和无头宿主，确认相关进程确实退出；滞留的 SCE.exe / SCE.HeadlessEditor.exe 可能阻止程序和 DLL 更新。具体关闭方式见关闭宿主与更新编辑器。

完成第一次真实连服运行 ​

第一次运行按下面的顺序完成，每一步都要有可观察结果：

  1. 让 AI 读取项目规则和首次上手 Skill，选择与目标最接近的现有官方模板；首次链路检查可用 game_entry，并保留已有的数据、触发器和默认控件。
  2. 通过宿主的保存、生成和构建工具完成客户端与服务端双端构建，并部署两个 AppBundle。只编译一端不算通过。
  3. 启动一个真实连服客户端，跟进同一个调试 operation_id，关联 Host game_session_id、客户端 PID 和 Runtime 目标。启动进程或编译成功都还不足以证明运行成功。
  4. 先验证链路：如果使用 game_entry，在未修改的项目中按 E，服务端日志应出现 Hello,world!。确认后再实现并验收下面的小玩法，不要停在只显示一条消息。
  5. 检查客户端画面、Runtime 状态和双端日志。跨端行为必须在同一局核对客户端与服务端结果。
  6. 结束本轮调试，确认客户端和进程清理。近期继续开发且无需更新时保留宿主，否则正常关闭。

小玩法验收 ​

建议目标与上面的 AI 任务一致：屏幕显示可点击目标和当前分数；客户端发送命中，服务端按玩家维护分数并在 10 分时判定胜利；客户端显示服务端返回的分数和结果；重开后清零并可再次完成一局。

至少核对：

  • 初始 0 分，客户端显示与服务端状态一致。
  • 每次点击只增加 1 分；胜利后继续点击不改变结果。
  • 第 10 分后客户端显示胜利，服务端记录胜利结果。
  • 重开后回到 0 分，并能再次完成一局。
  • Server-Debug、Client-Debug 都通过；同一局的客户端画面、服务端日志和结果能对应。

这是任务和验收标准，不代表本文已经用一个新项目真实跑通。

运行时日志通常在编辑器安装根目录的 logs/ 下：客户端在 logs/client，服务端在 logs/server。具体路径和失败排查见快速开始及无头编辑器指南。

构建成功、mcp_ready 和客户端已启动都只是中间证据；没有画面、Runtime 状态和双端日志，不能算完成第一次运行。

初始化没有完成时 ​

后续重新开始无头开发时，已知安装路径就先用同一安装的 sce.cmd prepare <项目目录> 准备当前渠道/API 的最新 SDK、文档和 AI 上下文，保留项目版本约束；成功后重新读取项目规则和 Skill。本轮刚完成 init / prepare 无需重复。路径未知时先定位，无法确定则说明尚未准备，不猜路径。已有项目宿主需先保存并正常关闭，详见开发前准备。

资源下载失败时按诊断重试。项目目录已经创建后，使用原地准备入口继续：

powershell
& $Sce doctor --project 'D:/Games/FirstGame'
& $Sce prepare 'D:/Games/FirstGame'

prepare 保留项目身份和用户文件，不重新创建项目。若身份申请已发出但结果未知，程序会停止自动注册；保留诊断和恢复记录，按错误码处理后再继续。不要删除记录后反复申请。

--mode local --package-name <本地标识> 用于明确的本地创建，不能作为连服或发布权限的证明。第一次真实连服使用默认的授权创建流程。

需要帮助 ​

  • 编辑器或 2.0 版本问题（版本选择、安装更新、构建或运行异常）：加入星火 2.0 反馈与支持 QQ 群 1021737313。
  • 发行支持与 TapTap 测试/上线接洽：见快速开始的“需要帮助”。
  • 初始化或构建失败时，先保留诊断、日志和恢复记录，不要删除记录后反复申请。

下一步 ​

  • 回到图形界面路线：快速开始说明安装、登录、项目创建、MCP 连接和第一次双端调试。
  • **发布并创建内测码：**发布前先结束本轮调试并确认清理；发布准备会独占项目。读平台内测与内测码，正常发布后在创作者中心配置测试模式并创建内测码；内测码测试没有额外的测试准入条件，但仍需完成正常发布和后台模式配置。内测运行在 test 环境，只能消耗已有星火币、不能充值；上线（formal）后可在星火对战平台充值。TapTap App 内嵌启动仍需另行开通 TapTap 测试。
  • **TapTap 测试与正式上线：**读 TapTap 测试与正式上线。可以验证星火币充值和 TapTap App 内嵌启动，但测试开通需要联系工作人员，不能自行开通；它不是开始内测的前置步骤。
  • 日常开发闭环：星火 2.0 发布、调试与 AI 辅助开发流程。
  • 深入无头能力：无头编辑器指南。
  • 发布前检查：游戏完整性检查清单。

init 完成或第一局运行成功都不等于发布；发布、后台模式配置和内测码创建是另外的步骤。