lecodes-sdk 0.19.0

package/src/gl/touch.ts

@@ -0,0 +1,68 @@
+// 3D pointer dispatch. Registers the host touch callbacks lazily (first listener) and routes hits to
+// the struck Node and to the active scene's listeners. Ported from worker/src/TouchEventSystem.ts.
+
+import { ClickEvent, TouchStartEvent, type TrackHandler } from "../runtime/touch"
+import { nodeRegistry } from "./Node"
+import { glState } from "./state"
+
+// Hits inside a loaded model (GLB) land on sub-entities the user never created a Node for — walk up
+// the transform hierarchy to the nearest entity someone actually holds (the model's Node).
+const resolveHitNode = (entityId: number) => {
+  let node = nodeRegistry.get(entityId)
+  for (let id = entityId, i = 0; !node && i < 32; i++) {
+    id = _creator.getParent(id)
+    if (id === 0) break
+    node = nodeRegistry.get(id)
+  }
+  return node ?? null
+}
+
+const onTouchEnd = (pointerId: number, clientX: number, clientY: number, entityId: number): TrackHandler | null => {
+  const scene = glState.activeScene
+  if (!scene) return null
+  const ev = new ClickEvent<any>(clientX, clientY, pointerId)
+  if (entityId > 0) {
+    const node = resolveHitNode(entityId)
+    ev.target = node
+    if (node) node._dispatchEvent("click", ev)
+  } else {
+    ev.target = null
+  }
+  for (const listener of scene._clickListeners.slice()) listener(ev)
+  return null
+}
+
+const onTouchStart = (pointerId: number, clientX: number, clientY: number, entityId: number): TrackHandler | null => {
+  const scene = glState.activeScene
+  if (!scene) return null
+  const ev = new TouchStartEvent<any>(clientX, clientY, pointerId)
+  if (entityId > 0) {
+    const node = resolveHitNode(entityId)
+    ev.target = node
+    if (node) {
+      node._dispatchEvent("touchstart", ev)
+      if (ev._trackHandler) return ev._trackHandler
+    }
+  } else {
+    ev.target = null
+  }
+  for (const listener of scene._touchStartListeners.slice()) {
+    listener(ev)
+    if (ev._trackHandler) return ev._trackHandler
+  }
+  return null
+}
+
+let touchStartRegistered = false
+export const registerTouchStartEvent = (): void => {
+  if (touchStartRegistered) return
+  touchStartRegistered = true
+  _creatorUI.registerTouchStartEvent(onTouchStart)
+}
+
+let touchEndRegistered = false
+export const registerTouchEndEvent = (): void => {
+  if (touchEndRegistered) return
+  touchEndRegistered = true
+  _creatorUI.registerTouchEndEvent(onTouchEnd)
+}

package/src/host.d.ts

@@ -0,0 +1,61 @@
+// JS-runtime globals provided by the host engine (web viewer / desktop / iOS), NOT by the SDK.
+// Declared only so SDK and user code type-check — never bundled or injected. Mirrors
+// packages/projects/src/global.d.ts.
+
+declare global {
+  function setTimeout(handler: (...args: any[]) => void, timeout?: number): number
+  function setInterval(handler: (...args: any[]) => void, timeout?: number): number
+  function clearTimeout(id: number): void
+  function clearInterval(id: number): void
+  /** Per-frame loop, driven by the host (viewer RAF / desktop runTick). `dt` is **seconds** since
+   *  the previous frame. */
+  function setLoop(handler: (dt: number) => void): number
+  function clearLoop(id: number): void
+
+  /** π/180 — substituted at compile time (bundler `define`). */
+  var DEG2RAD: number
+  /** 180/π — substituted at compile time (bundler `define`). */
+  var RAD2DEG: number
+
+  /** Compile-time boolean: `true` in scene-editor bundles, `false` (const-folded + DCE'd) in
+   *  shipped ones — `if (EDITOR) { … }` costs zero bytes in production. `*.editor.ts` files are
+   *  the file-level form. */
+  var EDITOR: boolean
+
+  var console: {
+    log(...data: any[]): void
+    warn(...data: any[]): void
+    info(...data: any[]): void
+    error(...data: any[]): void
+  }
+
+  /** Compile-time macro: `asset('./hero.png')` is desugared by the bundler into the module import
+   *  for that resource. The file must exist — a path that resolves to nothing fails the compile
+   *  (`asset not found: ./hero.png (main.ts:3)`); there is no runtime fallback. Calls inside
+   *  comments and string literals are text, not macros. */
+  function asset(path: string): string
+
+  /** Compile-time macro: installs a font and returns its family name — using a font IS declaring
+   *  it. A registry id (`font("manrope")`) resolves against the font registry; a project path
+   *  (`font("./fonts/Brand.ttf")`) reads family/weight/italic from the file itself. `opts`
+   *  narrows/extends the face set (default: the family's standard weights). String-literal
+   *  argument only. No awaiting — faces load with app boot and the host holds first paint for
+   *  them. */
+  function font(id: string, opts?: { weights?: number[], italic?: boolean }): string
+
+  /** Compile-time macro: resolves one icon from the icon registry at build time and inlines it as
+   *  an image source for `UIImage(...)` — offline, identical on every host. `id` is `"pack:name"`
+   *  (e.g. `"lucide:bell"`), string literal only. Recolor via `{ color }`: a hex LITERAL is baked
+   *  into the SVG at compile time, a token/expression is applied as a tint (as is the `tintColor`
+   *  style prop). */
+  function assetIcon(id: string, opts?: { color?: string }): { readonly svg: string, tintColor: string | null }
+
+  /** Type-only editor convenience: the style object type of a UI element. `Style<UIButton>` (or
+   *  `Style<typeof myButton>`) is what you'd pass to `el.style(...)` — for typing reusable style
+   *  presets. Deliberately no `Partial<>` wrapper: every style prop is already optional, and
+   *  Partial over ClassStyles' `$`-index signature adds `| undefined`, breaking assignability back
+   *  into `.style(...)`. Round-trip guarded by sdk/tests/ui-types.test.ts. */
+  type Style<T> = T extends { style: (s: infer S) => any } ? S : never
+}
+
+export {}

package/src/inject.ts

@@ -0,0 +1,203 @@
+// THE aggregation point. Every public global the SDK provides is re-exported here under the exact
+// name user code uses it as. The bundler passes this file to esbuild's `inject:` option, so user
+// code references `Scene`, `Sprite`, `toast`, … with no imports; esbuild tree-shakes away whatever
+// a given project does not use (so a pure-2D project drops all 3D classes, and vice versa).
+//
+// Rule: this is the ONLY file that `export`s public names. Everything else is internal and imported
+// by it. Host-provided globals (setLoop, console, setTimeout, DEG2RAD, asset, …) are NOT here —
+// they live in src/host.d.ts as declarations and stay as free references at runtime.
+
+// ---- math ----
+export { Mathf } from "./math/Mathf"
+export { Vec2, Vec3 } from "./math/vec"
+export { Quat } from "./math/quat"
+export { Mat4 } from "./math/mat4"
+export { Color } from "./core/color"
+
+// ---- aspects (attachable node capabilities) ----
+export { Aspect, System, type With, type SystemHost } from "./core/Aspect"
+export { type EventMap } from "./core/events"
+export { Time } from "./core/time"
+export { StateMachine, defineStates, type StateDef, type StatesDef, type StateGuard, type StateHandler, type StateMachineEvents } from "./core/StateMachine"
+export { InspectorUI } from "./core/InspectorUI"
+
+// ---- reactivity (signals; UI text/style props also accept `() => value` bindings) ----
+export { signal, computed, effect, type Signal, type Computed } from "./core/signals"
+export { __compWrite, __compOp, type CompAxis, type CompWriter } from "./core/compWrite"
+
+// ---- canvas (core 2D drawing that bakes to a texture; shared by 2D/3D/UI) ----
+export { Canvas, Bitmap } from "./canvas/Canvas"
+
+// ---- platform runtime (injected globals; the host provides the lower-level _creator* bridges) ----
+export { toast, openURL, SvgSource } from "./runtime/misc"
+export { app, type AppState, type OrientationLock } from "./runtime/app"
+export { clipboard } from "./runtime/clipboard"
+export { date, type DateValue, type DateInput, type Unit, type Locale } from "./runtime/datetime"
+export { fetch, fetchLocal, FormData, File, type FetchResponse } from "./runtime/fetch"
+export { localStorage } from "./runtime/storage"
+export { device, type HapticStyle, type MotionOptions } from "./runtime/device"
+export { Input, InputChannel, type InputKeyEvent, type InputGamepadEvent, type InputEventName, type GamepadState, type GamepadAxisName } from "./runtime/input"
+export { WebSocket } from "./runtime/net"
+// Multiplayer (docs/multiplayer-plan.md): roles, players, JSON messages over the _creatorNet transport.
+export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, type NetStatus, type NetEvents, type NetLaunch, type NetInput, type NetKind, type NetTransform } from "./net"
+// App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
+// only ever imports its server functions (docs/backend-plan.md §4).
+export { __rpc, __channel, __serverOnly, RpcError, type ClientChannel } from "./runtime/rpc"
+export { AudioPlayer, VideoPlayer } from "./runtime/media"
+export { openFilePicker, files, type FileData } from "./runtime/files"
+export { share } from "./runtime/share"
+export { ClickEvent, TouchStartEvent, LongPressEvent } from "./runtime/touch"
+
+// ---- 2D engine (creator-2d) ----
+export { Scene2D } from "./g2/Scene2D"
+export { Node2D } from "./g2/Node2D"
+export { Camera2D } from "./g2/Camera2D"
+export { Sprite } from "./g2/Sprite"
+export { SpriteAnimation } from "./g2/SpriteAnimation"
+export { Shape2D } from "./g2/Shape2D"
+export { Physics2D } from "./g2/Physics2D"
+export { Trigger2D } from "./g2/Trigger2D"
+export { CharacterController2D } from "./g2/CharacterController2D"
+export { OneWay2D } from "./g2/OneWay2D"
+export { PhysicsGroup2D } from "./g2/groups2d"
+export { Tilemap } from "./g2/Tilemap"
+export { Texture2D } from "./g2/Texture2D"
+// sprite sheets as data (.sprite.ts files — see src/g2/SpriteSheet.ts)
+export { SpriteSheet, defineSpriteSheet } from "./g2/SpriteSheet"
+export type { SpriteSheetDef, SheetSprite, SpriteMakeOptions } from "./g2/SpriteSheet"
+// tilesets as data (.tiles.ts files — autotile materials, see src/g2/Tileset.ts + autotile.ts)
+export { Tileset, defineTileset, Autotile2D } from "./g2/Tileset"
+export { rawCell, isRawCell, rawIndex } from "./g2/autotile"
+export { rot90, rot180, rot270, flipX, packTile, tileIndex, tileTurns, tileFlip, tileOriented } from "./g2/autotile"
+export type {
+  TilesetDef, TileMaterial, PatchMaterial, PathMaterial, PatchSlots, EdgeSlot, FillBlock, BlockEntry,
+  TileBlock, TilePart,
+} from "./g2/autotile"
+// 2D scenes as data (.scene2d.ts files — see src/g2/defineScene2d.ts) + the cells('…') payload
+export { defineScene2d, Scene2dHandle } from "./g2/defineScene2d"
+export type { Scene2dDef, Scene2dNodeDef, Scene2dEnv, SpriteSourceDef, TilemapSourceDef, Camera2dNodeDef, LoadedScene2d } from "./g2/defineScene2d"
+export { cells, encodeCells, type CellsData } from "./g2/cells"
+// no-code 2D scenario aspects (attachable in scene files — see src/g2/scenarios2d.ts)
+export { CameraFollow } from "./g2/scenarios2d"
+
+// ---- UI (creator-ui) ----
+export {
+  UIScreen, type UIScreenStyle,
+  UIRow, UIColumn, UIBox, type UIContainerStyle,
+  UIText, type UITextStyle,
+  UIButton, type UIButtonStyle,
+  UIImage, type UIImageStyle,
+  UIVideo, type UIVideoStyle,
+  UIInput, UITextArea, type UIInputStyle,
+  UIScrollable, type UIScrollableStyle,
+  UIPager, type UIPagerStyle,
+  UITabs, type UITabDef,
+  defineTabs, type TabDef, type TabsHandle,
+  UIWidget, type UIWidgetStyle,
+  UIModal, type UIModalStyle,
+  UIBottomSheet, type UIBottomSheetStyle,
+  UIPopover, type UIPopoverStyle,
+  UISpacer, type UISpacerStyle,
+  UIVirtualizedList,
+  Router,
+  NativeView, type UINativeViewStyle,
+  registerFont,
+  __uiMap,
+  __UIColumn, __UIRow, __UIBox, __UIButton, __UIScreen, __UIScrollable, __UIWidget,
+} from "./ui/UI"
+// The Presentable navigation contract (docs/navigation-presentable-plan.md). `Presentable` is
+// interface + runtime companion (declaration merging): `Presentable.current` = what's on screen.
+export { Presentable } from "./ui/UI"
+export type { PresentOptions, Transition, TransitionName, TransitionSpec, TransitionTransform } from "./ui/UI"
+// The base node type + the union a container accepts as children — documented as the signature of
+// UIColumn/UIRow/append/etc., so they must be global (type-only; erased at runtime).
+export type { UINode, UINodeChild } from "./ui/UINode"
+// App theme variables (docs/ui-theme-plan.md): theme({...}) merges + returns typed var()
+// accessors; system vars are static props (theme.primaryColor, theme["comfort-top"], …).
+export { theme, type ThemeValues, type ThemeAccessors } from "./ui/theme"
+
+// ---- animate ----
+export { animate, animateMat4, stopAnimation, pauseAnimation, resumeAnimation } from "./animate/animate"
+export { cubicBezier } from "./animate/bezier"
+export { easeIn, easeOut, easeInOut } from "./animate/easings"
+
+// ---- plugins (optional, host-provided capabilities — typed NativeView/service wrappers, see src/plugins/) ----
+export { QRScanner } from "./plugins/qr"
+export { CameraView, type CameraFacing } from "./plugins/camera"
+export { Geolocation, type GeoPosition, type GeoOptions, type GeoWatch } from "./plugins/geolocation"
+export { Push, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/push"
+export { OAuth, type OAuthCredential, type OAuthProviderName } from "./plugins/oauth"
+export { Service } from "./plugins/service"
+
+// ---- scenes as data (.scene.ts files — see src/scene/defineScene.ts) ----
+export { defineScene, use, ref, make, SceneHandle, applyEditorPose as __applyEditorPose } from "./scene/defineScene"
+export {
+  defineMaterial, MaterialHandle,
+  // editor-harness helpers (the scene editor's live material paths — not app API)
+  assignMaterialDef as __assignMaterialDef, applyMaterialParam as __applyMaterialParam,
+} from "./scene/material"
+export type { MaterialData, MaterialParamValue, ShaderMaterialDef, LitMaterialDef, UnlitMaterialDef } from "./scene/material"
+export type { SceneDef, SceneNodeDef, MeshDef, LightDef, MaterialDef, CameraNodeDef, AspectEntry, MakeEntry, LoadedScene, SceneInstance } from "./scene/defineScene"
+export { CameraPlace } from "./gl/CameraPlace"
+// Procedural placement for large maps (line/grid/ring/scatter/place) — built for make() factories.
+export { Level } from "./scene/level"
+export type { LevelSpot, LevelBuild, LevelCollider, LevelLineOptions, LevelGridOptions, LevelRingOptions, LevelScatterOptions, LevelPlaceOptions } from "./scene/level"
+export type { FieldMeta } from "./core/fields"
+// Editor-only line drawing from generator rebuild() / make() factories / tool hooks — drawn by the
+// scene editor's viewport overlay, a no-op everywhere else (see src/scene/gizmos.ts).
+export { Gizmos, GizmoBuffer as __GizmoBuffer, withGizmoScope as __withGizmoScope } from "./scene/gizmos"
+export type { GizmoStyle, GizmoAnchor } from "./scene/gizmos"
+
+// ---- no-code scenario aspects (attachable in the scene editor — see src/gl/scenarios.ts) ----
+export { MoveTo, FollowPath, Spin, LookAt, PlayAnimation } from "./gl/scenarios"
+
+// ---- editor plugins (called from `*.editor.ts` files — editor bundles only; DCE'd from apps) ----
+export { registerEditorWindow, registerEditorTool, __editorPlugins } from "./scene/editorPlugins"
+export type { EditorApi, EditorRayHit, EditorToolHooks, EditorWindowFn } from "./scene/editorPlugins"
+
+// ---- 3D engine (creator-gl) ----
+export { Scene, ARScene, VRScene } from "./gl/Scene"
+export { Node } from "./gl/Node"
+export { Mesh } from "./gl/Mesh"
+export { Model } from "./gl/Model"
+export { Shape } from "./gl/Shape"
+export { Physics } from "./gl/Physics"
+export { Trigger } from "./gl/Trigger"
+export { CharacterController } from "./gl/CharacterController"
+export { Vehicle } from "./gl/Vehicle"
+export type { DriveLayout, DifferentialMode, EngineConfig, SteeringConfig, AeroConfig } from "./gl/Vehicle"
+export { Wheel } from "./gl/Wheel"
+export { Ragdoll } from "./gl/Ragdoll"
+export type { RagdollPart, RagdollHinge } from "./gl/Ragdoll"
+export type { TireCurve, WheelSuspension, WheelTire, WheelVisual } from "./gl/Wheel"
+export { Gearbox } from "./gl/Gearbox"
+export { AnimationClip } from "./gl/animation/AnimationClip"
+export type { ClipDef, ClipTrackDef, ClipKey } from "./gl/animation/AnimationClip"
+export { Animator } from "./gl/animation/Animator"
+export type { WarpOptions, FeetOptions, FootState } from "./gl/animation/Animator"
+export { Playback } from "./gl/animation/Playback"
+export { Loop } from "./gl/animation/Loop"
+export { Layer } from "./gl/animation/Layer"
+export type { PlayOptions, StopOptions, LayerOptions, LoopOptions, LoopDef, BlendPosition, ActiveClip } from "./gl/animation/core"
+export { IK } from "./gl/IK"
+export type { IKTwoBone, IKLookAt } from "./gl/IK"
+export { Light } from "./gl/Light"
+export { Lightmap } from "./gl/Lightmap"
+export { Terrain } from "./gl/Terrain"
+export type { TerrainOptions, TerrainLayer, TerrainRegion, ConformOptions, RibbonOptions, AutoPaintRules, SculptOptions, TerrainHit, TerrainSnapshot } from "./gl/Terrain"
+export { NavMesh, NavCrowd } from "./gl/NavMesh"
+export type { NavMeshLoadOptions, NavMeshInfo, NavPath, NavQueryOptions, NavRaycastHit, NavAgentSize } from "./gl/NavMesh"
+export { NavAgent } from "./gl/NavAgent"
+export type { NavAgentState, NavAgentAvoidance, NavAgentDrive, NavAgentEvents } from "./gl/NavAgent"
+export { Locomotion } from "./gl/Locomotion"
+export type { LocomotionSet, LocomotionClip, LocomotionTuning, LocomotionState, LocomotionEvents, Displacement, Gait } from "./gl/Locomotion"
+export { Material } from "./gl/Material"
+export { Geometry } from "./gl/Geometry"
+export { InstancedMesh } from "./gl/InstancedMesh"
+export type { InstanceTransform } from "./gl/InstancedMesh"
+export { Texture } from "./gl/Texture"
+export { Camera } from "./gl/Camera"
+export { Ray } from "./gl/Ray"
+export { Plane } from "./gl/Plane"
+export { Noise } from "./gl/Noise"
+export { Particles, Trail, curve, colorCurve } from "./gl/Particles"

package/src/math/Mathf.ts

@@ -0,0 +1,118 @@
+// Scalar / general math helpers, exposed to user code as the `Mathf` global. Vector & quaternion
+// helpers live with the engine that uses them (vec2 in g2/, vec3+quat in gl/). `smoothDamp` works on
+// both numbers and numeric arrays here (no gl-matrix), which covers 2D (vec2) and 3D position damping.
+
+export type Damper<T extends number | number[]> = ((target: T, dt: number) => T) & {
+  /** Snap the damper's internal current value (e.g. on teleport). */
+  setValue(value: T): void
+}
+
+const clamp = (v: number, min: number, max: number): number => (v < min ? min : v > max ? max : v)
+
+const smoothDampNumber = (initial: number, smoothTime: number, maxSpeed: number): Damper<number> => {
+  let current = initial
+  let velocity = 0
+  const damp = ((target: number, dt: number): number => {
+    smoothTime = Math.max(0.0001, smoothTime)
+    const omega = 2 / smoothTime
+    const x = omega * dt
+    const exp = 1 / (1 + x + 0.48 * x * x + 0.235 * x * x * x)
+    const maxDelta = maxSpeed * smoothTime
+    let delta = clamp(current - target, -maxDelta, maxDelta)
+    const newTarget = current - delta
+    const temp = (velocity + omega * delta) * dt
+    velocity = (velocity - omega * temp) * exp
+    current = newTarget + (delta + temp) * exp
+    return current
+  }) as Damper<number>
+  damp.setValue = (v) => { current = v; velocity = 0 }
+  return damp
+}
+
+function smoothDamp(initial: number, smoothTime: number, maxSpeed?: number): Damper<number>
+function smoothDamp(initial: number[], smoothTime: number, maxSpeed?: number): Damper<number[]>
+function smoothDamp(initial: any, smoothTime: number, maxSpeed = Infinity): any {
+  return typeof initial === "number"
+    ? smoothDampNumber(initial, smoothTime, maxSpeed)
+    : smoothDampArray(initial, smoothTime, maxSpeed)
+}
+
+const smoothDampArray = (initial: number[], smoothTime: number, maxSpeed: number): Damper<number[]> => {
+  const n = initial.length
+  let current = initial.slice()
+  const velocity = new Array(n).fill(0)
+  const damp = ((target: number[], dt: number): number[] => {
+    smoothTime = Math.max(0.0001, smoothTime)
+    const omega = 2 / smoothTime
+    const x = omega * dt
+    const exp = 1 / (1 + x + 0.48 * x * x + 0.235 * x * x * x)
+    const maxDelta = maxSpeed * smoothTime
+
+    const delta = new Array(n)
+    let mag = 0
+    for (let i = 0; i < n; i++) { delta[i] = current[i] - target[i]; mag += delta[i] * delta[i] }
+    mag = Math.sqrt(mag)
+    if (mag > maxDelta && mag > 0) {
+      const s = maxDelta / mag
+      for (let i = 0; i < n; i++) delta[i] *= s
+    }
+
+    const out = new Array(n)
+    for (let i = 0; i < n; i++) {
+      const newTarget = current[i] - delta[i]
+      const temp = (velocity[i] + omega * delta[i]) * dt
+      velocity[i] = (velocity[i] - omega * temp) * exp
+      out[i] = newTarget + (delta[i] + temp) * exp
+    }
+    current = out
+    return out.slice()
+  }) as Damper<number[]>
+  damp.setValue = (v) => { current = v.slice(); velocity.fill(0) }
+  return damp
+}
+
+export const Mathf = {
+  PI: Math.PI,
+  TAU: Math.PI * 2,
+  EPSILON: 1e-6,
+  DEG2RAD: Math.PI / 180,
+  RAD2DEG: 180 / Math.PI,
+
+  deg2rad: (deg: number): number => deg * (Math.PI / 180),
+  rad2deg: (rad: number): number => rad * (180 / Math.PI),
+
+  clamp,
+  clamp01: (v: number): number => clamp(v, 0, 1),
+  lerp: (a: number, b: number, t: number): number => a + (b - a) * t,
+  inverseLerp: (a: number, b: number, v: number): number => (a === b ? 0 : (v - a) / (b - a)),
+  remap: (v: number, inMin: number, inMax: number, outMin: number, outMax: number): number =>
+    outMin + ((v - inMin) / (inMax - inMin)) * (outMax - outMin),
+
+  /** Move `a` toward `b` by at most `maxDelta`. */
+  moveTowards: (a: number, b: number, maxDelta: number): number => {
+    const d = b - a
+    return Math.abs(d) <= maxDelta ? b : a + Math.sign(d) * maxDelta
+  },
+  /** Frame-rate-independent exponential approach (good default: lambda 5..15). */
+  damp: (a: number, b: number, lambda: number, dt: number): number => a + (b - a) * (1 - Math.exp(-lambda * dt)),
+
+  sign: Math.sign,
+  /** Loop a value into [0, length). */
+  repeat: (t: number, length: number): number => clamp(t - Math.floor(t / length) * length, 0, length),
+  /** Ping-pong a value in [0, length]. */
+  pingPong: (t: number, length: number): number => {
+    const r = clamp(t - Math.floor(t / (length * 2)) * (length * 2), 0, length * 2)
+    return length - Math.abs(r - length)
+  },
+
+  random: (min = 0, max = 1): number => min + Math.random() * (max - min),
+  randomInt: (min: number, max: number): number => Math.floor(min + Math.random() * (max - min + 1)),
+
+  /**
+   * Critically-damped follow (Unity SmoothDamp). Returns a stateful damper you call every frame:
+   *   const d = Mathf.smoothDamp([x, y], 0.15)
+   *   pos = d(targetPos, dt)
+   * Works on a number or a numeric array (vec2 / vec3).
+   */
+  smoothDamp,
+}