- Select ref document -

Spine model API documentation

version 1.2.149

Functions and messages for interacting with the 'Spine' 2D bone animation system.

Functions

spine.cancel

spine.cancel(url)

Cancels all running animations on a specified spine model component.

Parameters

url

string | hash | url the spine model for which to cancel the animation

url

string | hash | url the spine model for which to cancel the animation

Examples

The following examples assumes that the spine model has id "spinemodel".

How to cancel all animation:

function init(self)
  spine.cancel("#spinemodel")
end

spine.get_go

spine.get_go(url, bone_id)

Returns the id of the game object that corresponds to a specified skeleton bone. The returned game object can be used for parenting and transform queries. This function has complexity O(n), where n is the number of bones in the spine model skeleton. Game objects corresponding to a spine model skeleton bone can not be individually deleted.

Parameters

url

string | hash | url the spine model to query

bone_id

string | hash id of the corresponding bone

url

string | hash | url the spine model to query

bone_id

string | hash id of the corresponding bone

Returns

id

hash id of the game object

id

hash id of the game object

Examples

The following examples assumes that the spine model has id "spinemodel".

How to parent the game object of the calling script to the "right_hand" bone of the spine model in a player game object:

function init(self)
  local parent = spine.get_go("player#spinemodel", "right_hand")
  msg.post(".", "set_parent", {parent_id = parent})
end

spine.play_anim

spine.play_anim(url, anim_id, playback, [play_properties], [complete_function])

Plays a specified animation on a spine model component with specified playback mode and parameters.

An optional completion callback function can be provided that will be called when the animation has completed playing. If no function is provided, a spine_animation_done message is sent to the script that started the animation.

The callback is not called (or message sent) if the animation is cancelled with spine.cancel. The callback is called (or message sent) only for animations that play with the following playback modes:

  • go.PLAYBACK_ONCE_FORWARD
  • go.PLAYBACK_ONCE_BACKWARD
  • go.PLAYBACK_ONCE_PINGPONG

Parameters

url

string | hash | url the spine model for which to play the animation

anim_id

string | hash id of the animation to play

playback

constant playback mode of the animation

  • go.PLAYBACK_ONCE_FORWARD
  • go.PLAYBACK_ONCE_BACKWARD
  • go.PLAYBACK_ONCE_PINGPONG
  • go.PLAYBACK_LOOP_FORWARD
  • go.PLAYBACK_LOOP_BACKWARD
  • go.PLAYBACK_LOOP_PINGPONG
[play_properties]

table optional table with properties:

blend_duration
number duration of a linear blend between the current and new animation.
offset
number the normalized initial value of the animation cursor when the animation starts playing.
playback_rate
number the rate with which the animation will be played. Must be positive.
[complete_function]

function(self, message_id, message, sender)) function to call when the animation has completed.

self
object The current object.
message_id
hash The name of the completion message, "spine_animation_done".
message
table Information about the completion:
  • hash animation_id - the animation that was completed.
  • constant playback - the playback mode for the animation.
sender
url The invoker of the callback: the spine model component.
url

string | hash | url the spine model for which to play the animation

anim_id

string | hash id of the animation to play

playback

constant playback mode of the animation

  • go.PLAYBACK_ONCE_FORWARD
  • go.PLAYBACK_ONCE_BACKWARD
  • go.PLAYBACK_ONCE_PINGPONG
  • go.PLAYBACK_LOOP_FORWARD
  • go.PLAYBACK_LOOP_BACKWARD
  • go.PLAYBACK_LOOP_PINGPONG
[play_properties]

table optional table with properties:

blend_duration
number duration of a linear blend between the current and new animation.
offset
number the normalized initial value of the animation cursor when the animation starts playing.
playback_rate
number the rate with which the animation will be played. Must be positive.
[complete_function]

function(self, message_id, message, sender)) function to call when the animation has completed.

self
object The current object.
message_id
hash The name of the completion message, "spine_animation_done".
message
table Information about the completion:
  • hash animation_id - the animation that was completed.
  • constant playback - the playback mode for the animation.
sender
url The invoker of the callback: the spine model component.

Examples

The following examples assumes that the spine model has id "spinemodel".

How to play the "jump" animation followed by the "run" animation:

local function anim_done(self, message_id, message, sender)
  if message_id == hash("spine_animation_done") then
    if message.animation_id == hash("jump") then
      -- open animation done, chain with "run"
      local properties = { blend_duration = 0.2 }
      spine.play_anim(url, "run", go.PLAYBACK_LOOP_FORWARD, properties, anim_done)
    end
  end
end

function init(self)
    local url = msg.url("#spinemodel")
    local play_properties = { blend_duration = 0.1 }
    -- first blend during 0.1 sec into the jump, then during 0.2 s into the run animation
    spine.play_anim(url, "open", go.PLAYBACK_ONCE_FORWARD, play_properties, anim_done)
end

spine.reset_constant

spine.reset_constant(url, constant)

Resets a shader constant for a spine model component. The constant must be defined in the material assigned to the spine model. Resetting a constant through this function implies that the value defined in the material will be used. Which spine model to reset a constant for is identified by the URL.

Parameters

url

string | hash | url the spine model that should have a constant reset

constant

string | hash name of the constant

url

string | hash | url the spine model that should have a constant reset

constant

string | hash name of the constant

Examples

The following examples assumes that the spine model has id "spinemodel" and that the default-material in builtins is used, which defines the constant "tint". If you assign a custom material to the sprite, you can reset the constants defined there in the same manner.

How to reset the tinting of a spine model:

function init(self)
  spine.reset_constant("#spinemodel", "tint")
end

spine.reset_ik_target

spine.reset_ik_target(url, ik_constraint_id)

Resets any previously set IK target of a spine model, the position will be reset to the original position from the spine scene.

Parameters

url

string | hash | url the spine model containing the object

ik_constraint_id

string | hash id of the corresponding IK constraint object

url

string | hash | url the spine model containing the object

ik_constraint_id

string | hash id of the corresponding IK constraint object

Examples

The following example assumes that the spine model has id "spinemodel".

A player no longer has an item in hand, that previously was controlled through IK, let's reset the IK of the right hand.

function player_lost_item(self)
  spine.reset_ik_target("player#spinemodel", "right_hand_constraint")
end

spine.set_constant

spine.set_constant(url, constant, value)

Sets a shader constant for a spine model component. The constant must be defined in the material assigned to the spine model. Setting a constant through this function will override the value set for that constant in the material. The value will be overridden until spine.reset_constant is called. Which spine model to set a constant for is identified by the URL.

Parameters

url

string | hash | url the spine model that should have a constant set

constant

string | hash name of the constant

value

vector4 value of the constant

url

string | hash | url the spine model that should have a constant set

constant

string | hash name of the constant

value

vector4 value of the constant

Examples

The following examples assumes that the spine model has id "spinemodel" and that the default-material in builtins is used, which defines the constant "tint". If you assign a custom material to the sprite, you can reset the constants defined there in the same manner.

How to tint a spine model to red:

function init(self)
  spine.set_constant("#spinemodel", "tint", vmath.vector4(1, 0, 0, 1))
end

spine.set_ik_target

spine.set_ik_target(url, ik_constraint_id, target_url)

Sets a game object as target position of an inverse kinematic (IK) object. As the target game object's position is updated, the constraint object is updated with the new position.

Parameters

url

string | hash | url the spine model containing the object

ik_constraint_id

string | hash id of the corresponding IK constraint object

target_url

string | hash | url target game object

url

string | hash | url the spine model containing the object

ik_constraint_id

string | hash id of the corresponding IK constraint object

target_url

string | hash | url target game object

Examples

The following example assumes that the spine model has id "spinemodel".

How to set the target IK position of the right_hand_constraint constraint object of the player object to follow the position of game object with url "some_game_object"

function init(self)
  spine.set_ik_target("player#spinemodel", "right_hand_constraint", "some_game_object")
end

spine.set_ik_target_position

spine.set_ik_target_position(url, ik_constraint_id, position)

Sets a static (vector3) target position of an inverse kinematic (IK) object.

Parameters

url

string | hash | url the spine model containing the object

ik_constraint_id

string | hash id of the corresponding IK constraint object

position

vector3 target position

url

string | hash | url the spine model containing the object

ik_constraint_id

string | hash id of the corresponding IK constraint object

position

vector3 target position

Examples

The following example assumes that the spine model has id "spinemodel".

How to set the target IK position of the right_hand_constraint constraint object of the player object

function init(self)
  local pos = vmath.vector3(1, 2, 3)
  spine.set_ik_target_position("player#spinemodel", "right_hand_constraint", pos)
end

spine.set_skin

spine.set_skin(url, spine_skin, [spine_slot])

Sets the spine skin on a spine model.

Parameters

url

string | hash | url the spine model for which to set skin

spine_skin

string | hash spine skin id

[spine_slot]

string | hash optional slot id to only change a specific slot

url

string | hash | url the spine model for which to set skin

spine_skin

string | hash spine skin id

[spine_slot]

string | hash optional slot id to only change a specific slot

Examples

The following examples assumes that the spine model has id "spinemodel".

Change skin of a Spine model

function init(self)
  spine.set_skin("#spinemodel", "monster")
end

Change only part of the Spine model to a different skin.

function monster_transform_arm(self)
  -- The player is transforming into a monster, begin with changing the arm.
  spine.set_skin("#spinemodel", "monster", "left_arm_slot")
end

Messages

spine_animation_done

"spine_animation_done", { animation_id=…, playback=… }

This message is sent when a Spine animation has finished playing back to the script that started the animation.

No message is sent if a completion callback function was supplied when the animation was started. No message is sent if the animation is cancelled with model.cancel(). This message is sent only for animations that play with the following playback modes:

  • go.PLAYBACK_ONCE_FORWARD
  • go.PLAYBACK_ONCE_BACKWARD
  • go.PLAYBACK_ONCE_PINGPONG

Fields

animation_id

hash the id of the completed animation

playback

constant the playback mode of the completed animation

animation_id

hash the id of the completed animation

playback

constant the playback mode of the completed animation

Examples

function on_message(self, message_id, message, sender)
  if message_id == hash("spine_animation_done") then
    if message.animation_id == hash("run") and message.playback == go.PLAYBACK_ONCE_FORWARD then
      -- The animation "run" has finished running forward.
    end
  end
end

spine_event

"spine_event", { event_id=…, animation_id=…, t=…, blend_weight=…, integer=…, float=…, string=…, node=… }

This message is sent when Spine animation playback fires events. These events has to be defined on the animation track in the Spine animation editor. An event can contain custom values expressed in the fields integer, float and string.

Fields

event_id

hash the id of the event.

animation_id

hash the id of the animation.

t

number the time of the event in seconds, relative to the start of the animation.

blend_weight

[type:number the blend weight (between 0.0-1.0) of the current animation at time t.

integer

number user defined integer value for the event

float

number user defined floating point value for the event

string

hash user defined string value (hashed) for the event

node

node the source spine gui node if the event originated from gui, otherwise nil

event_id

hash the id of the event.

animation_id

hash the id of the animation.

t

number the time of the event in seconds, relative to the start of the animation.

blend_weight

[type:number the blend weight (between 0.0-1.0) of the current animation at time t.

integer

number user defined integer value for the event

float

number user defined floating point value for the event

string

hash user defined string value (hashed) for the event

node

node the source spine gui node if the event originated from gui, otherwise nil

Examples

The following example assumes that an animation sends event messages with the id "footstep" and that the integer field is used to distinguish between left and right foot (values 0 and 1).

function on_message(self, message_id, message, sender)
  if message_id == hash("spine_event") then
    -- Receiving animation event from Spine. Play footsteps.
    if message.event_id == hash("footstep") and message.integer == 0 then
      msg.post("#sound_footstep_right", "play_sound")
    elseif message.event_id == hash("footstep") and message.integer == 1 then
      msg.post("#sound_footstep_left", "play_sound")
  end
end

Properties

animation

READ ONLY The current animation set on the component. The type of the property is hash.

Examples

How to read the current animation from a spinemodel component:

function init(self)
  -- Get the current animation on component "spinemodel"
  local animation = go.get("#spinemodel", "animation")
end

cursor

The normalized animation cursor. The type of the property is number.

Please note that spine events may not fire as expected when the cursor is manipulated directly.

Examples

How to get the normalized cursor value:

function init(self)
  -- Get the cursor value on component "spine"
  cursor = go.get("#spine", "cursor")
end

How to animate the cursor from 0.0 to 1.0 using linear easing for 2.0 seconds:

function init(self)
  -- Get the current value on component "spine"
  go.set("#spine", "cursor", 0.0)
  -- Animate the cursor value
  go.animate("#spine", "cursor", go.PLAYBACK_LOOP_FORWARD, 1.0, go.EASING_LINEAR, 2)
end

playback_rate

The animation playback rate. A multiplier to the animation playback rate. The type of the property is number.

The playback_rate is a non-negative number, a negative value will be clamped to 0.

Examples

How to set the playback_rate on component "spine" to play at double the current speed:

function init(self)
  -- Get the current value on component "spine"
  playback_rate = go.get("#spine", "playback_rate")
  -- Set the playback_rate to double the previous value.
  go.set("#spine", "playback_rate", playback_rate * 2)
end

skin

The current skin on the component. The type of the property is hash. If setting the skin property the skin must be present on the spine model or a runtime error is signalled.

Examples

How to read and write the current skin from a spinemodel component:

function init(self)
  -- If the hero skin is set to "bruce_banner", turn him green
  local skin = go.get("#hero", "skin")
  if skin == hash("bruce_banner") then
    go.set("#hero", "skin", hash("green"))
  end
end