Add a retained 2D or 3D viewport without giving up Fission layout, actions,
semantics, or testing. Add the game runtime for fixed-step simulation,
snapshots, or replay. Add a physics provider only if the game needs it.
These APIs are alpha. The workflows below work, but public details may
change between alpha releases. Pin prerelease crates exactly and read the
migration notes before updating.
Run fission features to see the opt-in scene, game, asset, and physics
features together with their current API status. Passing one of these features
through the CLI also prints an alpha-compatibility notice.
Choose the smallest capability
| | |
|---|
Retained sprites, paths, text, picking, and batching | | |
Retained meshes, materials, lights, glTF, and picking | | |
Deterministic fixed-step state, input, snapshots, and replay | | |
Provider-neutral physics contracts | | |
| | fission::physics_rapier2d |
| | fission::physics_rapier3d |
For a 2D game with optional Rapier physics, enable the facade features:
[dependencies]
fission = { version = "0.16.0", features = [
"desktop",
"game",
"scene2d",
"physics-rapier2d",
] }
The facade already pins its alpha crates exactly. If you depend on those crates
directly instead, use exact prerelease requirements:
fission-scene = "=0.1.0-alpha.1"
fission-scene2d = "=0.1.0-alpha.1"
fission-game = "=0.1.0-alpha.1"
fission-physics = "=0.1.0-alpha.1"
fission-physics-rapier2d = "=0.1.0-alpha.1"
Use scene3d and physics-rapier3d for the corresponding 3D stack. Rapier is
not in the dependency graph unless its provider feature is enabled, and the 2D
and 3D providers are independently selectable.
Build a retained scene
Your app owns a serialisable scene value. The processor validates it and
prepares draw, culling, diagnostics, bounds, and picking results. The scene
does not contain renderer handles or backend types.
The following projection makes one model boundary concrete: a
warehouse zone is a rectangle with an app-owned identity, geometry, and fill.
It is a decorative scene node until the app supplies interaction metadata.
use fission::prelude::*;
use fission::scene2d::*;
fn zone_scene(
scene_id: SceneId,
zone_id: NodeId,
viewport: Viewport2D,
rect: Rect2D,
fill: Rgba,
) -> Scene2DIR {
let mut scene = Scene2DIR::new(scene_id, viewport);
let mut zone = Node2D::group(zone_id);
zone.content = NodeContent2D::Rectangle {
rect,
style: PathStyle2D {
fill: Some(Fill2D { color: fill }),
stroke: None,
},
corner_radius: 0.0,
};
scene.nodes.push(zone);
scene
}
fission_component! {
pub ZonePreview<()> {
props { scene: Scene2DIR }
}
view(preview, _state, _cx) => Scene2D(preview.scene.clone())
}
The parent derives those inputs from its actual zone model. zone_scene
returns scene data rather than a hidden widget tree; ZonePreview supplies
the Compose component boundary. Its viewport dimensions come from the scene.
Do not encode selection or inventory solely as fill colour—provide a semantic
control and textual status for operations that matter to the user.
Scene3DIR follows the same model. A 3D scene can contain cubes, spheres,
application-provided triangle meshes, and static glTF or GLB models. It also
supports unlit or basic metallic-roughness materials, textures, alpha policy,
depth, and ambient, directional, or point lights.
Each scene widget defaults its stable PresentationId to the scene ID. When
the same scene is visible in more than one viewport, assign a distinct
.presentation_id(...) to each widget so retained identity and interaction
coordinates remain independent.
Drive state with one deterministic clock
Implement Game for the authoritative simulation state. react handles typed
messages, step advances one fixed simulation step, and present derives the
scene. Rendering and physics remain projections of that state.
This implementation excerpt assumes the app defines MyGame, GameMessage,
and the three domain methods below. MyGame must also implement GameState;
the complete public-API examples later in the guide supply that runnable
simulation, rather than leaving those functions as invented no-ops.
use fission::game::*;
impl Game for MyGame {
type Message = GameMessage;
type Presentation = Scene2DIR;
fn input(map: &mut InputMap<Self::Message>) {
map.on(InputTrigger::KeyPressed { key: GameKey::ArrowLeft })
.send(GameMessage::MoveLeft);
}
fn react(&mut self, message: Self::Message, _ctx: &mut GameCtx<'_, Self>) {
self.pending.push(message);
}
fn step(&mut self, ctx: &mut StepCtx<'_, Self>) {
self.simulate(ctx.duration());
}
fn present(&self, _time: GameTime) -> Self::Presentation {
self.scene()
}
}
GameRuntime accepts elapsed presentation time and advances state in fixed
steps. Use GameTestHarness to control ticks and semantic input without a
window. Versioned snapshots preserve supported state, clock, input, and
random-stream data. Replay records ordered input and rejects unsupported
formats. GameInputRegion sends focused key-down and key-up transitions
through the same reducer action, so held movement remains visible across ticks.
Connect interaction and accessibility
2D nodes can declare tap, long-press, and drag start, update, end, and cancel
actions. The scene widget converts viewport coordinates to scene coordinates
and includes stable scene, node, and batch-instance identities in the normal
Fission action input. Decorative nodes do not receive pointer events.
For 3D, give Scene3D an on_pick action. It receives coordinates relative to
the scene's declared viewport, even when layout resizes the surface. Call
PreparedScene3D::pick_viewport to find the stable node. Also provide a
semantic action for every important operation so keyboard users, assistive
technology, and semantic tests do not depend on ray selection.
Add physics without binding game state to Rapier
Create bodies with stable PhysicsBodyId values and Fission shapes, poses, and
velocities. Put the implementation behind PhysicsProvider2D or
PhysicsProvider3D. Game state, queries, events, and snapshots then stay free
of Rapier handles, and another provider can implement the same contract.
The providers support fixed, kinematic, and dynamic bodies, collision and
trigger transitions, ray and overlap queries, forces, impulses, and snapshot
restore. The 3D provider also exposes the MVP kinematic character controller.
Assets and diagnostics
Give assets stable typed IDs and put them in a versioned AssetBundle. Record
the source and digest used to build it. Call fission_assets::verify_sha256
from build.rs with the packaged bytes; this catches stale bundle metadata
when an asset changes. The qualification games use this pattern and pass the
verified digest into their scene declarations. 2D scenes retain decoded images
and batch instances. GltfImporter imports static glTF or GLB meshes,
referenced textures, and the metallic-roughness values supported by the
renderer.
Add the verifier as an exact build dependency; it does not enter the runtime
dependency graph:
[build-dependencies]
fission-assets = "=0.1.0-alpha.1"
Loading, ready, and failed states are explicit. If a transform, geometry,
camera, material, asset, or renderer capability is invalid, scene preparation
returns a diagnostic instead of silently showing a blank viewport.
Run the complete examples
The repository contains two small games that use only public APIs:
fission run --target web --project-dir examples/scene2d-qualification
fission run --target web --project-dir examples/scene3d-qualification
Use linux, macos, or windows for the other initially qualified targets.
The examples include their public assets and provenance, complete objectives,
physics, picking, snapshots, and replay tests.
Each example contains ignored native_live and web_live qualification tests.
The native test launches the real desktop shell on Linux, macOS, or Windows;
the Web test connects to a running build in Chrome. Together they drive
coordinate and keyboard input, finish the games, capture the rendered scene,
and reject a blank or compatibility-only viewport. See each example README for
the exact commands and graphical-session requirements.
Current alpha boundary
The first alpha deliberately omits audio, skeletal animation and blending,
advanced gamepad setup, custom shaders, shadows, post-processing, multiplayer,
advanced asset streaming, and editor tooling. Android and iOS compile with the
scene APIs but are not advertised game targets until real-device rendering,
input, and lifecycle qualification is complete.