ludic.base, ludic.wildlife, ludic.npc: fact records reused, not made per fact

wl_fact made a new WildFact per fact, about one a frame, and Ludic never gives one back. ludic.base's q_unheld(q, pool, out) lists the records a queue no longer holds: neither waiting nor handed out by its last drain, which is good until the next drain. ludic.wildlife and ludic.npc now keep a pool, hand out a free record, and make a new one only when every record is held. Taking a record writes the state, so wl_fact / np_fact and the few callers holding their state read-only take it mut. Tests: q_unheld's rules (an empty drain holds on, the safe side); 3000 prints drained frame by frame use at most 4 records; 500 arrivals drained turn by turn use at most 4. base 37, wildlife 27, npc 17; all packages 420.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

packages/ludic.base/queue.ludic

@@ -56,6 +56,20 @@ export function q_clear<T>(q: Queue<T>) -> void {
   q.tag.pending = 0
 }
 
+# pool's records the queue no longer holds - neither waiting nor handed out by the last drain - put
+# into out (cleared first): what a package may fill again instead of making a new record per fact
+export function q_unheld<T>(q: Queue<T>, pool: []T, out: []T) -> int {
+  List.clear(out)
+  for i in 0 .. len(pool) {
+    let r = pool[i]
+    var held = false
+    for j in 0 .. len(q.items) { if q.items[j] == r { held = true } }
+    for j in 0 .. len(q.spare) { if q.spare[j] == r { held = true } }
+    if not held { push(out, r) }
+  }
+  return len(out)
+}
+
 # a queue's tag, for core_undrained: queues of different facts in one list
 export function q_tag<T>(q: Queue<T>) -> QueueTag { return q.tag }
 

packages/ludic.base/tests/queue_test.ludic

@@ -36,6 +36,32 @@ program QueueTest {
     expect(cs[0].weight == 1.5)
   }
 
+  # waiting and last handed out are held; what an earlier drain handed out is free again
+  function unheld_case() -> void {
+    let q: Queue<Caught> = queue_new("caught")
+    let a = caught(1, 1.0)
+    let b = caught(2, 2.0)
+    let c = caught(3, 3.0)
+    let pool = new []Caught
+    push(pool, a)
+    push(pool, b)
+    push(pool, c)
+    let free = new []Caught
+    q_push(q, a)
+    expect_eq(q_unheld(q, pool, free), 2)
+    q_drain(q)
+    q_push(q, b)
+    expect_eq(q_unheld(q, pool, free), 1)
+    expect(free[0] == c)
+    q_drain(q)
+    expect_eq(q_unheld(q, pool, free), 2)
+    q_drain(q)
+    expect_eq(q_unheld(q, pool, free), 2)   # an empty drain swaps nothing: b stays held, the safe side
+    q_push(q, a)
+    q_drain(q)
+    expect_eq(q_unheld(q, pool, free), 2)   # b is free at last, a is handed out
+  }
+
   function clear_case() -> void {
     let q: Queue<string> = queue_new("words")
     q_push(q, "a")
@@ -107,6 +133,7 @@ program QueueTest {
   test "an empty drain allocates nothing, and a drained list is the caller's" () { empty_case() }
   test "a queue holds records" () { record_case() }
   test "clear drops what is waiting" () { clear_case() }
+  test "a pool's records are free once no drain holds them" () { unheld_case() }
   test "a queue's element type is told by the queue alone" () { infer_case() }
   test "the undrained queues are named, and a drain clears the report" () { undrained_case() }
 }

packages/ludic.npc/act.ludic

@@ -30,7 +30,7 @@ function np_turns(act: int) -> bool {
 }
 
 # a player who came within notice since the last look is greeted - once, until they walk off
-export function npc_notice(npc_st: NpcState, p: NpcPerson) -> void {
+export function npc_notice(npc_st: mut NpcState, p: NpcPerson) -> void {
   let reach = NpcKinds[p.kind].notice
   for i in 0 .. NpcWorld.players() {
     if i >= 30 { break }

packages/ludic.npc/person.ludic

@@ -13,6 +13,9 @@ export state NpcState {
   np_n: int = 0                 # walkers about
   np_dice: Rng = rng_new(20260925)
   np_facts: Queue<NpcFact> = np_facts__new()
+  np_fpool: []NpcFact = new []NpcFact      # every fact record made, reused once no drain holds it
+  np_ffree: []NpcFact = new []NpcFact
+  np_fnext: int = 0
   np_next_h: float = 0.0        # the hour the census is next looked at
   np_hold: bool = false         # held where they stand (a shot of their poses)
   np_mirror: bool = false       # a guest drawing a host's: no routine runs here
@@ -29,8 +32,8 @@ export function npc_facts(npc_st: NpcState) -> Queue<NpcFact> {
   return npc_st.np_facts
 }
 
-function np_fact(npc_st: NpcState, what: int, p: NpcPerson, player: int) -> NpcFact {
-  let f = new NpcFact
+function np_fact(npc_st: mut NpcState, what: int, p: NpcPerson, player: int) -> NpcFact {
+  let f = np_fact_record(npc_st)
   f.what = what
   f.person = p.id
   f.slot = p.slot

packages/ludic.npc/tests/way_test.ludic

@@ -101,4 +101,20 @@ program NpcWayTest {
     expect_eq(p.act, NPCA_SIT)
     expect(p.phase > 100.0)
   }
+
+  test "an arrival a turn, drained each turn, makes a few fact records and then reuses them" (npc_st: mut NpcState, npc_tests_fake_st: mut NpcTestsFakeState, way_test_st: WayTestState) {
+    fk_setup(npc_st, npc_tests_fake_st)
+    npc_tests_fake_st.fk_want = 1
+    let p = npc_spawn(npc_st, NPCK_HIKER)
+    var arrived = 0
+    for k in 0 .. 500 {
+      npc_set_at(p, 0.0, 0.0)
+      npc_go(npc_st, p, 0.5, 0.0, NPCA_SIT, 30.0)
+      npc_tick(npc_st, 0.05)
+      let fs = q_drain(npc_facts(npc_st))
+      for i in 0 .. len(fs) { if fs[i].what == NPC_F_ARRIVED { arrived += 1 } }
+    }
+    expect(arrived > 400)
+    expect(npc_fact_records(npc_st) <= 4)
+  }
 }

packages/ludic.npc/way.ludic

@@ -4,7 +4,7 @@
 export const NPC_STUCK_DETOUR: int = 0     # a step round what was in front of it
 export const NPC_STUCK_RETRY: int = 1      # no closer for twenty seconds, or no step round: planned again
 export const NPC_STUCK_GAVE_UP: int = 2    # the third of those: the target given up
-function np_stuck_fact(npc_st: NpcState, p: NpcPerson, how: int) -> void {
+function np_stuck_fact(npc_st: mut NpcState, p: NpcPerson, how: int) -> void {
   let f = np_fact(npc_st, NPC_F_STUCK, p, -1)
   f.how = how
   f.x = p.x
@@ -77,3 +77,26 @@ export function npc_moved(p: NpcPerson, x: float, z: float, vx: float, vz: float
   if vx * vx + vz * vz > 0.01 { p.yaw = Math.atan2(-vx, -vz) }
   p.phase = p.phase + Math.sqrt(dx * dx + dz * dz) * 2.6
 }
+
+# a fact record no drain holds any more, made fresh (and kept) only when every one is held
+function np_fact_record(npc_st: mut NpcState) -> NpcFact {
+  if npc_st.np_fnext >= len(npc_st.np_ffree) {
+    q_unheld(npc_st.np_facts, npc_st.np_fpool, npc_st.np_ffree)
+    npc_st.np_fnext = 0
+  }
+  if npc_st.np_fnext < len(npc_st.np_ffree) {
+    let f = npc_st.np_ffree[npc_st.np_fnext]
+    npc_st.np_fnext += 1
+    f.line = -1
+    f.choice = -1
+    f.how = 0
+    f.x = 0.0
+    f.z = 0.0
+    return f
+  }
+  let f = new NpcFact
+  push(npc_st.np_fpool, f)
+  return f
+}
+# how many fact records have ever been made: the peak held at once, not the facts pushed
+export function npc_fact_records(npc_st: NpcState) -> int { return len(npc_st.np_fpool) }

packages/ludic.wildlife/birds.ludic

@@ -84,7 +84,7 @@ function wl_land(wildlife_st: mut WildlifeState, a: WildAnimal, dh: float, dt: f
 }
 
 # on the ground it pecks at seed or takes a drink at the water's edge; it leaves no droppings
-function wl_perch(wildlife_st: WildlifeState, a: WildAnimal, dh: float, dt: float) -> void {
+function wl_perch(wildlife_st: mut WildlifeState, a: WildAnimal, dh: float, dt: float) -> void {
   a.speed = 0.0
   a.y = WildlifeWorld.ground(a.x, a.z)
   a.bank = 0.0

packages/ludic.wildlife/facts.ludic

@@ -32,8 +32,31 @@ export function wildlife_facts(wildlife_st: WildlifeState) -> Queue<WildFact> {
   return wildlife_st.wl_facts
 }
 
-function wl_fact(wildlife_st: WildlifeState, what: int, a: WildAnimal) -> WildFact {
+# a fact record: one no drain holds any more, made fresh (and kept) only when every one is held - a
+# fact is pushed about once a frame, and a record a frame is never given back
+function wl_fact_record(wildlife_st: mut WildlifeState) -> WildFact {
+  if wildlife_st.wl_fnext[0] >= len(wildlife_st.wl_ffree) {
+    q_unheld(wildlife_st.wl_facts, wildlife_st.wl_fpool, wildlife_st.wl_ffree)
+    wildlife_st.wl_fnext[0] = 0
+  }
+  if wildlife_st.wl_fnext[0] < len(wildlife_st.wl_ffree) {
+    let f = wildlife_st.wl_ffree[wildlife_st.wl_fnext[0]]
+    wildlife_st.wl_fnext[0] += 1
+    f.player = 0
+    f.lure = 0
+    f.owner = -1
+    f.diet = 0
+    return f
+  }
   let f = new WildFact
+  push(wildlife_st.wl_fpool, f)
+  return f
+}
+# how many fact records have ever been made: the peak held at once, not the facts pushed
+export function wildlife_fact_records(wildlife_st: WildlifeState) -> int { return len(wildlife_st.wl_fpool) }
+
+function wl_fact(wildlife_st: mut WildlifeState, what: int, a: WildAnimal) -> WildFact {
+  let f = wl_fact_record(wildlife_st)
   f.what = what
   f.key = a.key
   f.nid = a.nid

packages/ludic.wildlife/ground.ludic

@@ -64,7 +64,7 @@ function wl_charge(wildlife_st: mut WildlifeState, a: WildAnimal, np: int, dh: f
 
 # Four postures read off the alert. Staring is a REACTION, not a condition: each times out and
 # hands the animal back to its business, and only a fresh rise above `seen` looks up again.
-function wl_posture(wildlife_st: WildlifeState, a: WildAnimal, np: int, dt: float) -> void {
+function wl_posture(wildlife_st: mut WildlifeState, a: WildAnimal, np: int, dt: float) -> void {
   if wl_sp(wildlife_st, a.sp).tame or a.state == WILD_EAT { return }
   if a.alert > 95.0 {
     if a.state != WILD_FLEE {

packages/ludic.wildlife/lures.ludic

@@ -86,7 +86,7 @@ function wl_bird_seed(wildlife_st: WildlifeState, a: WildAnimal) -> bool {
 }
 
 # it ate what was set out: calm for three game hours, and the game credits whoever left it
-function wl_ate(wildlife_st: WildlifeState, a: WildAnimal, uid: int, owner: int, diet: int) -> void {
+function wl_ate(wildlife_st: mut WildlifeState, a: WildAnimal, uid: int, owner: int, diet: int) -> void {
   a.calm = 180.0
   a.fed += 1
   let f = wl_fact(wildlife_st, WILD_FED, a)

packages/ludic.wildlife/react.ludic

@@ -54,7 +54,7 @@ function wl_approach(wildlife_st: mut WildlifeState, a: WildAnimal, dt: float) -
 }
 
 # at a snare it is held; at food it eats for 14 s; at a lure it stands curious for 9
-function wl_arrive(wildlife_st: WildlifeState, a: WildAnimal) -> void {
+function wl_arrive(wildlife_st: mut WildlifeState, a: WildAnimal) -> void {
   a.state = WILD_EAT
   a.timer = 9.0
   if a.lure_kind == WILD_FEED { a.timer = 14.0 }
@@ -69,7 +69,7 @@ function wl_arrive(wildlife_st: WildlifeState, a: WildAnimal) -> void {
 }
 
 # eating what it came to; when it is done, food is credited and it wanders off
-function wl_eat(wildlife_st: WildlifeState, a: WildAnimal) -> bool {
+function wl_eat(wildlife_st: mut WildlifeState, a: WildAnimal) -> bool {
   if a.state != WILD_EAT { return false }
   a.speed = 0.0
   if a.timer < 0.0 {

packages/ludic.wildlife/species.ludic

@@ -35,6 +35,9 @@ export property WildSpecies {
 
 export state WildlifeState {
   wl_facts: Queue<WildFact> = wl_facts__new()
+  wl_fpool: []WildFact = new []WildFact   # every fact record made, reused once no drain holds it
+  wl_ffree: []WildFact = new []WildFact   # of those, the ones free at the last look
+  wl_fnext: []int = words(1)              # the next of them to hand out
   wl_own: WildTable = null   # a guest's own animals, put away whole while it draws the host's
   wl_px: float = 0.0
   wl_pz: float = 0.0

packages/ludic.wildlife/tests/crowd_test.ludic

@@ -83,4 +83,14 @@ program WildCrowdTest {
     wildlife_clear(wildlife_st)
     expect(not wildlife_listed(wildlife_st, a))
   }
+
+  test "a fact a frame, drained each frame, makes a few records and then reuses them" (wildlife_st: mut WildlifeState, wildlife_tests_fake_st: mut WildlifeTestsFakeState) {
+    let a = walker(wildlife_st, wildlife_tests_fake_st)
+    for k in 1 .. 3001 {
+      wildlife_moved(wildlife_st, a, 0.0, -3.0 * float(k), 0.0, -1.2)
+      let fs = q_drain(wildlife_facts(wildlife_st))
+      for i in 0 .. len(fs) { expect_eq(fs[i].what, WILD_PRINT) }
+    }
+    expect(wildlife_fact_records(wildlife_st) <= 4)
+  }
 }