Crate bevy_grimoire_core

Expand description

bevy_grimoire_core — the engine-free half of world building.

Constraint IR, solver backends, Wave Function Collapse, Poisson/Delaunay geometry, and the seeded RNG they all draw from. Nothing here imports bevy, and nothing here knows what an SCP is.

§Why this is a crate and not a module

It always was engine-free — placement/ir.rs has carried the sentence “Nothing here imports bevy::” since long before this crate existed, and wfc.rs, geom.rs and scatter.rs each say the same about themselves. But a comment cannot fail a build. Now the manifest can: bevy_grimoire_core depends on serde, ron, rand and rand_chacha, so reaching for a bevy type or a game concept from in here does not compile.

That matters because three consumers need this code and only one of them is the game: the game itself, the offline search (bin/train), and the standalone editor described in docs/2026-08-03-emerge-mapper-plan.md. The editor is why the split happened now.

§The module layout is deliberately unchanged

placement::ir, placement::solver, placement::solvers, placement::scatter and placement::manifest keep the paths they had inside the game, so every crate::placement::ir::… inside these files still resolves and the move is reviewable as a pure git mv. The game re-exports them at their old paths for the same reason — a workspace split that also rewrites a thousand import lines is a split nobody can diff.

§What stayed behind, and why

placement::furnish is the Bevy boundary of the placement stack (it spawns entities); placement::mod binds to the game’s run lifecycle; placement::anomalies is SCP content. Those are the game’s, and ir.rs:7 already named furnish.rs as the boundary before the split.

Re-exports§

pub use bevy_grimoire_rng as rng;

Modules§

adjacency: Do the tiles the author placed agree with the tokens the author declared?
atomic_file: The one way the editor writes a file a person or a running game may read: a reader sees the old file or the new one, never a mix (#199, H2).
census: Every count, computed from the catalog, in one place.
clips: Reading what a GLB’s animations actually contain — names, durations, root motion, and the two numbers that are otherwise measured by hand.
composition: A named, reusable group of placements — and the one function that turns a reference to one back into ordinary map rows.
constraints: A mid-level constraint API over Boolean variables, and the grid rules written against it.
convert: Turning the two shipped schemas into descriptors, without losing anything that matters or carrying anything that does not.
data_files: Game data files the editor may tune: a registry and type-keeping leaf edits.
descriptor: The asset descriptor — one schema for what a mesh is, where it may go, and what it offers.
destructible: destructible.ron and destructible/<piece>.bake.ron: which pieces of a project break, and the chunks each one breaks into (#108).
draw_order: Which flat piece lies on top where two of them share ground.
family: family.ron: which of the owner’s family crates a project uses.
format_version: The version a saved format carries, and what reading a file of another one means (#202, H5 step 4).
gait: The gait cadence policy — the one function that turns ground speed into cycles per second.
geom: Hand-rolled computational geometry for the graph dungeon topology (Topology::Graph): Poisson-disk site sampling (Bridson 2007, “Fast Poisson Disk Sampling in Arbitrary Dimensions”) + an incremental Bowyer–Watson Delaunay triangulation, then a degree cap for the u32-masked graph collapse. Engine- free (no Bevy) and fully deterministic — every random choice flows from the caller’s DetRng, so a seed reproduces the same layout. f64 throughout for a bit-reproducible in-circle predicate.
glb: Measuring a mesh — the numbers a descriptor records, taken from the file rather than by hand.
grammar: Learn a map’s grammar, then continue it — WFC over what the author already placed.
grid: The authoring grid — one definition of what a cell is.
heightfield: A heightfield a map’s ground is sculpted into (#99, F3).
image_header: The header of a reference image, read well enough to say whether the file is the picture its name claims (#200, H3, kind reference_images).
import: Importing a mesh — measure it, propose a descriptor, and say what is wrong with it.
kits: Which directory provides which namespace — the project’s binding, and the loader that reads it.
library: A library — every descriptor a project can place, in one file, validated together.
live: Live editing’s engine-free half: notice that a project changed on disk, and say what changed.
map: The map — what is placed where, and what can be done there.
naming: Names that are also filenames — one spelling, forced at the point of entry.
note_agent: agent.ron: the command Send starts for the notes (#94).
notes: Notes for agents: the data, its file beside the map, and the rules that keep it honest.
placement: The engine-free placement stack — the constraint problem and the solvers that answer it.
plan: An agent’s plan: a checklist with a status per item, kept beside the map (E-069).
play: play.ron: how a project runs its game (#97).
plot: A raster the bench can draw curves into — RGBA8 pixels and nothing else.
policy: The project’s layer over the library — where one game’s architecture goes.
problem: One shape for a message that says something went wrong (UI-05, docs/ui/vision.md §2 and §7).
project_data: Read a project’s data at runtime, the way a game does: every file the editor writes, in one call, validated against each other.
range: Expressive-range metrics over a solved cell grid — enclosure and opening density.
references: Reference images as project data (E-075): the pictures a person points at with “like this”.
relations: Relations, not coordinates (#137, research lens #2).
reload: The reload contract: every kind of file the editor writes (and the hand-authored files it reads), and what a running program does when one changes on disk.
reload_check: Check a file’s text against its kind before anything applies it (#200, H3).
repetition: Which repeats a player will notice (#136, research lens #5).
rig_check: The four checks, one policy, both consumers.
rigs: What each rig’s clips are and how they play — the manifest that replaces six hand-written tables of magic indices.
rigs_edit: Editing one rig inside rigs.ron without destroying the rest of it.
ron_surgery: Editing RON without destroying it — the machinery both of this repo’s writers were built on.
rules: Block rules: what a laid-out block of tiles has to satisfy, shared by the editor and the game.
run: A run — one piece, repeated along a path, at the piece’s own pitch.
session: Per-turn measurement (#157, research lens #7–#9).
smart: Smart objects — who can do what, where, and with whom.
stack: What rests on what, and how high that puts it.
standards: Kit standards: the project’s dimensions every kit piece must meet (#138, research lens #4).
trust: What a person has allowed a project to run.
vocab: Closed token vocabularies — what a descriptor’s kind, effects and look are allowed to say.
volume: A map’s carved and added volume, saved beside the map as its edit list (#101, F5).
water: Where water comes from and goes, saved beside a map (#100, F4).
wfc: Engine-free Wave Function Collapse generator for a coarse dungeon room graph.

Functions§

smoothstep: Hermite ease between two edges. Pure math, so it lives here rather than in a crate that has a renderer — bevy_grimoire_anim’s weight blending and the game’s own util both take it from one place.