ludic/runtime/native/systems.ludic

# ============================================================================
# systems.ludic — engine-owned systems that run automatically over user
# components, each frame, without the game wiring a handler.
#
# This is the ECS hook issues #43 and #47 named as their real dependency: until
# now every system was a `handler` the game wrote. These `esys_*` functions are
# systems the *engine* owns — the compiler splices this file and inserts a call
# to each one at the right phase of the frame loop (see emit_engine_systems_for_
# phase in emit_game.ludic), so a component the game merely *declares and carries*
# is ticked for free.
#
# They stand entirely on the reflection ABI (World.prop_id / field_id / get /
# set / query_next — the same by-name world table a mod reads), so they never
# compile against a fixed field layout: a system resolves its fields by name and
# no-ops cleanly when the component (or a field) is absent. Everything is integer
# and deterministic — the frame clock ticks at a fixed 60/s — so replays and
# lockstep netcode reproduce animation and motion exactly.
#
# The opt-in is declaring the well-known component. A game that wants sprite
# animation declares `property SpriteAnim { ticks, fps, frames, mode, frame }`
# and puts it on a model; the engine advances `frame` every tick. No component,
# no system emitted — a game without them is byte-for-byte unchanged.
# ============================================================================

# floor of a/b for non-negative a (the frame clock only ever counts up).
function esys_div(a: int, b: int) -> int {
  if b <= 0 { return 0 }
  return a / b
}

# ---- SpriteAnim: spritesheet frame advance (#43) ---------------------------
# Component contract — `property SpriteAnim { ticks: int, fps: int, frames: int,
# mode: int, frame: int }`:
#   ticks   engine frames elapsed since the clip started (the engine advances it)
#   fps     playback rate in frames per second
#   frames  number of cells in the clip
#   mode    0 = loop, 1 = once (clamp on last), 2 = pingpong (bounce)
#   frame   OUTPUT: the cell index to draw this frame
# elapsed = ticks * fps / 60 whole animation frames; `mode` maps that back into
# 0..frames-1. Pure integer, so the same tick count always yields the same cell.
function esys_spriteanim() -> void {
  let p = World.prop_id("SpriteAnim")
  if p < 0 { return }
  let f_ticks  = World.field_id(p, "ticks")
  let f_fps    = World.field_id(p, "fps")
  let f_frames = World.field_id(p, "frames")
  let f_mode   = World.field_id(p, "mode")
  let f_frame  = World.field_id(p, "frame")
  if f_ticks < 0 { return }
  if f_frame < 0 { return }
  var e = World.query_next(p, 0)
  while e >= 0 {
    let ticks = World.get(e, p, f_ticks) + 1
    World.set(e, p, f_ticks, ticks)
    let fps    = World.get(e, p, f_fps)
    var frames = World.get(e, p, f_frames)
    let mode   = World.get(e, p, f_mode)
    if frames < 1 { frames = 1 }
    let elapsed = esys_div(ticks * fps, 60)          # whole animation frames elapsed
    var fr = 0
    if mode == 1 {                                   # once: clamp on the last frame
      fr = elapsed
      if fr > frames - 1 { fr = frames - 1 }
    } else {
      if mode == 2 {                                 # pingpong: bounce 0..frames-1..0
        let period = max(1, frames * 2 - 2)
        let m = elapsed % period
        if m < frames { fr = m } else { fr = period - m }
      } else {                                       # loop (mode 0 / default)
        fr = elapsed % frames
      }
    }
    World.set(e, p, f_frame, fr)
    e = World.query_next(p, e + 1)
  }
}

# ---- Motion: value tween advance (#43) -------------------------------------
# Component contract — `property Motion { ticks: int, dur: int, from: int,
# to: int, ease: int, value: int, done: int }`:
#   ticks   engine frames elapsed since the tween started (engine advances it)
#   dur     duration in engine frames (ticks); dur <= 0 snaps straight to `to`
#   from,to the interpolation endpoints (integer game units — position, alpha…)
#   ease    0 = linear, 1 = in (t^2), 2 = out, 3 = in-out
#   value   OUTPUT: the interpolated value this frame
#   done    OUTPUT: 1 once ticks has reached dur, else 0
# progress is carried in 0..1024 so easing curves are exact in integer math.
function esys_motion_ease(t: int, ease: int) -> int {
  if ease == 1 { return t * t / 1024 }               # ease-in: t^2
  if ease == 2 {                                      # ease-out: 1-(1-t)^2
    let u = 1024 - t
    return 1024 - (u * u / 1024)
  }
  if ease == 3 {                                      # ease-in-out
    if t < 512 { return (t * t / 1024) * 2 }
    let u = 1024 - t
    return 1024 - (u * u / 1024) * 2
  }
  return t                                            # linear
}

function esys_motion() -> void {
  let p = World.prop_id("Motion")
  if p < 0 { return }
  let f_ticks = World.field_id(p, "ticks")
  let f_dur   = World.field_id(p, "dur")
  let f_from  = World.field_id(p, "from")
  let f_to    = World.field_id(p, "to")
  let f_ease  = World.field_id(p, "ease")
  let f_value = World.field_id(p, "value")
  let f_done  = World.field_id(p, "done")
  if f_ticks < 0 { return }
  if f_value < 0 { return }
  var e = World.query_next(p, 0)
  while e >= 0 {
    let dur = World.get(e, p, f_dur)
    var ticks = World.get(e, p, f_ticks) + 1
    if ticks > dur { ticks = dur }                    # clamp so `value` rests at `to`
    World.set(e, p, f_ticks, ticks)
    let from = World.get(e, p, f_from)
    let to   = World.get(e, p, f_to)
    let ease = World.get(e, p, f_ease)
    var t = 1024
    if dur > 0 { t = esys_div(ticks * 1024, dur) }
    if t > 1024 { t = 1024 }
    let te = esys_motion_ease(t, ease)
    let value = from + (to - from) * te / 1024
    World.set(e, p, f_value, value)
    if f_done >= 0 {
      var d = 0
      if ticks >= dur { d = 1 }
      World.set(e, p, f_done, d)
    }
    e = World.query_next(p, e + 1)
  }
}