ludic/packages/ludic.core/components.ludic

# components.ludic — the canonical engine-ABI components (#77).
#
# These are the exact bundles runtime/native/systems_move.ludic (#65) reads by
# name. Import this file instead of re-declaring them, and the engine-owned
# `esys_move` system moves and collides your entities for free — declare a Body
# (and optionally a Collider) and it is ticked in the Update phase.
#
# Every field is defaulted so a game overrides only what it needs, and any field
# the move system does not find on an entity no-ops cleanly. Extend by
# *composition*: attach your own components (Health, Sprite, an AI brain) on the
# same model next to these; nothing here needs subclassing.

# The world anchor: integer pixels. This is the *rendered* location — a
# framebuffer pixel is the smallest drawable unit — so it stays integer. Sub-pixel
# motion accumulates in Body.rx/ry (Q16.16) and only the whole-pixel carry reaches
# Position (see docs/RFC-POSITION-TYPES.md, #78).
property Position { x: int = 0, y: int = 0 }

# A moving body: Q16.16 velocity, optional gravity, engine-owned sub-pixel
# accumulators, and the polled contact outputs the move system writes each frame.
#   policy 0 = platformer (gravity applies)   policy 1 = top-down (no gravity)
# on_ground / hit_wall / hit_ceiling and the optional contact normal hit_nx/hit_ny
# are OUTPUTS: read them in a handler to raise your own landing / bonk events
# (the SpriteAnim.event_fired pattern — polled flags, no engine coupling).
enum BodyPolicy { Platformer, TopDown }        # Body.policy: gravity applies / no gravity
property Body {
  vx: fixed = 0.0, vy: fixed = 0.0,
  gravity: fixed = 0.0, max_fall: fixed = 0.0,
  rx: fixed = 0.0, ry: fixed = 0.0,
  policy: int = 0,
  on_ground: int = 0, hit_wall: int = 0, hit_ceiling: int = 0,
  hit_nx: int = 0, hit_ny: int = 0
}

# An axis-aligned box off the Position anchor. A solid Collider resolves swept-AABB
# collisions; a trigger (is_trigger = 1) reports overlap without resolving. layer /
# mask are collision bitmasks (0 = all); one_way = 1 is a platform that blocks only
# a downward landing. hit / entered / exited are trigger OUTPUTS.
property Collider {
  w: int = 0, h: int = 0, offx: int = 0, offy: int = 0,
  is_trigger: int = 0, one_way: int = 0, layer: int = 0, mask: int = 0,
  hit: int = 0, entered: int = 0, exited: int = 0
}

# A drawable sprite (#85): declare it and the engine-owned sprite-render system
# draws the entity each Render frame from its Position — no hand-written Render
# handler. `id` is a sprite id (png_load / atlas cell); when the entity also carries
# SpriteAnim, the current animation frame is added to it. offx/offy offset from the
# Position anchor, scale is an integer zoom (0/1 = 1:1), flip mirrors horizontally,
# tint (non-zero) draws every opaque pixel in one colour (hit flash), hidden = 1
# skips it. Draw order is spawn order; a game wanting custom draw omits Sprite.
# atlas = 1 marks `id` as an atlas sprite (Sprite.cell / Sprite.cell_span — any size,
# including multi-cell characters); 0 = the 16x16 sprite table (png_load). (#90)
# move_id: the strip drawn while the entity moves (0 = always `id`); face = 1 turns
# the sprite toward its movement (TopDown intent, else Body velocity); flash and
# blink are countdowns: white tint while flash > 0, hidden every other pair of
# frames while blink > 0 (a hit flash and invulnerability blink, no handler).
property Sprite {
  id: int = 0, offx: int = 0, offy: int = 0, scale: int = 1, flip: int = 0, tint: int = 0, hidden: int = 0, atlas: int = 0,
  move_id: int = 0, face: int = 0, flash: countdown = 0, blink: countdown = 0
}

# Collider.center(e): the middle of an entity's box, from its Position and Collider
@Namespace(Collider) function collider_center(e: int) -> IVec2 {
  let PP = World.prop_id("Position")
  let PC = World.prop_id("Collider")
  var x = 0;  var y = 0;  var w = 0;  var h = 0
  if (PP >= 0) and (World.has(e, PP) != 0) { x = World.get(e, PP, World.field_id(PP, "x"));  y = World.get(e, PP, World.field_id(PP, "y")) }
  if (PC >= 0) and (World.has(e, PC) != 0) { w = World.get(e, PC, World.field_id(PC, "w"));  h = World.get(e, PC, World.field_id(PC, "h")) }
  return IVec2.make(x + w / 2, y + h / 2)
}

# Optional single config entity that turns the tile-grid broadphase on: solids are
# read from the Map.* tilemap. tile > 0 sets the tile size in px; wall is the solid
# glyph; oneway is an optional one-way-platform glyph (0 = none).
# solid2 is an optional second solid glyph (0 = none) — e.g. a closed door drawn with
# its own TileSkin while it blocks movement.
property Solids { tile: int = 0, wall: int = 0, oneway: int = 0, solid2: int = 0 }

# The engine-advanced animation clock (esys_spriteanim): `frame` is the current cell
# (0..frames-1) and the sprite system adds it to Sprite.id. mode 0 loop, 1 once, 2 pingpong.
enum AnimMode { Loop, Once, PingPong }         # SpriteAnim.mode
property SpriteAnim { ticks: int = 0, fps: int = 8, frames: int = 4, mode: int = 0, frame: int = 0 }

# One entity per map glyph: the engine tilemap-render system paints every Map.* cell
# carrying `glyph` with `sprite` (atlas id when atlas = 1), before sprites are drawn.
property TileSkin { glyph: int = 0, sprite: int = 0, atlas: int = 1, size: int = 16, scale: int = 1 }

# Optional single config entity defining a world boundary / play area (#84): a rect
# (x, y, w, h) and a policy the engine applies to every moving Body each frame —
# 0 clamp (walls), 1 wrap (toroidal), 2 bounce (flip velocity), 3 kill (despawn when
# fully outside). Off by default (no Bounds entity = open world).
enum BoundsPolicy { Clamp, Wrap, Bounce, Kill }   # Bounds.policy
property Bounds { x: int = 0, y: int = 0, w: int = 0, h: int = 0, policy: int = 0 }