Repository navigation
Spawn v0.2.0: Phase 2 Complete
Phase 1 delivered 14 standalone library crates. Phase 2 turns those libraries into a running engine: it wires platform → input → ECS → physics → render into a fixed-step frame loop, grows the two subsystems whose Phase 1 form was deliberately a seed (the render graph and the editor) into real implementations, and adds the server-authoritative netcode stack the transport was always built to carry. The result is a runnable engine with a visual editor and end-to-end multiplayer replication, each layer spec'd before implementation and reviewed before commit.
All 42 commits in this release were spec'd before implementation and code-reviewed before commit; ECS-, render-, and netcode-touching commits received additional domain-specific review passes (ecs-guardian, render-guardian). 851 tests pass across the workspace (up from 639 at v0.1.0); cargo clippy --workspace --all-features --all-targets -D warnings, cargo fmt --check, and cargo deny check are clean. The workspace builds with #![deny(warnings)] and contains no unsafe code outside dependencies. Two new crates join the workspace this release, spawn-engine and spawn-replication, plus spawn-serialize and the editor aggregate spawn-editor-shell, bringing the workspace to 18 crates.
Phase 2a: Integration loop (spawn-engine)
A new crate that owns the engine and the frame. It wires the spawn-platform run loop → input pump → asset integration → fixed-step physics → spawn-ecs Schedule/Stage execution → render begin_frame/graph/end_frame, with audio pumped once per frame.
- Fixed-timestep accumulator decouples simulation rate from present rate: physics steps a fixed number of times per frame from accumulated wall time, preserving the spawn-physics substepped determinism reference end to end, while rendering runs at display rate.
- Frontend/backend command split over wgpu: game-side simulation produces render commands consumed a frame later, copying UE's pipelined model, but with a low-latency sync mode selectable from day one that bounds frames-in-flight, rather than UE's unbounded-pipelining failure mode retrofitted later.
- Render-thread-owned proxies extracted at a defined sync point (the ECS stage boundary): render-relevant state is copied into render-owned structures so no lock spans the frame boundary. ecs-guardian verified no shared component storage is locked across the pipeline.
- Prerequisites landed first as their own committed modules: spawn-ecs resource storage (
Res/ResMut/SystemParam) and events (Events/EventWriter/EventReader), plusSchedule::run_stagesfor caller-controlled event swap and aSend + Syncwindow handle for the run loop. - A headless example and a windowed example both run the complete loop to a clean shutdown.
Phase 2b: Render graph (spawn-render)
Growth of Phase 1's ordered-and-validated render-graph-lite into a derivation engine, then the multi-pass features that the single-pass Phase 1 renderer deferred.
- Graph derivation: from declared pass I/O alone, the graph derives execution order, resource lifetimes, and transient render-target aliasing: resources with disjoint lifetimes share GPU memory, cutting the peak render-target watermark below naive per-pass allocation. wgpu remains the barrier authority; the graph never inserts a manual barrier.
- Draw proxy rasterization via a
RenderResourcesregistry: meshes, materials, and textures resolve through stable ids, and the forward-lit pass consumes the extracted per-frame draw list. - Directional light + shadow map: a
ShadowDepthpass renders the scene from the light into a transient depth target; theForwardLitpass samples it for shadowing, closing the spawn-render §11 lighting deferral and proving the multi-pass model. Per-pass camera uniforms and a resource model back it. - GPU-validated on real hardware (NVIDIA A16, Vulkan): graph compiles, passes execute, and a frame presents with zero wgpu validation errors; the GPU-gated device tests skip cleanly on hosts without an adapter.
Phase 2c: Editor shell
The visual editor that consumes the headless Phase 1 framework, plus the spawn-ui/spawn-render foundations it needs. Six gated, reviewed commits.
- Component reflection (
spawn-ecs): a minimalReflecttrait withfn-pointer vtables (no derive macro, nounsafe) exposing each component's scalar leaves by dotted path ("translation.x"), built once at registration, exactly what the inspector needs and no more. - Scoped, nestable transactions (
spawn-editor): theCommandStackgains Slate-style transactions with an action counter that commits only when it returns to 1, with abort/flatten-on-nest; merge-on-drag is the special case, so a continuous gizmo orDragValuedrag coalesces into one undo entry. - Widget layer (
spawn-ui): the Phase 2 compositions (Panel,Label,Button,Checkbox,DragValue) over the retained widget tree. - Embedded bitmap font (
spawn-render): an 8×8 monospace glyph atlas and font registry, the runtime text path (Phase 1Textwas a measured layout box only). Overlay2Dpass (spawn-render): a UI draw-list + text + gizmo-line pass with its UI and line pipelines in the cache, layered after the lit scene.- Editor shell (
spawn-editor-shell, new crate): the visual editor: a scene view rendering the live ECS world through the 2b lit graph + Overlay2D, a viewport/camera controller, translate/rotate/scale gizmos that draw and pick against rendered geometry, a reflection-driven inspector routing every edit through undoable transactions, a flat outliner, and conservative Edit/Play over the Phase 1 snapshot contract. A bespoke immediate-modePlatformAppdriver (editor state holds non-SendBox<dyn Command>, so it cannot be aSendECS extract), dark theme with the#C1440Eaccent reserved for selection/active/focus.
Phase 2d: Netcode (server-authoritative replication)
The fork was decided deliberately, server-authoritative replication rather than deterministic rollback, after a focused research pass, then built on two new transport/codec prerequisites plus a validated interest-management prototype. Ten commits across three crates.
spawn-serialize(new crate): a structured bit-level codec:BitWriter/BitReader, the read/write-symmetricStream/Serializetraits so each type has one serialization function that drives both directions, integer/zig-zag/bounded-range helpers, float quantization, bounded-position packing, and smallest-three unit-quaternion compression (29 bits).spawn-core+stdonly, zerounsafe.spawn-netfragmentation: packet fragmentation and reassembly above the 1200-byte MTU cap for the unavoidable large messages (the initial full baseline snapshot, large reliable RPCs). APacketType::Fragmentwith a 6-byte sub-header; reliable fragments reuse the connection's existing per-packet ack endpoint for completion; best-effort fragments reassemble with a timeout. The sub-MTU path is byte-for-byte unchanged; no new third-party dependency.spawn-replication(new crate): the server-authoritative layer above the transport, following the bevy_replicon-style engine/game split (engine = mechanism; game = which components replicate, RPC semantics + validation, ownership, relevancy policy). Landed in seven reviewed sub-module commits:- Roles + markers: the
NetRoletriad (Authority / AutonomousProxy / SimulatedProxy, derived per peer, never stored), theReplicated/AlwaysRelevant/OwnerOnly(ClientId)/StaticRelevantmarker components, and a denseReplIdmap with free-list recycling that keeps the id space at peak-concurrent-live. - Interest management: relevancy class as markers→archetypes; the per-client current/previous visibility bitsets in a server resource (validated cheaper and archetype-stable vs per-entity storage); a spatial-hash grid with an incremental per-entity cell cache; a gather-then-diff loop emitting exactly-once spawn/despawn deltas. The gather block covers the exit radius (a 7×7 block at the default
cell_size ≈ 0.5 × view_radius) so the 25% exit-radius hysteresis cannot spuriously despawn boundary-band entities. The throwaway prototype surfaced that correction and the spec absorbed it. - Snapshot + delta: a
Replicatetrait and fn-pointer registry; per-serialize-unit acked-baseline delta compression (the Quake3 model: a 1-bit changed marker per field, absolute when there is no baseline), a per-client snapshot ring (≥32), a 1-bit continue-marker section framing, a 1400-byte/tick send budget, and a 20 Hz default rate. - Interpolation: simulated proxies render in the past (default delay = 2 snapshot intervals) with Hermite position interpolation using transmitted velocity and slerp orientation, written to a separate
InterpolatedTransformcomponent (never an override of the authoritativeTransform3D). - Prediction: opt-in client-side prediction with a wrap-correct input buffer, a replay helper, and snap-vs-smooth error correction. Snap-only reconciliation is the shipping baseline; replay is gated on spawn-ecs change detection (decision 4).
- RPC: the Server / Client / Multicast taxonomy over the reliable-ordered channel, ownership-gated (a client may only invoke a Server RPC on an entity it owns), with game-side payload validation.
- Drivers: the
ReplicatorandReplicationClientpublic API, 1-byte message-kind framing multiplexing snapshots / inputs / RPCs over the spawn-net channels, the per-client baseline-ack loop, and a staleness priority accumulator for budget-bounded partial snapshots. A headless loopback test demonstrates two clients with distinct viewers converging on the server world, each interest-filtered, including an MTU-exceeding baseline that exercises fragmentation.
- Roles + markers: the
Quality gates
Every module followed the same pipeline: written spec → approval → implementation → independent code review → fix cycles → commit. Reviewers caught real defects before commit, including:
- spawn-replication interest management: the gather block was sized to the enter radius, but the 25% hysteresis keeps an entity visible out to the exit radius; a hysteresis-band entity one cell beyond the block was never gathered and got spuriously despawned, reintroducing the exact boundary thrash hysteresis exists to prevent. Caught with a negative-axis reproduction; fixed to cover the exit radius (7×7 block) in code, spec, and research note.
- spawn-replication snapshot delta: the delta reader advanced its baseline cursor only on unchanged fields, so a changed field desynced the baseline stream and every subsequent unchanged field decoded the wrong baseline bits. Fixed so the reader consumes the baseline unit for every field, in lockstep with the writer.
- spawn-net fragmentation: a transmit I/O error mid-burst dropped the in-flight reliable fragmented message (the
out_fragslot was taken out and discarded on the error path), violating the reliable-delivery invariant. Fixed to restore the message before propagating the error, with a failing-sink regression test. - spawn-replication ids:
ReplIdMap::bindcould leave a stale reverse mapping and over-count when an entity was rebound to a different id; hardened to clear any prior binding of either the id or the entity, plus aMAX_SPAWN_REPL_IDclamp so a hostile snapshot cannot drive an unbounded client-side allocation. - spawn-replication interpolation: the sample ring evicted newer history when an out-of-order straggler arrived; fixed to discard the straggler and keep the newer sample.
- spawn-editor-shell inspector: a multi-frame
DragValuedrag opened and closed a transaction per frame, producing N undo entries for one drag; fixed to route through the command merge so a continuous drag coalesces into one undo step.
Known follow-ups
Deferred, non-blocking, and recorded:
- spawn-replication per-tick allocation: the snapshot/baseline-recording path allocates per component per tick (the absolute-bytes
to_vec, the per-client spawn/despawn/update vectors, theSnapshotStatemap). This deviates from the crate's zero-steady-state-allocation target; the fix is to hoist these into reused driver-owned scratch/pools. - Prediction replay is gated on spawn-ecs change detection (
Changed<T>/Added<T>): snap-only reconciliation ships now; replay-style reconciliation and component-level dirty-tracking deltas land once change detection does. This is the single largest netcode unlock remaining. - The client input buffer is unbounded if acks never arrive (the driver should cap it); the interest grid's
HashMapcarries a cache term an array/Morton-ordered grid could remove at high client counts. - RPC payload dispatch and interpolation feeding are game-driven (the engine surfaces raw bytes and the
InterpBuffertool) rather than auto-wired. - On-target interactive validation of the editor window is pending. It needs a desktop window station, the same constraint as the Phase 1 present path. PIE-equivalent Edit/Play world isolation beyond the Phase 1 snapshot contract is gated on a dedicated research pass.
Not in Phase 2 (deferred to Phase 3)
- Netcode breadth: encryption / DTLS, NAT traversal and hole punching, matchmaking, congestion control beyond the per-tick budget, lag compensation (server-side rewind for hit detection), and authority transfer. The deterministic-rollback fork is explicitly not pursued under the recorded server-authoritative decision. Line-of-sight / frustum relevancy refinement on top of the spatial grid.
- spawn-ecs change detection, which gates prediction replay and dirty-tracking deltas (above), plus component/world serialization for scene save, entity hierarchy/parenting, and Mass-style chunk subdivision (measure-first).
- Assets: streaming / partial loads / LOD and the World-Partition-style spatial streaming strategy (research-gated); the spawn-build CLI binary, platform packaging, and single-blob packing.
- Editor depth: detachable/multi-monitor panels, asset browser, scene (de)serialization, prefabs, and entity hierarchy in the outliner.
- A Phase 3 roadmap has not yet been written; it needs its own planning and research pass.
License
Business Source License 1.1. Change Date: 2029-05-14. Change License: Apache 2.0.