星火 2.0 开发文档

主题

部署环境与运行时环境指南 ​

WasiCore 现在把“环境”拆成两个正交维度：

  • 部署环境：官方平台、编辑器、SDK 和运行时所在的发布通道，代码中由 Game.DeploymentEnvironment / GameDeploymentEnvironment 表示。
  • 运行时环境：当前游戏局属于项目自己的调试、内测还是正式链路，代码中由 Game.RuntimeEnvironment / GameRuntimeEnvironment 表示。

两条轴会组合成完整环境。SDK 枚举上可以表达 3 x 3 组合；其中 master 是部署通道保留值，不作为项目发布、测试或迁移目标。新项目默认在线上生产环境（production）开发、测试和发布；alpha 外网公开测试环境只在需要提前验证尚未进入线上的能力时使用。项目判断仍然围绕 production（必要时外加 alpha）以及 debug / test / formal 三个运行时环境展开。

这两个概念不要混用：alpha 不是项目内测，test 也不是编辑器外网测试。

推荐中文称呼 ​

文档、客服沟通和项目代码注释建议统一使用下面的称呼：

代码值推荐中文名说明
GameDeploymentEnvironment.Alpha外网公开测试环境编辑器和运行时的外网测试部署环境
GameDeploymentEnvironment.Production线上生产环境正式线上部署环境
GameDeploymentEnvironment.Mastermaster 部署保留值不作为项目发布、测试或迁移目标
GameRuntimeEnvironment.Debug调试环境编辑器调试、远端调试等开发调试链路
GameRuntimeEnvironment.Test项目内测环境项目邀请玩家参与内测的运行环境
GameRuntimeEnvironment.Formal项目正式环境项目正式上线后公开玩家游玩的运行环境

如果需要同时写出完整环境，建议使用“部署环境 + 运行时环境”的组合说法，例如 production + formal 可以称为“线上生产环境的项目正式环境”。

部署环境 ​

部署环境描述官方平台和编辑器发布通道。

部署环境项目侧含义主要用途
master部署通道保留值不作为项目发布、测试或迁移目标
alpha外网公开测试环境通常第一时间收到当周编辑器、SDK、服务端和客户端运行时的新能力
production线上生产环境项目正式上线、审核和公开运营依赖的生产部署环境

production 是项目正式公开运营时依赖的生产环境。新项目默认使用线上生产环境 production：从官网下载线上版本编辑器，直接在线上环境创建项目、调试和发布，不需要先在外网公开测试环境开发。外网公开测试环境 alpha 只在下面这些情况下使用：

  • 需要提前验证尚未进入线上的新 API、编辑器能力、官方依赖库或客户端能力。
  • 官方明确要求配合外网验证或复现问题。
  • 项目要从外网迁移到线上，需要在 alpha 做上线前对照。

日常开发、项目内测和正式发布都应以线上生产环境为基准，alpha 不是新作者的默认起点。

外网新能力进入线上的时间不是固定承诺。具体间隔取决于当批发布内容和各平台客户端版本覆盖，涉及客户端二进制的能力会更晚。排期时以项目内 docs/sdk/CHANGELOG.md、官方公告和编辑器提示为准，不要把某个固定天数或固定周期当成长期约定。

alpha 可用只说明能力可以在外网公开测试环境验证，不代表 production 已经可用。用户真正能在线上使用一个新 API，需要编辑器、SDK/API 文档、官方依赖库和运行时能力都进入线上生产环境。

运行时环境 ​

运行时环境描述项目自己的游戏局类型和数据隔离标签。

运行时环境推荐中文名典型入口主要用途
debug调试环境编辑器调试、远端调试开发期验证代码、数据、UI 和运行时行为
test项目内测环境项目测试入口或内测码项目还没准备好正式上线时，邀请一批玩家测试
formal项目正式环境正式发布入口上架审核通过后，对公开玩家开放

test 是用户项目自己的内测环境，不是编辑器的 alpha 外网公开测试环境。一个项目可以运行在 alpha + test，也可以运行在 production + test；它们分别表示“外网公开测试部署里的项目内测”和“线上生产部署里的项目内测”。

production + formal 表示用户游戏正式发布：项目经过平台审核并上架 TapTap 渠道后，玩家可以在 TapTap App 和星火对战平台上公开找到并游玩游戏。

test 表示项目还没有准备好正式上线，但希望先邀请一批玩家测试。项目发布后，test 环境仍会继续运作；玩家可以通过星火对战平台上的项目测试入口或项目提供的内测码进入，不需要担心项目进入 formal 后 test 环境自动消失。

数据隔离 ​

部署环境和运行时环境会共同决定云数据等环境侧数据的隔离空间。换句话说，alpha + test、alpha + formal、production + test、production + formal 是彼此独立的数据环境；枚举中可表达的所有 3 x 3 组合也按组合隔离。

尤其要注意：test 和 formal 的云数据是分开的。玩家在项目内测环境里的存档、货币、背包、排行榜或其他云数据，不会自动进入项目正式环境。

因此，项目内测阶段不要随意承诺“不删档测试”。如果内测发生了付费或等价的付费行为，常见做法是记录订单和发放情况，在正式环境为玩家补发等值的游戏内一级付费货币或其他补偿。也可以选择导出内测数据清单，再在正式环境还原，但这种做法成本高、风险高，也更少见。

项目正式上线后，test 环境仍然继续存在，内测数据不会因为正式环境上线而自动删除。只是 test 与 formal 数据相互独立，需要在玩家沟通和运营活动中把这一点说清楚。

同样的隔离原则也适用于依赖环境标签的服务端能力。例如 ServerChannel 会按当前运行时环境隔离，同名频道在内测环境和正式环境中不会互相收到消息。

在代码中读取环境 ​

服务端和客户端都可以读取当前环境：

csharp
var deployment = Game.DeploymentEnvironment;
var runtime = Game.RuntimeEnvironment;

if (Game.IsProductionDeploymentEnvironment && Game.IsFormalRuntimeEnvironment)
{
    Game.Logger.LogInformation("当前处于线上生产环境的项目正式环境");
}

if (Game.IsTestRuntimeEnvironment)
{
    Game.Logger.LogInformation("当前处于项目内测环境");
}

常见用途：

  • 在日志、诊断信息或后台消息中写明当前环境。
  • 对内测和正式环境使用不同的运营提示、活动开关或灰度逻辑。
  • 避免把 debug / test 数据误当作 formal 数据处理。
  • 在上线前检查当前是否真的运行于 production + formal。

不要用这些 API 绕过平台审核、支付合规或玩家告知流程。它们只是让项目代码明确知道当前所处环境。

在服务端逻辑中，可以把 Game.DeploymentEnvironment 和 Game.RuntimeEnvironment 作为当前游戏局的环境来源，直接按 test / formal 等环境编写分支。Unknown 不代表一个可发布、可运营的环境；客户端代码读到 Unknown 时，通常表示当前时机还没有取得环境信息，或遇到了当前 SDK 暂不认识的新环境值。

客户端如果读到 Unknown，不要把它当作 alpha、production、test 或 formal 的默认替代值；更稳妥的做法是记录日志，并在关键上线、付费、迁移逻辑中显式阻断或走保守分支。

从外网公开测试迁移到线上生产 ​

从 alpha 迁移到 production 前，建议逐项确认：

  1. 当前项目依赖的 SDK、编辑器、客户端和服务端能力是否已经进入线上生产环境。
  2. 项目是否依赖近期才在 alpha 验证的新 API、编辑器生成内容、底层运行时或客户端能力；如果依赖，先在 docs/sdk/CHANGELOG.md 确认它所在的发布周期。
  3. 外网公开测试通过的问题是否已经在线上生产等价环境重新验证。
  4. 项目内测环境和项目正式环境的数据策略是否已经说明清楚，尤其是云数据、排行榜、货币和付费补偿。
  5. 自定义资源是云端资源还是项目资源，线上生产环境是否具备对应资源。
  6. 发布资源统计是否完整，ref/objref.txt 和发布产物 ref/full.ref 是否包含项目所需资源。
  7. 运营配置、测试入口、邀请码、后台配置、环境侧数据等是否已经按线上流程重新配置。
  8. 如果依赖刚修复的线上问题，确认它是依赖库/服务端热修，还是仍需要等待客户端版本覆盖。

不要把 alpha 验证等同于 production 验证，也不要把 test 验证等同于 formal 验证。前者是部署环境差异，后者是项目运行时环境和数据隔离差异。

如何看更新日志和发布周期 ​

用户可以在项目文件夹里的 docs/sdk/CHANGELOG.md 查看最新一批发布到外网公开测试环境的更新日志。这个文件对应 WasiCoreSDK 仓库中的 docs/CHANGELOG.md。

更新日志按发布周期倒序排列，周期标题会标注本批更新的日期范围和发布状态。一般情况下：

  • 外网更新通常在工作日发布，具体日期看当期更新日志和公告。
  • 同一批外网更新进入线上的间隔随发布内容变化，不是固定承诺。
  • 涉及客户端二进制或平台版本覆盖的能力，线上可用时间还要加上对应版本的放出时间。
  • 如果某个新 API、编辑器能力或官方依赖库能力出现在某个外网周期的更新日志里，可以据此估算线上可用时间，再以官方公告、编辑器提示或当前发布计划为准。

项目排期时，建议先在 docs/sdk/CHANGELOG.md 找到目标能力所在的发布周期，再判断它目前是“已发布到外网公开测试环境”还是已经进入线上生产环境。不要只看到更新日志里有功能说明，就默认线上项目当天可用。

线上问题修复预期 ​

线上出现问题时，修复速度取决于问题落在哪一层：

问题类型一般处理方式项目侧建议
官方依赖库 bug通常可以通过官方依赖库热修处理联系官方确认修复计划；项目侧保留验证用例
服务端 bug通常可以通过服务端热修处理优先确认是否影响存档、结算、匹配、云数据等线上状态
客户端 bug往往需要客户端版本发布和全平台覆盖预期修复完整覆盖可能至少两周，最多三周；期间优先使用 workaround 规避

如果线上遇到客户端 bug，项目侧不要把排期建立在“马上全量修好”上。更稳妥的做法是临时绕开触发路径，例如关闭相关功能、改用旧 API、加兼容分支、降低资源或表现配置，等客户端修复完成后再恢复。

资源迁移 ​

资源迁移只是部署环境迁移的一部分，但它很容易在最后阶段暴露。

资源管理器里通常有两种选择：

维度云端资源项目资源
资源位置上传到当前环境的资源库放在当前项目目录中，随项目发布
跨项目复用同一环境内可以被多个项目共享每个项目各自携带，不能跨项目只下载一次
玩家下载玩家玩多个游戏时，相同云端资源可以复用本地缓存，避免反复下载玩家下载游戏时，会下载项目客户端和项目内资源；多个项目使用同一资源也会各自下载
外网/线上迁移自定义云端资源在外网和线上互相独立，需要重新上传或官方同步资源跟随项目发布，外网和线上都更自洽
典型用途多项目共享角色、怪物、通用场景件、大型音频/模型库项目私有资源、活动资源、迁移期资源、必须随包保证存在的资源

云端资源适合多个项目共享。玩家如果玩多个使用了同一云端资源的游戏，客户端可以复用已经下载过的资源缓存，不需要为每个项目重复下载同一份模型、音频或特效。

但要注意：用户上传的自定义云端资源在外网公开测试环境和线上生产环境是互相独立的。外网上传过的自定义模型、粒子、音频或材质，不会因为项目迁移到线上就自动出现在线上环境。

如果项目大量使用自定义云端资源，并且准备从外网迁移到线上，应提前找官方人员协助同步两个环境的自定义资源。少量资源可以按当前编辑器能力在目标环境重新上传；大量资源不要等到线上发布当天逐个补。

项目资源的优点是自洽。项目内的模型、粒子、音频、材质等会随项目发布，项目无论在外网还是线上环境都能正常跑，不会因为目标环境缺少自定义云资源而丢模型或特效。代价是多个项目中的同一资源无法只下载一次。

官方资源已经在外网和线上同步，通常不用担心官方模型、官方特效、官方音频的环境迁移问题。如果官方资源发布后缺失，更常见原因是资源路径没有进入发布资源引用清单，应该按 发布资源缺失排查指南 检查 Client-Resource、ref/objref.txt 和 ref/full.ref。

迁移时如何选择资源放置方式 ​

优先选择云端资源的情况：

  • 同一批资源会被多个项目复用。
  • 资源体积较大，玩家跨游戏下载缓存复用很重要。
  • 已经确认目标线上环境有对应自定义云端资源，或已经安排官方同步。

优先选择项目资源的情况：

  • 资源只服务于当前项目。
  • 项目要从外网迁移到线上，且希望迁移链路尽量自洽。
  • 活动、测试、演示项目需要保证“不依赖目标环境提前存在某个自定义云资源”。
  • 资源数量不大，重复下载成本低于环境同步成本。

项目资源的目录和代码路径规则见 项目资源路径指南。发布后缺模型、粒子或音频时，继续看 发布资源缺失排查指南。

相关文档 ​