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, andBox<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-fieldMovingPtrs via thedeconstruct_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:
cell—SyncCell,SyncUnsafeCellsync::atomic— plain re-export ofcore::sync::atomicsync::Mutex—MutexGuardsync::RwLock—RwLockReadGuard,RwLockWriteGuardsync::Once/OnceLock—OnceStatesync::LazyLocksync::Barrier—BarrierWaitResultsync::Arc/Weak— plain re-export ofalloc::synchash—FxHasher,FoldedFxHasher,FixedHasher,fixed_hash_onecollections—HashMap,HashSet,OpenHashMap,OpenHashSet
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().stdonly provides it forRandomState. UseHashMap::default()(with the type known),HashMap::with_hasher(FixedHasher), orHashMap::with_capacity_and_hasher(n, FixedHasher). FixedHasheris deterministic and not DoS-resistant. Keys an attacker chooses belong in astdmap with its ownRandomState.
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
| System | Frequency | Budget | Status |
|---|---|---|---|
Network tick (mid-net) | 128 Hz | 7.8 ms / tick | Not started |
Physics (mid-ecs) | 60 Hz | 16.6 ms / tick | Not started |
Max entities (mid-ecs) | 100,000+ per core | — | Not started |
Log hot path (mid-log) | 0 µs | zero frame impact | Implemented |
Math primitives (mid-math) | SSE2 | 16-byte aligned Vec3/4/Quat | In 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
NOTICEheader comment pointing to its crate's owndocs/<crate-name>.mdfile 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-leveldocs/, 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.