SectorSync

SectorSync is dependency-light Rust middleware for spatial, real-time entity replication across large maps and multiple simulation stations. It provides bounded, embeddable primitives without imposing a game engine, ECS, gateway process, async runtime, or cluster platform.

Capabilities

• Deterministic 3D cell indexing, AOI queries, visibility hooks, and allocation-light movement updates.
• Single-owner authority, read-only ghosts, handoff, snapshots, barriers, and cell migration primitives.
• Compiled cadence, priority, visibility, and byte-budget replication planning with caller-owned reusable scratch.
• Bounded command, event, replication, gateway, deployment-route, and tracking state with explicit backpressure.
• Binary wire frames plus in-memory, reliable-packet, security-hook, and non-blocking UDP adapters.
• Runtime load sampling, conservative hotspot splitting, and deterministic station scheduling.
• Adaptive small/large collection paths and reusable buffers for multi-room, single-process deployments.
• Guarded, machine-readable benchmarks for latency, bytes, queue pressure, scheduler decisions, and retained capacity.

SectorSync owns synchronization mechanics, not game semantics. Authentication, anti-cheat, matchmaking, gameplay state, persistence, process orchestration, service discovery, production cryptography, and GPU execution remain with the embedding application. See Production adapter boundaries.

Requirements

• Rust 1.88 or newer with Edition 2024 support.
• No operating-system service, database, or mandatory runtime dependency.

Installation

Use the fast-by-default product facade:

[dependencies]
sectorsync = "=2026.713.0"

The facade delegates to the low-level crates and does not introduce a mandatory ECS, async runtime, or network service. Advanced integrations may depend on sectorsync-core, sectorsync-wire, sectorsync-transport, or sectorsync-runtime directly.

Optional performance features are explicit:

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

simd enables the safe range-only SIMD candidate path. parallel exposes a bounded replication pool and deterministic parallel station planning. Neither feature creates hidden threads in the default build.

Quick Start

use sectorsync::prelude::{
    Bounds, EntityId, GridSpec, InstanceId, NodeId, PolicyId, Position3,
    SpawnEntity, StationConfig, StationId, StationRuntime, StationRuntimeConfig,
};

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

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

assert_eq!(station.index().query_sphere(position, 128.0), vec![handle]);

Run the complete validated command-to-replication flow:

cargo run -p sectorsync-bench --example sdk_flow

The SDK integration guide covers bootstrap, per-tick ordering, ownership, bounded failures, barriers, migration, and observability. Existing low-level users should follow the breaking API migration guide.

Workspace

The five library crates share one exact workspace version and publish in dependency order: core, wire, transport, runtime, then the facade.

Performance

Run the bounded smoke acceptance profile:

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

The benchmark emits machine-readable latency, selection, byte, queue, replication, scheduler, threshold, and benchmark_ok fields. Medium, large, and oversized manual workloads require explicit --allow-heavy opt-in.

The guarded many-room example models independent room instances and sequential single-process work:

cargo run --release -q -p sectorsync-bench --example many_rooms

The deterministic gameplay-shaped scenario adds active/idle/hot room mixes, commands, movement, component changes, projectiles, events, frame transport, client decode, ACK tracking, and bounded room recreation:

cargo run --release -q -p sectorsync-bench --example dynamic_gameplay

On the current development host, its default 500-room workload has demonstrated 30 Hz headroom for spatial planning and direct delta encoding. This excludes gameplay, room lifecycle, persistence, matchmaking, and kernel networking, so it is regression evidence rather than a production capacity guarantee.

Benchmark profiles, baselines, A/B commands, measurements, and interpretation rules live in the performance acceptance matrix.

Documentation

Start with the documentation index:

• SDK integration guide: application ownership, bootstrap, tick flow, failures, and executable examples.
• Performance acceptance matrix: guarded profiles, thresholds, A/B evidence, and heavy calibration.
• Production adapter boundaries: security, transport, routing, persistence, and infrastructure ownership.
• Delivery status: completed SDK scope, explicit non-goals, and criteria for future work.

Generate API documentation with:

cargo doc --workspace --all-features --no-deps

Development

The release-quality gate is:

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

See CONTRIBUTING.md before submitting changes. Public SDK changes require focused tests and a relevant executable example. Routine verification stays smoke-safe; heavier performance runs must be deliberate.

Versioning

SectorSync uses calendar versions in YYYY.MMDD.REVISION form with an unpadded numeric MMDD field. The date identifies a release and does not claim semantic API compatibility. Workspace dependencies remain exact and equal; review the release notes before upgrading.

Authority, boundedness, and explicit-state invariants remain compatibility commitments.

Security and License

Report vulnerabilities through the private process in SECURITY.md, not a public issue. SectorSync is available under the MIT License.