API reference

Anchor against the untrimmed SOURCE canvas, not against the per-frame trimmed rectangle. A trimmed atlas gives every frame its own size and its own AnimatedSpriteClipDefinition.frameOffsets entry. Measuring the anchor against that rectangle would move the pivot on every frame advance, so an anchored character would wobble around its own feet for the length of the animation. The pivot has to stand still, which means measuring against a box that is constant for the whole clip. A clip carries no explicit untrimmed size, so the box is derived from the frames themselves: width = max(offset.x + frame.width) and height = max(offset.y + frame.height) over every frame, anchored at the local origin (0, 0) - the point the offsets are expressed relative to. That is the smallest canvas every frame of the clip fits on, it is computed once per clip in addClip, and it is identical for every frame index. It can under-report an authored canvas whose right or bottom edge is empty in every single frame; nothing in the frame data can distinguish that case, and the pivot stays stable either way. A clip WITHOUT frameOffsets is not trimmed, so its frame rectangle is its layout box and the base implementation already measures the right thing. It is used unchanged there - deriving a clip-wide box would be actively wrong for it, because such a clip keeps its rendered pixel size across differently-sized frames (see _applyFrame) and the per-frame extent is what maps onto that constant rendered box.

Register a named clip. Frame rectangles are cloned so the caller may mutate the originals.

Release keyboard focus from this node if it currently holds it.

Contribute this node to the render plan under construction: skip it when it is destroyed, invisible, or outside the builder's cull rect, otherwise emit it as one plan entry. Custom node types override this to add their own admission rules and must call super.collect(builder, seq) to keep the skip semantics. seq orders the entry within its parent; omit it to append. Part of the renderer SDK contract for extension renderers.

Compute a full CollisionResponse between this shape and target. Returns null in two cases: - the shapes do not overlap, **or** - the specific shape-pair combination does not support response generation (e.g. Line against any shape, Ellipse against Ellipse or Polygon). Use intersectsWith for a universal boolean overlap check that works across all supported shape pairs.

Return true if the world-space point (x, y) lies inside the quad. Uses a fast AABB check for axis-aligned quads, and a cross-product sign test for rotated or skewed quads. A RenderNode.hitArea replaces the quad test entirely.

Releases everything this node owns, including GPU-side resources. Calling it is mandatory for a node that has acted as a render root: from its first recorded frame such a node owns a group-scoped instance, transform and tint buffer, and the backend holds that bundle until the node is destroyed or the backend itself is. Dropping the last reference is not enough - GPU lifetime is deterministic here on purpose and is not tied to garbage collection. Idempotent: a second call is a no-op.

Request keyboard focus for this node through its owning focus service.

Axis-aligned bounding box of this node in its GLOBAL-transform space. That is world space for ordinary nodes, but GROUP-LOCAL space for nodes inside an engaged RetainedContainer transform group (the group matrix is applied on the GPU, not here) - this is deliberate and matches the rendering convention. For a true world-space extent of such a node, lift this rect by the group's getWorldTransform matrix. Pass out to receive a copy you own. Without it the return value is this node's **cached** rectangle, rebuilt in place whenever the transform or the local extent changes - retaining it across frames hands you a value that silently moves. The cache is why the no-arg form does not allocate: this runs per node per frame for culling and hit-testing.

This node's untransformed extent in its own local coordinate space. Returns the LIVE internal rectangle, not a copy: it is read on hot paths (updateBounds re-reads it on every transform-dirty recompute, i.e. potentially every frame for a moving node), so copying it here would add a per-frame allocation. It is therefore typed as a ReadonlyRectangle - reads are unchanged, writes are rejected at compile time. Writing to it directly would skip the bounds/content invalidation the engine needs, leaving culling, hit-testing and retained render fragments on a stale extent. A custom Drawable that owns its own size sets it through setLocalBounds, which writes and invalidates in one step.

Return the four outward-facing edge normals of the rotated quad, lazily computed from vertices. Used by the SAT collision system.

The node's TRUE world-space transform, composed through every transform-group boundary (RetainedContainer) in the ancestor chain. getGlobalTransform deliberately stops at the nearest engaged boundary (descendants resolve group-RELATIVE transforms; the renderer multiplies the group matrix back in on the GPU), so it is the right space for rendering but the wrong one for spatial queries. Use THIS accessor whenever a real world position/orientation is needed - picking, spatial audio, physics, world-space math against nodes outside the group. Without any engaged boundary ancestor it returns the exact getGlobalTransform matrix (same instance, no extra work). With one, it lazily caches groupLocal × groupWorld and revalidates on read via version/stamp compares - including runtime space flips such as RetainedContainer's deep-barrier sub-branch escape.

Test whether this shape overlaps target using a fast boolean algorithm (no penetration depth or normal computed). Prefer this over collidesWith when only the yes/no result is needed.

Mark this node's visual content dirty without going through a standard setter - e.g. a custom Drawable subclass backed by externally mutable data (the pattern TileChunkNode in @codexo/exojs-tilemap already uses via its own _chunk.revision compare). Call this after mutating such state so the Track-B retained-plan skip does not serve a stale frame for this node.

Start playing the named clip. By default restarts from frame 0; pass { restart: false } to resume from the current frame if the same clip is already active. Optionally overrides the clip's repeat setting. Safe to call before the sprite is attached to a scene tree (in a constructor, ahead of addChild): the sprite simply has no owning AnimationSystem to register with yet, and joins one the moment it is attached.

Project all four quad vertices onto axis and return the resulting scalar interval. Used by the SAT collision system.

Remove a registered clip by name. Stops playback first if the clip is currently active.

Raw rendering entry point. Direct backend access - bypasses the RenderPlan pipeline machinery. Prefer the high-level RenderingContext.render path via the owning RenderingContext wherever possible.

Reset the texture frame to the full dimensions of the current texture. Throws if no texture is set.

Set the normalized anchor and re-derive origin from it.

Change the blend mode. No-ops if the value is unchanged. Invalidates the render cache when the blend mode actually changes.

Replace all registered clips with the provided map. Clears any previously registered clips first.

Write this node's local extent and run the bounds invalidation the change implies - the node's own bounds flag, the ancestor bounds cascade, and the content-dirty stamp that keeps retained fragments from replaying the old extent. This is the only supported way to resize a node from outside getLocalBounds; the rectangle itself is handed out read-only so the invalidation cannot be forgotten. Built-in drawables (Sprite, Text, BitmapText, Mesh, ...) and custom ones alike go through here. Part of the renderer SDK contract for extension renderers.

Assign a new texture, refreshing the texture frame to the full texture dimensions. Does **not** bump the texture's version. That signal means "the source data has been mutated"; replacing the sprite's texture reference is not that. Bumping it here would force the backend to re-allocate the GPU texture on the next bind - destroying any FBO content already rendered into a RenderTexture (the cacheAsTexture and filter capture pipelines). Call updateTexture explicitly when you mutate the source.

Set a sub-region of the texture to render. When resetSize is true (default) the sprite's logical size snaps to the new frame dimensions; pass false to keep the current pixel size (useful for animation playback where the frame changes but the display size should stay constant).

Set the tint colour by copying color into the internal Color instance. Invalidates the render cache so the change is picked up on the next frame. A retained product recognises a tint-only change and rewrites the affected row rather than re-recording, so tinting per frame stays cheap. Writing through the returned tint instance instead (sprite.tint.r = 8) bypasses that entirely and is not observed at all - assign a colour, or call RenderNode.invalidateContent after mutating in place.

Stop playback and rewind the active clip to frame 0.

Advance playback by deltaSeconds - seconds, the same unit as Tween.update, and the unit a Time delta reports through delta.seconds. Clip authoring stays in its own units: AnimatedSpriteClipDefinition.frameDurations is still seconds per frame and fps is still frames per second. Called automatically once per frame by the owning AnimationSystem for a playing, attached sprite - call it yourself only for a sprite that is not part of an application's scene tree, or to step playback manually. Dispatches onFrame for each frame boundary crossed and onComplete when the clip completes its final AnimatedSpriteClipDefinition.repeat cycle.

Signal the GPU backend that the underlying texture source has changed and reset the frame to full dimensions.

Construct an AnimatedSprite from the named animations defined on a Spritesheet. Each animation becomes an indefinitely-looping clip whose frames are the spritesheet frame rectangles in declaration order.

When true and interactive is also true, this node will be automatically repositioned to follow the pointer during a drag gesture. The framework captures the pointer offset at drag-start so the node doesn't snap to the cursor position. Both interactive and draggable must be set for dragging to work - a draggable but non-interactive node will never receive pointerdown and therefore cannot start a drag.

When true, this node can receive keyboard focus - via focus, Tab traversal, or app.interaction.focus(node) - and is delivered key events through onKeyDown / onKeyUp while focused, or while any of its descendants holds focus (key events bubble up the parent chain like pointer InteractionEvents do). A Widget additionally has to be enabled: disabling one takes it out of the Tab order and rejects programmatic focus, without touching this flag.

Optional pick shape in this node's LOCAL space, replacing the bounds test contains would otherwise perform. Defaults to null. The world-space point is mapped through the inverse of the node's global transform before the shape is tested, so the region follows the node's position, rotation, scale and skew like the rendered output does - the shape itself is never re-transformed and never needs updating when the node moves. Affects picking only. Bounds, culling and rendering ignore it entirely, and because the interaction system finds candidates by their bounds, a hit area reaching outside the node's bounds is only reliably picked where the two overlap. Use it to shrink or reshape a pick region, not to grow one. The shape is the caller's: it is read live on every hit test, so mutating it in place takes effect immediately, and the node never destroys it.

Optional human-readable identity for this node. Defaults to null. Purely a label the engine never interprets: useful for debugging, find-by-name lookups, prefab references, and as a stable key when merging serialized state back onto an existing tree. Not required to be unique.

Tab-traversal order among focusable nodes in the same focus scope. Lower values are visited first; equal values keep document (tree) order.

Normalized anchor in 0..1 along each axis that derives origin from this drawable's layout box. (0, 0) = top-left, (0.5, 0.5) = centre, (1, 1) = bottom-right. Updates origin whenever the anchor or the layout box changes. The mapping is a pure function of the anchor and the box size - the same anchor value always yields the same origin, whatever it was set to before - so (0, 0), the default, always means origin = (0, 0). Set origin directly instead when the pivot is not a fraction of the box.

Bake this node's subtree into a RenderTexture once and replay that texture until the subtree changes, instead of walking and drawing it every frame. Worth it for a subtree that is expensive to draw and rarely changes. The cache is invalidated by anything that moves the node's world bounds - the node's own transform included - so a node that animates re-bakes every frame and is strictly slower than not caching it at all. Setting it to false frees the texture immediately.

Resolution the cacheAsTexture texture is baked at, in device pixels per logical unit. 'inherit' (the default) matches the surface the cache is composited into, so enabling the cache does not soften the picture on a HiDPI display. Pin it to a number to trade sharpness for memory and bake cost - a cache is resolution² texels, so 1 on a DPR-3 phone is a ninth of the VRAM and a ninth of the fill per re-bake. Changing it invalidates the cache.

When true, descendants are geometrically clipped to clipShape. Unlike mask (which is alpha/visibility masking), clip is a hard geometric boundary: - clipShape === null - clip to this node's world-space bounds (getBounds), using the GPU scissor fast path. - clipShape is a Rectangle - clip to that world-space rectangle via scissor. - clipShape is a Geometry - clip to the geometry's silhouette via the stencil buffer (WebGL2). Only fragments inside the shape survive. Clipping wraps the node's final (filtered/masked) output and acts as a render barrier: draw commands are never reordered or batched across the clip boundary.

Clip region used when clip is true. A Rectangle (or null for the node's bounds) maps to the scissor fast path; a Geometry maps to the stencil path. Has no effect while clip is false.

When false, this node is never culled by the viewport check and is always considered in-view. Defaults to true.

Custom rectangle used for viewport cull intersection test. When set, replaces the default node bounds in cull checks. Set to null to restore default bounds-based culling.

true once destroy has run on this node. A destroyed node has released its pooled resources (transform/bounds), has been unlinked from its parent, renders nothing, and must not be reused or re-attached. The render plan skips a destroyed node, so even one handed straight to a renderer as a detached root contributes nothing.

The mask source that controls visibility of this node's render output. See MaskSource for accepted source types and their semantics. Setting to null removes any active mask. Setting a RenderNode that is this is rejected (a node cannot mask itself). Indirect cycles (a.mask = b; b.mask = a) are rejected as well: the candidate's mask chain is walked and any cycle - whether it closes on this or was already present in the chain - fails the assignment.

Custom material giving this sprite its own fragment program, uniforms, and extra texture bindings, or null for the default multi-texture sprite path. Sprites that share the same material instance and base texture still batch into a single instanced draw call; the base texture stays on the sprite and is bound per batch. Assigning a non-sprite material throws.

Render-only pixel-snapping policy for this drawable. Aligns the rendered origin (PixelSnapMode.Position) or origin plus shared geometry boundaries (PixelSnapMode.Geometry) to the active render target's device-pixel grid. Purely visual: logical x/y, transforms, bounds, collision, tween and physics state are never affected, and getBounds/getGlobalTransform keep returning logical values. PixelSnapMode.Geometry is guaranteed only for axis-aligned transforms; rotation or skew (on this node, an ancestor, or the view) downgrade it to PixelSnapMode.Position for the affected frame, with no logical-state change. Snapping targets device pixels (× view scale × pixel ratio), not integer world units. Setting the current value is a no-op. Setting a value outside the PixelSnapMode enum throws and leaves the prior mode unchanged.

When true, material-aware overlap reordering is disabled for this node's draw-order scope. Draw commands are submitted in exact document order (after scope-local z-sorting), preserving the painter's guarantee irrespective of material compatibility or AABB safety analysis. Adjacency coalescing of consecutive same-material draws still applies; it does not change visual output order.

How many cycles the current clip plays before stopping. Returns the override set via play's options.repeat or this setter, otherwise the clip's own repeat value (or -1 if no clip is active). The override belongs to the current playback run: the next play that starts a run drops it unless that call supplies one of its own.

Rotation angle in degrees. Wraps via trimRotation on assignment.

Horizontal skew angle in degrees. Shears the node along the X axis (positive values lean the top edge right). Combines correctly with rotation and scale.

Vertical skew angle in degrees. Shears the node along the Y axis (positive values lean the left edge downward). Combines correctly with rotation and scale.

Packed UV coordinates for the four quad corners, encoded as two 16-bit fixed-point values per element (low 16 bits = U, high 16 bits = V, each in the range 0-65535). Accounts for Texture.flipY. Throws if no texture is assigned.

World-space corner positions of the sprite quad, computed lazily from the current transform and texture frame. Layout: [x0,y0, x1,y1, x2,y2, x3,y3] (TL, TR, BR, BL). Cached until the transform is invalidated.

Fired when this node loses keyboard focus.

Fired when a pointer requests a context menu over this node - right-click, or a long-press/touch gesture that has an attributable pointer. Bubbles like the other pointer events, so a scene-wide fallback can listen on an ancestor. Carries no native event - whether the browser's own menu appears is decided by ApplicationOptions.input.allowNativeContextMenu, independently of this. Requires an attributable pointer: a pointerless keyboard-only request (the context-menu key, or Shift+F10, with no pointer ever having touched the surface - see ContextMenuRequest's doc comment) has nothing to hit-test or bubble with, so it never reaches this per-node event. It only ever reaches the engine-wide, scene-graph-independent app.input.onContextMenu.

Fired on every pointer-move while this node is being dragged. Does not bubble.

Fired when the drag gesture ends (pointer-up or cancel). Does not bubble.

Fired once when a drag gesture begins on this node. Does not bubble.

Fired when this node gains keyboard focus.

Fired for each key pressed while this node - or a descendant of it - holds focus. Bubbles; see KeyEvent.

Fired for each key released while this node - or a descendant of it - holds focus. Bubbles; see KeyEvent.