A cross-platform 3D game engine in Rust — one codebase for desktop, the web, Android and iOS, with testing built in from the first line.
Space3d is a small, modular engine built on wgpu and
winit: an ECS (hecs) with a deterministic fixed
tick, a GPU-driven renderer that draws a million instances in a handful of draw calls, async
assets/networking/database access that never blocks a frame, and a test harness where input
simulation and golden screenshots are ordinary cargo tests. The space3d CLI scaffolds a
game, builds it for every platform, serves the web build, runs the storybook and publishes
releases to GitHub.
use space3d::prelude::*;
struct Spin;
fn build(app: &mut App) {
app.add_plugin(DefaultPlugins::new().title("Hello cube"));
app.add_system(Stage::Startup, |ctx| {
let cube = ctx.resources.expect_mut::<RenderAssets>().add_mesh(MeshData::cube(1.0));
ctx.world.spawn((Transform::default(), Mesh3d(cube), Material::srgb(0.9, 0.4, 0.2), Spin));
ctx.world.spawn((Transform::default().looking_at(Vec3::new(-0.4, -1.0, -0.3), Vec3::Y), DirectionalLight::default()));
ctx.world.spawn((Transform::from_xyz(0.0, 1.5, 4.0).looking_at(Vec3::ZERO, Vec3::Y), Camera3d::default()));
});
app.add_system(Stage::FixedUpdate, |ctx| {
let dt = ctx.time().fixed_delta.as_secs_f32();
for (t, _) in ctx.world.query_mut::<(&mut Transform, &Spin)>() {
t.rotation *= Quat::from_rotation_y(dt);
}
});
}
// `fn main` on desktop, `#[wasm_bindgen(start)]` on the web,
// `android_main` on Android, `extern "C" start_app` on iOS.
space3d::main!(build);- Everything is a plugin.
DefaultPlugins/MinimalPluginsgroups; every engine crate is optional behind a cargo feature of thespace3dfacade. - Deterministic simulation.
Stage::FixedUpdateruns at a fixedTickRate(60 Hz by default), decoupled from the frame rate; tests drive time withApp::step_ticks(n). - Renderer (wgpu 30). Metallic/roughness lighting, directional + point lights, textures,
render-to-texture, MSAA; automatic instancing of ECS entities and explicit
InstanceBuffer<T>s for 1M+ instances; GPU frustum culling + (multi-)indirect draws with a CPU fallback (WebGL2); dirty-range uploads through a staging belt; headless rendering and capture. - Graphics. HDR with AgX/ACES/Khronos tonemapping, bloom, auto exposure, color grading and
LUTs, FXAA, lens effects, screen-space distortion; normal, ORM and emissive maps lit straight
from glTF, every blend mode; cubemap skyboxes with image-based lighting; a shadow-casting sun;
100k GPU particles with ribbons, beams, flipbooks and a built-in effect library; render nodes
and HDR overlay stages for custom effects;
GraphicsQualitypresets from WebGL2 to Ultra (below). - Never block the frame. I/O runs on
space3d_tasks(tokio natively,wasm-bindgen-futureson the web); CPU work on a compute pool; systems only pollTasks or registerAsyncQueuecallbacks. - Assets. Async asset server with typed handles and hot reload; PNG/JPEG/WebP/…, glTF/GLB and OBJ; texture editing (resize, filters, brushes, flood fill, generators, undo/redo) and mesh editing (normals, weld, subdivide, extrude, UV projection, decimation, OBJ/glTF export).
- Networking. HTTP client and WebSocket client on every platform; HTTP/WebSocket servers (axum) natively; typed channels for replication.
- Persistence. SQLite on a worker thread (migrations, KV store, save slots with
thumbnails, leaderboards) with a
localStoragefallback on the web. - Physics, audio, scenes. rapier rigid bodies/colliders/raycasts on the fixed tick; kira audio with spatial emitters; RON/JSON scenes, prefabs and world snapshots.
- UI and tools. egui integration with a compact debug overlay (F3), profiler (F4) and
console; an opt-in compact density (
app.insert_resource(UiTheme::compact())); Chinese and Japanese line breaking (kinsoku, plus no break before a no-break space or after an opening bracket) in egui's text layout (both in docs/ui.md); scene inspector, texture and model editors; a storybook for isolated, parameterized scenes. - Testing. Headless
TestApp, tick-accurate keyboard/mouse/touch/gamepad simulation and recorded input scripts, golden screenshots with diff images and an HTML report, determinism and performance assertions. GPU tests skip when there is no adapter. - Shipping.
space3dCLI for desktop, web (wasm-bindgen), Android (cargo-apk) and iOS (Xcode via XcodeGen) builds, a local web server with cross-origin isolation, GitHub Actions generation and GitHub releases; in-game update checker and opt-in crash reporter.
┌──────────────────────────── your game ─────────────────────────────┐
│ build(app) · GamePlugin · systems · stories · tests │
└───────────────┬──────────────────────────────────────┬─────────────┘
│ space3d::prelude / space3d::main! │ space3d::test
┌─────────────── space3d (facade: features, DefaultPlugins, MinimalPlugins, entry points) ─────┐
│ │
│ platform ── winit runner (desktop · web canvas · Android NativeActivity · iOS UIKit), Input │
│ │ │
│ render ──── wgpu: mesh arena · PBR maps · lights · IBL · shadows · HDR · post · nodes │
│ particles ─ GPU/CPU effects: sprites · ribbons · beams · built-in library │
│ ui ──────── egui overlay · debug overlay · profiler · console editor ── inspectors │
│ assets ──── asset server · loaders · hot reload · texture/mesh editing │
│ physics (rapier) · audio (kira) · scene (RON) · net (HTTP/WS) · db (SQLite/localStorage) │
│ stories ─── storybook, gallery test ── TestApp, input sim, goldens github ── CI │
│ │
│ tasks ───── spawn / spawn_compute / Task::poll / AsyncQueue (tokio · rayon · wasm futures) │
│ core ────── App · Plugin · ECS (hecs) · Resources · Events · Stages · TickRate · Transform │
└───────────────────────────────────────────────────────────────────────────────────────────────┘
Frame: Startup (once) → PreUpdate (task completions, input, network inbox)
→ FixedUpdate × N (deterministic simulation, physics) → Update → PostUpdate (transforms)
→ Render → Last (event buffers, cleanup)
| crate | role |
|---|---|
space3d |
facade: feature-gated re-exports, plugin groups, prelude, main! |
space3d-core |
App, Plugin, ECS, resources, events, stages, fixed tick, Transform |
space3d-tasks |
async runtime bridge, Task, AsyncQueue |
space3d-render |
wgpu renderer (architecture, graphics) |
space3d-particles |
particle effects drawn as a render node (docs) |
space3d-platform |
winit runner for all platforms, input, action maps |
space3d-assets |
asset server, loaders, hot reload, editing ops |
space3d-net |
HTTP/WebSocket clients and servers |
space3d-db |
SQLite / localStorage stores |
space3d-physics |
rapier integration |
space3d-audio |
kira integration |
space3d-scene |
scenes, prefabs, snapshots |
space3d-ui |
egui integration, debug tools |
space3d-editor |
scene inspector, texture and model editors |
space3d-stories |
storybook |
space3d-test |
test harness |
space3d-github |
GitHub REST, update checker, crash reporter, CI templates |
space3d-cli |
the space3d command |
The renderer draws a top-down space battle with every effect a space game needs — and nothing
changes until a game asks: a camera without PostProcess renders exactly as before.
use space3d::particles::prelude::*;
use space3d::prelude::*;
ctx.world.spawn((
Transform::from_xyz(0.0, 400.0, 150.0).looking_at(Vec3::ZERO, Vec3::Y),
Camera3d::default(),
PostProcess::default().with_tonemapper(Tonemapper::AgXPunchy).with_exposure(0.5), // HDR + bloom
Skybox::new(nebula), // a cubemap behind everything …
EnvironmentLight::new(nebula), // … that also lights the hulls
));
ctx.world.spawn((sun_transform, DirectionalLight::default(), DirectionalShadow::default()));
let ship = space3d::assets::render::spawn_model(ctx.world, &hull, transform); // glTF maps as authored
ctx.spawn_effect(builtin::EXPLOSION, EffectSpawn::at(p)); // one call: fireball, debris, flash, shockwave
GraphicsQuality::recommended_for(renderer).apply(ctx.world, ctx.resources); // Low on WebGL2| feature | what you get |
|---|---|
| HDR, tonemapping, exposure | PostProcess on a camera: linear HDR scene, AgX / AgX punchy / ACES / Khronos PBR Neutral / Reinhard, manual or histogram auto exposure |
| bloom | position-stable, energy-proportional, resolution-independent; emissive, particles and HDR skies glow |
| post chain | color grading (white balance, lift/gamma/gain, 3D LUTs, WGSL hooks), FXAA, vignette, chromatic aberration, film grain |
| distortion | heat haze and shockwaves from particles, DistortionMaterial meshes and render nodes |
| materials | normal, ORM, metallic-roughness, occlusion and emissive maps; opaque, alpha-mask, alpha, premultiplied and additive blending; GGX shading |
| glTF | every material slot straight from the file, sRGB/linear by slot, texCoord sets, texture transforms, MikkTSpace tangents |
| sky and IBL | cubemaps from faces, three.js faces or panoramas (LDR/HDR); Skybox; diffuse + GGX-prefiltered specular baked on the GPU |
| shadows | one directional shadow, fitted to a top-down camera, PCF 1–16 taps |
| particles | GPU simulation (CPU on WebGL2), 100k+, sprites, ribbons, beams, flipbooks, soft particles, light flashes, sorting, LOD; 14 built-in space effects |
| extension | render nodes (compute + draws in the frame's passes), HDR overlay stages, custom WGSL |
| quality | GraphicsQuality::{Low, Medium, High, Ultra} for every knob; recommended per device; prewarm plans |
| WebGL2 | every feature has a path (Ldr fallback, CPU particles, CPU culling) |
The Battle reference scene (300 ships with PBR maps, 100k particles, IBL, shadows, bloom, MSAA)
costs about 1.5 ms of GPU and 1.45 ms of CPU per 1080p frame on an Apple M4 Max.
Overview and how-tos: docs/graphics.md · adopting it in a game:
docs/graphics/migration.md · try it:
cargo run -p graphics_showcase --release.
# install the CLI from this repository
cargo install --path crates/space3d-cli
space3d new my_game --template 3d # basic | 3d | multiplayer
cd my_game
space3d run # desktop
space3d serve # web: builds wasm, serves http://localhost:8080
space3d test # input-simulation + screenshot tests
space3d stories # storybook viewer
space3d editor # editor with the game scene loaded
space3d doctor # what is missing for web / Android / iOS, and how to fix itspace3d new depends on Space3d via git by default; --space3d-path ../Space3d uses a local
checkout. The generated project contains the game library (build + GamePlugin), the
desktop/web entry point, a storybook binary, tests, web/index.html, a mobile/ crate for
Android and iOS, and a GitHub Actions workflow. See docs/getting-started.md.
Other commands: space3d build --target desktop|web|android|ios [--release],
space3d publish --tag v1.0.0 [--dry-run], space3d ci init --targets desktop,web,android,ios,
space3d editor, space3d bench. Every command takes --dry-run to print what it would run.
| Windows | macOS | Linux | Web | Android | iOS | |
|---|---|---|---|---|---|---|
| graphics backend | DX12 / Vulkan | Metal | Vulkan / GLES | WebGPU / WebGL2 | Vulkan / GLES | Metal |
| typical draw path | GPU multi-draw-count | GPU multi-draw | GPU multi-draw-count | GPU indirect / CPU | GPU / CPU | GPU multi-draw |
entry point (main!) |
fn main |
fn main |
fn main |
#[wasm_bindgen(start)] |
android_main |
start_app() |
| build | space3d build |
space3d build |
space3d build |
space3d build -t web |
space3d build -t android |
space3d build -t ios |
| input | keyboard, mouse | keyboard, mouse | keyboard, mouse | keyboard, mouse, touch | touch | touch |
| audio | ✓ | ✓ | ✓ | ✓ (after a user gesture) | ✓ | ✓ |
| database | SQLite | SQLite | SQLite | localStorage (KV/saves) | SQLite | SQLite |
| HTTP / WebSocket client | ✓ | ✓ | ✓ | ✓ (fetch / WebSocket) | ✓ | ✓ |
| HTTP / WebSocket server | ✓ | ✓ | ✓ | — | ✓ | ✓ |
| hot reload | ✓ | ✓ | ✓ | — | — | — |
Details and per-platform setup: docs/platforms.md.
Games test themselves with the same harness the engine uses:
use space3d::prelude::*;
use space3d::test::prelude::*;
#[test]
fn holding_right_moves_the_player() {
let mut app = TestApp::headless(320, 240); // no window; renderer only if a GPU exists
app.add_plugin(my_game::GamePlugin);
app.hold_key(KeyCode::ArrowRight, 30); // exactly 30 fixed ticks
assert!(app.translation(app.find_by_name("player").unwrap()).x > 1.0);
assert_screenshot!(&mut app, "moved_right"); // golden image in tests/__screenshots__/
}- The first run writes the golden PNG; later runs compare (tolerances, SSIM, per-backend
variants) and write
*.actual.png/*.diff.pngon failure. space3d testsetsSPACE3D_TEST_REPORTand prints a summary with links into an HTML report (expected / actual / diff side by side);space3d test --update-snapshotsre-blesses.- Without a GPU adapter, screenshot tests skip instead of failing (
SPACE3D_REQUIRE_GPU=1makes them fail); CI uses a software Vulkan driver (lavapipe) so they run there too. - Determinism (
assert_deterministic), frame budgets and allocation counts are assertions too.
More: docs/testing.md.
A story is an isolated, parameterized scene — a prop, a material, a level chunk, a UI panel — with knobs (floats, colors, choices, …). The same story is browsed interactively, rendered into a static gallery, and checked as a golden screenshot test:
space3d stories # viewer
space3d stories --headless --out target/stories # PNGs + index.html galleryspace3d::stories::storybook_tests!(my_game::stories::storybook); // one golden per storyMore: docs/storybook.md.
Numbers from the renderer design (ARCHITECTURE.md) and
the instancing_million example:
- 1,000,000 cubes, one draw. An explicit
InstanceBuffer<InstancePacked>stores each instance in 32 bytes (position, uniform scale, snorm16 quaternion, unorm8 color, layer) — 2.5× smaller than matrix + color — so a million instances are ~31 MiB of vertex data, culled on the GPU by a compute pass (64 instances per workgroup, compacted in-workgroup) and drawn with (multi-)indirect draws. - Upload only what changed. User buffers track dirty ranges (merged within 16 instances,
at most 64 ranges; >50 % dirty → one full copy). The example rewrites a 16,384-instance band
per frame and uploads 512 KiB instead of 31 MiB;
--staticuploads 0 bytes after the first frame. - Measured (
cargo run -p instancing_million --release, Apple M4 Max, Metal,GpuMultiDraw): 1,000,000 cubes = 12 M triangles in 1 indirect draw call, holding the display's 120 Hz vsync while uploading 512 KiB per frame (0 KiB with--static). - Static scenes cost nothing. Renderer-owned buffers keep a CPU shadow and upload only differing byte ranges: an unchanged scene with a still camera uploads 0 bytes per frame; moving one ECS entity uploads one 64-byte matrix.
- No per-frame staging allocations. All uploads go through a 4 MiB-chunk staging belt recycled after the GPU is done; copies ≥ 1 MiB are split across rayon workers.
- Automatic batching. Entities with equal mesh + material are sorted into one instanced draw,
so 1,000 identical-looking entities are one draw call even with separate
Materialvalues. - One mesh arena. All meshes share one vertex and one index buffer (36-byte vertices), so a GPU multi-draw covers many meshes without rebinding.
RenderStats (draw calls, instances, triangles, bytes uploaded, draw path, …) is a resource, and
the debug overlay (F3) shows it live. More: docs/performance.md.
| example | shows |
|---|---|
hello_cube |
window, lit rotating cube |
instancing_million |
1M instances, dirty-range uploads, stats overlay |
physics_playground |
rapier bodies, click/space to drop, raycasts |
multiplayer_chat |
WebSocket server + clients in one binary |
save_game |
SQLite save slots + key/value settings |
async_loading |
assets over HTTP + compute-pool meshes while the frame keeps ticking |
web_demo |
a browser-first scene built with space3d::main! |
graphics_showcase |
the Battle reference scene with every graphics feature, quality tiers, egui HUD, headless PNG, web |
pbr_showcase |
a glTF ship with PBR maps, skybox + IBL, a shadow-casting sun, every blend mode |
post_processing |
every post effect toggled with keys |
particles, particles_stress |
the particle library in a small battle; 100k+ particles |
cargo run -p hello_cube
cargo run -p instancing_million --release
SPACE3D_EXIT_AFTER_FRAMES=120 cargo run -p physics_playground # smoke test: quit after 120 frames
SPACE3D_HEADLESS=1 SPACE3D_EXIT_AFTER_FRAMES=60 cargo run -p hello_cube # no window at all
SPACE3D_HEADLESS=1 cargo run -p graphics_showcase --release # writes graphics_showcase.pngEvery dependency is pinned to its newest stable release (no alpha/beta/rc) in
[workspace.dependencies] of the root Cargo.toml; crates use foo.workspace = true. Before
adding a crate, check cargo search --limit 1 <crate>. (Example: winit stays on 0.30.x because
0.31 is still a beta.) One crate is patched: egui's epaint, vendored in third_party/ with
the kinsoku patch; an egui bump needs python3 scripts/update-epaint.py
(third_party/README.md).
Read AGENTS.md. In short: everything is a Plugin; never block the frame; the
simulation lives in FixedUpdate; runtime crates must build for wasm32-unknown-unknown; GPU
tests skip without an adapter; and
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspaceLicensed under the Apache License, Version 2.0. See NOTICE for the copyright line and the third-party code kept in this repository.
This covers the whole history: earlier revisions and other branches, some of which still carry the proprietary licence text from before the source was published, are offered under the Apache License 2.0 as well.
Unless you say otherwise, any contribution you submit for inclusion in Space3d is licensed under the same terms, without additional conditions.
