Merge lifecycle hooks: @OnStart/@OnQuit/@OnDespawn/@OnAttach

The full game/entity/property lifecycle as @-hooks, symmetric with @OnSpawn.
test.sh 16/16, C-free fixpoint holds, goldens byte-identical.

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

LANGUAGE.md

@@ -295,24 +295,43 @@ property Velocity {
 }
 ```
 
-**`@OnSpawn` — a constructor.** `@OnSpawn(Model)` on a handler runs its body every
+**Lifecycle hooks.** A game's timeline has fixed moments, and each is a handler
-time a `Model` is spawned, with the model's properties bound by name — a place to
+annotation. They fire in this order and each reduces to ordinary code, so the
-initialize an entity. It's a handler keyed to the spawn, not an observer on the
+data stays plain and behaviour stays in handlers:
-data, so the ECS model is untouched:
+
+```
+boot ── @OnStart ─▶ spawn ── @OnAttach(P), @OnSpawn(M) ─▶ … ── @OnDespawn(M) ─▶ quit ── @OnQuit
+```
+
+- **`@OnStart` / `@OnQuit`** — the *program*. `@OnStart` runs once at boot (it is
+  the `Start` phase); `@OnQuit` runs once at shutdown, after the frame loop stops
+  and before the process exits — the place to `save()` or clean up.
+- **`@OnSpawn(Model)` / `@OnDespawn(Model)`** — an *entity*. Both bind the model's
+  properties by name; `@OnSpawn` is a constructor, `@OnDespawn` a destructor.
+  Despawn doesn't statically know an entity's model, so despawn hooks compile to
+  functions dispatched on the entity's kind.
+- **`@OnAttach(Property)`** — a *property*, fired each time that property is
+  attached to an entity (once its fields are seeded), with the property bound by
+  name.
 
 ```ludic
-# doc-check: skip — a spawn hook
+# doc-check: skip — lifecycle hooks
-@OnSpawn(Enemy)
+@OnStart          handler Boot  { seed(1) }
-handler InitEnemy { Health.hp = Health.max }     # start every Enemy at full HP
+@OnSpawn(Enemy)   handler Init  { Health.hp = Health.max }     # constructor
+@OnDespawn(Enemy) handler Clean { drop_loot(Health.hp) }       # destructor
+@OnAttach(Sprite) handler Load  { Sprite.id = image_load("goblin.png") }
+@OnQuit           handler Save  { save() }                     # once, at shutdown
 ```
 
 **`@Handles` — the handlers a program drives.** Written in front of the
 `program`, `@Handles(Move)` names the handlers it uses. It parses and reads as
 documentation; every declared handler still runs (registration is implicit).
 
-See [`examples/annotations.ludic`](examples/annotations.ludic), which uses all
+See [`examples/annotations.ludic`](examples/annotations.ludic) (queries, computed
-four. (`@OnDespawn` and change-reactions are future work — despawn doesn't
+fields, one hook) and [`examples/lifecycle.ludic`](examples/lifecycle.ludic) (the
-statically know an entity's model, and reactions need change-tracking.)
+whole timeline). Still to come: **`@OnDetach`** (needs the same runtime kind
+dispatch as despawn, per property) and **scene** hooks (`@OnEnter`/`@OnExit`),
+which wait on `scene` support landing in the compiler.
 
 ## Structs, arrays and slices
 

examples/lifecycle.ludic

@@ -0,0 +1,28 @@
+# lifecycle.ludic — a game's whole lifecycle as @-hooks. Each fires at one point
+# on the timeline and reduces to ordinary code, so nothing is hidden and the
+# data-oriented model is untouched. Running it prints: 1 700 50 950 2 — one line
+# per hook, in the order the timeline reaches them.
+#
+#   boot ── @OnStart ──▶ spawn ── @OnAttach, @OnSpawn ──▶ … ── @OnDespawn ──▶ quit ── @OnQuit
+program Life {
+  property Health { hp: int = 0, max: int = 100 }
+  property Sprite { id: int = 0 }
+  model Enemy { Health, Sprite }
+
+  # ---- program lifecycle -----------------------------------------------------
+  @OnStart handler Boot { print_int(1) }               # once, at boot
+  @OnQuit  handler Bye  { print_int(2) }               # once, at shutdown
+
+  # ---- property / entity lifecycle -------------------------------------------
+  @OnAttach(Sprite)  handler Load  { print_int(Sprite.id + 700) }   # when a Sprite is attached
+  @OnSpawn(Enemy)    handler Init  { Health.hp = Health.max }        # constructor
+  @OnDespawn(Enemy)  handler Clean { print_int(Health.hp + 900) }    # destructor (dispatched by kind)
+
+  handler Seed phase Start { spawn Enemy { Health { max: 50 } } }
+
+  handler Run phase Render {
+    for (h) in query [Health] { print_int(h.hp) }      # 50 — Init set hp to max
+    for (e) in query [Health] { despawn self() }        # Clean fires: 50 + 900 = 950
+    quit()
+  }
+}

selfhost/emit_core.ludic

@@ -176,6 +176,29 @@ fn onspawn_body(model: ptr) -> Node {
   return ptr_null()
 }
 
+# @OnDespawn(Model): a Model -> hook-body registry. Despawn does not statically
+# know an entity's model, so these are emitted as functions and dispatched on the
+# entity's kind at each `despawn`. @OnAttach(Property) fires per property-attach.
+var g_ondespawn: []Node         # each: s = Model name, a = hook body block
+var g_onattach: []Node          # each: s = Property name, a = hook body block
+
+fn register_ondespawn(model: ptr, body: Node) -> void {
+  let n = node(N_BLOCK); n.s = model; n.a = body; push(g_ondespawn, n)
+}
+fn ondespawn_body(model: ptr) -> Node {
+  let i = 0
+  while i < len(g_ondespawn) { if streq(g_ondespawn[i].s, model) { return g_ondespawn[i].a };  i = i + 1 }
+  return ptr_null()
+}
+fn register_onattach(prop: ptr, body: Node) -> void {
+  let n = node(N_BLOCK); n.s = prop; n.a = body; push(g_onattach, n)
+}
+fn onattach_body(prop: ptr) -> Node {
+  let i = 0
+  while i < len(g_onattach) { if streq(g_onattach[i].s, prop) { return g_onattach[i].a };  i = i + 1 }
+  return ptr_null()
+}
+
 # local variable environment
 fn loc_reset() -> void { nloc = 0 }
 fn loc_push(name: ptr, r: ptr, ty: ptr) -> void {

selfhost/emit_game.ludic

@@ -29,10 +29,37 @@ fn emit_calls_for_phase(phase: ptr) -> void {
   }
 }
 
+# @OnDespawn(Model) hooks compile to `@on_despawn_<Model>(entity)` functions that
+# bind the model's properties and run the body — dispatched by kind at `despawn`.
+fn emit_despawn_hooks() -> void {
+  let i = 0
+  while i < len(g_ondespawn) {
+    let hk = g_ondespawn[i]
+    let model = find_arch(hk.s)
+    ll_t = 0;  ll_lbl = 0;  g_term = false;  loc_reset();  nloop = 0;  nself = 0
+    ret_ty = "void"
+    let fbody = buf_new()
+    falloc = buf_new()
+    let saved = code
+    code = fbody
+    emit_bind_props(model, "%e")
+    emit_block(hk.a)
+    if not g_term { emit("  br label %ret\n") }
+    emit("ret:\n  ret void\n")
+    code = saved
+    emit("define void @on_despawn_");  emit(hk.s);  emit("(i32 %e) {\nentry:\n")
+    emit(buf_str(falloc))
+    emit(buf_str(fbody))
+    emit("}\n\n")
+    i = i + 1
+  }
+}
+
 fn emit_game_main() -> void {
   # every system becomes a function first
   let i = 0
   while i < len(prog) { if prog[i].kind == N_SYS { emit_system_fn(prog[i]) };  i = i + 1 }
+  emit_despawn_hooks()
 
   emit("define i32 @main(i32 %argc, ptr %argv) {\nentry:\n")
   emit("  store i32 %argc, ptr @L_argc\n")
@@ -63,6 +90,7 @@ fn emit_game_main() -> void {
   emit_calls_for_phase("Render")
   emit("  br label %loop\n")
   emit("done:\n")
+  emit_calls_for_phase("OnQuit")               # @OnQuit shutdown hooks run once, before teardown
   if not ptr_is_null(find_fn("rt_shutdown")) { emit("  call void @fn_rt_shutdown()\n") }
   emit("  ret i32 0\n}\n")
 }

selfhost/emit_spawn.ludic

@@ -37,6 +37,16 @@ fn emit_init_component(e: ptr, comp: ptr, rec: Node) -> void {
       j = j + 1
     }
   }
+  # @OnAttach(Property) runs once the property is attached and seeded
+  let ab = onattach_body(comp)
+  if not ptr_is_null(ab) {
+    let save = nloc
+    let vslot = emit_alloca("ptr")
+    emit("  store ptr ");  emit(slot);  emit(", ptr ");  emit(vslot);  emit("\n")
+    loc_push(comp, vslot, comp)
+    emit_block(ab)
+    nloc = save
+  }
 }
 
 # bind each of a model's properties to entity `e`'s component storage, so an
@@ -87,5 +97,21 @@ fn emit_spawn(st: Node) -> void {
 
 fn emit_despawn(st: Node) -> void {
   let v = emit_expr(st.a)
+  # @OnDespawn: dispatch on the entity's kind and run the matching model's hook
+  if len(g_ondespawn) > 0 {
+    let me = itoa(MAX_ENT)
+    let kp = nreg();  emit("  ");  emit(kp);  emit(" = getelementptr inbounds [");  emit(me);  emit(" x i32], ptr @L_kind, i32 0, i32 ");  emit(v.code);  emit("\n")
+    let kind = emit_bind(sconcat("load i32, ptr ", kp))
+    let i = 0
+    while i < len(g_ondespawn) {
+      let mname = g_ondespawn[i].s
+      let c = emit_bind(sconcat("icmp eq i32 ", sconcat(kind, sconcat(", ", itoa(find_arch_id(mname))))))
+      let yes = lbl("dh");  let no = lbl("dhn")
+      emit("  br i1 ");  emit(c);  emit(", label %");  emit(yes);  emit(", label %");  emit(no);  emit("\n")
+      emit(yes);  emit(":\n  call void @on_despawn_");  emit(mname);  emit("(i32 ");  emit(v.code);  emit(")\n")
+      emit("  br label %");  emit(no);  emit("\n");  emit(no);  emit(":\n")
+      i = i + 1
+    }
+  }
   emit("  call void @L_free_entity(i32 ");  emit(v.code);  emit(")\n")
 }

selfhost/parse.ludic

@@ -283,13 +283,20 @@ fn parse_one_decl() -> void {
   let is_export = false
   let qspec: Node = ptr_null()
   let onspawn_model: ptr = ptr_null()
+  let ondespawn_model: ptr = ptr_null()
+  let onattach_prop: ptr = ptr_null()
+  let hook_phase: ptr = ptr_null()            # @OnStart / @OnQuit override the phase
   while is_op("@") {
     pi = pi + 1; let a = eat_id()             # collect a leading @annotation
     if streq(a, "export") { is_export = true }
-    else { if streq(a, "Queries") { qspec = parse_queries_anno() }   # @Queries(these: [...], on: ...)
+    else { if streq(a, "Queries") { qspec = parse_queries_anno() }               # @Queries(these: [...], on: ...)
-    else { if streq(a, "OnSpawn") { eat_op("("); onspawn_model = eat_id(); eat_op(")") }   # @OnSpawn(Model)
+    else { if streq(a, "OnSpawn") { eat_op("("); onspawn_model = eat_id(); eat_op(")") }
+    else { if streq(a, "OnDespawn") { eat_op("("); ondespawn_model = eat_id(); eat_op(")") }
+    else { if streq(a, "OnAttach") { eat_op("("); onattach_prop = eat_id(); eat_op(")") }
+    else { if streq(a, "OnStart") { hook_phase = "Start" }                       # boot
+    else { if streq(a, "OnQuit") { hook_phase = "OnQuit" }                       # shutdown
     else { if is_op("(") { let d = 0          # any other @anno(args) — parsed and skipped
-        while true { if is_op("(") { d = d + 1 };  if is_op(")") { d = d - 1 };  pi = pi + 1;  if d == 0 { break } } } } } }
+        while true { if is_op("(") { d = d + 1 };  if is_op(")") { d = d - 1 };  pi = pi + 1;  if d == 0 { break } } } } } } } } } }
     skipnl()
   }
   if is_id("import") { pi = pi + 1
@@ -305,9 +312,10 @@ fn parse_one_decl() -> void {
   if is_id("model") { push(prog, parse_archetype()); return }
   if is_id("handler") {
     let h = parse_system()
-    if not ptr_is_null(onspawn_model) {        # @OnSpawn(Model): a spawn hook, not a phased handler
+    if not ptr_is_null(onspawn_model) { register_onspawn(onspawn_model, h.a); return }       # spawn hook
-      register_onspawn(onspawn_model, h.a); return
+    if not ptr_is_null(ondespawn_model) { register_ondespawn(ondespawn_model, h.a); return } # despawn hook
-    }
+    if not ptr_is_null(onattach_prop) { register_onattach(onattach_prop, h.a); return }      # attach hook
+    if not ptr_is_null(hook_phase) { h.ty = hook_phase }                                     # @OnStart/@OnQuit
     if not ptr_is_null(qspec) {               # @Queries wraps the body in its S_QUERY
       qspec.a = h.a
       let wrap = node(N_BLOCK); push(wrap.kids, qspec); h.a = wrap
@@ -353,6 +361,8 @@ fn parse_program() -> void {
   prog = new []Node
   g_computed = new []Node
   g_onspawn = new []Node
+  g_ondespawn = new []Node
+  g_onattach = new []Node
   loaded_paths = new []ptr
   skipnl()
   g_game_name = "Ludic"

test.sh

@@ -56,6 +56,11 @@ if ./selfhost/game-build.sh build/ludicc examples/annotations.ludic "/tmp/ludic_
    && [ "$(/tmp/ludic_ann </dev/null | tr '\n' ' ')" = "3 25 0 0 " ]; then
   ok "annotations.ludic (@Queries / @Computed / @OnSpawn / @Handles)"
 else bad "annotations: $(tail -1 /tmp/ann.out)"; fi
+# Lifecycle hooks fire in timeline order: @OnStart @OnAttach @OnSpawn @OnDespawn @OnQuit.
+if ./selfhost/game-build.sh build/ludicc examples/lifecycle.ludic "/tmp/ludic_life" >/tmp/life.out 2>&1 \
+   && [ "$(/tmp/ludic_life </dev/null | tr '\n' ' ')" = "1 700 50 950 2 " ]; then
+  ok "lifecycle.ludic (@OnStart/@OnAttach/@OnSpawn/@OnDespawn/@OnQuit in order)"
+else bad "lifecycle: $(tail -1 /tmp/life.out)"; fi
 # --- Toolchain-agent CLI smoke tests append below this line ---
 echo "== self-hosted front-end binaries (ludicc / ludic) =="
 # The two commands are one multi-call native binary built from the seed with