Spine

EntityVisualceramic.Spine (Class)

Spine animation runtime for Ceramic engine.

This class provides full support for Spine 2D skeletal animations, including:

  • Animation playback with mixing and blending
  • Skin switching at runtime
  • Slot customization and visibility control
  • Hierarchical Spine composition (Spine within Spine)
  • Attachment rendering (regions, meshes, clipping)
  • Event handling and animation completion callbacks
  • Tint black support for advanced coloring
  • Bounding box hit testing

Basic Usage

var spine = new Spine();
spine.spineData = assets.spine('hero');
spine.animation = 'walk';
spine.loop = true;
add(spine);

Advanced Features

  • Slot Control: Hide/show specific slots, or use slot whitelists
  • Spine Binding: Attach child Spine animations to parent slots
  • Custom Rendering: Hook into slot update events for custom drawing
  • Performance: Automatic freezing when animations complete

Static Members

spine
globalSlotIndexForName(slotName: String): Int

Gets a globally unique slot index for the given slot name.

Global slot indices are consistent across all skeletons, unlike regular slot indices which vary by skeleton structure. This enables efficient slot operations across different Spine instances.

The same slot name always returns the same global index, making it ideal for slot blacklists, whitelists, and cross-skeleton references.

Name Type Description
slotName String The name of the slot
Returns Description
Int A unique global index for this slot name

Instance Members

spine
renderDirtyAgressive: Bool

Internal flag to know if render became dirty because of a skin change or a new animation was set.


spine
renderDirty: Bool

spine
hasSlotsWithTintBlack: Bool

Indicates whether any slot in the skeleton uses tint black coloring. This is automatically detected when the skeleton data is loaded. When true, a special shader is used to support dark tinting.


spine
skeletonOriginX: Float

The horizontal origin point of the skeleton (0-1). Determines the pivot point for positioning and transformations. Default is 0.5 (center).


spine
skeletonOriginY: Float

The vertical origin point of the skeleton (0-1). Determines the pivot point for positioning and transformations. Default is 0.5 (center).


spine
skeletonScale: Float

Uniform scale factor applied to the entire skeleton. Use this to resize the skeleton without affecting individual bone scales. Default is 1.0 (original size).


spine
forceTintBlack: Bool

Forces the use of tint black shader even if the skeleton doesn't require it. Enable this if you need dark tinting support for dynamically created attachments.


spine
hiddenSlots: IntBoolMap

Map of slot indices to hide (blacklist). Slots in this map will not be rendered. Use Spine.globalSlotIndexForName() to get slot indices.


spine
visibleSlots: IntBoolMap

Map of slot indices to show (whitelist). When set, only slots in this map will be rendered. Use Spine.globalSlotIndexForName() to get slot indices.


spine
disabledSlots: IntBoolMap

Map of slot indices that are completely disabled. Disabled slots are skipped entirely during rendering. Use Spine.globalSlotIndexForName() to get slot indices.


spine
animationTriggers: Map

Map of animation names to trigger animations. When an animation event matches a key in this map, the corresponding animation will be triggered.


spine
hitWithSlotIndex: Int

Specifies which slot index to use for hit testing. Set to -1 (default) to use the visual's bounds instead. This allows precise hit detection using a specific slot's attachment.


spine
hitWithFirstBoundingBox: Bool

When true, uses the first bounding box attachment for hit testing. This provides accurate collision detection for complex shapes. Overrides hitWithSlotIndex when enabled.


spine
renderWhenInvisible: Bool

When true, forces rendering even when the visual is not visible. Useful for animations that need to continue updating off-screen.


spine
hasParentSpine: Bool

Indicates whether this Spine instance is a child of another Spine animation. Child animations are managed and rendered by their parent.


spine
color: Color

Global tint color applied to the entire skeleton. Multiplied with individual slot and attachment colors. Default is WHITE (no tinting).


spine
autoRenderOnAnimate: Bool

When true, forces an immediate render after calling animate(). Useful for ensuring the first frame is displayed immediately.


spine
spineData: SpineData

The Spine skeleton data containing all animations, bones, and slots. Setting this property loads a new skeleton and resets the animation state.


spine
skin: String

The current skin applied to the skeleton. Skins allow swapping attachment sets at runtime (e.g., different armor sets). Set to null to use the default skin.


spine
animation: String

The name of the currently playing animation. Setting this property starts the animation immediately. Set to null to clear the animation.


spine
nextAnimations: Array<String>

Array of animation names to play sequentially after the current animation. Each animation in the chain will play once before moving to the next. The finishCurrentAnimationChain event fires when all animations complete.


spine
loop: Bool

Whether the current animation should loop continuously. Only applies to the main animation, not animations in nextAnimations.


spine
skeleton: spine.Skeleton

The Spine skeleton instance containing the current pose. Provides access to bones, slots, and attachments for runtime manipulation.


spine
skeletonData: spine.SkeletonData

The skeleton data containing all setup pose information. This includes bones, slots, animations, and skins definitions.


The animation state managing animation playback and mixing. Use this for advanced animation control like layering multiple animations.


Configuration for animation mixing (crossfading) durations. Defines how long transitions between animations should take.


spine
autoUpdate: Bool

Controls automatic animation updates each frame. Set to false if you need manual control over update timing. Note: Use paused to pause animations, not this property.


spine
pausedOrFrozen: Bool

Indicates whether the animation is currently paused or frozen. This is a combination of the paused and frozen states.


spine
autoFreeze: Bool

Enables automatic freezing when animations complete. Frozen animations stop updating to improve performance. The animation resumes when a new animation is set.


spine
paused: Bool

Pauses the animation at its current frame. The animation can be resumed by setting this to false.


spine
frozen: Bool

Indicates whether the animation is frozen (auto-paused after completion). Frozen animations automatically resume when a new animation is set.


spine
resetAtChange: Bool

When true, resets the skeleton to setup pose when animations change. This ensures clean transitions between animations.


spine
skeletonOrigin(skeletonOriginX: Float, skeletonOriginY: Float): Void

Sets the skeleton's origin point for positioning. Values are normalized (0-1) where 0.5 is center.

Name Type Description
skeletonOriginX Float Horizontal origin (0=left, 0.5=center, 1=right)
skeletonOriginY Float Vertical origin (0=top, 0.5=center, 1=bottom)

spine
clear(): Void

spine
computeContent(): Void

spine
computeBounds(): Void

spine
animate(animationName: String, ?loop: Bool = false, ?trackIndex: Int = 0, ?trackTime: Float = -1): Void

Starts playing an animation on the specified track.

This is the main method for controlling animation playback. Animations can be played on multiple tracks for layering effects (e.g., walk + shoot).

Name Type Default Description
animationName String Name of the animation to play, or null for empty animation
loop Bool false Whether the animation should repeat continuously
trackIndex Int 0 The track to play the animation on (default 0)
trackTime Float -1 Starting time of the animation in seconds (default -1 for beginning)

spine
forceRender(?muteEvents: Bool = true): Void

Forces an immediate render of the current animation state.

This bypasses normal update cycles and renders the skeleton immediately. Useful for capturing specific animation frames or ensuring visual updates.

Name Type Default Description
muteEvents Bool true Whether to suppress animation events during rendering

spine
reset(): Void

Resets the skeleton to its setup pose.

This clears all animation data and returns bones and slots to their default positions and values as defined in the Spine project.


spine
destroy(): Void

spine
update(delta: Float): Void

Updates the Spine animation by the given delta time.

This method is called automatically each frame if autoUpdate is true. It updates the animation state, applies it to the skeleton, and renders the result. Child Spine instances are updated by their parent.

Name Type Description
delta Float Time elapsed since last update in seconds

spine
canFreeze(): Bool

Checks if the animation can be frozen for performance optimization.

An animation can freeze when all tracks have completed their non-looping animations. Frozen animations stop updating until a new animation is set.

Returns Description
Bool True if the animation has no active tracks that need updating

spine
add(visual: Visual): Void

Add a child visual. If the child is a spine animation, it will be managed by its parent and compositing becomes possible.

Name Type
visual Visual

spine
remove(visual: Visual): Void
Name Type
visual Visual

spine
onUpdateSlotWithName(owner: Null<Entity>, slotName: String, handleInfo: Function): Void

Registers a handler for updates to a specific slot by name.

This is more efficient than the general updateSlot event as it only fires for the specified slot, reducing overhead for complex skeletons.

Name Type Description
owner Null<Entity> Optional owner entity for automatic cleanup
slotName String Name of the slot to monitor
handleInfo Function Handler function called when the slot updates

spine
onUpdateSlotWithGlobalIndex(owner: Null<Entity>, index: Int, handleInfo: Function): Void

Registers a handler for updates to a specific slot by global index.

This is the most efficient way to monitor specific slots, using pre-computed global indices for direct lookup.

Name Type Description
owner Null<Entity> Optional owner entity for automatic cleanup
index Int Global slot index (use globalSlotIndexForName())
handleInfo Function Handler function called when the slot updates

spine
offUpdateSlotWithName(slotName: String, ?handleInfo: Function): Void
Name Type Default
slotName String
handleInfo Function (optional)

spine
offUpdateSlotWithGlobalIndex(index: Int, ?handleInfo: Function): Void
Name Type Default
index Int
handleInfo Function (optional)

spine
onUpdateVisibleSlotWithName(owner: Null<Entity>, slotName: String, handleInfo: Function): Void

Same as onUpdateSlotWithName, but fired only for visible slots (drawDefault=true)

Name Type
owner Null<Entity>
slotName String
handleInfo Function

spine
onUpdateVisibleSlotWithGlobalIndex(owner: Null<Entity>, index: Int, handleInfo: Function): Void

Same as onUpdateSlotWithGlobalIndex, but fired only for visible slots (drawDefault=true)

Name Type
owner Null<Entity>
index Int
handleInfo Function

spine
offUpdateVisibleSlotWithName(slotName: String, ?handleInfo: Function): Void
Name Type Default
slotName String
handleInfo Function (optional)

spine
offUpdateVisibleSlotWithGlobalIndex(index: Int, ?handleInfo: Function): Void
Name Type Default
index Int
handleInfo Function (optional)

spine
bindParentSlot(parentSlot: String, ?options: Null<BindSlotOptions>): Void

Binds a parent Spine slot to this child Spine instance.

This enables Spine-in-Spine composition, where child animations follow parent slot transformations. Common uses include:

  • Weapons attached to hands
  • Armor pieces following body parts
  • Modular character systems
Name Type Default Description
parentSlot String Name of the parent slot to bind to
options Null<BindSlotOptions> (optional) Optional binding configuration (local slot, flipping)

spine
unbindParentSlot(parentSlot: String): Void

Removes a parent slot binding.

This disconnects the child Spine from following the specified parent slot.

Name Type Description
parentSlot String Name of the parent slot to unbind from

spine
new(): Void

Private Members

spine
listener: SpineListener

spine
slotMeshes: IntMap<Mesh>

spine
slotInfo: SlotInfo

spine
subSpines: Array<Spine>

spine
subDepthStep: Float

spine
boundParentSlots: IntMap<Array<ceramic._Spine.BindSlot>>

spine
boundChildSlots: IntMap<ceramic._Spine.BindSlot>

spine
boundChildSlotsDirty: Bool

spine
globalBoundParentSlotGlobalIndex: Int

spine
globalBoundParentSlot: spine.Slot

spine
globalBoundParentSlotDepth: Float

spine
globalBoundParentSlotVisible: Bool

spine
setupBoneTransforms: IntMap<Transform>

spine
firstBoundingBoxSlotIndex: Int


spine
clipShape: Shape

spine
slotClips: IntMap<Shape>

spine
muteEvents: Bool

spine
deferEvents: Bool

spine
renderScheduled: Bool

spine
resetSkeleton: Bool

spine
globalSlotIndexFromSkeletonSlotIndex: Array<Int>

spine
updateSlotWithNameDispatchers: IntMap<ceramic._Spine.DispatchSlotInfo>

spine
updateSlotWithNameDispatchersAsList: Array<ceramic._Spine.DispatchSlotInfo>

spine
updateVisibleSlotWithNameDispatchers: IntMap<ceramic._Spine.DispatchSlotInfo>

spine
updateVisibleSlotWithNameDispatchersAsList: Array<ceramic._Spine.DispatchSlotInfo>

spine
intToFloatColor(value: Int): Float

Encodes the ABGR int color as a float. The high bits are masked to avoid using floats in the NaN range, which unfortunately

  • means the full range of alpha cannot be used.
Name Type
value Int
Returns
Float

spine
emitComplete(): Void

Emitted when a Spine animation completes a full cycle. For looped animations, this is fired at the end of each loop. For non-looped animations, this is fired when the animation reaches its end.


spine
emitBeginRender(): Void

Emitted when the Spine instance begins rendering its slots. Use this to perform setup before slot rendering begins.


spine
emitEndRender(): Void

Emitted when the Spine instance finishes rendering all slots. Use this to perform cleanup or post-processing after rendering.


spine
emitUpdateSlot(info: SlotInfo): Void

Emitted for each slot that is about to be rendered. This includes both visible and invisible slots. Modify the info parameter to customize slot rendering.

Name Type Description
info SlotInfo Contains slot data and transform information

spine
emitUpdateVisibleSlot(info: SlotInfo): Void

Emitted only for visible slots that will be rendered. This is a filtered version of updateSlot that excludes hidden slots.

Name Type Description
info SlotInfo Contains slot data and transform information

spine
emitUpdateSkeleton(): Void

Emitted before the skeleton's animation state is updated. Use this to modify skeleton properties before animation is applied.


spine
emitUpdateWorldTransform(): Void

Emitted before world transforms are calculated for all bones. Hook into this event to apply custom bone transformations.


spine
emitFinishCurrentAnimationChain(): Void

Emitted when a chain of animations completes without interruption. This is fired when all animations in nextAnimations have finished. If the animation chain is interrupted, this event is not fired.


spine
emitApplyNextAnimation(animation: String): Void

Emitted when an animation from nextAnimations is applied. This allows tracking of animation transitions in a chain.

Name Type Description
animation String The name of the animation being applied

spine
emitSpineEvent(entry: spine.TrackEntry, event: spine.Event): Void

Emitted when a Spine event keyframe is triggered during animation. Spine events are defined in the Spine editor and triggered at specific times.

Name Type Description
entry spine.TrackEntry The track entry that triggered the event
event spine.Event The Spine event data

spine
runScheduledRender(): Void

spine
runScheduledRenderDyn(): Void

spine
clearMeshes(): Void

spine
emitCompleteIfNotDestroyed(): Void

spine
willEmitComplete(): Void

spine
updateSkeleton(delta: Float): Void

Update skeleton with the given delta time.

Name Type
delta Float

spine
render(delta: Float, z: Float, setup: Bool): Void

Process spine draw order and output quads and meshes.

Name Type
delta Float
z Float
setup Bool

spine
updateSlotIndexMappings(): Void

spine
willEmitUpdateSlot(info: SlotInfo): Void
Name Type
info SlotInfo

spine
willEmitUpdateVisibleSlot(info: SlotInfo): Void
Name Type
info SlotInfo

spine
computeBoundChildSlots(): Void

Compute boundChildSlots from boundParentSlots to make it more efficient to gather parent slot transformations when drawing child animation.


spine
spineComputeVisibility(): Void

spine
computeVisibility(): Void

spine
hitTest(x: Float, y: Float, matrix: Transform): Bool
Name Type
x Float
y Float
matrix Transform
Returns
Bool

Metadata

Name Parameters
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()