星火 2.0 开发文档

主题

星火 2.0 平台内测与线上发布指南 ​

本文面向已经能在编辑器里运行项目、准备让测试者通过星火对战平台进入的开发者，说明从线上版编辑器发布、资源准备、创作者中心测试模式、内测码、作者加入内测、测试者进局，到更新和日志反馈的完整闭环。

本文只覆盖星火对战平台的 PC / Android / iOS 客户端内测。TapTap App 内嵌启动、TapTap 工坊测试与正式上架不在本文范围。对战平台内测运行在项目的 test 环境，因此只能消耗已有星火币、不能充值；项目上线后运行在 formal 环境，星火对战平台可以正常充值。充值流程与环境差异见 TapTap 测试与上架。

> 本文按“新项目默认使用线上版编辑器”的路线整理。外网公开测试环境（alpha）只用于需要提前验证尚未进入线上的能力，或官方明确要求的情况。官网入口顺序、编辑器默认渠道和后台页面文案可能仍在调整；本文中的菜单和按钮名称按当前公开资料整理，实际以当前官网、更新器和创作者中心页面为准。

先分清四个词 ​

发布和内测最容易出错的地方，是把“部署环境”和“项目运行时环境”混在一起。

名称代码 / 后台中的常见叫法用途
线上生产环境production、pd、线上环境新项目默认使用的部署环境；线上编辑器、线上创作者中心和线上对战平台属于这里
外网公开测试环境alpha、测试环境、外网 Public Test提前验证尚未进入线上的编辑器、SDK 或客户端能力；只作为特殊路线
项目内测环境test、TapCanary项目自己的邀请测试环境，测试者通过内测码进入
项目正式环境formal、创意工坊项目正式上线后对公开玩家开放的环境

alpha + test、alpha + formal、production + test、production + formal 是彼此独立的数据环境。项目内测环境与项目正式环境的云数据也相互隔离：测试阶段的存档、货币、背包、排行榜等不会自动进入正式环境。内测阶段不要承诺“不删档”；如果测试中发生了付费或等价付费行为，需要在正式环境按项目规则安排补偿，具体边界见部署环境与运行时环境指南。

外网 alpha 和线上 production 的自定义云端资源同样互相独立。项目资源随项目发布，通常更自洽；如果项目大量使用自定义云端资源，从外网迁移到线上前要提前确认目标环境已有对应资源，或安排官方同步。

默认路线与公开入口 ​

新项目默认使用下面这条完整链路：

  1. 安装并登录线上版（production 渠道）星火编辑器。
  2. 在线上版编辑器里打开项目，完成构建、调试和上传发布。
  3. 登录线上创作者中心，配置项目测试模式和内测码。
  4. 使用线上版星火对战平台（PC / Android / iOS）进入内测。

只有需要提前验证尚未进入线上的能力时，才切换到外网公开测试链路。切换时，编辑器、创作者中心、对战平台和项目发布环境必须整体对应，不能把线上编辑器、外网对战平台和外网项目混用。

以下公开入口在 2026-11-02 核对可访问；如果官网已经改版，以当前页面提供的入口为准。

用途线上（默认）外网公开测试（特殊需要）
星火编辑器官网<https://sce.taptap.cn/&gt;外网测试版入口以官方通知为准
编辑器下载页<https://package-pd.spark.xd.com/pd_editor.html&gt;<https://package-pd.spark.xd.com/alpha_editor.html&gt;
创作者中心<https://developer.spark.xd.com/&gt;<https://developer-alpha.spark.xd.com/&gt;
PC 对战平台<https://package-pd.spark.xd.com/pd_client_pc.html&gt;<https://package-pd.spark.xd.com/alpha_client_pc.html&gt;
Android 对战平台<https://package-pd.spark.xd.com/pd_client_android.html&gt;<https://package-pd.spark.xd.com/alpha_client_android.html&gt;
iOS 对战平台App Store 星火对战平台外网测试 iOS 入口待核实

星火编辑器官网当前提示编辑器下载需在 PC 浏览器打开，且仅支持 Windows；安装包页面只显示“星火编辑器”并自动开始下载，不代表某个具体版本号。版本和渠道以编辑器更新器及当前官网为准。iOS 线上客户端已通过 App Store 公开提供（应用 ID 6480159137）；外网测试 iOS 客户端是否存在、如何获取，需要向官方确认，本文不自行推断。

星火 2.0 文档站是 <https://doc-sce.taptap.cn/>；doc.sce.xd.com 是星火 1.0 文档，仅历史对照，不是 2.0 当前契约，也不应作为新作者安装 2.0 编辑器或对战平台的入口。

从线上编辑器发布 ​

1. 准备资源 ​

发布前先确认资源属于哪一类：

  • 项目资源：放在项目目录的 res/、ui/ 等位置，随项目发布一起打包。模型、粒子、音频、项目私有材质通常优先放在这里，迁移到线上时更自洽。
  • 自定义云端资源：上传到当前部署环境的资源库，同一环境内可以被多个项目共享，但外网和线上互相独立。准备长期在线上运营的项目，应优先确认线上环境已有资源，或提前安排同步。
  • 官方资源：官方模型、特效、音频通常已经在外网和线上同步；发布后缺失更常见的原因是资源没有进入引用清单，而不是环境缺少官方资源。

UI 图片、Spine 和项目字体有各自的路径规则：UI 图片和 Spine 放在项目 ui/ 下，代码路径从 ui/ 之下开始；项目 GameUI 字体放在 res/font/... 并加入 ref/fontref.txt。完整规则见项目资源路径指南和自定义字体。

需要刷新资源清单、Humanoid 烘焙动画或模型预烘焙碰撞时，在编辑器菜单执行 “工具 → 资源统计和动画重定向” 下的“统计资源并生成”或“生成”。发布流程本身也会执行资源统计；单独执行适合在发布前先排查资源清单。

资源统计后重点检查：

  • ref/objref.txt 是否包含需要客户端预下载的资源路径。
  • ref/model_animation.json 是否包含目标模型和技能动画；Humanoid 动画应生成到 res/anim/<模型名>/...。
  • ref/model_collision.json 是否包含需要预烘焙碰撞的模型；实际产物是 block/model_collision/<08x>.bin 和配套的 block/model_collision/<08x>.roles.dat。
  • 项目 res/ 内的模型、贴图和音频随项目包发布，不要求进入 objref.txt；缺失时先检查本地文件、引用和项目打包。

发布后缺模型、粒子、音频或动画时，按发布资源缺失排查继续定位。有自定义 UI 图集时，可在发布成功后用 project_publish_verify_resources 检查发布包中的 JSON、纹理容器和区域配置；它不能代替目标客户端进局显示验收。

2. 构建与本地验收 ​

发布前至少完成：

  • Server-Debug 和 Client-Debug 都能编译通过。
  • 有服务端逻辑的项目，走一次标准调试，确认客户端、服务端日志和整局流程。
  • 纯客户端项目，或服务端项目中的客户端局部预览，走一次纯客户端调试并用 Runtime MCP 截图或 UI 快照确认关键界面。
  • 对照游戏完整性检查清单，确认核心玩法、失败/胜利流程、UI 状态、断线/重进和资源加载不是只“能编译”。

3. 上传发布 ​

  1. 在线上版编辑器中打开目标项目，确认当前编辑器渠道是线上版，而不是外网测试版。
  2. 保存项目，使用编辑器的发布/上传入口（当前公开资料显示为 “发布 → 上传”），或让 AI 调用 project_publish_start 复用同一套保存、生成代码、资源统计和上传流程。
  3. 等待上传和后台发布完成。accepted 只代表上传已受理；只有带后台最终结果（final_result）且发布身份（publish_identity）与本次项目/环境一致的 succeeded 才表示后台发布完成。accepted / unknown 都不要重复上传，先用同一个 operation_id 查询。
  4. 到线上创作者中心确认项目内容已经更新。上传成功不等于大厅入口已经可用，测试模式是下一步的独立配置。
  5. 如果返回未上传的依赖资源列表，先处理这些资源再重试；结果为 unknown 时继续查询或打开返回的 backend_url。

预期结果：project_publish_status 进入 succeeded，创作者中心显示最新内容；如果仍是 accepted 或 unknown，继续查询原操作。

发布入口不会执行创作者中心的审核、上架或正式环境晋级，也不用于依赖库发布。工具细节见 SCE Editor MCP 工具速查。

配置测试模式 ​

项目上传成功后，测试者能否在平台大厅看到并进入游戏，取决于创作者中心的测试模式配置。编辑器里的 GameDataGameMode、workflow_create_game_mode 只配置项目内玩法，不会自动创建创作者中心的大厅模式；两处都需要核对。

在创作者中心配置 ​

下面使用当前公开资料中的菜单名称；创作者中心可能按版本调整名称和分组，实际以当前页面为准。

  1. 登录线上创作者中心，选择目标项目。
  2. 打开 “大厅配置”，把配置环境切到测试环境（test，当前后台也可能显示为 TapCanary 一类名称）。
  3. 进入 “游戏多模式”，添加或编辑一个模式。
  4. 至少确认：模式处于显示状态；生效范围包含当前项目；房间人数和开局人数与项目玩家槽位匹配；模式类型符合实际玩法。
  5. 保存后重新读取模式列表，确认保存结果。已打开的后台页面在保存前先刷新，避免页面缓存的整份旧配置覆盖新值。

后台配置的房间人数和开局人数应与项目玩家槽位匹配。修改项目队伍或玩家配置后，需要重新发布项目才会生效。

如果项目使用大厅模块、商店或其他局外配置，按项目需要一并检查；模式本身是进入游戏的必要条件，不能用编辑器内的 GameDataGameMode 代替。

预期结果：重新读取模式列表时能看到该模式为显示状态，生效范围包含当前项目，人数与玩家槽位匹配。

通过作者后台 MCP 核对或配置 ​

使用 author_get_project_setup / author_get_test_modes 读回项目与测试模式；需要写入时，按作者后台 MCP 指南使用 author_preflight_test_mode、author_create_test_mode、author_edit_test_mode。完整参数、权限、版本和请求约束在该指南维护。

写入时按指南使用读取到的版本和唯一请求；超时或结果未知时用同一请求重试，不要新建写入。写入后读回当前模式、版本和确认状态，再读一次模式列表。测试模式写入只操作测试环境，不会自动同步到正式环境；正式同步、创意工坊配置和游戏发布是独立操作。

创建内测码 ​

项目发布并配置好测试模式后，在创作者中心的项目测试/内测入口创建或查看邀请码。具体菜单名称以当前后台为准；邀请码可以分享和禁用；需要替换或重新启用时，按后台当前可用操作处理。

作者后台 MCP 也提供邀请码读取与创建入口，完整权限和返回字段见作者后台 MCP 指南。仅在用户明确要求时创建；已有邀请码会原样返回，不会自动替换或重新启用。

预期结果：邀请码状态为启用，能读到完整邀请码；如果已有邀请码，先确认它仍属于当前部署环境。

邀请码是给测试者分享的代码，不是授权票据；MCP 的 Bearer 票据仍然必须保密。邀请码与部署环境、项目发布环境对应，线上项目应使用线上创作者中心生成的邀请码，不要把外网 alpha 的邀请码拿到线上对战平台使用。

作者自助内测有没有额外准入条件 ​

作者自己组织的平台内测不要求测试者先申请资格或参加官方组织的测试项目。作者自行完成项目发布并在后台创建邀请码后，把邀请码分享给测试者即可。这不等于可以跳过正常发布、后台测试模式配置、平台内容合规和客户端版本匹配。

星火官方组织的测试（例如鉴赏家测试）不属于作者自助内测；如需参加，按当期官方通知和安排参与即可。报名方式、编辑器和账号要求以当期官方说明为准，不沿用历史测试口径。

作者加入自己的内测 ​

作者本人不必手动输入邀请码。可以在创作者中心的项目测试/内测入口点击 “加入我的内测”；也可以按作者后台 MCP 指南调用 author_join_my_test。两种方式都要求项目已有且启用的内测邀请码，工具不会自动创建或启用邀请码。

加入使用票据账号和项目，不接受额外账号、项目、邀请码或环境参数。成功后读回内测列表确认；随后在对战平台使用同一账号刷新内测列表，无需自行输入邀请码。

结果未知时保持同一账号、项目和授权重试同一工具，不要新建请求；邀请码缺失、禁用或轮换时先核对邀请码状态。成功加入内测只代表账号进入内测列表，不代表测试模式一定可用，也不代表实际进局已经验证。完整错误码和返回字段见作者后台 MCP 指南。

测试者进入内测 ​

给测试者分享邀请码时，一并说明编辑器/平台环境、项目名、目标平台和测试模式。测试者按下面步骤进入：

  1. 下载与项目环境匹配的星火对战平台：线上项目使用线上版 PC / Android 客户端，或从 App Store 星火对战平台 安装 iOS 客户端。
  2. 使用测试者自己的 TapTap/SCE 账号登录，不需要使用作者账号。
  3. 打开平台的 “内测” 入口，选择 “加入内测”。
  4. 输入作者分享的邀请码，进入项目。
  5. 如果平台中同时存在测试环境和正式环境，确认进入的是项目内测条目，而不是正式环境条目。

预期结果：测试者能看到项目内测条目并成功进入项目；如果只能进大厅、进不了游戏，回到测试模式检查可见状态、生效范围和人数。

平台按钮文案可能随版本调整；上面是当前公开资料描述的主流程，实际以客户端页面为准。

在手机上粘贴邀请码时，不要使用输入法的快捷粘贴，部分输入法会截断邀请码。

内测码无效时先检查什么 ​

  • 对战平台版本和项目所属的部署环境是否一致。线上项目必须使用线上平台；外网项目必须使用对应的外网平台。
  • 项目是否已经上传到对应环境，并在创作者中心显示为最新内容。
  • 测试环境是否有处于显示状态、生效范围包含当前项目的模式。
  • 模式房间人数和开局人数是否与项目玩家槽位匹配。
  • 邀请码是否已启用、是否被禁用或重新生成。
  • 邀请码是否被输入法截断，或粘贴时混入了空格。

PC 单人内测快捷启动（test 渠道） ​

线上对战平台（pd）的 test 渠道已包含 lib_lobby 快捷启动脚本，可以在命令行直接进入指定项目、指定单人模式的内测局，省掉手工选择项目和模式。formal 渠道仍是旧版本，不包含该参数；正式渠道不要使用。

适用前提：

  • 平台先按正常方式登录，账号已经加入该项目的内测（作者本人可“加入我的内测”，或用已启用的邀请码加入）。
  • 测试模式已在创作者中心配置为显示、生效范围包含该项目、人数与玩家槽位匹配。
  • 只支持冷启动的单实例：启动参数只在进程启动时读取，已经在运行的平台或大厅不会接收新参数。需要重新带参数启动时，先正常关闭旧进程。
  • 只自动开局**单人（SINGLE）**模式；匹配、组队、随进随出等其它模式返回 mode_type_unsupported。
  • 地图按项目 ID 进入，不解析后台项目别名；-author_test_project 必须等于实际地图名。
  • 这些参数不新增权限，也不能绕开内测资格、模式可见性或人数限制；资格不足时仍按平台原有规则失败。

先在 PowerShell 里定位本机实际的对战平台安装路径（各人安装位置不同，不要默认从某个固定目录启动，也不要为此重新下载安装包），再执行：

powershell
$Launcher = '<星火对战平台安装目录>\星火对战平台.exe'   # 换成实际路径
& $Launcher `
  -wx_lobby=app_box `
  -tag=test `
  -author_test_project=<项目ID> `
  -author_test_mode=<模式ID> `
  -author_test_request_id=<可选，便于在日志里定位本次启动>
  • 路径含空格时必须用 & 加引号调用（如上面 $Launcher 的写法），不要直接把整条路径和参数拼成字符串执行。
  • -wx_lobby=app_box 与 -tag=test 必须同时存在；其它渠道或大厅会拒绝并记录日志。
  • 不传任何 -author_test_* 参数时，平台行为与原来完全一致。

判断是否真的进局，不要只看进程是否启动：

  1. 大厅 Lua 日志出现 AUTHOR_TEST_LAUNCH {json} 回执，其中 result=success、actual_map_name 与请求项目一致、actual_map_kind=0、actual_session_id 非空；失败时按 detail 与 result（如 mode_not_found、mode_locked、update_failed、timeout）继续排查。
  2. mode_confirmed 恒为 false：平台“开始游戏”事件不携带模式 ID，不能把该字段当成模式已确认。需要确认模式时，对照同一次启动的 match_info 与实际模式名、类型。
  3. 再核对客户端加载：AppBundle 来自该项目、出现场景加载完成（如 Client scene load completed），以及客户端连接成功日志。三层都成立才算进入游戏。

自动化脚本结束时不要抢占用户鼠标键盘；需要退出时正常关闭本轮启动的平台进程，并确认没有遗留子进程。快捷启动只证明“进入测试局”，游戏内具体玩法仍需单独验证。

更新与重新测试 ​

平台内测的更新闭环是“修改 → 构建与调试 → 重新上传 → 确认后台 → 测试端重新进入”。

  1. 在线上版编辑器中修改代码、数据、触发器或资源。
  2. 重新编译 Server-Debug 和 Client-Debug，并在编辑器里走一次与本次修改匹配的调试。
  3. 重新执行“发布 → 上传”，等待后台发布成功。
  4. 在创作者中心确认项目内容已经更新；如果本次修改涉及大厅模式或人数，重新核对测试模式。
  5. 让测试者关闭并重新打开对战平台，或按客户端提示更新项目内容后再进入同一测试条目。
  6. 用同一测试账号、同一模式重跑上一轮失败的场景，记录新的日志和截图。

不要假设重新上传会自动更换邀请码，也不要假设旧邀请码一定失效；是否需要禁用旧码、替换或调整启用状态，以创作者中心或 author_get_test_invite_status 的当前读回为准。

测试环境更新不等于正式环境更新。项目正式上线、TapTap 审核、正式环境配置和正式环境数据同步都是独立流程，不能因为内测通过就自动完成。

反馈与日志闭环 ​

先让测试者提供可定位的信息 ​

让测试者反馈时至少提供：

  • 星火账号的 SCE 昵称或 SCE ID。
  • 出问题的平台（PC / Android / iOS）和客户端版本或截图。
  • 进入的项目、模式，以及是测试环境还是正式环境。
  • 大致时间、操作步骤、期望结果和实际结果。
  • 截图或录屏；涉及崩溃、黑屏、卡加载时保留发生时间。

读取日志 ​

创作者中心提供玩家/游戏局日志查询入口；用 SCE 昵称或 SCE ID 找到玩过本游戏的玩家后，可以查看当前后台可见的游戏局日志记录。记录范围、保留时间和查询方式以当前后台为准，具体见日志文件。

作者后台 MCP 也可以读取客户端上传日志和游戏局脚本日志；先列出记录，再按实际记录读取文本。查询时选择测试环境，不要拿正式环境日志排查内测问题；完整工具、分页和字段见日志文件。

列表为空时先核对项目、环境和时间范围，再扩大查询；仍为空则需要新的客户端上传日志或游戏局样本。平台侧能读到的是已经上传的客户端日志和游戏局脚本日志。如果项目没有提供客户端日志上传入口，不要把测试者机器上的本地客户端日志当作后台已有记录；此时应让测试者提供截图、复现时间和账号，并用游戏局日志排查服务端侧。

在游戏内提供上传日志入口 ​

如果项目希望在游戏内提供“上传日志”按钮，可在客户端调用 ClientEnvironment.Diagnostics.TryUploadLogs()，并先用 Runtime.Supports(ClientRuntimeFeature.ClientLogUpload) 判断当前客户端是否支持。该能力需要客户端能力版本 6；返回值只表示客户端是否接受上传请求，不表示网络上传已经完成。界面不应在请求返回时直接显示“上传成功”，应以作者后台出现对应记录为准。细节见客户端二进制兼容与能力版本。

修复与复测 ​

  1. 按日志把问题归到客户端、服务端、数据配置、资源发布或平台环境，不要把一次现象直接归因为框架缺陷。
  2. 修复后重新编译、调试、上传，并按上一节更新测试内容。
  3. 让同一测试者在同一平台、同一模式和同一操作路径复测。
  4. 保留复测截图、客户端上传日志或游戏局日志；只有服务端证据时，结论写“服务端已验证，客户端待验收”。
  5. 测试环境验证通过后，再进入正式发布、TapTap 审核和正式环境配置。

编辑器调试日志通常在 <EditorRoot>/logs/client、<EditorRoot>/logs/server 和 <EditorRoot>/logs/build 下；平台内测不能直接假设测试者机器上的这些目录可读，必须通过创作者中心或作者后台 MCP 获取平台侧日志。

支付与 TapTap 边界 ​

已有星火币消费 ​

如果项目包含商店或支付流程，对战平台内测允许使用账号已有星火币购买商品、扣费、发货和查看余额变化。测试时使用已有余额的账号；余额不足时不要通过充值补齐，改用有余额的测试账号，或把该项标记为未验证。

该边界适用于当前对战平台内测能力；平台版本或支付入口变化后，以当期说明为准。

内测（test）不能充值，上线（formal）可以 ​

能否充值取决于项目运行环境，不是对战平台本身的能力限制。内测运行在 test 环境，对战平台只允许消耗账号已有星火币，不能发起充值；项目正式上线后运行在 formal 环境，可以在星火对战平台正常充值。内测完全自助、由用户自行操作；正式上线和 TapTap 测试的开通流程有人值守，充值涉及资金，因此不对完全自助的内测开放。

充值入口、支付面板、支付回调和充值后返回大厅需要按运行环境分别验证：test 内测不要用已有余额消费的结果代替充值验收；formal 上线后按真实支付流程验证。TapTap App 内嵌启动仍需要开通 TapTap 测试。

TapTap App 内嵌启动不在本范围内 ​

本文所有进局验证都指星火对战平台 PC / Android / iOS 客户端，TapTap App 内嵌启动不在对战平台内测范围内。TapTap 测试可以验证充值和 TapTap App 内嵌启动，但需要联系工作人员开通 TapTap 测试，作者无法自行开通；具体流程见 TapTap 测试与上架。

数据隔离与补偿 ​

项目内测环境和项目正式环境的云数据相互隔离。测试环境的购买、货币、背包和存档不会自动进入正式环境。测试阶段如果发生付费或等价付费行为，需要在正式环境按项目规则安排补偿；不要向测试者承诺“内测数据会带入正式环境”。补偿和迁移细节见部署环境与运行时环境指南。

验收清单 ​

  • [ ] 使用线上版编辑器、线上创作者中心和线上对战平台，没有混用外网 alpha 组件。
  • [ ] Server-Debug 和 Client-Debug 编译通过，标准调试完成。
  • [ ] 项目资源、云端资源、UI 图片、字体和动画清单已按发布范围核对。
  • [ ] 项目已上传到目标环境，创作者中心显示最新内容。
  • [ ] 测试模式处于显示状态，生效范围包含项目，人数与玩家槽位匹配。
  • [ ] 已创建并启用邀请码，且邀请码属于目标部署环境。
  • [ ] 作者已加入自己的内测，或测试者已用邀请码加入。
  • [ ] 至少在一台目标平台实机进入游戏，完成加载、核心玩法、退出和重进。
  • [ ] 更新后重新上传并复测，确认测试端拿到新内容。
  • [ ] 已收集测试者账号、时间、平台、模式和日志；问题有复测结论。
  • [ ] 已明确内测与正式环境的数据隔离；充值验证和 TapTap App 内嵌启动按 TapTap 测试流程另行确认。

相关文档 ​