From bf73f7edafeb552247b276125e8d3fdfc7e45937 Mon Sep 17 00:00:00 2001 From: Orkuncakilkaya Date: Fri, 25 Sep 2026 04:54:43 +0300 Subject: [PATCH] feat(ludic.tracks): prints, their age and reading them as a mechanic package A ring of prints per kind; a port for the trip's time, the reader's tier, a bearing in words and a hook the game draws each print through. A read is a TrackRead fact on tracks_reads() every time and a count the first time; other sign is told with tracks_note. The count and last bearing are its save section. Co-Authored-By: Claude Opus 5.5 --- packages/ludic.tracks/README.md | 53 +++++++ packages/ludic.tracks/config.ludic | 37 +++++ packages/ludic.tracks/index.ludic | 11 ++ packages/ludic.tracks/leave.ludic | 37 +++++ packages/ludic.tracks/package.ludic | 5 + packages/ludic.tracks/queries.ludic | 47 ++++++ packages/ludic.tracks/read.ludic | 54 +++++++ packages/ludic.tracks/state.ludic | 66 ++++++++ packages/ludic.tracks/system.ludic | 31 ++++ packages/ludic.tracks/tests/tracks_test.ludic | 146 ++++++++++++++++++ 10 files changed, 487 insertions(+) create mode 100644 packages/ludic.tracks/README.md create mode 100644 packages/ludic.tracks/config.ludic create mode 100644 packages/ludic.tracks/index.ludic create mode 100644 packages/ludic.tracks/leave.ludic create mode 100644 packages/ludic.tracks/package.ludic create mode 100644 packages/ludic.tracks/queries.ludic create mode 100644 packages/ludic.tracks/read.ludic create mode 100644 packages/ludic.tracks/state.ludic create mode 100644 packages/ludic.tracks/system.ludic create mode 100644 packages/ludic.tracks/tests/tracks_test.ludic diff --git a/packages/ludic.tracks/README.md b/packages/ludic.tracks/README.md new file mode 100644 index 00000000..b97054b5 --- /dev/null +++ b/packages/ludic.tracks/README.md @@ -0,0 +1,53 @@ +# ludic.tracks + +What animals leave on the ground: prints in a ring per kind, each remembering who left it, which +way it went and when, so a print can be read up close ("fresh elk tracks, heading north-west"). +Other sign - droppings, a legend's mark - is told to the package so every reading goes through +one queue and one count. Uses [`ludic.base`](../ludic.base/README.md) and nothing else. + +```ludic +import "ludic.tracks" +``` + +The package is the logic only. A kind is the game's number (a hoof, a paw); the game draws the +prints through the `placed` hook, which hands it the kind and the ring index, and the ring index +is stable until the ring comes round and writes over it. + +A print is read ONCE: reading it again is still a `TrackRead` fact (the game says what it is +again) but `first` is false and it counts nothing, so pressing a key over one print is not as +good as walking a trail. + +## The port + +```ludic +property TracksWorld { + now: fn() -> float # game hours counted from the start of the trip (unbound: 0) + skill: fn() -> int # the reader's tier; at tracks_config_reading's name_at it names the animal + bearing: fn(float) -> string # a yaw in words, "" for none (a reader with no compass) + placed: fn(int, int) -> void # a print was put down at (kind, ring index): draw it +} +``` + +## API + +| | | +| --- | --- | +| `tracks_bind(w)`, `tracks_config(kinds, cap)`, `tracks_config_reading(name_at, fresh, recent)` | the port; how many kinds and how many prints of each; the skill that names the animal and the ages (hours) under which a print is fresh or recent | +| `tracks_leave(kind, x, z, yaw, sp, legend) -> int`, `tracks_leave_at(..., made)` | a print, now or at another machine's time; returns its ring index | +| `tracks_clear()` | the ground forgets every print (a new world); the reader keeps what it learned | +| `tracks_nearest(x, z, r) -> int` | the nearest print within `r`, as a slot (`kind * cap + index`), or -1 | +| `tracks_read(slot)` | read a print: a fact every time, a count and the last bearing | +| `tracks_note(sp, source, legend, yaw, first)` | a sign that is not a print (`TRACK_SIGN`, `TRACK_SCAT`); the caller knows whether it is its first reading | +| `tracks_note_bearing(yaw)`, `tracks_set_read_count(n)` | the way the last thing went (a bed); the count outright (a test, an old save) | +| `tracks_kinds()`, `tracks_cap()`, `tracks_count(kind)`, `tracks_slot(kind, i)` | the rings | +| `tracks_x`, `tracks_z`, `tracks_yaw`, `tracks_sp`, `tracks_legend`, `tracks_made`, `tracks_age`, `tracks_was_read` (slot) | a print | +| `tracks_fresh_of(age)` | `TRACK_FRESH`, `TRACK_RECENT` or `TRACK_OLD` | +| `tracks_read_count()`, `tracks_last_yaw()`, `tracks_has_bearing()` | what the reader has learned | +| `tracks_reads() -> Queue` | the facts: `{ sp, source, kind, legend, age, fresh, yaw, named, bearing, first }` | +| `tracks_system() -> System` | `"tracks"`, `PH_SIMULATE`: reset, and its save section (the count and the last bearing; the prints are the ground's and are not saved) | + +## Tests + +```bash +ludic build packages/ludic.tracks/tests/tracks_test.ludic --headless -o /tmp/tracks_test && /tmp/tracks_test +``` diff --git a/packages/ludic.tracks/config.ludic b/packages/ludic.tracks/config.ludic new file mode 100644 index 00000000..0d2b7507 --- /dev/null +++ b/packages/ludic.tracks/config.ludic @@ -0,0 +1,37 @@ +# config.ludic - how many kinds of print, how many of each the ground remembers, how the reader +# reads, and the port's defaults +export function tracks_config(kinds: int, cap: int) -> void { + tk_kinds = kinds + tk_cap = cap + tk_ring = new []Track + tk_count = new []int + tk_next = new []int + for i in 0 .. kinds * cap { push(tk_ring, new Track) } + for k in 0 .. kinds { + push(tk_count, 0) + push(tk_next, 0) + } +} + +# a reader at `name_at` or above can tell the animal; a print is fresh under `fresh` hours old, +# recent under `recent`, and old after +export function tracks_config_reading(name_at: int, fresh: float, recent: float) -> void { + tk_name_at = name_at + tk_fresh_h = fresh + tk_recent_h = recent +} + +function tk_now() -> float { + if tk_world == null or tk_world.now == null { return 0.0 } + return tk_world.now() +} + +function tk_named() -> bool { + if tk_world == null or tk_world.skill == null { return true } + return tk_world.skill() >= tk_name_at +} + +function tk_bearing(yaw: float) -> string { + if tk_world == null or tk_world.bearing == null { return "" } + return tk_world.bearing(yaw) +} diff --git a/packages/ludic.tracks/index.ludic b/packages/ludic.tracks/index.ludic new file mode 100644 index 00000000..1489c88d --- /dev/null +++ b/packages/ludic.tracks/index.ludic @@ -0,0 +1,11 @@ +# ludic.tracks - a ring of prints per kind, each remembering who left it, which way it went and +# when; reading one is a fact on a queue, and the game draws them through a hook +module ludic_tracks +numbers float +import "ludic.base" +import "state.ludic" +import "config.ludic" +import "leave.ludic" +import "read.ludic" +import "queries.ludic" +import "system.ludic" diff --git a/packages/ludic.tracks/leave.ludic b/packages/ludic.tracks/leave.ludic new file mode 100644 index 00000000..e37c08ce --- /dev/null +++ b/packages/ludic.tracks/leave.ludic @@ -0,0 +1,37 @@ +# leave.ludic - a print put down. Each kind is a ring: past its cap the oldest is written over, and +# a slot written over is a new print, unread +function tk_ok(kind: int) -> bool { return tk_ring != null and kind >= 0 and kind < tk_kinds } + +# a print made at `made` game hours (another machine's, arriving here); the ring index, or -1 +export function tracks_leave_at(kind: int, x: float, z: float, yaw: float, sp: int, legend: bool, made: float) -> int { + if not tk_ok(kind) { return -1 } + var i = tk_next[kind] + if tk_count[kind] < tk_cap { + i = tk_count[kind] + tk_count[kind] = tk_count[kind] + 1 + } + tk_next[kind] = (i + 1) % tk_cap + let t = tk_ring[kind * tk_cap + i] + t.x = x + t.z = z + t.yaw = yaw + t.sp = sp + t.legend = legend + t.made = made + t.read = false + if tk_world != null and tk_world.placed != null { tk_world.placed(kind, i) } + return i +} + +export function tracks_leave(kind: int, x: float, z: float, yaw: float, sp: int, legend: bool) -> int { + return tracks_leave_at(kind, x, z, yaw, sp, legend, tk_now()) +} + +# the ground forgets every print (a new world) +export function tracks_clear() -> void { + if tk_ring == null { return } + for k in 0 .. tk_kinds { + tk_count[k] = 0 + tk_next[k] = 0 + } +} diff --git a/packages/ludic.tracks/package.ludic b/packages/ludic.tracks/package.ludic new file mode 100644 index 00000000..ba8cea8e --- /dev/null +++ b/packages/ludic.tracks/package.ludic @@ -0,0 +1,5 @@ +# ludic.tracks - what animals leave on the ground, how old it is, and reading it. Uses ludic.base +# and nothing else. See README.md. +package "ludic.tracks" +version "0.1.0" +kind source diff --git a/packages/ludic.tracks/queries.ludic b/packages/ludic.tracks/queries.ludic new file mode 100644 index 00000000..8749e468 --- /dev/null +++ b/packages/ludic.tracks/queries.ludic @@ -0,0 +1,47 @@ +# queries.ludic - what the world asks the ground. A slot is kind * cap + ring index. +export function tracks_kinds() -> int { return tk_kinds } +export function tracks_cap() -> int { return tk_cap } + +export function tracks_count(kind: int) -> int { + if not tk_ok(kind) { return 0 } + return tk_count[kind] +} + +export function tracks_slot(kind: int, i: int) -> int { return kind * tk_cap + i } + +export function tracks_x(slot: int) -> float { return tk_ring[slot].x } +export function tracks_z(slot: int) -> float { return tk_ring[slot].z } +export function tracks_yaw(slot: int) -> float { return tk_ring[slot].yaw } +export function tracks_sp(slot: int) -> int { return tk_ring[slot].sp } +export function tracks_legend(slot: int) -> bool { return tk_ring[slot].legend } +export function tracks_made(slot: int) -> float { return tk_ring[slot].made } +export function tracks_was_read(slot: int) -> bool { return tk_ring[slot].read } + +# game hours since it was made; never below 0 +export function tracks_age(slot: int) -> float { return Math.max(0.0, tk_now() - tk_ring[slot].made) } + +# the nearest print within `r` of (x, z), as a slot; -1 when there is none +export function tracks_nearest(x: float, z: float, r: float) -> int { + var best = r * r + var at = -1 + for k in 0 .. tk_kinds { + for i in 0 .. tk_count[k] { + let t = tk_ring[k * tk_cap + i] + let dx = t.x - x + let dz = t.z - z + let d2 = dx * dx + dz * dz + if d2 < best { + best = d2 + at = k * tk_cap + i + } + } + } + return at +} + +# signs read for the first time, of every source +export function tracks_read_count() -> int { return tk_read_n } + +# the heading of the last sign read, and whether there has been one +export function tracks_last_yaw() -> float { return tk_yaw } +export function tracks_has_bearing() -> bool { return tk_has_yaw } diff --git a/packages/ludic.tracks/read.ludic b/packages/ludic.tracks/read.ludic new file mode 100644 index 00000000..645f413d --- /dev/null +++ b/packages/ludic.tracks/read.ludic @@ -0,0 +1,54 @@ +# read.ludic - reading the ground. A print is read once: reading it again says the same thing +# and counts nothing, so pressing a key over one print is not as good as walking a trail. +export function tracks_fresh_of(age: float) -> int { + if age > tk_recent_h { return TRACK_OLD } + if age > tk_fresh_h { return TRACK_RECENT } + return TRACK_FRESH +} + +function tk_push(f: TrackRead) -> void { + if f.first { tk_read_n += 1 } + q_push(tracks_reads(), f) +} + +# read the print at a slot (tracks_nearest's answer): a fact every time, a count the first time +export function tracks_read(slot: int) -> void { + if slot < 0 or tk_ring == null or slot >= len(tk_ring) { return } + let t = tk_ring[slot] + let f = new TrackRead + f.sp = t.sp + f.source = TRACK_PRINT + f.kind = slot / tk_cap + f.legend = t.legend + f.age = tracks_age(slot) + f.fresh = tracks_fresh_of(f.age) + f.yaw = t.yaw + f.named = tk_named() + f.bearing = tk_bearing(t.yaw) + f.first = not t.read + t.read = true + tracks_note_bearing(t.yaw) + tk_push(f) +} + +# a sign that is not a print (droppings, a legend's mark): the caller knows whether it is the +# first reading of it +export function tracks_note(sp: int, source: int, legend: bool, yaw: float, first: bool) -> void { + let f = new TrackRead + f.sp = sp + f.source = source + f.legend = legend + f.yaw = yaw + f.named = tk_named() + f.bearing = tk_bearing(yaw) + f.first = first + tk_push(f) +} + +# the way the last thing read went (a bed, droppings, a print) +export function tracks_note_bearing(yaw: float) -> void { + tk_yaw = yaw + tk_has_yaw = true +} + +export function tracks_set_read_count(n: int) -> void { tk_read_n = n } diff --git a/packages/ludic.tracks/state.ludic b/packages/ludic.tracks/state.ludic new file mode 100644 index 00000000..ca5a83cc --- /dev/null +++ b/packages/ludic.tracks/state.ludic @@ -0,0 +1,66 @@ +# state.ludic - the port, the prints, the facts, and what the reader has learned +# what the tracks ask the world. Any field may be left null: the time is then 0, the reader +# can name every animal, no bearing is given, and nothing is drawn. +export property TracksWorld { + now: fn() -> float = null # game hours, counted from the start of the trip + skill: fn() -> int = null # how well the reader reads (the game's tiers) + bearing: fn(float) -> string = null # a yaw in words ("north-west"), "" for none + placed: fn(int, int) -> void = null # a print was put down at (kind, ring index): draw it +} + +# where a sign came from +export const TRACK_PRINT: int = 0 # a print in a ring, read with tracks_read +export const TRACK_SIGN: int = 1 # a legend's sign, told with tracks_note +export const TRACK_SCAT: int = 2 # droppings, told with tracks_note + +# how old a print looks +export const TRACK_FRESH: int = 0 +export const TRACK_RECENT: int = 1 +export const TRACK_OLD: int = 2 + +export property Track { + x: float = 0.0 + z: float = 0.0 + yaw: float = 0.0 + sp: int = 0 + legend: bool = false + made: float = 0.0 + read: bool = false +} + +# a sign was read: `first` the first time this one was, `named` whether the reader could tell +# the animal, `bearing` the way it went in words ("" without them) +export property TrackRead { + sp: int = 0 + source: int = 0 + kind: int = 0 + legend: bool = false + age: float = 0.0 + fresh: int = 0 + yaw: float = 0.0 + named: bool = true + bearing: string = "" + first: bool = false +} + +var tk_world: TracksWorld = null +var tk_kinds: int = 0 +var tk_cap: int = 0 +var tk_ring: []Track = null # kinds x cap, kind-major +var tk_count: []int = null # per kind: how many of the ring are in use +var tk_next: []int = null # per kind: where the next print goes +var tk_name_at: int = 0 # the skill that tells the animal from its print +var tk_fresh_h: float = 0.5 +var tk_recent_h: float = 2.5 +var tk_read_n: int = 0 # signs read for the first time, of every source +var tk_yaw: float = 0.0 # the heading of the last sign read +var tk_has_yaw: bool = false +var tk_reads: Queue = null + +export function tracks_bind(w: TracksWorld) -> void { tk_world = w } + +# the facts: every sign read, oldest first +export function tracks_reads() -> Queue { + if tk_reads == null { tk_reads = queue_new("tracks.reads") } + return tk_reads +} diff --git a/packages/ludic.tracks/system.ludic b/packages/ludic.tracks/system.ludic new file mode 100644 index 00000000..2ce6f91f --- /dev/null +++ b/packages/ludic.tracks/system.ludic @@ -0,0 +1,31 @@ +# system.ludic - the reader as a system: what has been read and the last bearing are saved; the +# prints themselves are the ground's and are not (the animals leave new ones) +export function tracks_reset() -> void { + tk_read_n = 0 + tk_yaw = 0.0 + tk_has_yaw = false + q_clear(tracks_reads()) +} + +export function tracks_save() -> Val { + let v = Value.object() + sv_put_int(v, "read", tk_read_n) + sv_put_bool(v, "has_yaw", tk_has_yaw) + sv_put_float(v, "yaw", tk_yaw) + return v +} + +export function tracks_load(v: Val, version: int) -> void { + tracks_reset() + tk_read_n = sv_int(v, "read", 0) + tk_has_yaw = sv_bool(v, "has_yaw", false) + tk_yaw = sv_float(v, "yaw", 0.0) +} + +export function tracks_system() -> System { + let s = system_new("tracks", PH_SIMULATE) + s.reset = fn tracks_reset + s.save = fn tracks_save + s.load = fn tracks_load + return s +} diff --git a/packages/ludic.tracks/tests/tracks_test.ludic b/packages/ludic.tracks/tests/tracks_test.ludic new file mode 100644 index 00000000..558cbe76 --- /dev/null +++ b/packages/ludic.tracks/tests/tracks_test.ludic @@ -0,0 +1,146 @@ +# tracks_test.ludic - prints go into a ring per kind and are drawn through the hook, they age on +# the world's clock, the nearest is found, a read is a fact every time and a count once, and the +# reader's state saves +import "ludic.tracks" +import "ludic.base" +program TracksTest { + numbers float + var now: float = 0.0 + var skill: int = 1 + var placed_n: int = 0 + var placed_last: int = -1 + + function fake_now() -> float { return now } + function fake_skill() -> int { return skill } + function fake_bearing(yaw: float) -> string { + if yaw > 0.0 { return "east" } + return "west" + } + function fake_placed(kind: int, i: int) -> void { + placed_n += 1 + placed_last = i + } + + function fresh() -> void { + now = 10.0 + skill = 1 + placed_n = 0 + placed_last = -1 + let w = new TracksWorld + w.now = fn fake_now + w.skill = fn fake_skill + w.bearing = fn fake_bearing + w.placed = fn fake_placed + tracks_bind(w) + tracks_config(3, 4) + tracks_config_reading(1, 0.5, 2.5) + tracks_reset() + } + + function reads() -> []TrackRead { return q_drain(tracks_reads()) } + + test "a print goes into its kind's ring and is drawn" { + fresh() + let i = tracks_leave(1, 5.0, 6.0, 1.0, 7, false) + expect_eq(i, 0) + expect_eq(tracks_count(1), 1) + expect_eq(tracks_count(0), 0) + expect_eq(placed_n, 1) + let s = tracks_slot(1, 0) + expect(tracks_x(s) == 5.0 and tracks_z(s) == 6.0) + expect_eq(tracks_sp(s), 7) + } + + test "a full ring writes over its oldest print" { + fresh() + for n in 0 .. 5 { tracks_leave(2, float(n), 0.0, 0.0, n, false) } + expect_eq(tracks_count(2), 4) + expect_eq(placed_last, 0) + expect_eq(tracks_sp(tracks_slot(2, 0)), 4) + } + + test "a print ages on the world's clock" { + fresh() + tracks_leave(1, 0.0, 0.0, 0.0, 1, false) + now = 13.0 + let s = tracks_slot(1, 0) + expect(tracks_age(s) == 3.0) + expect_eq(tracks_fresh_of(tracks_age(s)), TRACK_OLD) + expect_eq(tracks_fresh_of(0.2), TRACK_FRESH) + expect_eq(tracks_fresh_of(1.0), TRACK_RECENT) + } + + test "the nearest print within reach, or none" { + fresh() + tracks_leave(1, 10.0, 0.0, 0.0, 1, false) + tracks_leave(2, 1.0, 1.0, 0.0, 2, false) + expect_eq(tracks_nearest(0.0, 0.0, 2.0), tracks_slot(2, 0)) + expect_eq(tracks_nearest(50.0, 50.0, 2.0), -1) + } + + test "a print read twice is two facts and one count" { + fresh() + tracks_leave(1, 0.0, 0.0, 1.0, 3, true) + let s = tracks_nearest(0.0, 0.0, 2.0) + tracks_read(s) + tracks_read(s) + let rs = reads() + expect_eq(len(rs), 2) + expect(rs[0].first and not rs[1].first) + expect_eq(rs[0].source, TRACK_PRINT) + expect_eq(rs[0].kind, 1) + expect(rs[0].legend) + expect(rs[0].bearing == "east") + expect_eq(tracks_read_count(), 1) + expect(tracks_has_bearing() and tracks_last_yaw() == 1.0) + } + + test "a reader without the skill cannot name the animal" { + fresh() + skill = 0 + tracks_leave(1, 0.0, 0.0, 0.0, 3, false) + tracks_read(tracks_slot(1, 0)) + expect(not reads()[0].named) + } + + test "a sign that is not a print is told, and counts when it is the first" { + fresh() + tracks_note(4, TRACK_SCAT, false, -1.0, true) + tracks_note(4, TRACK_SCAT, false, -1.0, false) + let rs = reads() + expect_eq(len(rs), 2) + expect_eq(rs[0].source, TRACK_SCAT) + expect_eq(tracks_read_count(), 1) + } + + test "a written-over slot is a new, unread print" { + fresh() + tracks_leave(0, 0.0, 0.0, 0.0, 1, false) + tracks_read(tracks_slot(0, 0)) + for n in 0 .. 4 { tracks_leave(0, 0.0, 0.0, 0.0, 2, false) } + expect(not tracks_was_read(tracks_slot(0, 0))) + } + + test "clearing the ground forgets the prints, not the reader" { + fresh() + tracks_leave(1, 0.0, 0.0, 0.0, 1, false) + tracks_read(tracks_slot(1, 0)) + tracks_clear() + expect_eq(tracks_count(1), 0) + expect_eq(tracks_read_count(), 1) + } + + test "a save section reads back the same reader" { + fresh() + tracks_note(1, TRACK_SIGN, true, 0.0, true) + tracks_note_bearing(2.5) + let root = save_tree() + save_section(root, "tracks", 1, tracks_save()) + let text = save_encode(root) + tracks_reset() + let n = load_section(save_decode(text), "tracks") + tracks_load(n.data, n.version) + expect_eq(tracks_read_count(), 1) + expect(tracks_has_bearing() and tracks_last_yaw() == 2.5) + } +}