Animation, Tween, Particles, and Tilemaps

AuraJS exposes several deterministic helper namespaces for animation-heavy gameplay.

Scaffolded 2D Authoring Layer

Non-blank generated projects also ship a higher-level 2D authoring layer in src/starter-utils/:

• animation-2d.js for named sprite states and current-frame resolution
• animation-packaging-2d.js for atlas/clip/state packaging over the sprite animation lane
• atlas-assets-2d.js for explicit image-path plus animation-manifest ownership over the packaging lane
• tween-2d.js for sequence/parallel/delay/yoyo/repeat style motion composition
• combat-feedback-2d.js for floating text, hit sparks, hit flashes, and hover/lift feedback
• tilemap-world-2d.js for one-map load/query/move ownership over aura.tilemap
• tilemap-nav-2d.js for mutable grid navigation with topology and occupancy invalidation
• streamed-world-2d.js for explicit region ownership, focus-driven load/unload, and routed point/AABB/ray queries over multiple tilemap-world regions

That local path stays copied into the scaffold so authored game code can be inspected and edited without waiting on package installation. When you need the shared package-backed helper lane directly, use @auraindustry/aurajs/helpers/2d.

Use these when you want a faster scaffolded 2D game-authoring path. Use raw aura.anim2d, aura.animation, and aura.tween directly when you need custom low-level ownership.

For authored sprite atlases, the packaging helper keeps the boundary explicit:

• clips own frame ranges / loop / timing defaults
• states map gameplay-facing names onto those clips
• the helper still compiles onto the existing animation-2d.js runtime lane instead of inventing a second playback system
• atlas-assets-2d.js is the truthful paved road when the image path and the clip/state manifest should stay separate but packaged together in authored JS
• the accepted packaged/native atlas path is a project-relative asset path such as assets/pilot-ui-sheet.png
• generated://... remains a proof-only or runtime-authored image source, not the packaged asset guarantee for a shipped project

Example:

import {
  createAtlasAssetManifest2D,
  createAnimationPackageFromAtlasAsset2D,
  createPackagedSpriteAnimator2D,
  createSpriteAnimationRuntime2D,
} from '@auraindustry/aurajs/helpers/2d'

const runtime = createSpriteAnimationRuntime2D(aura)
const atlasAsset = createAtlasAssetManifest2D({
  name: 'pilot-ui',
  image: 'assets/pilot-ui-sheet.png',
  manifest: {
    frameWidth: 48,
    frameHeight: 48,
    columns: 4,
    defaultFrameDuration: 0.18,
    clips: {
      idle: [0, 1],
      alert: [2, 3],
    },
    states: {
      idle: { clip: 'idle', frameDuration: 0.24 },
      alert: { clip: 'alert', frameDuration: 0.12 },
    },
    defaultState: 'idle',
  },
})

const animationPackage = createAnimationPackageFromAtlasAsset2D(atlasAsset)
const animator = createPackagedSpriteAnimator2D(runtime, animationPackage)

For larger 2D worlds, keep the boundary honest:

• streamed-world-2d.js is a JS-first logical region helper, not a full persistence or off-screen simulation framework
• it owns region load/unload and query routing over current tilemap seams
• persistent rehydrate, distant-region simulation budgets, and scene-audio ownership stay in the later Stage 188 follow-on tasks

`aura.anim2d`

2D clip/state-machine helper:

• registerClip(name, frames, options?)
• createMachine(initialState?)
• defineState(machineId, stateName, clipName, options?)
• play(machineId, stateName)
• update(dt)
• getState(machineId)
• onComplete(machineId, callback, order?)

Use cases:

• sprite animation state machines
• deterministic state transitions for characters and UI avatars

`aura.animation`

Timeline and atlas-driven animation surface:

• create(options)
• play(timelineId)
• pause(timelineId)
• resume(timelineId)
• seek(timelineId, time)
• transition(timelineId, options)
• crossfade(fromId, toId, options)
• onComplete(timelineId, callback, order?)
• onEvent(timelineId, callback, order?)
• setLoop(timelineId, loop)
• setSpeed(timelineId, speed)
• getState(timelineId)
• update(dt)

Atlas/spritesheet helpers:

• registerAtlas(name, atlasSpec)
• resolveAtlasFrame(name, frame)
• createAtlasClip(options)
• stepAtlasClip(clipId, dt)
• getAtlasClipState(clipId)

Use cases:

• event-tagged timelines
• atlas-based clips without external timeline glue
• deterministic clip/event control for menus and gameplay

`aura.tween`

Deterministic scalar tween helper:

• create(options)
• pause(tweenId)
• resume(tweenId)
• cancel(tweenId)
• onUpdate(tweenId, callback, order?)
• onComplete(tweenId, callback, order?)
• update(dt)
• getState(tweenId)

Use cases:

• value easing
• UI transitions
• simple procedural motion driven by agents

In scaffolded 2D projects, src/starter-utils/tween-2d.js is the default wrapper for authored move/fade/scale/pulse/punch flows.

`aura.particles`

Lightweight particle/VFX helper:

• emit(options)
• burst(options)
• update(dt)
• draw()
• stop(emitterId)
• kill(emitterId)
• setLayer(emitterId, layer)
• setBlend(emitterId, mode)
• setGravity(emitterId, gravity)
• getState(emitterId)

Use cases:

• simple impact and weapon effects
• environmental effects and ambient loops

`aura.particles3d`

Retained 3D particle-emitter helper:

• create(options)
• destroy(emitterId)
• emit(emitterId, count?)
• burst(emitterId, count)
• burst(options) for one-shot emitters
• pause(emitterId)
• resume(emitterId)
• stop(emitterId)
• update(dt)
• draw()
• setPosition(emitterId, x, y, z)
• setEmitRate(emitterId, rate)
• getState(emitterId)

Truthful ownership:

• create(...) returns a retained emitter that persists until destroy(...)
• burst(options) is the one-shot path; it auto-destroys after its particles empty instead of pretending to be a retained ambient emitter
• pause(...) freezes simulation/emission, stop(...) halts future emission while leaving live particles alone, and resume(...) clears both paused and stopped state
• getState(...) reports retained runtime truth such as paused, stopped, emitting, particles, and autoDestroyWhenEmpty

Current authoring aliases:

• velocity: { x, y, z } can stand in for direction + speed
• acceleration: { x, y, z } can stand in for gravity

Current rendering truth:

• draw() submits camera-facing billboard particles through the Draw3D billboard/material lane
• this is the practical retained 3D gameplay emitter seam, not a GPU-compute particle simulation system
• deeper screen-space compatibility breadth such as SSR/DOF/motion-blur correctness remains a later renderer follow-on

`aura.particles3d`

Shared JS-first 3D emitter/runtime helper:

• create(options)
• destroy(emitterId)
• emit(emitterId, count?)
• burst(emitterId, count) or burst({ ... , count }) for a one-shot emitter
• pause(emitterId)
• resume(emitterId)
• stop(emitterId)
• update(dt)
• draw()
• getState(emitterId)

Truthful runtime notes:

• pause(...) freezes that emitter's simulation and emission state until resumed
• resume(...) clears paused/stopped state and resumes normal emit-rate-driven behavior
• stop(...) halts future emission while allowing existing particles to age out naturally
• one-shot burst({ ... , count }) emitters auto-destroy when empty
• destroy(...) returns cleanup confirmation including destroyed and particlesCleared
• draw() currently submits camera-facing billboards through aura.draw3d.billboard(...)

`aura.tilemap`

Tilemap import/render/query/mutation surface:

• import(source, options?)
• create(model, options?)
• unload(mapId)
• getInfo(mapId)
• drawLayer(mapId, layerRef, options?)
• draw(mapId, options?)
• setTile(mapId, layerRef, x, y, gid)
• setRegion(mapId, layerRef, region, gid)
• removeRegion(mapId, layerRef, region)
• replaceRegion(mapId, layerRef, region, fromGid, toGid)
• setTileCollision(mapId, layerRef, x, y, collision)
• setLayerFlags(mapId, layerRef, flags)
• setLayerVisibility(mapId, layerRef, visible)
• setLayerCollision(mapId, layerRef, collision)
• queryPoint(mapId, point, options?)
• queryAABB(mapId, bounds, options?)
• queryRay(mapId, ray, options?)
• queryRaycast(mapId, ray, options?)
• queryObjects(mapId, options?)
• queryObjectsAtPoint(mapId, point, options?)
• queryObjectsInAABB(mapId, bounds, options?)
• setTileAnimation(mapId, layerRef, gid, animationSpec)
• updateAnimations(mapId, dt)
• getAnimationState(mapId)
• setOrientation(mapId, orientation)
• tileToScreen(mapId, x, y)
• screenToTile(mapId, x, y)

Use cases:

• authored maps
• live mutation for destructible/dynamic levels
• collision and object-layer query flows