星火 2.0 开发文档

主题

游戏架构路线、SCE 场景空间模型与 Canvas/GameGraph 边界 ​

先确定想完成的玩法，以及项目已经有哪些可复用内容，再为具体功能选择能力。WasiCore 不应只按“2D 游戏 / 3D 游戏”选择技术路线；玩法机制、显示方式、联网需求和空间模型需要分别判断。

熟悉暴雪地图编辑器、星火 1.0 或 Unity / Urho 的读者，可以先看理解星火迁移已有经验。零基础用户可以直接走快速开始，不需要先完成架构选型课程。已有项目需要访问底层对象时，查GameCore 与 GameGraph 桥接。

按功能选择，按经验解释 ​

用户经验决定如何解释，游戏需求决定采用什么实现。现成系统适合时可以构成完整玩法；缺少某项能力时可以局部扩展；不适合的功能也可以直接用 Node 与组件组织。一个新需求不自动要求为整个项目重新选路线。

判断对实现的影响
是否能直接复用单位、技能、物品、视野或 AI 机制评估高层系统能节省多少工作，以及默认机制是否适合
已有实现是否满足主体玩法优先保留合适的部分，局部增加表现、物理或自定义状态
需要什么权威和同步客户端视觉效果、本地游戏与服务端权威状态分别设计
用户以后要如何修改内容保留所需的数据、触发器或代码入口，不能因为 AI 写代码方便就放弃图形化编辑
是否反复绕过框架默认行为比较局部定制与直接 GameGraph 的成本，不强求套入 Unit

“有血量”“有角色模型”“需要联机”单独出现，都不足以要求使用 Unit。架构规则按能力需求组织，类型示例不是游戏类型白名单。

三条主路线 ​

路线主要入口适合不自动提供
SCE 场景 + Unit/技能系统GameCore / GameData / Unit / Ability / Scene角色、怪物、技能、Buff、AI、视野、属性、服务端权威联机游戏不等于必须是真 3D 体积场景
直接 GameGraph SceneGraphSceneGraph / Node / RigidBody / CollisionShape直接构造 3D 场景、机关、物理对象、沙盒、工具预览、非 Unit 服务端权威物理Unit/Ability/Buff/AI 等框架单位能力
Canvas / GameUI 绘制Canvas / CanvasAnimated / GameUI 控件全屏绘制型游戏、卡牌、棋盘、弹球、HUD、小地图、2D 表现层服务端同步、SCE 场景、Unit 系统

这些路线可以混用。一个项目可以同时有 SCE 场景、Unit、GameGraph Node、Canvas HUD 和普通 GameUI 控件。

SCE 场景空间模型 ​

SCE 场景的 GameDataScene.SpaceModel 是 服务端寻路、单位高度和碰撞语义，不是渲染维度开关。

SpaceModel推荐称呼语义
Surface2D2.5D 单层地表场景可以渲染 3D 地形、模型、粒子和光照，也存在 Z 坐标；但服务端单位寻路和投射物碰撞不区分同一 XY 的多层高度。桥上/桥下都可独立行走、空中平台等多层地表不属于该模型。
Volumetric3D真 3D 多层空间需要生成 3D 场景产物，支持同一 XY 多层可走面、3D 导航和 3D 场景碰撞。角色控制器可选择 3D 寻路模式，也可选择物理 motor 模式实现重力、台阶和跳跃。

Surface2D 里的“跳跃”类技能通常是技能/移动器表现出的位移效果，不等同于物理 motor 在真 3D 空间里受重力和碰撞约束的跳跃。

什么时候用 SCE Unit 系统 ​

优先使用 SCE 场景 + Unit/技能系统，当需求包含：

  • 玩家角色、怪物、召唤物、建筑或可被技能选中的单位。
  • 生命值、属性、Buff、技能、冷却、AI、目标过滤、命令队列、视野或阵营关系。
  • 服务端权威创建和同步 Unit。
  • 想让编辑器的数据系统、触发器和技能配置承担主要玩法工作。

在这条路线里再选择空间模型：

  • 画面是 3D，但玩法是单层地表：通常用 Surface2D。
  • 需要桥上桥下、上下楼层、多层平台、3D 导航或物理角色跳跃：用 Volumetric3D，并生成 3D 场景产物。

什么时候直接用 GameGraph ​

用户要做 3D 游戏时，不一定要使用 SCE 场景和 Unit/技能系统。可以直接用 GameGraph API 构造 SceneGraph 和 Node，开发体验接近通用 3D 引擎：

  • 客户端本地 3D 原型、模型/材质 probe、工具预览：用客户端 local SceneGraph。
  • 非 Unit 的服务端权威物理对象：服务端创建 replicated SceneGraph / Node，用 Publish(player) 同步给指定玩家。
  • 服务端权威物理对象的碰撞和 transform 同步：服务端 local RigidBody 推进，replicated Node 同步 transform，客户端挂 local mesh/material/effect 表现。

直接创建 GameGraph 节点不会自动获得 Unit/Ability/Buff/AI 等高层玩法机制。后续需要这些机制时，比较接入现成系统和保留自定义实现的成本；可以局部组合，不必把所有对象重建成 Unit。

SCE Unit 也可以下钻到 Node 级别：通过 unit.GetNode()、scene.GetSceneGraph()、scene.GetSyncRoot() 等 API 使用 GameGraph 的底层能力。

什么时候用 Canvas / CanvasAnimated ​

Canvas 是 GameUI 中的客户端即时绘制控件，适合“画面由脚本每帧绘制”的游戏或表现层。

Canvas-only 游戏通常可以不加载任何 SCE 场景：

csharp
_ = new GameDataGameMode(MyLinks.CanvasMode)
{
    SceneList = [],
    DefaultScene = null,
};

CanvasAnimated 适合动画、相机、简单物理和游戏循环；普通 UI 面板、按钮、列表和弹窗仍优先用 GameUI 控件。Canvas 也常用于 SCE Unit 游戏的 HUD、小地图、技能指示、调试 overlay。

Canvas 绘制本身是客户端表现。若 Canvas 游戏需要联机同步，应使用 GameCore 状态、PropertyObject、TypedMessage 或混合同步方案，而不是假设 Canvas 会同步状态。

AI Agent 路由规则 ​

AI 按当前功能和已有项目选型；对零基础用户先推进一个可玩的最小目标，按需要解释概念。只有涉及玩法效果、联网、性能或未来编辑方式等实际取舍时，才需要用户参与技术方向选择。多人/单机、可编辑性等关键假设必须说明，不能静默收窄用户需求。

用户说法先判断推荐阅读
“做一个 3D RPG/ARPG/生存/塔防，有角色和技能”是否需要 Unit、技能、AI、生命值3d-unit-game，再读 3DSceneSetup.md
“做一个 3D 物理小游戏/沙盒/模型预览，不需要单位技能系统”是否需要服务端权威单机/本地读 client-scenegraph-game；服务端权威读 server-authoritative-3d-physics
“画一个 2D 游戏/卡牌/棋盘/弹球”是否主要用 Canvas 绘制canvas-2d-game；移动端再读 canvas-mobile-performance
“画面是 3D，要不要改 Volumetric3D”是否需要同一 XY 多层可走面或物理角色需要才用 Volumetric3D；否则保留 Surface2D
“Canvas 游戏要不要场景”是否需要地形、单位、场景资源或 SceneGraph不需要时 SceneList = []、DefaultScene = null

禁止误导性归类 ​

  • 不要把 Surface2D 解释成无 Z 轴、无 3D 渲染的 2D 场景。
  • 不要把“3D 游戏”自动等同于 SCE Unit/技能系统。
  • 不要把“2D 游戏”自动等同于没有 Unit、没有服务端或没有 GameUI 控件。
  • 不要因为项目使用 Canvas HUD，就判断它是 Canvas-only 游戏。
  • 不要因为项目使用 GameGraph Node，就判断它不能使用 SCE Unit 系统。

相关文档 ​