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