resources (25.5e): @creates/@releases on Physics' handles - every shape maker and phys_shape_free (PhysShape), the body adds and phys_remove (PhysBody), the walker (PhysWalker), and ludic.nav's crowd agents (NavAgent)

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

packages/ludic.nav/crowd.ludic

@@ -22,12 +22,14 @@ function nv_crowd_drop(nav_st: mut NavState, kind: int) -> void {
 
 # a walker at (x, y, z) with its width, height, top speed, taste and how hard it keeps its distance
 # from the others (2 an ordinary walker): its index, or -1
+@creates(NavAgent)
 export function nav_crowd_add(nav_st: NavState, kind: int, x: float, y: float, z: float, radius: float, height: float, speed: float, filter: int, separation: float) -> int {
   let c = nv_crowd(nav_st, kind)
   if c == null { return -1 }
   return nvc_crowd_add(c, x, y, z, radius, height, speed, filter, separation)
 }
 # a walker the crowd avoids but never moves (a player): put where it is each frame with nav_crowd_place
+@creates(NavAgent)
 export function nav_crowd_add_fixed(nav_st: NavState, kind: int, x: float, y: float, z: float, radius: float, height: float) -> int {
   let c = nv_crowd(nav_st, kind)
   if c == null { return -1 }
@@ -38,6 +40,7 @@ export function nav_crowd_place(nav_st: NavState, kind: int, i: int, x: float, y
   let c = nv_crowd(nav_st, kind)
   return c != null and i >= 0 and nvc_crowd_place(c, i, x, y, z, vx, vz) == 1
 }
+@releases(NavAgent)
 export function nav_crowd_remove(nav_st: NavState, kind: int, i: int) -> void {
   let c = nv_crowd(nav_st, kind)
   if c != null and i >= 0 { nvc_crowd_remove(c, i) }

packages/ludic.physics/bodies.ludic

@@ -20,12 +20,15 @@ function ph_add(physics_st: mut PhysicsState, shape: int, x: float, y: float, z:
 }
 
 # the ground: a heightfield or a mesh at the world's origin
+@creates(PhysBody)
 export function phys_ground_add(physics_st: mut PhysicsState, shape: int) -> int { return ph_add(physics_st, shape, 0.0, 0.0, 0.0, 0.0, 0, 0, 0.0) }
 # a thing that never moves: a trunk, a boulder, a tent, a bear box
 export function phys_static_add(physics_st: mut PhysicsState, shape: int, x: float, y: float, z: float, yaw: float) -> int { return ph_add(physics_st, shape, x, y, z, yaw, 0, 1, 0.0) }
 # a thing moved by the game that pushes what it meets: the player's body
+@creates(PhysBody)
 export function phys_kinematic_add(physics_st: mut PhysicsState, shape: int, x: float, y: float, z: float, yaw: float) -> int { return ph_add(physics_st, shape, x, y, z, yaw, 1, 2, 0.0) }
 # a thing that falls, rolls and floats; mass in kilograms (0: from the shape at 1000 kg/m3)
+@creates(PhysBody)
 export function phys_body_add(physics_st: mut PhysicsState, shape: int, x: float, y: float, z: float, yaw: float, mass: float) -> int { return ph_add(physics_st, shape, x, y, z, yaw, 2, 2, mass) }
 
 # after many still things are added at once, before the first query
@@ -37,6 +40,7 @@ export function phys_count(physics_st: PhysicsState) -> int {
 }
 
 # gone from the world, for good: what a struck tent needs, and the shape it owned (owned.ludic) with it
+@releases(PhysBody)
 export function phys_remove(physics_st: mut PhysicsState, id: int) -> void {
   if physics_st.ph_world == null or id < 0 { return }
   phys_sink(physics_st, id)

packages/ludic.physics/hull.ludic

@@ -2,6 +2,7 @@
 # middle. Its bow is -z at yaw 0, the way the valley faces (forward is (-sin yaw, -cos yaw)).
 
 # hx, hy, hz its half width, depth and length; buoyancy over 1 floats it (4: a quarter under)
+@creates(PhysBody)
 export function phys_hull_add(physics_st: mut PhysicsState, x: float, y: float, z: float, yaw: float, hx: float, hy: float, hz: float, mass: float, buoyancy: float, drag: float) -> int {
   let s = phys_box(physics_st, hx, hy, hz)
   let id = phys_body_add(physics_st, s, x, y, z, yaw, mass)

packages/ludic.physics/shape_ids.ludic

@@ -22,6 +22,7 @@ function ph_shape(physics_st: PhysicsState, id: int) -> pointer {
 
 # a shape let go: a body made with it keeps its own hold until it is removed, and the id may be
 # handed to the next shape made
+@releases(PhysShape)
 export function phys_shape_free(physics_st: mut PhysicsState, id: int) -> void {
   let s = ph_shape(physics_st, id)
   if s == null { return }

packages/ludic.physics/shapes.ludic

@@ -40,21 +40,27 @@ export function phys_close(physics_st: mut PhysicsState) -> void {
 }
 
 # a crate: half extents in metres
+@creates(PhysShape)
 export function phys_box(physics_st: mut PhysicsState, hx: float, hy: float, hz: float) -> int { return ph_keep(physics_st, jph_shape_box(hx, hy, hz)) }
+@creates(PhysShape)
 export function phys_sphere(physics_st: mut PhysicsState, r: float) -> int { return ph_keep(physics_st, jph_shape_sphere(r)) }
 # a trunk or a body: upright, its straight part 2 * half_h tall, centred on its origin
+@creates(PhysShape)
 export function phys_capsule(physics_st: mut PhysicsState, half_h: float, r: float) -> int { return ph_keep(physics_st, jph_shape_capsule(half_h, r)) }
 # a post: upright, 2 * half_h tall, centred on its origin
+@creates(PhysShape)
 export function phys_cylinder(physics_st: mut PhysicsState, half_h: float, r: float) -> int { return ph_keep(physics_st, jph_shape_cylinder(half_h, r)) }
 # a boulder: a dome r across and h tall, standing on its origin
 export function phys_dome(physics_st: mut PhysicsState, r: float, h: float) -> int { return ph_keep(physics_st, jph_shape_dome(r, h)) }
 
 # a rock: the convex hull of n points (x, y, z) about its origin, its edges rounded by 2 cm
+@creates(PhysShape)
 export function phys_convex(physics_st: mut PhysicsState, v: []float, n: int) -> int {
   if n < 4 or len(v) < n * 3 { return -1 }
   return ph_keep(physics_st, jph_shape_convex(v, n, 0.02))
 }
 # another shape k times its size, so one hull serves every boulder of its shape
+@creates(PhysShape)
 export function phys_scaled(physics_st: mut PhysicsState, shape: int, k: float) -> int {
   let s = ph_shape(physics_st, shape)
   if s == null { return -1 }
@@ -62,6 +68,7 @@ export function phys_scaled(physics_st: mut PhysicsState, shape: int, k: float)
 }
 
 # another shape moved and turned about y inside its body (a post whose foot is its origin)
+@creates(PhysShape)
 export function phys_offset(physics_st: mut PhysicsState, shape: int, x: float, y: float, z: float, yaw: float) -> int {
   let s = ph_shape(physics_st, shape)
   if s == null { return -1 }
@@ -70,6 +77,7 @@ export function phys_offset(physics_st: mut PhysicsState, shape: int, x: float,
 
 # n x n heights, row by row along z, the first at (ox, oz), cell metres apart; PHYS_HOLE is none
 export const PHYS_HOLE: float = 340282346638528859811704183484516925440.0
+@creates(PhysShape)
 export function phys_heightfield(physics_st: mut PhysicsState, h: []float, n: int, ox: float, oz: float, cell: float) -> int {
   if len(h) < n * n { return -1 }
   return ph_keep(physics_st, jph_shape_heightfield(h, n, ox, oz, cell))
@@ -77,12 +85,14 @@ export function phys_heightfield(physics_st: mut PhysicsState, h: []float, n: in
 
 # the ground as a renderer draws a cubic B-spline height map: tex is n x n texels, the first
 # texel's centre at (ox, oz), cell metres apart; the smoothing is done in C
+@creates(PhysShape)
 export function phys_heightfield_smooth(physics_st: mut PhysicsState, tex: []float, n: int, ox: float, oz: float, cell: float) -> int {
   if len(tex) < n * n { return -1 }
   return ph_keep(physics_st, jph_shape_heightfield_bspline(tex, n, ox, oz, cell))
 }
 
 # a dock or a cabin: v holds nv points (x, y, z), tri holds nt triangles (i, j, k)
+@creates(PhysShape)
 export function phys_mesh(physics_st: mut PhysicsState, v: []float, nv: int, tri: []int, nt: int) -> int {
   if len(v) < nv * 3 or len(tri) < nt * 3 { return -1 }
   return ph_keep(physics_st, jph_shape_mesh(v, nv, tri, nt))

packages/ludic.physics/walker.ludic

@@ -24,6 +24,7 @@ function ph_walker(physics_st: PhysicsState, id: int) -> pointer {
 }
 
 # r wide and h tall, feet at (x, y, z), mass in kg; -1 with no world
+@creates(PhysWalker)
 export function phys_walker_add(physics_st: mut PhysicsState, r: float, h: float, x: float, y: float, z: float, max_slope: float, mass: float) -> int {
   if physics_st.ph_world == null { return -1 }
   ph_buffers()
@@ -47,6 +48,7 @@ export function phys_walker_limits(physics_st: PhysicsState, id: int, step_up: f
   if k != null { jph_char_limits(k, step_up, stick, max_slope) }
 }
 
+@releases(PhysWalker)
 export function phys_walker_remove(physics_st: mut PhysicsState, id: int) -> void {
   let k = ph_walker(physics_st, id)
   if k == null { return }