Lifecycle hooks: @OnStart/@OnQuit, @OnDespawn, @OnAttach (like @OnSpawn)

Adds the rest of the game/entity/property lifecycle as @-hooks, each firing at
one timeline moment and reducing to ordinary code:

- @OnStart / @OnQuit (program): @OnStart aliases the Start phase; @OnQuit runs in
  the frame loop's done: block, after the loop stops and before teardown.
- @OnDespawn(Model) (entity): a destructor. Despawn doesn't statically know the
  entity's model, so hooks compile to @on_despawn_<Model>(entity) functions and
  emit_despawn dispatches on @L_kind. Symmetric with @OnSpawn.
- @OnAttach(Property): fires in emit_init_component once a property is attached
  and seeded, with the property bound by name.

Registries + parsing mirror @OnSpawn. examples/lifecycle.ludic narrates the whole
timeline (output 1 700 50 950 2). Behaviour-preserving (goldens byte-identical,
despawn users unaffected when no hooks registered); test.sh 16/16, fixpoint holds.

Deferred: @OnDetach (per-property runtime dispatch) and scene @OnEnter/@OnExit
(need scene support in the compiler).

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

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, "OnSpawn") { eat_op("("); onspawn_model = eat_id(); eat_op(")") }   # @OnSpawn(Model)
+    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(")") }
+    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
-      register_onspawn(onspawn_model, h.a); return
-    }
+    if not ptr_is_null(onspawn_model) { register_onspawn(onspawn_model, h.a); return }       # spawn hook
+    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"