WasiCore Game Architecture Routing

Use this skill when choosing an implementation for a game or feature, explaining Spark's object model, or extending an existing project across GameCore and GameGraph. Routine edits within an established approach do not require repeating architecture selection.

Start From The Desired Game

Help the user build the game they want. Their prior experience determines how to explain the implementation, not which architecture they must use. Choose capabilities per feature; a project can combine integrated gameplay, custom nodes, and UI without changing its overall structure.

• For beginners, start with a small playable objective. Do not require them to learn Unit/Actor/Node or choose a framework before proceeding. Ask about observable gameplay when information is missing, rather than asking them to make routine technical choices.
• For Blizzard map-editor or Spark 1.0 users, connect scene editing, data definitions, and trigger events to their existing experience. Keep suitable graphical data and triggers editable; using AI or GameGraph does not require rewriting them into handwritten C#.
• For Unity/Urho users, explain scene graphs, nodes, components, and the integrated gameplay systems they can reuse. These are conceptual mappings, not API or lifecycle compatibility promises.
• For users delegating implementation to AI, choose a suitable approach and explain tradeoffs that affect gameplay, networking, performance, or future editing. State material assumptions; do not silently assume single-player, code-only authoring, or a closed set of supported game types.

Evaluate the existing project and the requested feature: which integrated mechanisms genuinely help, which behavior needs custom implementation, and where authority, synchronization, and cleanup belong. An existing approach that fits should be preserved. A local extension does not justify rebuilding the project; repeated workarounds for unsuitable defaults can justify a different implementation for that feature.

Read only the reference needed for the task. Paths below are relative to this skill in the SDK; in a generated project, find them under docs/sdk/guides/ or docs/sdk/systems/ if the skill copy's relative link is unavailable.

• Understanding Spark: optional conceptual introduction for experienced developers; not a beginner prerequisite.
• Architecture routes: gameplay fit, rendering, SpaceModel, and networking decisions.
• GameCore / GameGraph bridge: exact Unit/Actor/Scene node access, component lookup, authority, and lifetime.

Do Not Classify By Visual Dimension

WasiCore has three common architecture routes:

Route	Use When	Main Skills
SCE scene + Unit/Ability system	Units, skills, HP, Buff, AI, orders, targeting, scene vision, server-authoritative Unit gameplay	3d-unit-game, data-editor, trigger-editor-mcp
Direct GameGraph SceneGraph	Code-created SceneGraph / Node gameplay, local 3D preview, scene-space 2D/Spine presentation, non-Unit physics objects, engine-like 3D development	client-scenegraph-game, server-authoritative-3d-physics, gamegraph-materials
Canvas / GameUI drawing	Full-screen drawn games, board/card/arcade UI, HUD/minimap/debug overlays, CanvasAnimated game loops	canvas-2d-game, canvas-mobile-performance, ui-layout-api

These routes can be mixed. A SCE Unit game can use Canvas HUD and GameGraph nodes. A direct GameGraph game can use GameUI controls. A Canvas game can still use GameCore state when it needs multiplayer.

GameGraph primarily exports and wraps commonly used gameplay APIs from Spark's Urho engine as C# interfaces, adding Spark-specific capabilities and bridges to GameCore Unit, Actor, and Scene systems. Use existing Urho knowledge to find implementation approaches, then verify types, signatures, and client/server availability in the current SDK's api/client / api/server declarations. Consult Spark topic documentation for extensions and behavior differences; GameGraph is not a complete one-to-one Urho binding.

This applies to direct Node development and low-level extensions inside existing Unit projects, on either side where the API is available. The shared reference is GameGraph overview, under its Urho compatibility section, including coordinates, resource/rendering boundaries, and particle/animation differences. Choose a specialized skill according to the feature's client/server responsibilities.

SCE Scene SpaceModel

GameDataScene.SpaceModel is pathfinding, Unit height, and collision semantics. It is not a rendering-dimension switch.

Value	Meaning
Surface2D	2.5D single-surface navigation. The scene can still render 3D terrain, models, particles, lights, slopes, platforms, and Z coordinates. Server Unit pathfinding and projectile collision do not distinguish multiple height layers at the same XY.
Volumetric3D	True 3D multi-layer space. Use when gameplay needs bridge-over-bridge, tunnels, stacked platforms, 3D navigation, or physical character motor movement. Requires generated 3D scene products.

Do not switch to Volumetric3D just because the camera and assets look 3D. Switch when gameplay needs multi-layer movement/collision semantics or physical character motor behavior.

Route Selection

When the feature benefits from integrated unit identity, abilities, Buffs, orders, targeting, AI, vision, or server-authoritative Unit behavior, evaluate the SCE Unit route and read 3d-unit-game. A health value, character model, or networking requirement alone does not require Unit. For example, durability on an existing GameGraph physics object may remain lightweight business state. Despite its legacy name, 3d-unit-game covers Unit-system gameplay; its SCE scene may be Surface2D when gameplay is single-surface.

If the user wants to build a 3D game by directly creating scene nodes and physics bodies, and does not need the Unit/Ability framework, use direct GameGraph. For local single-player or preview work, read client-scenegraph-game. For multiplayer/server-authoritative non-Unit physics, read server-authoritative-3d-physics.

If the user wants to display Spine, Spriter, or a 2D animated character inside a 3D scene, use direct GameGraph AnimatedSprite2D for the presentation layer and read client-scenegraph-game plus docs/systems/GameGraph2DAnimation.md. Use GameUI Spine only for UI-layer Spine, and use Canvas/AnimatedImageSource when the whole gameplay view is drawn in a Canvas render loop.

If the user wants a full-screen drawn game, card/board game, UI-heavy arcade game, or CanvasAnimated loop, use Canvas. Read canvas-2d-game. For Canvas-only game modes, do not load a default SCE scene unless needed:

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

Canvas is client rendering. Multiplayer Canvas games still need GameCore state, PropertyObject, TypedMessage, or another explicit sync route.

Common Corrections

• "2D game" alone does not choose Canvas, Unit, or GameGraph; inspect gameplay and presentation needs. It does not imply SceneSpaceModel.Surface2D.
• Surface2D does not mean no Z axis and does not mean non-3D rendering.
• "3D game" does not automatically mean SCE Unit/Ability. Direct GameGraph is valid.
• "Spine in 3D scene" does not mean UI Spine, Canvas, or render-to-texture by default; use AnimatedSprite2D when it should participate in scene camera/depth behavior.
• "3D Unit game" does not automatically require Volumetric3D; use Surface2D for single-surface 3D-looking maps.
• A jump-like ability in Surface2D is usually mover/skill displacement, not true physical jumping in volumetric space.
• SCE Unit games can use low-level GameGraph APIs via unit.GetNode() and scene SceneGraph access.

Bridge Existing Objects Deliberately

Before generating bridge code, read the bridge reference and verify the exact receiver, overload, and available side in the current SDK API:

• Unit and Entity implement IActorAnimationPlayable; use their animation bridge methods directly. Do not invent unit.GetActor() or cast Unit to ActorModel.
• Client unit.GetNode() prefers the visual node and falls back to an existing default binding. Server unit.GetNode() can create the default binding. Use a role/key lookup or GetNodeBinding() for explicit binding queries.
• IActor.TryGetClientVisualNode(...) is client-only and never means a server-authoritative binding node.
• Use scene.GetSceneGraph() for an existing SCE scene. new SceneGraph(...) creates an independent graph, not access to the current map. Framework-owned graphs must not be disposed or manually published as if script-owned.
• Query components on the intended node; prefab components may be on children. A recursive first match does not identify every model or guarantee that independently found components belong together.
• Identify who writes transforms and animation state, how multiplayer state reaches clients, and who owns cleanup. Retrieving a node does not transfer control or ownership.

Judge the result by playable behavior and maintainable editing, not by whether the project showcases both layers. Examples: a map-editor user's physics sandbox may use direct GameGraph; a Unity user's RPG may benefit from Unit/Ability/Item; adding a bone effect to an existing Unit game should usually be a local client extension.

Next Skill

After this routing step, load only the relevant specialized skill:

• wasicore-game-scaffold for choosing a starting template.
• 3d-unit-game for Unit/Ability/AI/HP gameplay.
• client-scenegraph-game for local direct SceneGraph games and previews.
• server-authoritative-3d-physics for non-Unit server physics and replicated nodes.
• canvas-2d-game for Canvas / CanvasAnimated gameplay.
• multiplayer-hybrid-sync when Canvas or non-Unit state must sync across players.