Spine
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
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
Internal flag to know if render became dirty because of a skin change or a new animation was set.
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.
The horizontal origin point of the skeleton (0-1). Determines the pivot point for positioning and transformations. Default is 0.5 (center).
The vertical origin point of the skeleton (0-1). Determines the pivot point for positioning and transformations. Default is 0.5 (center).
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).
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.
Map of slot indices to hide (blacklist).
Slots in this map will not be rendered.
Use Spine.globalSlotIndexForName()
to get slot indices.
Map of slot indices to show (whitelist).
When set, only slots in this map will be rendered.
Use Spine.globalSlotIndexForName()
to get slot indices.
Map of slot indices that are completely disabled.
Disabled slots are skipped entirely during rendering.
Use Spine.globalSlotIndexForName()
to get slot indices.
Map of animation names to trigger animations. When an animation event matches a key in this map, the corresponding animation will be triggered.
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.
When true, uses the first bounding box attachment for hit testing.
This provides accurate collision detection for complex shapes.
Overrides hitWithSlotIndex
when enabled.
When true, forces rendering even when the visual is not visible. Useful for animations that need to continue updating off-screen.
Indicates whether this Spine instance is a child of another Spine animation. Child animations are managed and rendered by their parent.
Global tint color applied to the entire skeleton. Multiplied with individual slot and attachment colors. Default is WHITE (no tinting).
When true, forces an immediate render after calling animate()
.
Useful for ensuring the first frame is displayed immediately.
The Spine skeleton data containing all animations, bones, and slots. Setting this property loads a new skeleton and resets the animation state.
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.
The name of the currently playing animation. Setting this property starts the animation immediately. Set to null to clear the animation.
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.
Whether the current animation should loop continuously.
Only applies to the main animation, not animations in nextAnimations
.
The Spine skeleton instance containing the current pose. Provides access to bones, slots, and attachments for runtime manipulation.
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.
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.
Indicates whether the animation is currently paused or frozen.
This is a combination of the paused
and frozen
states.
Enables automatic freezing when animations complete. Frozen animations stop updating to improve performance. The animation resumes when a new animation is set.
Pauses the animation at its current frame. The animation can be resumed by setting this to false.
Indicates whether the animation is frozen (auto-paused after completion). Frozen animations automatically resume when a new animation is set.
When true, resets the skeleton to setup pose when animations change. This ensures clean transitions between animations.
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) |
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) |
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 |
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.
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 |
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 |
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 |
Name | Type |
---|---|
visual |
Visual |
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 |
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 |
Name | Type | Default |
---|---|---|
slotName |
String | |
handleInfo |
Function | (optional) |
Name | Type | Default |
---|---|---|
index |
Int | |
handleInfo |
Function | (optional) |
Same as onUpdateSlotWithName
, but fired only for visible slots (drawDefault=true
)
Name | Type |
---|---|
owner |
Null<Entity> |
slotName |
String |
handleInfo |
Function |
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 |
Name | Type | Default |
---|---|---|
slotName |
String | |
handleInfo |
Function | (optional) |
Name | Type | Default |
---|---|---|
index |
Int | |
handleInfo |
Function | (optional) |
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) |
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 |
Private Members
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 |
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.
Emitted when the Spine instance begins rendering its slots. Use this to perform setup before slot rendering begins.
Emitted when the Spine instance finishes rendering all slots. Use this to perform cleanup or post-processing after rendering.
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 |
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 |
Emitted before the skeleton's animation state is updated. Use this to modify skeleton properties before animation is applied.
Emitted before world transforms are calculated for all bones. Hook into this event to apply custom bone transformations.
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.
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 |
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 |
Update skeleton with the given delta time.
Name | Type |
---|---|
delta |
Float |
Process spine draw order and output quads and meshes.
Name | Type |
---|---|
delta |
Float |
z |
Float |
setup |
Bool |
Name | Type |
---|---|
info |
SlotInfo |
Name | Type |
---|---|
info |
SlotInfo |
Compute boundChildSlots
from boundParentSlots
to make it more efficient
to gather parent slot transformations when drawing child animation.
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() |