ludic/docs/language/annotations/annot-onstart.md

---

id: annot-onstart name: @OnStart category: annotations kind: annotation tokens: @OnStart sig: @OnStart handler Name { … } tip: Run a handler once at boot instead of assigning it a frame phase. order: 50

@OnStart pins a handler to the program's boot moment: it runs exactly once when the program starts, before the per-frame phases begin, instead of being placed in a recurring phase. Use it for one-time setup — spawning the initial world, seeding program vars, loading a scene. It overrides the handler's phase, so you write @OnStart handler Name { … } rather than handler Name phase Start and get the same once-at-boot placement through the annotation channel. Its shutdown counterpart is @OnQuit; add @Public to also emit a program_start event other modules can hook.

program BootHook {
  property Health { current: int = 0, maximum: int = 100 }
  model Player { Health }

  state BootHookState {
    elapsed_frames: int = 0
  }

  @OnStart handler CreateWorld(boot_hook_st: mut BootHookState) {                     # runs once at boot
    spawn Player { Health { current: 100, maximum: 100 } }
    boot_hook_st.elapsed_frames = 0
  }

  handler CountFrames(boot_hook_st: mut BootHookState) phase Update { boot_hook_st.elapsed_frames = boot_hook_st.elapsed_frames + 1 }
}