sdec

Snapshot Delta Encoding Codec — A transport-agnostic, bit-packed snapshot + delta codec for realtime state synchronization.

Overview

sdec provides a high-performance codec for replicating game state over the network. It focuses on:

• Bit-packed encoding — Minimize bandwidth with bit-level precision
• Delta compression — Send only what changed since the last acknowledged state
• Quantization — Configurable precision for position, rotation, and other numeric fields
• Correctness first — Bounded decoding, no panics, explicit error handling
• Engine agnostic — Bytes in, bytes out. No assumptions about ECS or networking stack

For interest management and per-client change lists, use the sdec-repgraph crate. It decides what gets encoded and feeds directly into codec::encode_delta_from_changes.

What We Solve

Real-time state replication needs predictable bandwidth and deterministic behavior, not just fast serialization. sdec is built to encode snapshots and deltas efficiently and safely, explicitly prioritizing network bytes over CPU when the two are in tension, with control over change detection, quantization, and wire budgets.

Philosophy

• Determinism over heuristics — Same inputs produce the same bytes across platforms.
• Bandwidth first — Bit-packed fields and delta semantics keep packets small.
• Explicit control — Schemas define codecs, change policies, and thresholds.
• Composable layers — Codec, schema, wire framing, and relevancy are separate concerns.

Status

🚧 Work in Progress — Core protocol is stable; sessions/compact headers and repgraph integration are active, and public APIs are still evolving.

Initial Results (Simbench)

Dense, 16 players, 300 ticks (delta encoding):

Commands:

cargo run -p simbench --release

In this codec-only harness, SDEC produces significantly smaller deltas than a generic bincode delta payload at the cost of higher CPU per encode. This matters in realtime replication where bandwidth (not CPU) is often the limiting factor.

Initial Results (sdec-bevy-demo)

Dense, 64 entities, 300 ticks, 100% dirty (end-to-end Bevy path):

Commands:

cargo run -p sdec-bevy-demo --release --bin sdec-bevy-demo -- --entities 64 --ticks 300 --dirty-pct 1.0
cargo run -p sdec-bevy-demo --release --bin sdec-bevy-demo -- --mode naive --entities 64 --ticks 300 --dirty-pct 1.0

This path includes change extraction, delta building, encoding, and apply logic. The naive/bincode baseline is faster but more than 2x larger on the wire. SDEC trades CPU for bandwidth, which is usually the binding constraint in realtime replication.

See ARCHITECTURE.md for design details and WIRE_FORMAT.md for the binary protocol specification.

Docs

• Getting Started
• Protocol: Sessions and Compact Frames
• Recovery and Failure Modes

Workspace Structure

Quick Start

use codec::{
    apply_delta_snapshot, encode_delta_snapshot, encode_full_snapshot, CodecLimits, Snapshot,
    SnapshotTick,
};
use schema::{ComponentDef, FieldCodec, FieldDef, FieldId, Schema};

let component = ComponentDef::new(schema::ComponentId::new(1).unwrap())
    .field(FieldDef::new(FieldId::new(1).unwrap(), FieldCodec::bool()));
let schema = Schema::new(vec![component]).unwrap();

let baseline = Snapshot {
    tick: SnapshotTick::new(10),
    entities: vec![],
};

let mut buf = [0u8; 256];
let _full_len = encode_full_snapshot(
    &schema,
    baseline.tick,
    &baseline.entities,
    &CodecLimits::for_testing(),
    &mut buf,
)
.unwrap();

let delta_len = encode_delta_snapshot(
    &schema,
    SnapshotTick::new(11),
    baseline.tick,
    &baseline,
    &baseline,
    &CodecLimits::for_testing(),
    &mut buf,
)
.unwrap();

let applied = apply_delta_snapshot(
    &schema,
    &baseline,
    &buf[..delta_len],
    &wire::Limits::for_testing(),
    &CodecLimits::for_testing(),
)
.unwrap();

Tools

The sdec-tools CLI provides packet inspection and decoding:

cargo run -p tools -- inspect packet.bin --schema schema.json
cargo run -p tools -- inspect captures/ --schema schema.json --glob "delta_*.bin" --sort size --limit 10
cargo run -p tools -- decode packet.bin --schema schema.json
cargo run -p tools -- decode packet.bin --schema schema.json --format pretty

Schema JSON is available via the optional serde feature on the schema crate.

Demo Simulation

Generate deterministic captures and a summary report:

cargo run -p demo-sim -- --players 16 --ticks 300 --seed 1 --out-dir captures

This writes schema.json, full_*.bin, delta_*.bin, and summary.json to the output directory.

Simbench Harness

Run a deterministic benchmark and emit summary.json:

cargo run -p simbench -- --players 16 --ticks 300 --seed 1 --out-dir target/simbench

Building

# Build all crates
cargo build --workspace

# Run tests
cargo test --workspace

# Run clippy
cargo clippy --workspace --all-targets -- -D warnings

# Format code
cargo fmt --all

Design Goals

1. Correctness and safety — Bounded decoding, no panics, no OOM amplification
2. Engine agnostic — No dependency on specific game engines or networking stacks
3. Pragmatic performance — Zero steady-state allocations, competitive wire efficiency
4. Evolvable format — Versioned wire protocol with room for extensions
5. First-class tooling — Inspection and debugging tools are part of the product

Non-Goals (for now)

• Transport layer (UDP, QUIC, etc.)
• Client prediction / server reconciliation
• Encryption / authentication

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Contributions are welcome! Please read the architecture docs before submitting PRs.

Every PR should:

• Add/extend tests proportional to changes
• Pass cargo clippy with no warnings
• Pass cargo fmt --check
• Maintain the correctness invariants documented in ARCHITECTURE.md