feat(ecs): ludic.base Table<T> - dense rows of hot columns, generational handles, a spatial grid, kind indexes and an id map kept current by the setters; ludic.things on it

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>

packages/ludic.things/dispatch.ludic

@@ -45,14 +45,22 @@ export function thing_is_personal(t: Thing) -> bool { return thing_kind_ok(t.kin
 # set down by someone rather than grown by the world: the kind says, and the port has the last word
 export function thing_is_put_down(t: Thing) -> bool { return ThingsWorld.put_down(t) }
 
-# every active Thing whose kind ticks, `hours` of the world's clock on
-export function things_tick(things_st: ThingsState, hours: float) -> void {
-  let all = things_all(things_st)
-  for i in 0 .. len(all) {
-    let t = all[i]
-    if not t.active or not thing_kind_ok(t.kind) { continue }
-    let k = ThingKinds[t.kind]
-    if k.tick != null { k.tick(t, hours) }
+# every active Thing whose kind ticks, `hours` of the world's clock on: only the kinds that tick
+# are visited, through the kind index, from a list of handles taken first - a tick may hide one
+export function things_tick(things_st: mut ThingsState, hours: float) -> void {
+  let hs = things_st.th_hs
+  List.clear(hs)
+  let tb = things_st.th.tab
+  for k in 0 .. TH_COUNT {
+    if ThingKinds[k].tick == null { continue }
+    let rows = ix_rows(things_st.th.kinds, k)
+    for i in 0 .. len(rows) { push(hs, tb.ent[rows[i]]) }
+  }
+  for i in 0 .. len(hs) {
+    let r = tb_row(tb, hs[i])
+    if r < 0 { continue }
+    let t = tb.rec[r]
+    if t.active { ThingKinds[t.kind].tick(t, hours) }
   }
 }
 

packages/ludic.things/index.ludic

@@ -6,6 +6,8 @@ import "ludic.base"
 import "kinds.ludic"
 import "port.ludic"
 import "store.ludic"
+import "verbs.ludic"
 import "queries.ludic"
+import "near.ludic"
 import "dispatch.ludic"
 import "system.ludic"

packages/ludic.things/kinds.ludic

@@ -19,6 +19,8 @@ export property Thing {
   sz: float = 0.0
   syaw: float = 0.0
   shared: bool = false    # the game copies it to others (a party)
+  ent: int = -1           # its handle in the table, -1 once removed
+  tab: Table<Thing> = null  # the table holding it, so a verb on the Thing alone keeps the indexes
 }
 
 export property ThingKind {

packages/ludic.things/near.ludic

@@ -0,0 +1,26 @@
+# near.ludic - the neighbourhood questions a frame asks many times: what is around a point, of any
+# kind or of one, into a list the CALLER keeps (in its own state, reused every frame), from the grid
+# or the kind's own list - never a walk of every Thing, and nothing allocated or written here
+export function things_near(things_st: ThingsState, x: float, z: float, r: float, out: []Thing) -> int {
+  return tb_within_recs(things_st.th.tab, things_st.th.grid, x, z, r, -1, 0, out)
+}
+
+export function things_near_of(things_st: ThingsState, kind: int, x: float, z: float, r: float, out: []Thing) -> int {
+  return tb_within_of_recs(things_st.th.tab, things_st.th.grid, things_st.th.kinds, x, z, r, kind, out)
+}
+
+# the nearest active Thing within maxr (0: any distance) that `keep` says yes to, or null
+export function thing_nearest_where(things_st: ThingsState, x: float, z: float, maxr: float, keep: fn(Thing) -> bool) -> Thing {
+  let r = tb_nearest_where(things_st.th.tab, things_st.th.grid, x, z, maxr, keep)
+  if r < 0 { return null }
+  return things_st.th.tab.rec[r]
+}
+
+# every one of a kind, active or not, counted and walked without a list
+export function things_count_all_of(things_st: ThingsState, kind: int) -> int { return ix_count(things_st.th.every, kind) }
+
+export function thing_of_kind_all(things_st: ThingsState, kind: int, i: int) -> Thing {
+  let rows = ix_rows(things_st.th.every, kind)
+  if i < 0 or i >= len(rows) { return null }
+  return things_st.th.tab.rec[rows[i]]
+}

packages/ludic.things/queries.ludic

@@ -1,38 +1,43 @@
-# queries.ludic - where the Things are. Only active Things answer, except thing_by_uid and
-# things_each_all, which ask about everything that exists. A kind below 0 is any kind.
+# queries.ludic - where the Things are, answered by the table's indexes rather than a scan. Only
+# active Things answer, except thing_by_uid and things_each_all, which ask about everything that
+# exists. A kind below 0 is any kind.
 function th_of(t: Thing, kind: int) -> bool { return kind < 0 or t.kind == kind }
 
-# the first active one of a kind (and of that id, unless id < 0), in the order placed
+# the first-placed active one of a kind (and of that id, unless id < 0)
 export function thing_find(things_st: ThingsState, kind: int, id: int) -> Thing {
-  let all = things_all(things_st)
-  for i in 0 .. len(all) {
-    let t = all[i]
-    if t.active and th_of(t, kind) and (id < 0 or t.id == id) { return t }
+  let tb = things_st.th.tab
+  var best: Thing = null
+  if kind < 0 {
+    for r in 0 .. tb_len(tb) { best = th_earlier(best, tb.rec[r], id) }
+    return best
   }
-  return null
+  let rows = ix_rows(things_st.th.kinds, kind)
+  for k in 0 .. len(rows) { best = th_earlier(best, tb.rec[rows[k]], id) }
+  return best
+}
+
+# the one of the two placed first that is active and has the id asked for
+function th_earlier(best: Thing, t: Thing, id: int) -> Thing {
+  if not t.active or (id >= 0 and t.id != id) { return best }
+  if best == null or t.uid < best.uid { return t }
+  return best
 }
 
 export function thing_by_uid(things_st: ThingsState, uid: int) -> Thing {
-  let all = things_all(things_st)
-  for i in 0 .. len(all) { if all[i].uid == uid { return all[i] } }
-  return null
+  let r = tb_row(things_st.th.tab, imap_get(things_st.th_uids, uid, -1))
+  if r < 0 { return null }
+  return things_st.th.tab.rec[r]
 }
 
 # the nearest active one of a kind to (x, z), or null
 export function thing_nearest(things_st: ThingsState, kind: int, x: float, z: float) -> Thing {
-  var best: Thing = null
-  var bd = 0.0
-  let all = things_all(things_st)
-  for i in 0 .. len(all) {
-    let t = all[i]
-    if not t.active or not th_of(t, kind) { continue }
-    let d = thing_dist2(t, x, z)
-    if best == null or d < bd {
-      best = t
-      bd = d
-    }
+  let tb = things_st.th.tab
+  var r = -1
+  if kind < 0 { r = tb_nearest(tb, things_st.th.grid, x, z, 0.0, -1, 0) } else {
+    r = tb_nearest_of(tb, things_st.th.grid, things_st.th.kinds, x, z, 0.0, kind)
   }
-  return best
+  if r < 0 { return null }
+  return tb.rec[r]
 }
 
 # the squared ground distance from a Thing to (x, z)
@@ -42,14 +47,13 @@ export function thing_dist2(t: Thing, x: float, z: float) -> float {
   return dx * dx + dz * dz
 }
 
-# every active one within r of (x, z), nearest first
+# every active one within r of (x, z), nearest first, in a new list: for a question asked now and
+# then - a frame's question is things_near, into a list the caller keeps
 export function things_within(things_st: ThingsState, x: float, z: float, r: float) -> []Thing {
+  let found = new []Thing
+  things_near(things_st, x, z, r, found)
   let out = new []Thing
-  let all = things_all(things_st)
-  for i in 0 .. len(all) {
-    let t = all[i]
-    if t.active and thing_dist2(t, x, z) <= r * r { th_insert(out, t, x, z) }
-  }
+  for k in 0 .. len(found) { th_insert(out, found[k], x, z) }
   return out
 }
 
@@ -63,18 +67,44 @@ function th_insert(out: []Thing, t: Thing, x: float, z: float) -> void {
   out[j] = t
 }
 
-# every active one of a kind, in the order placed
+# every active one of a kind, first placed first
 export function things_each(things_st: ThingsState, kind: int) -> []Thing {
-  let out = new []Thing
-  let all = things_all(things_st)
-  for i in 0 .. len(all) { if all[i].active and th_of(all[i], kind) { push(out, all[i]) } }
-  return out
+  return th_listed(things_st, ix_rows(things_st.th.kinds, kind))
 }
 
 # every one of a kind, active or not
 export function things_each_all(things_st: ThingsState, kind: int) -> []Thing {
-  let out = new []Thing
-  let all = things_all(things_st)
-  for i in 0 .. len(all) { if th_of(all[i], kind) { push(out, all[i]) } }
-  return out
+  return th_listed(things_st, ix_rows(things_st.th.every, kind))
+}
+
+# how many active ones of a kind there are, without a list
+export function things_count_of(things_st: ThingsState, kind: int) -> int {
+  return ix_count(things_st.th.kinds, kind)
+}
+
+function th_listed(things_st: ThingsState, rows: words) -> []Thing {
+  let out = new []Thing
+  for k in 0 .. len(rows) { push(out, things_st.th.tab.rec[rows[k]]) }
+  return th_by_uid_order(out)
+}
+
+function th_by_uid_order(xs: []Thing) -> []Thing {
+  for i in 1 .. len(xs) {
+    let t = xs[i]
+    var j = i
+    while j > 0 and xs[j - 1].uid > t.uid {
+      xs[j] = xs[j - 1]
+      j -= 1
+    }
+    xs[j] = t
+  }
+  return xs
+}
+
+# the i-th active one of a kind, 0 .. things_count_of(kind) - 1, in the index's order (which a
+# removal or a hide changes: walk it within a frame, never keep an i)
+export function thing_of_kind(things_st: ThingsState, kind: int, i: int) -> Thing {
+  let rows = ix_rows(things_st.th.kinds, kind)
+  if i < 0 or i >= len(rows) { return null }
+  return things_st.th.tab.rec[rows[i]]
 }

packages/ludic.things/store.ludic

@@ -1,10 +1,38 @@
-# store.ludic - the Things, and the only verbs that make, remove, move, show and hide one; each
-# placing and removing is a fact, and the port is told at once so the game can draw it
+# store.ludic - the Things, rows of a ludic.base Table: where each stands and whether it is active
+# are columns a grid and two kind indexes are kept over, and only the verbs (verbs.ludic) make,
+# move, show, hide and remove one; each placing and removing is a fact the port hears at once
+export const TH_X: int = 0          # float columns
+export const TH_Z: int = 1
+export const TH_KIND: int = 0       # int columns
+export const TH_ON: int = 1         # 1 while active
+const TH_CELL: float = 16.0
+
+# the table and the indexes kept over it, made together
+export property ThingsTable {
+  tab: Table<Thing> = null
+  grid: Grid = null
+  kinds: IntIndex = null            # active Things by kind
+  every: IntIndex = null            # every Thing by kind, active or not
+}
+
 export state ThingsState {
-  th_list: []Thing = new []Thing
+  th: ThingsTable = th__new()
+  th_uids: IntMap = imap_new()
   th_uid: int = 0
   th_facts: Queue<ThingFact> = th_facts__new()
-  th_marked: int = -1
+  th_hs: words = words(0)           # things_tick's handles, taken before any tick runs
+}
+
+function th_facts__new() -> Queue<ThingFact> { return queue_new("things.facts") }
+
+function th__new() -> ThingsTable {
+  let th = new ThingsTable
+  let tb: Table<Thing> = table_new(2, 2)
+  th.tab = tb
+  th.grid = tb_grid(tb, TH_X, TH_Z, TH_ON, TH_CELL)
+  th.kinds = tb_index(tb, TH_KIND, TH_ON)
+  th.every = tb_index(tb, TH_KIND, -1)
+  return th
 }
 
 export function things_facts(things_st: ThingsState) -> Queue<ThingFact> {
@@ -24,88 +52,37 @@ function th_fact(things_st: ThingsState, what: int, t: Thing) -> void {
 }
 
 # whether a world has been set out (things_clear) since the program began
-export function things_ready(things_st: ThingsState) -> bool { return things_st.th_list != null }
+export function things_ready(things_st: ThingsState) -> bool { return things_st.th.tab != null }
 
-# every Thing, in the order placed; the list is the package's, never to be pushed to
-export function things_all(things_st: ThingsState) -> []Thing {
-  return things_st.th_list
-}
+# every Thing, one per row - the table's own list: read it, never push to it. A removal moves the
+# last Thing into the removed one's place, so the order is the table's, not the order placed.
+export function things_all(things_st: ThingsState) -> []Thing { return things_st.th.tab.rec }
 
-export function things_count(things_st: ThingsState) -> int { return len(things_all(things_st)) }
+export function things_count(things_st: ThingsState) -> int { return tb_len(things_st.th.tab) }
 
 # a new world: every Thing forgotten, quietly (the game has already dropped its drawings)
-export function things_clear(things_st: mut ThingsState) -> void { things_st.th_list = new []Thing }
-
-export function thing_spawn(things_st: mut ThingsState, kind: int, look: string, x: float, y: float, z: float, yaw: float, id: int) -> Thing {
-  return th_place(things_st, new Thing, kind, look, x, y, z, yaw, id)
+export function things_clear(things_st: mut ThingsState) -> void {
+  let tb = things_st.th.tab
+  for r in 0 .. tb_len(tb) { tb.rec[r].ent = -1 }
+  tb_clear(tb)
+  imap_clear(things_st.th_uids)
 }
 
-function th_place(things_st: mut ThingsState, t: Thing, kind: int, look: string, x: float, y: float, z: float, yaw: float, id: int) -> Thing {
-  t.kind = kind
-  t.look = look
-  t.x = x
-  t.y = y
-  t.z = z
-  t.yaw = yaw
-  t.id = id
-  things_st.th_uid += 1
-  t.uid = things_st.th_uid
-  push(things_all(things_st), t)
-  ThingsWorld.placed(t)
-  th_fact(things_st, THING_PLACED, t)
-  return t
+# the row a Thing stands in, or -1 when it is not in the table any more
+function th_row(t: Thing) -> int {
+  if t == null or t.tab == null { return -1 }
+  return tb_row(t.tab, t.ent)
 }
 
-# a Thing on the ground (the port's), set into it by `sink`, used from `reach`
-export function thing_put(things_st: mut ThingsState, kind: int, look: string, x: float, z: float, yaw: float, sink: float, reach: float, id: int) -> Thing {
-  let t = new Thing
-  t.reach = reach
-  return th_place(things_st, t, kind, look, x, ThingsWorld.ground(x, z) - sink, z, yaw, id)
-}
-
-# gone for good
-export function thing_remove(things_st: mut ThingsState, t: Thing) -> void {
-  if t == null { return }
-  things_st.th_marked = t.uid
-  things_drop(things_st, fn th_is_marked)
-  things_st.th_marked = -1
-}
-
-function th_is_marked(things_st: ThingsState, t: Thing) -> bool { return t.uid == things_st.th_marked }
-
-# every Thing `gone` says so is removed for good
-export function things_drop(things_st: mut ThingsState, gone: fn(Thing) -> bool) -> void {
-  let keep = new []Thing
-  let all = things_all(things_st)
-  for i in 0 .. len(all) {
-    let t = all[i]
-    if gone(t) {
-      ThingsWorld.removed(t)
-      th_fact(things_st, THING_REMOVED, t)
-    } else {
-      push(keep, t)
-    }
+# the columns say what the record says: a Thing's fields written around the verbs are caught here
+export function things_verify(things_st: ThingsState) -> int {
+  let tb = things_st.th.tab
+  var bad = 0
+  for r in 0 .. tb_len(tb) {
+    let t = tb.rec[r]
+    var on = 0
+    if t.active { on = 1 }
+    if tb.f[TH_X][r] != t.x or tb.f[TH_Z][r] != t.z or tb.i[TH_KIND][r] != t.kind or tb.i[TH_ON][r] != on or t.ent != tb.ent[r] { bad += 1 }
   }
-  things_st.th_list = keep
+  return bad
 }
-
-export function thing_move(t: Thing, x: float, z: float, yaw: float) -> void {
-  thing_move_to(t, x, ThingsWorld.ground(x, z), z, yaw)
-}
-
-export function thing_move_to(t: Thing, x: float, y: float, z: float, yaw: float) -> void {
-  t.x = x
-  t.y = y
-  t.z = z
-  t.yaw = yaw
-  ThingsWorld.moved(t)
-}
-
-export function thing_set_active(t: Thing, on: bool) -> void {
-  if t == null { return }
-  t.active = on
-  ThingsWorld.shown(t)
-}
-export function thing_hide(t: Thing) -> void { thing_set_active(t, false) }
-export function thing_show(t: Thing) -> void { thing_set_active(t, true) }
-function th_facts__new() -> Queue<ThingFact> { return queue_new("things.facts") }

packages/ludic.things/tests/things_test.ludic

@@ -155,4 +155,27 @@ program ThingsTest {
     expect_eq(t.owner, 0)
     expect_eq(things_test_st.back, 1)
   }
+
+  test "removals keep the indexes true: nearest, find, uid and the columns agree" (things_st: mut ThingsState) {
+    things_clear(things_st)
+    var keep: Thing = null
+    for i in 0 .. 400 {
+      let t = put(things_st, TH_BRANCH + (i % 2), float(i) * 3.0 - 600.0, float(i % 17) * 5.0)
+      if i == 250 { keep = t }
+    }
+    let gone = thing_find(things_st, TH_BRANCH, -1)
+    let uid = gone.uid
+    thing_remove(things_st, gone)
+    expect(thing_by_uid(things_st, uid) == null)
+    expect(thing_by_uid(things_st, keep.uid) == keep)
+    expect_eq(things_count(things_st), 399)
+    expect_eq(things_count_of(things_st, TH_BRANCH), 199)
+    thing_move(keep, 5000.0, 5000.0, 0.0)
+    expect(thing_nearest(things_st, -1, 4990.0, 4990.0) == keep)
+    thing_hide(keep)
+    expect(thing_nearest(things_st, -1, 4990.0, 4990.0) != keep)
+    expect_eq(things_verify(things_st), 0)
+    keep.x = 1.0
+    expect_eq(things_verify(things_st), 1)
+  }
 }

packages/ludic.things/verbs.ludic

@@ -0,0 +1,115 @@
+# verbs.ludic - the only ways a Thing is made, removed, moved, shown or hidden: each writes the
+# record and the table's columns together, so the grid and the kind indexes never fall behind
+export function thing_spawn(things_st: mut ThingsState, kind: int, look: string, x: float, y: float, z: float, yaw: float, id: int) -> Thing {
+  return th_place(things_st, new Thing, kind, look, x, y, z, yaw, id)
+}
+
+function th_place(things_st: mut ThingsState, t: Thing, kind: int, look: string, x: float, y: float, z: float, yaw: float, id: int) -> Thing {
+  t.kind = kind
+  t.look = look
+  t.x = x
+  t.y = y
+  t.z = z
+  t.yaw = yaw
+  t.id = id
+  things_st.th_uid += 1
+  t.uid = things_st.th_uid
+  let tb = things_st.th.tab
+  t.tab = tb
+  t.ent = tb_add(tb, t)
+  th_columns(t)
+  imap_put(things_st.th_uids, t.uid, t.ent)
+  ThingsWorld.placed(t)
+  th_fact(things_st, THING_PLACED, t)
+  return t
+}
+
+# the record's x, z, kind and active into its row, refiled once
+function th_columns(t: Thing) -> void {
+  let r = th_row(t)
+  if r < 0 { return }
+  let tb = t.tab
+  tb.f[TH_X][r] = t.x
+  tb.f[TH_Z][r] = t.z
+  tb.i[TH_KIND][r] = t.kind
+  var on = 0
+  if t.active { on = 1 }
+  tb.i[TH_ON][r] = on
+  tb_refile(tb, r)
+}
+
+# a Thing on the ground (the port's), set into it by `sink`, used from `reach`
+export function thing_put(things_st: mut ThingsState, kind: int, look: string, x: float, z: float, yaw: float, sink: float, reach: float, id: int) -> Thing {
+  let t = new Thing
+  t.reach = reach
+  return th_place(things_st, t, kind, look, x, ThingsWorld.ground(x, z) - sink, z, yaw, id)
+}
+
+# gone for good
+export function thing_remove(things_st: mut ThingsState, t: Thing) -> void {
+  if th_row(t) < 0 { return }
+  ThingsWorld.removed(t)
+  th_fact(things_st, THING_REMOVED, t)
+  imap_del(things_st.th_uids, t.uid)
+  tb_remove(t.tab, t.ent)
+  t.ent = -1
+}
+
+# every Thing `gone` says so is removed for good; from the last row down, so the row a removal
+# moves into place has already been asked
+export function things_drop(things_st: mut ThingsState, gone: fn(Thing) -> bool) -> void {
+  let tb = things_st.th.tab
+  var r = tb_len(tb) - 1
+  while r >= 0 {
+    let t = tb.rec[r]
+    if gone(t) { thing_remove(things_st, t) }
+    r -= 1
+  }
+}
+
+export function thing_move(t: Thing, x: float, z: float, yaw: float) -> void {
+  thing_move_to(t, x, ThingsWorld.ground(x, z), z, yaw)
+}
+
+export function thing_move_to(t: Thing, x: float, y: float, z: float, yaw: float) -> void {
+  thing_place_at(t, x, y, z, yaw)
+  ThingsWorld.moved(t)
+}
+
+# moved without telling the port: a stand-in the game draws itself, or nothing draws
+export function thing_place_at(t: Thing, x: float, y: float, z: float, yaw: float) -> void {
+  t.x = x
+  t.y = y
+  t.z = z
+  t.yaw = yaw
+  let r = th_row(t)
+  if r >= 0 { tb_set_xz(t.tab, TH_X, TH_Z, r, x, z) }
+}
+
+export function thing_set_active(t: Thing, on: bool) -> void {
+  if t == null { return }
+  thing_set_on(t, on)
+  ThingsWorld.shown(t)
+}
+export function thing_hide(t: Thing) -> void { thing_set_active(t, false) }
+export function thing_show(t: Thing) -> void { thing_set_active(t, true) }
+
+# active or not without telling the port
+export function thing_set_on(t: Thing, on: bool) -> void {
+  if t == null { return }
+  t.active = on
+  let r = th_row(t)
+  if r < 0 { return }
+  var v = 0
+  if on { v = 1 }
+  tb_set_i(t.tab, TH_ON, r, v)
+}
+
+# where it stands on the ground plane, without telling the port (its height is the caller's)
+export function thing_set_xz(t: Thing, x: float, z: float) -> void {
+  if t == null { return }
+  t.x = x
+  t.z = z
+  let r = th_row(t)
+  if r >= 0 { tb_set_xz(t.tab, TH_X, TH_Z, r, x, z) }
+}