crcbl_core/
lib.rs

1//! Core primitives shared by every Crucible crate.
2//!
3//! Nothing here depends on a backend, a window, or a renderer — this is the
4//! vocabulary layer that the rest of the engine is written in:
5//!
6//! * [`handle`] — [`Handle`], a typed generational id, and [`Pool`], the slot
7//!   arena that issues and invalidates them.
8//! * [`world`] — [`WorldPos`], the sector-tiled absolute position that every
9//!   simulated thing in the engine uses. Plain `Vec3` is *only* ever
10//!   camera-relative render space; see [`WorldPos::relative_to`].
11//! * [`alloc`] — [`FrameArena`], a fixed-capacity bump allocator for per-frame
12//!   transient data.
13//! * [`time`] — [`FrameClock`], the fixed-timestep server tick accumulator plus
14//!   variable render delta, [`TickId`], and [`EventTime`], the stated-epoch
15//!   timestamp every input event carries.
16//! * [`input`] — the names for keys, buttons and axes ([`KeyCode`],
17//!   [`Keysym`](input::Keysym), [`PointerButton`](input::PointerButton),
18//!   [`Modifiers`](input::Modifiers)). Vocabulary only: the *event* enum lives
19//!   in `crcbl-shell`, which is the only crate that produces one.
20//! * [`log`] — stderr logging behind the [`log`](::log) facade, filtered by
21//!   `CRCBL_LOG`, with the console's log ring in [`log::console`] and the `log`
22//!   command that sets the filter while the engine runs.
23//! * [`player`] — [`PlayerId`], who a player is across sessions: drawn once by
24//!   a client, presented in every hello, and self-asserted — see the module
25//!   docs for how little an open server can trust it.
26//! * [`rand`] — deterministic values from an index, for simulations that
27//!   replay. Deliberately not a generator; see the module docs for why every
28//!   sample independently arrived at the same shape.
29//! * [`schedule`] — [`FixedRateSchedule`](schedule::FixedRateSchedule),
30//!   per-agent sampling at a fixed rate and a staggered phase, reporting each
31//!   sample at its exact time inside the tick. Sample times come from an
32//!   integer index, never an accumulated sum; see the module docs.
33//! * [`srgb`] — the sRGB transfer function, [`decode`](srgb::decode) to linear
34//!   light and [`encode`](srgb::encode) back, for colour authored in sRGB.
35//! * [`stats`] — [`percentile_of`](stats::percentile_of) and
36//!   [`MIN_PERCENTILE_SAMPLES`](stats::MIN_PERCENTILE_SAMPLES), the nearest-rank
37//!   arithmetic the debug panel's budget row and `crcbl bench` both report
38//!   through. No mean, on purpose; see the module docs.
39//! * [`mod@trace`] — [`Span`](trace::Span) and [`counter`](trace::counter), the CPU
40//!   half of the profiler: scoped spans with static names, nesting freely and
41//!   carrying the thread they ran on, plus named `u64` counters. Compiled into
42//!   every build and gated at runtime; see the module docs for what that costs.
43//! * [`trig`] — [`sin`](trig::sin), [`cos`](trig::cos),
44//!   [`atan`](trig::atan) and [`atan2`](trig::atan2) in `f64`, built from
45//!   operations IEEE-754 pins down so a simulation that calls them reaches the
46//!   same bits on every target. No platform `libm`; see the module docs.
47//! * [`hash`] — FNV-1a ([`fnv1a_32`](hash::fnv1a_32),
48//!   [`fnv1a_64`](hash::fnv1a_64) and the [`Fnv1a64`](hash::Fnv1a64) hasher),
49//!   for ids and digests that must be the same on every target and run.
50//! * [`surface`] — [`SurfaceTarget`], the native window handles the shell
51//!   produces and a HAL backend consumes. It lives here, and not in either of
52//!   those crates, because neither may depend on the other; see the module docs
53//!   for the dependency argument.
54
55pub mod alloc;
56pub mod bounds;
57pub mod handle;
58pub mod hash;
59pub mod input;
60pub mod log;
61pub mod logarithm;
62pub mod player;
63pub mod rand;
64pub mod schedule;
65pub mod srgb;
66pub mod stats;
67pub mod surface;
68pub mod time;
69pub mod trace;
70pub mod trig;
71pub mod world;
72
73/// Everything this crate exposes to the debug console.
74///
75/// One list per crate, gathered by the engine at one seam — debug-console
76/// decision 2 in `docs/notes/tooling.md`. It holds `log`, the command that
77/// reads and sets the live filter; `tests/console_table.rs` is what keeps it in
78/// step with what the source actually declares.
79#[must_use]
80pub fn console_table() -> crcbl_console::Table {
81    crcbl_console::table![cmd crate::log::log]
82}
83
84pub use alloc::FrameArena;
85pub use handle::{Handle, Pool};
86pub use input::KeyCode;
87pub use player::PlayerId;
88pub use surface::SurfaceTarget;
89pub use time::{EventTime, FrameClock, TickId};
90pub use world::{SECTOR_SIZE, WorldPos};
crcbl_core/lib.rs

crcbl_core/
lib.rs
