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 <noreply@anthropic.com>

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<TrackRead>` | 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
+```

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)
+}

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"

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
+  }
+}

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

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 }

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 }

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<TrackRead> = null
+
+export function tracks_bind(w: TracksWorld) -> void { tk_world = w }
+
+# the facts: every sign read, oldest first
+export function tracks_reads() -> Queue<TrackRead> {
+  if tk_reads == null { tk_reads = queue_new("tracks.reads") }
+  return tk_reads
+}

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
+}

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)
+  }
+}