SectorSync

SectorSync is a dependency-light Rust middleware workspace for spatial, real-time entity replication across large maps and multiple simulation stations. It provides low-level, bounded primitives that can be embedded in a game or simulation backend without imposing an engine, ECS, gateway process, or cluster platform.

The current calendar-versioned line is the basic embedded SDK. Its public boundaries are covered by workspace tests, executable integration examples, strict Clippy, rustdoc, and a guarded performance acceptance runner.

Features

• Uniform 3D cell indexing with deterministic AOI candidate queries.
• Exactly one authoritative owner per entity and read-only ghost semantics.
• Range, frustum, tag, cadence, priority, and byte-budget replication filters.
• Reusable caller-owned query and replication scratch buffers.
• Bounded command, event, client packet, and station packet queues.
• Binary command, acknowledgement, replication, barrier, dispatch, and station event frames.
• Low-level in-memory, reliable packet, and non-blocking UDP adapters.
• Tick-boundary barriers for freeze, snapshot, upgrade, and resume workflows.
• Runtime load sampling, conservative hotspot splitting, migration, and deterministic station scheduling.
• Guarded smoke benchmarks with machine-readable latency, bandwidth, queue, scheduler, and scratch-capacity fields.

What SectorSync Is Not

SectorSync is not a game engine, ECS framework, full game-server framework, or production cluster platform. The embedding application remains responsible for game rules, authentication, anti-cheat, durable persistence, crash recovery, service discovery, process orchestration, production cryptography, and GPU workloads.

See Production adapter boundaries for the exact integration ownership model.

Requirements

• Rust 1.88 or newer.
• Edition 2024 support.
• No operating-system service or external database is required.

Installation

After the first registry release, use only the layers needed by the embedding application:

[dependencies]
sectorsync-core = "=2026.711.0"
sectorsync-wire = "=2026.711.0"
sectorsync-transport = "=2026.711.0"
sectorsync-runtime = "=2026.711.0"

sectorsync-core can be used by itself. The higher layers build on it without adding mandatory async runtimes, serialization frameworks, ECS frameworks, or network services.

Performance integrations are opt-in:

sectorsync-core = { version = "=2026.711.0", features = ["simd"] }
sectorsync-runtime = { version = "=2026.711.0", features = ["parallel"] }

simd enables the safe eight-lane range-only candidate path. parallel exposes an explicitly constructed, bounded replication pool with deterministic station batch planning and synchronous ordered batch mapping. Neither feature creates threads or changes planner behavior in the default build.

Quick Start

use sectorsync_core::prelude::{
    Bounds, CellIndex, EntityId, GridSpec, InstanceId, NodeId, PolicyId,
    Position3, Station, StationConfig, StationId,
};

let mut station = Station::new(StationConfig {
    station_id: StationId::new(1),
    node_id: NodeId::new(1),
    instance_id: InstanceId::new(1),
    tick_rate_hz: 20,
});
let grid = GridSpec::new(32.0).expect("valid grid");
let mut index = CellIndex::new(grid);
let position = Position3::new(64.0, 0.0, 64.0);

let handle = station
    .spawn_owned(
        EntityId::new(42),
        position,
        Bounds::Point,
        PolicyId::new(1),
    )
    .expect("entity should spawn");
index.upsert(handle, position, Bounds::Point);

let candidates = index.query_sphere(position, 128.0);
assert_eq!(candidates, vec![handle]);

Run the complete validated command-to-replication flow:

cargo run -p sectorsync-bench --example sdk_flow

The integration order, ownership checks, bounded failures, barriers, migration, and observability handoff are described in the SDK integration guide.

Workspace

Published crates use one workspace version. The release order is core, wire, transport, then runtime.

Examples

Representative integration flows:

cargo run -p sectorsync-bench --example sdk_flow
cargo run -p sectorsync-bench --example replication_bridge
cargo run -p sectorsync-bench --example client_bridge
cargo run -p sectorsync-bench --example load_sampling
cargo run -p sectorsync-bench --example split_migration
cargo run -p sectorsync-bench --example barrier_upgrade
cargo run -p sectorsync-bench --example secure_command_ingress
cargo run -p sectorsync-bench --features parallel --example parallel_replication

The focused example-to-feature map is maintained in AGENTS.md. Security examples use explicit test hooks and are not production cryptography.

Performance

Routine checks use the bounded smoke profile:

cargo run -q -p sectorsync-bench -- --profile=smoke

On the current development host, the 2,000-entity, 100-client, four-station, five-tick smoke workload reports approximately 2 ms p99 tick time, selects 125 logical entity updates, estimates 4,000 payload bytes, and retains four candidate handles in replication scratch. These figures are regression evidence, not production capacity guarantees.

Compare identical workloads with:

cargo run -q -p sectorsync-bench -- --profile=smoke --baseline=sectorsync
cargo run -q -p sectorsync-bench -- --profile=smoke --baseline=full
cargo run -q -p sectorsync-bench -- --profile=smoke --baseline=room
cargo run -q -p sectorsync-bench -- --profile=smoke --baseline=naive-grid

Medium, large, and oversized manual profiles require --allow-heavy. See the performance acceptance matrix before changing thresholds or running larger workloads.

For a deliberate measurement on the current development host, use the guarded release-mode local profile. It scales from detected host parallelism, caps the workload at 24,000 entities and 480 clients, fully encodes selected replication deltas in a bounded dense-AOI scenario, and enforces a 10-second between-tick time budget:

$env:CARGO_BUILD_JOBS=4
cargo run --release -q -p sectorsync-bench -- --profile=local --allow-heavy

This is a repeatable local regression and capacity signal, not a production or cross-machine network capacity guarantee.

The optimized 128 Hz simulation check keeps replication at an explicit 32 Hz, spreads viewers across four deterministic phases, and enforces the 7.8125 ms tick budget:

$env:CARGO_BUILD_JOBS=4
cargo run --release -q -p sectorsync-bench --features optimized -- `
  --profile=local --allow-heavy --planner=parallel --threads=8 `
  --replication-hz=32 --tick-ms-p99-budget=7.8125

Use --replication-hz=128 only as the harsher all-clients-every-tick comparison; it is not stable at 128 Hz on the current development host.

For the guarded many-room shape, each room receives its own InstanceId, and its Station count grows deterministically with player count. The runner advances all rooms sequentially on one thread and fully encodes every selected delta:

$env:CARGO_BUILD_JOBS=4
cargo run --release -q -p sectorsync-bench --example many_rooms

The default run covers 500 rooms with 4-24 players each, one Station per 12 players, eight entities per player, and eight measured sweeps. Use --rooms=300 --sweep-p99-budget-ms=33.333 for the current host's guarded 30 Hz acceptance shape. This measures spatial planning and wire encoding, not gameplay, matchmaking, room lifecycle, persistence, or network capacity.

Documentation

• SDK integration guide
• Performance acceptance matrix
• Production adapter boundaries
• Delivery status and explicit non-goals

Generate local API documentation with:

cargo doc --workspace --no-deps

Development

The default quality gate is intentionally lightweight:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo doc --workspace --no-deps
cargo run -q -p sectorsync-bench -- --profile=smoke
git diff --check

GitHub Actions runs the same quality gate on pushes and pull requests, plus a separate Rust 1.88 compatibility check. At 08:00 Asia/Hong_Kong each day, the Automatic release workflow checks main for commits after the current release. When work is pending, it assigns the current Asia/Hong_Kong calendar prefix and next same-day revision, reruns the quality gate, publishes the four library crates to crates.io in dependency order, and creates a GitHub Release with source archives and checksums. The first release of a local day uses revision zero; later manual or scheduled releases increment it. The workflow resumes safely when a crate version was already published by an earlier partial run. Registry authentication uses crates.io Trusted Publishing; the repository does not store a long-lived registry token.

Please read CONTRIBUTING.md before submitting changes. The project preserves a narrow middleware boundary and requires examples or tests for public SDK changes.

Stability

SectorSync uses calendar versions in YYYY.MMDD.REVISION form. The MMDD field is encoded as an unpadded integer, so July 10 starts at 2026.710.0 and January 5 starts at 2027.105.0. Same-day releases increment the final field. The three numeric fields remain valid for Cargo's SemVer parser, but the date identifies a release and does not claim API compatibility. Workspace crates depend on the exact same calendar version; consumers should review release notes before upgrading. Authority, boundedness, and explicit-state invariants remain compatibility commitments.

Security

Report suspected vulnerabilities using the private process described in SECURITY.md. Do not open a public issue for an unpatched security problem.

License

SectorSync is available under the MIT License.