crcbl-core 0.15.0

Crucible engine core: ids, handles, arenas, time, logging
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

//! Core primitives shared by every Crucible crate.
//!
//! Nothing here depends on a backend, a window, or a renderer — this is the
//! vocabulary layer that the rest of the engine is written in:
//!
//! * [`handle`] — [`Handle`], a typed generational id, and [`Pool`], the slot
//!   arena that issues and invalidates them.
//! * [`world`] — [`WorldPos`], the sector-tiled absolute position that every
//!   simulated thing in the engine uses. Plain `Vec3` is *only* ever
//!   camera-relative render space; see [`WorldPos::relative_to`].
//! * [`alloc`] — [`FrameArena`], a fixed-capacity bump allocator for per-frame
//!   transient data.
//! * [`time`] — [`FrameClock`], the fixed-timestep server tick accumulator plus
//!   variable render delta, [`TickId`], and [`EventTime`], the stated-epoch
//!   timestamp every input event carries.
//! * [`input`] — the names for keys, buttons and axes ([`KeyCode`],
//!   [`Keysym`](input::Keysym), [`PointerButton`](input::PointerButton),
//!   [`Modifiers`](input::Modifiers)). Vocabulary only: the *event* enum lives
//!   in `crcbl-shell`, which is the only crate that produces one.
//! * [`log`] — stderr logging behind the [`log`](::log) facade, filtered by
//!   `CRCBL_LOG`, with the console's log ring in [`log::console`] and the `log`
//!   command that sets the filter while the engine runs.
//! * [`player`] — [`PlayerId`], who a player is across sessions: drawn once by
//!   a client, presented in every hello, and self-asserted — see the module
//!   docs for how little an open server can trust it.
//! * [`rand`] — deterministic values from an index, for simulations that
//!   replay. Deliberately not a generator; see the module docs for why every
//!   sample independently arrived at the same shape.
//! * [`schedule`] — [`FixedRateSchedule`](schedule::FixedRateSchedule),
//!   per-agent sampling at a fixed rate and a staggered phase, reporting each
//!   sample at its exact time inside the tick. Sample times come from an
//!   integer index, never an accumulated sum; see the module docs.
//! * [`srgb`] — the sRGB transfer function, [`decode`](srgb::decode) to linear
//!   light and [`encode`](srgb::encode) back, for colour authored in sRGB.
//! * [`stats`] — [`percentile_of`](stats::percentile_of) and
//!   [`MIN_PERCENTILE_SAMPLES`](stats::MIN_PERCENTILE_SAMPLES), the nearest-rank
//!   arithmetic the debug panel's budget row and `crcbl bench` both report
//!   through. No mean, on purpose; see the module docs.
//! * [`mod@trace`] — [`Span`](trace::Span) and [`counter`](trace::counter), the CPU
//!   half of the profiler: scoped spans with static names, nesting freely and
//!   carrying the thread they ran on, plus named `u64` counters. Compiled into
//!   every build and gated at runtime; see the module docs for what that costs.
//! * [`trig`] — [`sin`](trig::sin) and [`cos`](trig::cos) in `f64`, built
//!   from operations IEEE-754 pins down so a simulation that calls them reaches
//!   the same bits on every target. No platform `libm`; see the module docs.
//! * [`hash`] — FNV-1a ([`fnv1a_32`](hash::fnv1a_32),
//!   [`fnv1a_64`](hash::fnv1a_64) and the [`Fnv1a64`](hash::Fnv1a64) hasher),
//!   for ids and digests that must be the same on every target and run.
//! * [`surface`] — [`SurfaceTarget`], the native window handles the shell
//!   produces and a HAL backend consumes. It lives here, and not in either of
//!   those crates, because neither may depend on the other; see the module docs
//!   for the dependency argument.

pub mod alloc;
pub mod bounds;
pub mod handle;
pub mod hash;
pub mod input;
pub mod log;
pub mod logarithm;
pub mod player;
pub mod rand;
pub mod schedule;
pub mod srgb;
pub mod stats;
pub mod surface;
pub mod time;
pub mod trace;
pub mod trig;
pub mod world;

/// Everything this crate exposes to the debug console.
///
/// One list per crate, gathered by the engine at one seam — debug-console
/// decision 2 in `docs/notes/tooling.md`. It holds `log`, the command that
/// reads and sets the live filter; `tests/console_table.rs` is what keeps it in
/// step with what the source actually declares.
#[must_use]
pub fn console_table() -> crcbl_console::Table {
    crcbl_console::table![cmd crate::log::log]
}

pub use alloc::FrameArena;
pub use handle::{Handle, Pool};
pub use input::KeyCode;
pub use player::PlayerId;
pub use surface::SurfaceTarget;
pub use time::{EventTime, FrameClock, TickId};
pub use world::{SECTOR_SIZE, WorldPos};