Introduction

Mid Engine is a modular, high-speed Rust engine toolkit — "The Middle Man."

Traditional monolithic engines hide their internals behind layers of abstraction, while others demand unlimited hardware just to render a basic scene. Mid Engine takes a different approach: a modular toolkit for developers who want complete control over their hardware stack, with every crate designed to be dropped into a larger project rather than forcing an all-or-nothing commitment.

It's a true "Middle Man" in two senses. First, every crate is FFI-compatible out of the box, built with as few external dependencies as possible, so it can sit between a game's logic and a lower-level system (or a completely different language's codebase) without friction. Second, it's meant to be the layer between "roll everything yourself" and "adopt a full engine" — whether that means assembling a sovereign engine from these crates, or injecting individual modules into an existing C++/C# environment through raw pointers.

Where this book fits

This is the user-facing documentation site — architecture, how to use each crate, and the project's own conventions. It's a different thing from the docs/*.md files in the repository itself, which are internal, AI-facing working notes (design decisions, fix histories, MSRV walls) meant for whoever — human or AI — is actively developing the engine, not for someone using it. If something here seems to assume familiarity a repo-only reader wouldn't have, that's the split working as intended, not a mistake.

See Tests and Benchmarks for live results from each crate's own CI, and the Getting Started page to build the workspace yourself.

Getting Started

Mid Engine is a Cargo workspace. Most crates build on a plain, current stable toolchain, but a handful need a newer Rust than the workspace's usual floor — see Crate Dependency Order and each crate's own page for specifics before assuming a bare, unqualified command below will cover everything.

Build and test

# Everything a bare-minimum, no-flags toolchain can build:
cargo build
cargo test

# A release build:
cargo test --release

# One crate specifically -- always safe, regardless of any MSRV wall
# elsewhere in the workspace:
cargo build -p mid-math
cargo test  -p mid-math

# The headless server example:
cargo run --example headless-server

A note on -p

Several crates deliberately need a newer toolchain than the rest of the workspace (an upstream dependency's own edition2024 requirement, mostly — see each crate's page for the specific wall). A bare cargo build/cargo test with no -p flag pulls every workspace member in, including those. Building a single crate with -p <crate-name> only resolves that crate's own dependency closure, so it stays on whatever toolchain that crate actually needs — usually the workspace floor.

CI

Every crate's tests run through its own workflow_dispatch-only GitHub Actions workflow — nothing runs automatically on push. Trigger one from the repository's Actions tab, then check the Tests page (or the run's own Job Summary) for results. See Contributing & CI for the full convention.

Design Mandates

Four rules apply to every crate in this workspace, no exceptions:

Multiplayer-first

Network sync is baked into the ECS from day one, rather than being bolted on later. Multiplayer isn't a feature added after the fact — it shapes how state is structured from the start.

FFI-ready

Every crate exposes a strict #[repr(C)] FFI boundary to act as a cross-language "Middle Man." In practice: rlib + cdylib + staticlib crate types, and a real extern "C" surface with a C header, not just a Rust API that happens to be #[repr(C)]-annotated internally.

Zero hidden abstractions

If you need to understand the memory layout, you can read the code directly. No macro-generated indirection that obscures what's actually stored where.

Profile before optimize

Every performance claim cites a real, benchmarked [RELEASE] build number — not a theoretical estimate. See Benchmarks for the numbers behind any performance claim made elsewhere in this book.

Zero-to-minimal external dependencies

Every core crate, no exceptions. This project has turned down its own published dixscript crate as a core dependency over its transitive dependency count — the bar is real, not aspirational. When a crate needs a capability an external crate provides (a fast hash algorithm, a spin-based mutex for no_std), the default is to check whether it can be hand-rolled first, and to defer the decision with a named trigger condition when it can't be decided cleanly yet. mid-platform's own page is the clearest example of this in practice.

Crate Dependency Order

mid-math        (no engine deps — pure math foundation)
mid-ptr         (no engine deps — type-erased pointer wrappers)
mid-platform    (no engine deps — Mutex/Arc/atomics/cells)
mid-collections (no engine deps — SparseSet, generational index, FFI span)
mid-arena       (no engine deps — bump/slot/compact arenas)
mid-alloc       (no engine deps — custom allocators, SpinLock)
mid-common      (uses mid-math — shared traits and error types)
mid-log         (uses mid-common)
mid-trace       (uses mid-common)
mid-geom        (uses mid-math — geometric algorithms)
mid-ecs         (uses mid-math, mid-common, mid-collections)
mid-net         (uses mid-math, mid-common)
mid-physics     (uses mid-math, mid-geom)
mid-anim        (uses mid-math, mid-ecs)

The crates with no engine-internal dependency at all (mid-math, mid-ptr, mid-platform, mid-collections, mid-arena, mid-alloc) are the ones safest to work on in parallel — nothing else in the workspace has to land first for one of them to be usable, and nothing about them can be blocked by another crate's own unfinished state.

See each crate's own page for what it actually depends on today versus this list's target shape — a couple of these (mid-physics, mid-anim, mid-app, mid-time) currently exist as early v0 stubs rather than finished crates.

mid-math

SIMD-dispatched vector and matrix math library: Vec2/Vec3/Vec4, Quat, Mat3/Mat4, strictly 16-byte-aligned #[repr(C)] primitives for FFI safety. Includes a hand-rolled MidVec<T, N> small-vector container (union + MaybeUninit) used by curve types and cascaded shadow maps.

Zero external dependencies, comprehensive benchmarking infrastructure (see Benchmarks). The second crate in the workspace (after mid-math itself, chronologically first) to opt into [lints] workspace = true and take on real unsafe for its SIMD intrinsics.

Status: practically done, second optimization pass planned.

mid-common

Shared types and traits used across the workspace — EntityId, TickId, network-sync-related types. Depends on mid-math.

Kept deliberately thin: helper crates (mid-app, mid-time, and others) live as their own workspace members rather than being folded in here, so this crate doesn't accumulate every cross-cutting concern by default.

Status: in progress.

mid-log

Non-blocking tiered logger built on a lock-free SPSC ring buffer — zero frame-time impact on the hot path. Ships a C header for FFI callers (headers/mid_log.h) and has its own C-side smoke test.

Status: done, needs a second optimization pass.

mid-collections

no_std + alloc collection types: a generational-index allocator, a sparse set, and FfiSpan — a type-erased, C-safe view into a Rust array for crossing the FFI boundary safely (built on zerocopy).

FfiSpan specifically is why mid-platform's own Phase 1 doesn't need to solve the "type-erased pointer for FFI" problem again — see that crate's own page and docs/roadmap.md's Decision 3 for the full reasoning.

Status: in progress.

mid-arena

Arena allocators: bump, slot, and compact-slot variants, each benchmarked against comparable crates. No engine-internal dependencies.

Status: in progress — next up for updates and proper benches per the project roadmap.

mid-alloc

Custom memory allocators and layout management, including SpinLock<T> — a hand-rolled spinlock validated under real multi-threaded stress tests (8 real OS threads, thousands of increments each, zero lost updates). That same proven algorithm is the basis for mid-platform::sync::Mutex's own no_std fallback (an independent copy, not a dependency — see that crate's page for why).

Status: in progress; paused pending mid-arena updates.

mid-ptr

Type-erased raw pointer wrappers, ported from Bevy's bevy_ptr crate (MIT/Apache-2.0) and adapted to this workspace's own conventions. no_std, zero dependencies.

What it gives you

  • Ptr, PtrMut, OwningPtr — type-erased pointers mirroring &T, &mut T, and Box<T> respectively, minus the compile-time type information. Useful for storing heterogeneous data (different component types in one column, for instance) without generics at the storage layer.
  • MovingPtr — moves a value to a new location without ever passing it by value, and can be deconstructed into per-field MovingPtrs via the deconstruct_moving_ptr! macro. Useful for migrating a value's bytes between two locations (an archetype table column, say) without an extra copy.
  • ThinSlicePtr — a &[T] with the length stripped out, for callers that already track the length separately.
  • Aligned/Unaligned — marker types threaded through all of the above, so a pointer's alignment guarantee (or lack of one) is visible in its type rather than only in a doc comment.

Full port, including MovingPtr

This is a close port of the real, current upstream source, not a redesign — including the newer MovingPtr + field-deconstruction machinery, which is genuinely the more novel, riskier-to-hand-verify half of the crate. Built on direct instruction, after surfacing that the project's own roadmap had originally deferred this crate.

FFI

Not yet exposed over a C boundary — a known, tracked gap against this project's own FFI-ready mandate, not an oversight left undocumented. See the repository's docs/mid-ptr.md for the current status.

Status

See the Tests page for the latest CI run, or run mid-ptr — Tests from the Actions tab yourself.

mid-platform

No-std-safe replacements for the pieces of std::sync/std::cell mid-engine actually needs, std-backed on native targets and hand-rolled (spin-based, no OS to ask for a real wait) wherever std is off. Zero external dependencies — every fallback in this crate is a from-scratch port of a real, proven algorithm rather than a spin dependency, so mid-engine's real target matrix (native desktop, wasm32-unknown-unknown) gets the behavior without the crate.

Modules:

Status: Phases 1, 2 and 3 done (see docs/mid-platform.md): the locks and cells, the fast hasher, and HashMap/HashSet. C FFI: Once and Barrier are callable from C today (see their own module pages); Mutex/RwLock/OnceLock/LazyLock are open work — see docs/mid-platform.md, "Fixes and Problems."

cell

SyncCell<T> and SyncUnsafeCell<T> — ways to make a type Sync without locking, for the cases where locking would be the wrong tool.

What it does

SyncCell<T> reimplements the currently-unstable std::sync::Exclusive: it makes any T unconditionally Sync by only ever handing out &mut T (through get()), never a shared &T unless T itself is already Sync (read() requires T: Sync). Since Sync only allows multithreaded access through a shared reference, and this type never allows unsynchronized shared access to a non-Sync inner value, marking it Sync doesn't open any real hole — mutable access is still exclusive by Rust's own borrow rules.

SyncUnsafeCell<T> reimplements the currently-unstable std::cell::SyncUnsafeCell: a plain UnsafeCell<T> that additionally implements Sync whenever T does. UnsafeCell itself is never Sync, specifically to stop accidental cross-thread misuse — this type opts back in deliberately, for a caller who's going to provide their own synchronization around the raw pointer it hands out (get()). It carries none of the runtime overhead a lock would — no atomics, no spinning, just the same interior-mutability primitive UnsafeCell already is.

Example usage

#![allow(unused)]
fn main() {
use mid_platform::cell::{SyncCell, SyncUnsafeCell};

// SyncCell: exclusive access only, so it's Sync even for a !Sync T.
let mut counter = SyncCell::new(0u32);
*counter.get() += 1;

// SyncUnsafeCell: raw-pointer access, caller provides synchronization.
let cell = SyncUnsafeCell::new(0u32);
unsafe {
    *cell.get() += 1;
}
assert_eq!(unsafe { *cell.get() }, 1);
}

Status

Done — Phase 1. See docs/mid-platform.md, "Build order."

sync::atomic

A portable set of atomic types — the same ones every target this crate actually supports (x86_64, aarch64, wasm32) already has natively.

What it does

A plain re-export of core::sync::atomic's Atomic* types and Ordering — AtomicBool, AtomicI8..AtomicI64, AtomicIsize, AtomicPtr, AtomicU8..AtomicU64, AtomicUsize. Upstream bevy_platform falls back to the portable-atomic crate on targets missing a native atomic width; none of mid-engine's real targets are missing one, so this module carries no fallback dependency at all. If this crate is ever built for a target that genuinely lacks full-width atomics, a compile_error! fails the build loudly and explains why, rather than silently miscompiling.

Example usage

#![allow(unused)]
fn main() {
use mid_platform::sync::atomic::{AtomicU32, Ordering};

let counter = AtomicU32::new(0);
counter.fetch_add(1, Ordering::SeqCst);
assert_eq!(counter.load(Ordering::SeqCst), 1);
}

Status

Done — Phase 1. See docs/mid-platform.md, "Build order."

sync::Mutex

A std-shaped mutual-exclusion lock that also works with std off.

What it does

std::sync::Mutex directly when the std feature is on. Otherwise a hand-rolled spin-based fallback: "test, then test-and-set" — attempt the real atomic compare-exchange first, and only on contention fall back to spinning on a plain Relaxed load, which is cheaper than repeatedly retrying the exclusive compare-exchange while the lock is genuinely held elsewhere. This is an independent copy of the exact algorithm mid_alloc::sync::SpinLock already validated under real multi-threaded stress tests, not a dependency on that crate. Never actually poisons — a panic while holding the guard just unwinds past Drop and releases the lock normally; is_poisoned()/clear_poison() exist only to keep this type a drop-in replacement for std::sync::Mutex call sites.

Example usage

#![allow(unused)]
fn main() {
use mid_platform::sync::Mutex;

let counter = Mutex::new(0u32);
*counter.lock().unwrap() += 1;
assert_eq!(*counter.lock().unwrap(), 1);
}

Status

Done — Phase 1. Full design write-up: docs/mid-platform.md, "Why not just depend on mid-alloc for SpinLock" and "Build order" (a Phase 1 file — predates this doc's per-module ### sync/<file>.rs sections, which start with Phase 2 below).

sync::RwLock

A std-shaped reader/writer lock — any number of concurrent readers, or one exclusive writer, never both at once.

What it does

std::sync::RwLock directly when the std feature is on. Otherwise a hand-rolled spin-based fallback grounded in spin::RwLock's real algorithm (read fresh from its own source, not from memory): a single packed atomic holds both the writer flag and the reader count, so read() and try_read() never block each other, while write()/try_write() only succeed when the lock is fully free. Simplified from the real spin algorithm by leaving out its upgradeable-guard mechanism — this type's surface is read/write/try_read/try_write only. Like spin::RwLock itself, this is unfair to writers under continuous read pressure; there's no fairness mechanism to prevent a steady stream of readers from starving a waiting writer.

Example usage

#![allow(unused)]
fn main() {
use mid_platform::sync::RwLock;

let data = RwLock::new(vec![1, 2, 3]);

// Many readers can hold the lock at once.
{
    let r1 = data.read().unwrap();
    let r2 = data.read().unwrap();
    assert_eq!(r1.len(), r2.len());
}

// Only one writer, and only once every reader has released.
data.write().unwrap().push(4);
assert_eq!(data.read().unwrap().len(), 4);
}

Status

Done — Phase 2. Full design write-up, including exactly why the write guard's unlock can't be a blind store(0, ..): docs/mid-platform.md, "sync/rwlock.rs."

sync::Once / OnceLock

Run something exactly once, or lazily initialize a value exactly once, safely across any number of racing threads.

What it does

std::sync::{Once, OnceLock, OnceState} directly when the std feature is on. Otherwise a hand-rolled fallback built on top of this same crate's own sync::Mutex rather than a from-scratch atomic state machine — the actual mutual exclusion during initialization is just the crate's already-tested Mutex. A separate atomic completion flag, checked before ever touching the lock, keeps OnceLock::get() fully lock-free once a value exists, so reading an already-initialized value never pays a locking cost. Once is a thin wrapper around OnceLock<()> — "has this run yet" is exactly what an initialized-or-not unit cell already answers. Neither type ever poisons; OnceState::is_poisoned() always returns false.

Example usage

#![allow(unused)]
fn main() {
use mid_platform::sync::{Once, OnceLock};

// Run initialization exactly once, however many times/threads call it.
static INIT: Once = Once::new();
INIT.call_once(|| {
    // one-time setup
});

// Lazily compute and cache a value exactly once.
static CONFIG: OnceLock<u32> = OnceLock::new();
let value = CONFIG.get_or_init(|| expensive_computation());
assert_eq!(*value, *CONFIG.get().unwrap());

fn expensive_computation() -> u32 { 42 }
}

Status

Done — Phase 2. Full design write-up, including why the four-state spin::Once-style atomic protocol was deliberately not ported: docs/mid-platform.md, "sync/once.rs."

Also callable from C: mid_platform_once_{new,free,call,is_completed} — see docs/mid-platform.md, "ffi.rs."

sync::LazyLock

A value that computes itself from a closure the first time it's actually used, safely across any number of racing threads.

What it does

std::sync::LazyLock directly when the std feature is on. Otherwise a fallback built directly on top of this crate's own OnceLock, plus cell::SyncUnsafeCell to hold the initializer closure until it's consumed. No new unsafe synchronization exists in this type at all — every guarantee it needs comes straight from OnceLock::get_or_init, which already guarantees the initializer runs on at most one thread, at most once. Dereferencing a LazyLock triggers initialization on first access and returns the cached value on every access after that.

Example usage

#![allow(unused)]
fn main() {
use mid_platform::sync::LazyLock;

static CONFIG: LazyLock<Vec<u32>> = LazyLock::new(|| {
    // Runs once, on whichever thread first dereferences CONFIG.
    (0..10).collect()
});

assert_eq!(CONFIG.len(), 10);
assert_eq!(CONFIG[0], 0);
}

Status

Done — Phase 2. Full design write-up, including why std::sync::LazyLock's real union-based layout wasn't ported: docs/mid-platform.md, "sync/lazy_lock.rs."

sync::Barrier

Blocks a fixed number of threads until they've all reached the same point, then releases them all together.

What it does

std::sync::{Barrier, BarrierWaitResult} directly when the std feature is on. Otherwise a fallback ported from spin::Barrier's real algorithm (read fresh from its own source) onto this crate's own sync::Mutex: a thread count and a generation counter behind a plain lock, not a bespoke atomic protocol. Every thread that calls wait() blocks until the last thread arrives; that last thread resets the count and bumps the generation, which wakes everyone else. A barrier is reusable across generations — calling wait() on it again after everyone's been released works the same way a second time.

Example usage

#![allow(unused)]
fn main() {
use mid_platform::sync::Barrier;
use std::sync::Arc;
use std::thread;

let barrier = Arc::new(Barrier::new(4));
let handles: Vec<_> = (0..4)
    .map(|_| {
        let barrier = Arc::clone(&barrier);
        thread::spawn(move || {
            // ... each thread's own work ...
            barrier.wait(); // blocks until all 4 threads reach this line
            // ... all 4 threads continue together from here ...
        })
    })
    .collect();
for h in handles {
    h.join().unwrap();
}
}

Status

Done — Phase 2, the lowest-priority primitive of this group (rarely used). Full design write-up: docs/mid-platform.md, "sync/barrier.rs."

Also callable from C: mid_platform_barrier_{new,free,wait} — see docs/mid-platform.md, "ffi.rs."

sync::Arc / Weak

Thread-safe reference counting — the same Arc/Weak every Rust codebase already reaches for, made available with or without std.

What it does

A plain re-export of alloc::sync::{Arc, Weak}, gated behind this crate's alloc feature. Upstream bevy_platform needs portable-atomic-util here only on targets lacking pointer-width native atomics; none of mid-engine's real targets (x86_64, aarch64, wasm32) are missing that, so this is zero-cost — no fallback implementation, no dependency, just the real standard-library type.

Example usage

#![allow(unused)]
fn main() {
use mid_platform::sync::Arc;

let shared = Arc::new(vec![1, 2, 3]);
let handle = Arc::clone(&shared);
assert_eq!(shared.len(), handle.len());
assert_eq!(Arc::strong_count(&shared), 2);
}

Status

Done — Phase 1. Design write-up: docs/mid-platform.md's dependency table entry for portable-atomic-util (a Phase 1 file — predates this doc's per-module ### sync/<file>.rs sections, which start with Phase 2).

hash

A fast, non-cryptographic hasher and a deterministic BuildHasher for it — for HashMap/HashSet keys you control, not keys an attacker chooses.

What it does

FxHasher is the fold/multiply hash rustc itself uses for its own compiler data structures: rotate, xor in the next word, multiply by a fixed constant, eight bytes at a time. It is fast because it does very little per word, and weak for the same reason. FixedHasher is a BuildHasher that hands out FoldedFxHashers from the same fixed starting state every time, so the same key hashes to the same value on every run and every platform (the state is u64 on every target, including wasm32). fixed_hash_one hashes a single value with it.

FoldedFxHasher is FxHasher plus one step at the end: a 64x64 to 128-bit multiply with the two halves XORed together. Plain Fx ends in a multiplication, so its low output bits depend only on the low bits of the key, and a table that picks buckets from the low bits collides heavily on keys that differ only higher up (i << 12, aligned addresses, an entity id with its generation in the high half). The folded multiply lets every key bit reach the low bits. The bare FxHasher is still there, unchanged and bit-for-bit equal to rustc-hash 1.1.0, for consumers that spread the hash themselves. Figures and the measurement behind the choice: the collections page and docs/mid-platform.md, "hash.rs."

There is no RandomState equivalent, on purpose. A fold/multiply hash can't be made DoS-resistant by randomizing its seed, so a randomized version would only look safer than it is. Anything that hashes untrusted input should use std's own RandomState.

Example usage

#![allow(unused)]
fn main() {
use std::collections::HashMap;
use mid_platform::hash::{fixed_hash_one, FixedHasher};

// As the hasher of a HashMap keyed by data the engine generates itself.
let mut cells: HashMap<(i32, i32), u32, FixedHasher> =
    HashMap::with_hasher(FixedHasher);
cells.insert((3, -4), 7);
assert_eq!(cells[&(3, -4)], 7);

// Hashing one value directly. Same result every run.
assert_eq!(fixed_hash_one("mid-engine"), fixed_hash_one("mid-engine"));
}

Status

Done — Phase 3, hasher half. FxHasher matches the published rustc-hash 1.1.0 on 64-bit targets, apart from negative i8/i16/i32 values. FixedHasher's folded-multiply finish is confirmed on CI: it fixes the collisions, costs 2.7x on a raw u64 hashing loop and 1.7x in a map insert-and-lookup loop (nothing measurable on strings), and is still 6.9x and 2.3x faster than SipHash on those two. Its output is a property of this crate version, not a stable format. The maps that use it are on the collections page. Callable from C: mid_platform_fixed_hash_{bytes,u64}. Full design write-up, including why this is a second copy of mid-collections's hasher rather than a dependency on it: docs/mid-platform.md, "hash.rs."

collections

HashMap and HashSet with the deterministic FixedHasher as the default hasher, in two implementations behind one API: std's own when std is on, a safe-code table of this crate's when it is off.

What it does

With the std feature (on by default), collections::HashMap and HashSet are aliases for std::collections' types, with FixedHasher filled in as the default hasher. std's map is hashbrown underneath, so that is hashbrown's speed with no dependency and no unsafe code written here.

Without std but with alloc, the same two names are aliases for OpenHashMap and OpenHashSet: linear probing over a power-of-two table, up to 3/4 full, removal by shifting the cluster back instead of leaving tombstones, all in safe code. Both are always reachable under their own names, so they can be tested and measured against std's map.

Both implementations share the part of std's map API they have in common, with std's signatures, so code written against collections::HashMap builds in either configuration. Two consequences:

  • There is no new(). std only provides it for RandomState. Use HashMap::default() (with the type known), HashMap::with_hasher(FixedHasher), or HashMap::with_capacity_and_hasher(n, FixedHasher).
  • FixedHasher is deterministic and not DoS-resistant. Keys an attacker chooses belong in a std map with its own RandomState.

Example usage

#![allow(unused)]
fn main() {
use mid_platform::collections::{HashMap, HashSet};
use mid_platform::hash::FixedHasher;

let mut counts: HashMap<&str, u32> = HashMap::with_hasher(FixedHasher);
for word in ["a", "b", "a"] {
    *counts.entry(word).or_insert(0) += 1;
}
assert_eq!(counts[&"a"], 2);

let seen: HashSet<u32> = (0..10).collect();
assert!(seen.contains(&3));
}

Status

Done: Phase 3, map half. 35 tests plus 2 doctests, run in default features and in the alloc-only configuration; 17 deliberate bugs each caught by at least one test. All three feature configurations pass on CI.

One thing that was wrong, and the fix: FixedHasher used to end in a plain multiplication, so its low output bits depended only on the key's low bits. CI showed that keys sharing their low bits (i << 12, aligned addresses) made the std alias 8x to 17x slower than std's own default map on insert, lookup, and remove, and 18x to 49x slower than OpenHashMap. FixedHasher now ends in a folded multiply (see the hash page), so the alias behaves on those keys: CI shows it at the same speed on sequential, i << 12, and i << 32 keys, 16x to 63x faster than before on the strided ones. On ordinary sequential keys the fix cost the alias's grow-inserts 1.75x and left lookups unchanged; it is still 2x to 3.7x faster than std's own default map everywhere. OpenHashMap was never exposed to it: it indexes by the top bits after one more multiply. Details and the pre-fix figures: docs/mid-platform.md, "collections/" and "Benchmarks."

mid-net

Reliable UDP transport with a hand-rolled wire codec, targeting a 128 Hz tick rate, plus a DixScript-based transport layer (native via quinn, and a wasm32 browser variant). Awaiting ECS integration.

Status: in progress.

mid-ecs

Data-oriented Entity Component System using a hybrid Archetype-core / Sparse-set-shell layout, built on mid-collections. Benchmarked directly against bevy_ecs (see Benchmarks).

Status: started — archetype core and sparse shell both underway.

mid-geom

Geometry algorithms: BVH construction, Delaunay triangulation, convex hull, mesh operations. Depends on mid-math.

Status: planned.

mid-trace

Distributed tracing. Depends on mid-common.

Status: planned.

Performance Targets

SystemFrequencyBudgetStatus
Network tick (mid-net)128 Hz7.8 ms / tickNot started
Physics (mid-ecs)60 Hz16.6 ms / tickNot started
Max entities (mid-ecs)100,000+ per core—Not started
Log hot path (mid-log)0 µszero frame impactImplemented
Math primitives (mid-math)SSE216-byte aligned Vec3/4/QuatIn progress

Per the Design Mandates, every claim here should eventually link to a real benchmark build number on the Benchmarks page rather than stand as an unverified target. Until a row does, treat it as a target, not a measured result.

Contributing & CI

Manual CI only

Every test and benchmark workflow in this repository is workflow_dispatch only. Nothing runs automatically on push, pull request, or a schedule — tests and benchmarks take real time and shouldn't run on every commit. Run a workflow from the repository's Actions tab when you actually want its results.

Each workflow writes a real, structured summary to its own run's Job Summary (parsed from the raw test/bench output, not a raw log dump), and uploads the raw log plus a JSON results file as a build artifact.

Publishing the site

This site itself deploys the same way: Deploy Site (.github/workflows/deploy-site.yml) is also workflow_dispatch only. It rebuilds this book, gathers the latest JSON results each crate's own test workflow produced, and deploys the whole thing to Cloudflare Pages. Running a crate's test workflow updates that crate's own results; running Deploy Site afterward is what actually publishes them here.

Documentation conventions

  • Every source file starts with a NOTICE header comment pointing to its crate's own docs/<crate-name>.md file and section there. Inline code comments describe what/how only — no fix history or decision logs inline.
  • Each crate's docs/<crate-name>.md (in the repository's top-level docs/, not nested per crate) holds per-file sections, a CI/workflow reference section, and a bottom "Fixes and Problems" section.
  • This book (web/site/) is the separate, user-facing counterpart to those internal docs — see Introduction for the split.