English | 简体中文
A compact, extensible, opinionated 3D renderer on wgpu, plus the ECS layer
built on top of it. It ships a built-in Lambert pipeline — simple
diffuse lighting from directional, point, spot and polygon lights — is
mobile-first, and runs on WebGPU as well as on the WebGL2 baseline. It uses
and exposes wgpu resources directly, allowing low-level control and
extension, with very little high-level CPU-side abstraction.
It targets developers and coding agents who know graphics rendering. Unlike mainstream engines aimed at a mass audience, it does not wrap things at a high level: you need WebGPU knowledge to use it well. It has few dependencies and compiles quickly.
The project is at an early stage of development. The APIs change freely; treat every crate as work in progress.
- Mobile-first, and cross-platform. Render passes are explicit — usually one, more when a frame composites — with transient depth and multisample textures, compressed vertices, and no pre-pass, compute shader or shadow path. The same frame loop drives a window, a headless offscreen target, the web examples and the Android APK.
- Runs on WebGL2 and on WebGPU-baseline devices. The adapter is picked at
runtime, WebGPU first and WebGL2 when that is all the platform has. WebGL2
lacks parts of the WebGPU baseline — no storage buffers, no
base_vertex— so the shader reads the frame's arrays throughtextureLoadand a mesh's vertex offset is baked into its indices; a device that has the baseline keeps the storage buffers and the whole-buffer bindings, which cost no extra pass state. Which path is taken follows the adapter's own downlevel capabilities, not a build feature. - A scene the caller composes. A frame is a sequence of passes, each an ordinary entity holding the views it draws into, and each pass records the frame sources below it, which contribute their own draws and state where in that pass they belong. The built-in mesh rendering, the egui overlay and a caller's own source have exactly the same standing.
- A small ECS. Borrowing OOP's focus on object state, an entity's archetype is immutable, systems are driven externally rather than built in, and a behaviour is a component holding a closure rather than a system — see unlit_ecs. A renderable entity carries its mesh, material and pipeline as components, so game logic and drawing share one model.
- A variant-driven lit pipeline. A shader variant contains exactly the channels a mesh uses — position, UV, vertex color, per-instance transform and color, base-color texture, skinning, morph targets — and is specialized for the frame's target.
- Lambert lighting, forward clustered. A lit draw and an unlit one are the
same variant with one flag set or cleared, over the same vertex streams and the
same mesh group. The clusters are built on the CPU, so the shader needs no
compute and WebGL2 runs the same path. No shadows. The mechanism is in
unlit_wgpu's lighting section. - Custom shaders and per-instance data. A caller's own family registers
through the same call as the built-in one, draws with its own pipeline — a
hand-written
wgpuone or a WESL module composed against the crate's public shader package — and owns its own per-instance vertex stream, described by the sameInstanceDatatrait the built-in lit family implements. - Optional glTF loading. The
unlit3dgltffeature loads a glTF 2.0 document into a plain record of the model — noWorld, no GPU state — and patches its images, materials and meshes into the resource graph of a world you already render, unloads them again, and spawns the entities that draw the document's default scene. Node hierarchies, skinned and morphed primitives, blended or cut-off materials, the document's animations — sampled at a time you choose — andKHR_draco_mesh_compressionprimitives, all come across. Cameras do not: the renderer draws with the world's ownCamera, so the caller places it. - Persistent, pooled GPU resources. Draws work with raw
wgpuresources; they live across frames, are rebuilt only when needed, and share and reuse the buffers uploads go through. - CPU frustum culling and auto instancing. Off-screen meshes cost nothing, and draws with matching state collapse into one instanced draw.
- egui and portable input. egui can be overlaid on the render or drawn into a texture of its own; input is unified and driven by OOP-style callbacks.
- Deterministic and snapshot-tested in CI. Rendering the same scene offscreen
produces the same frame every time. CI renders every example scene and compares
it against its stored image with SSIMULACRA2; see
TESTING.mdfor the two tiers of jobs. - Built-in MCP support. An MCP server can be embedded into an application, letting AI agents read and write components and take screenshots. The server carries no knowledge of the engine: every crate registers the tools that act on the types it defines.
| Crate | Role |
|---|---|
unlit_wgpu |
The lower-level renderer: resource graph, mesh compression, buffer pools, staging, the declarative Scene, the built-in lit pipeline, and an egui backend. Knows nothing about ECS. |
unlit3d |
The high-level rendering API: ECS components, frame sources, input, egui and winit presentation, plus an optional glTF loader that patches models into another world's MeshSource. |
unlit_ecs |
The small archetype ECS the high-level layer uses: no change detection, events, relations or scheduler. It also carries the MCP server that exposes a running world over stdio, which each crate extends with its own tools. |
unlit_wgpu_test_util |
The headless GPU test harness: device setup, buffer and texture readback, SSIMULACRA2 snapshots. |
unlit3d_examples |
A windowed example with selectable scenes, whose tests/gpu_suite.rs compares them against snapshots; it is also one of the two examples the Android APK packages. |
unlit3d_asset_bytes |
The models unlit3d_examples draws, carried in the binary: include_bytes! sits in an #[inline(never)] function body, so those bytes stay out of every dependent's metadata. |
unlit3dx_asset_bytes |
The soundfont unlit3dx_examples plays, carried the same way; its build.rs substitutes an empty stub when the file is absent, or fails where UNLIT3D_REQUIRE_SOUNDFONT demands the real one. |
unlit3d_cli |
A command-line tool that renders glTF documents to an image, driven by a JSON configuration file and overridden by its own options; its tests/gpu_cli.rs is the end-to-end snapshot check. |
unlit3dx |
The multi-world runtime: one-way jobs out, subscriptions back — snapshots for state, streams for events — joining a render sub-world with physics, audio and gameplay worlds, each on a thread of its own or stepped by the host's frames. |
xtask |
The repository task runner behind cargo xtask. |
unlit3d_benchmarks |
The frame-path benchmarks: Criterion throughput numbers and the phase timings the profiling scopes report. |
unlit_wgpu is the foundation and depends on nothing in the workspace.
unlit3d sits on top of it and on unlit_ecs, keeping both as direct
dependencies: its prelude re-exports what most callers need, and everything
else stays reachable through its own crate path.
Two principles shape the layering: the built-in pipeline gets no privilege, being composed from the same public facilities a caller's own pipeline uses; and frame sources are peers, with the built-in mesh source and a caller's own pass differing in nothing.
Each crate's README carries the design rationale for what it owns:
unlit_wgpu covers the resource graph, the
declarative scene, pipeline specialization and per-frame uploads;
unlit3d covers the frame model, the lit
pipeline, egui and input; unlit_ecs covers why the
ECS is as small as it is.
- Prefer general mechanisms over privileges for built-in features. Design for generality so users can customize and extend the library. Built-in implementations (lit rendering, say) should not have privileges or private internal paths; internal implementations should move outward to keep the library customizable and extensible.
- Route around a backend bug where it bites, and write down why. A driver
that miscompiles valid code is worked around at the code that trips it, with
the symptom, the cause and the cost recorded in
WORKAROUND.md, so a later reader can tell a deliberate oddity from a mistake.
See xtask/README.md for the cargo xtask tasks and their arguments.
The layers the tests fall into, how to run them, what each crate covers, the
benchmarks, and the CI workflows that run them are in TESTING.md.
crates/unlit_wgpu/ the renderer, its WESL shaders and its GPU tests
crates/unlit3d/ the ECS-integrated rendering API
crates/unlit_ecs/ the archetype ECS
crates/unlit_wgpu_test_util/ the shared GPU test harness
crates/unlit3dx/ the multi-world runtime: jobs, snapshots, threaded
and stepped worlds
unlit3d_examples/ the windowed example, its scenes and their snapshot tests
asset_bytes/ the glTF models it embeds, in a crate of their own
unlit3d_examples_android/ the shared library an Android activity loads
unlit3dx_examples/ the multi-world demo: five worlds, one window, a web
page and an Android activity
asset_bytes/ the soundfont it embeds, in a crate of its own
unlit3dx_examples_android/ that demo's shared library for its own activity
unlit3d_cli/ the glTF-to-image command-line tool and its end-to-end test
unlit3d_benchmarks/ the frame-path benchmarks and the profiling runs
android/ the Gradle project that packages the examples as an APK
xtask/ the `cargo xtask` task runner
Dual-licensed under either of MIT or Apache-2.0, at your option, as declared in the workspace manifest.