# SectorSync
[](https://github.com/4fuu/SectorSync/actions/workflows/ci.yml)
[](LICENSE)
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](docs/production-adapters.md) 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:
```toml
[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:
```toml
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
```rust
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:
```bash
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](docs/sdk-integration.md).
## Workspace
| `sectorsync-core` | Spatial index, authority, entities, policies, AOI, components, replication planning, snapshots | Yes |
| `sectorsync-wire` | Bounded binary frame definitions, encoders, decoders, and replication frame builder | Yes |
| `sectorsync-transport` | In-memory, reliable packet, security-hook, and UDP transport adapters | Yes |
| `sectorsync-runtime` | Transport bridges, gateway/deployment routing, barriers, load sampling, scheduling, and migration | Yes |
| `sectorsync-bench` | Executable examples and guarded performance acceptance runner | No |
Published crates use one workspace version. The release order is core, wire,
transport, then runtime.
## Examples
Representative integration flows:
```bash
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](AGENTS.md#verification). Security examples use explicit test hooks
and are not production cryptography.
## Performance
Routine checks use the bounded smoke profile:
```bash
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:
```bash
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](docs/performance-acceptance.md) 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:
```powershell
$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:
```powershell
$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:
```powershell
$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](docs/sdk-integration.md)
- [Performance acceptance matrix](docs/performance-acceptance.md)
- [Production adapter boundaries](docs/production-adapters.md)
- [Delivery status and explicit non-goals](docs/gaps.md)
Generate local API documentation with:
```bash
cargo doc --workspace --no-deps
```
## Development
The default quality gate is intentionally lightweight:
```bash
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](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](SECURITY.md). Do not open a public issue for an unpatched security
problem.
## License
SectorSync is available under the [MIT License](LICENSE).