What is deterministic is made at build time by the game's own code (`ludic bake`) and read at run
time. baked.ludic, baked_hash.ludic, baked_stream.ludic:
- The header, 32 bytes little-endian: "LBAK" | u32 format (BAKE_FORMAT 1) | u32 generator version |
u32 payload offset | u64 inputs hash | u64 payload length | then the key (UTF-8, zero-padded to 8),
then the payload at its offset, whose layout is the bake's own.
- bake_write(path, key, version, inputs_hash, payload, n) makes the directories and writes it;
bake_inputs_hash(inputs) is FNV-1a 64 over each space-separated input: its path, a 0, its bytes.
- baked_open(path, key, version) -> []byte: the payload as a view of the file (no copy), or null for
a missing file or another format, key or version. The runtime never hashes inputs; `ludic bake
--check` holds a baked file to them at build time.
- baked_open_range(path, key, version) -> BakedFile kept open (header checked once),
baked_read(bf, at, n, into) -> count read into the caller's buffer from payload offset `at`
(held to the buffer and the payload), baked_len, baked_close: a streamed bake (placements by chunk,
terrain by tile) with nothing made per read. Pack-aware through file_open: on macOS a packed entry
is an fmemopen over the mapped pack (a seek is free), on Windows a temporary copy of the entry made
once when it is opened.
- baked_path(map, file), bake_missing(bake_st, key) (a dev build's line, once a key).
tests/baked_test.ludic: a payload round-trips for its key and version only, a streamed read at an
offset and one past the end, the inputs hash follows path and bytes. Written, type-checked, not run
(compile-only rule).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A streamed world loads and lets go of a chunk's entities together, so a chunk is a first-class
group: chunk_of(x, z, size) packs a chunk's cell into an int, tb_remove_all(tb, ix, v) removes every
row an index files under one value (the observers told of each). IntIndex kept one list per value
up to the largest, which a packed chunk number (hundreds of millions) turned into hundreds of
millions of empty lists and a 12 GB test run; a value past 1024 now gets its slot through an IntMap,
so a sparse value costs one list.
ludic.things files every Thing under its 256 m chunk (TH_CHUNK), kept by every move;
things_chunk_count and things_drop_chunk (the port and the facts told of each removal, as
thing_remove tells them) are what the memory budget's streamed chunks ask. The moves are their own
file (moves.ludic). Tests: ludic.base 35, ludic.things 8, all under a 2 GB cap (24 MB peak).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tb_on_add / tb_on_remove take a fn(int) (its states supplied, like a system's) told each handle as
its row is made and before it goes (ecs_hooks.ludic), so what follows a table - a drawing, a
message - does so without a scan. Every row's tick now also stamps its 64-row block, and
tb_changed_since / tb_added_since skip the blocks nobody wrote since: a delta over a large table
costs the blocks that moved. A row moved into a removal's gap keeps its own tick (it was not
written); a removal is told by the hook. ecs_test holds both. The ludic.wildlife table
(5ac3d48, written while builds were held) now builds and passes its 19 tests.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A mechanic that keeps many of something keeps them as rows of a Table<T> rather than a list it
scans. Removal swaps the last row in; a handle (22-bit slot, 9-bit generation) goes stale when its
entity is removed. tb_set_f / tb_set_xz / tb_set_i stamp a change tick and refile the row in every
index over that column in O(1): tb_grid (a doubly linked spatial hash, rings outward for nearest,
rehashing as it grows), tb_index (a cached query: the rows of each value of a kind column, gated by
an active column), tb_nearest_of / tb_within_of (a rare kind from its own list), tb_nearest_where
(a predicate on the record), tb_within_recs (into the caller's list), tb_changed_since /
tb_added_since, IntMap. No question allocates or writes: Ludic frees nothing, and the old lists'
per-call copies leaked every frame.
ludic.things keeps its Things as a Table<Thing> with x, z, kind and active as columns; every verb
writes the record and the row together (a Thing carries its handle and table, so thing_hide(t)
still needs no state), thing_set_on / thing_set_xz / thing_place_at are the silent forms the game
used to do by assignment, and things_verify holds the columns against the records.
things_near(_of) fill a caller's list, thing_of_kind walks a kind, things_count_of counts one, and
things_tick visits only the kinds that tick. thing_find answers the first-placed by uid.
Against a []Record scanned (M4 Pro): nearest 0.37 / 1.5 / 7.2 us at 10k / 100k / 1M (list 30 /
307 / 3075), by id 0.09 us at 100k (list 17), a move refiled in 11-44 ns. ecs_fuzz_test holds the
grid, the kind index and the record queries against a scan through 9000 random changes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ludic.clock, .effects, .inventory, .wallet, .weather and .tracks say
'uses ludic_base' (ludic.base uses nothing). ClockWorld, PackRules,
WeatherWorld and TracksWorld are export ports whose defaults are the old
fallbacks; clock_bind, inv_bind, weather_bind and tracks_bind are gone,
and the tests bind their fakes. The base README's toy does the same.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A mechanic package depends on ludic.base and nothing else: ports (records of
function values for now) for questions, queues for facts, verbs for changes,
phases for order and its own versioned save section. The runner inits, resets,
saves and loads systems in the order added and ticks them phase by phase; a
missing save section is a reset. Tests for each piece and a worked route
between two toy mechanics live under tests/. The old ludic.core (engine ECS
components) is used by examples/library and stays.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
