Skip to Content
defold-typescript libraries
defold (official)extension-spine

defold/extension-spine/spine.gui

Functions and constants for interacting with Spine models in GUI

  • GitHub: defold/extension-spine — pinned to 4.8.0 (released while Defold 1.13.1 was current)
    1. Pick a release from defold/extension-spine releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Call it through the global gui — no import. It adds members to the engine gui namespace.

Functions

gui.new_spine_node(pos: vector3 | vector4, spine_scene: string | hash): node

Dynamically create a new spine node.

Parameters

  • pos: vector3 | vector4 — node position
  • spine_scene: string | hash — spine scene id

Returns

  • node: node — new spine node

gui.play_spine_anim(node: node, animation_id: string | hash, playback: constant, play_properties: table, callback_function: function(self, node, message_id, message))

Starts a spine animation.

Parameters

  • node: node — spine node that should play the animation
  • animation_id: string | hash — id of the animation to play
  • playback: constant — playback mode - gui.PLAYBACK_ONCE_FORWARD - gui.PLAYBACK_ONCE_BACKWARD - gui.PLAYBACK_ONCE_PINGPONG - gui.PLAYBACK_LOOP_FORWARD - gui.PLAYBACK_LOOP_BACKWARD - gui.PLAYBACK_LOOP_PINGPONG
  • play_properties: table — optional table with properties. ⚠️ track is 1-based; passed to spine.gui unchanged.
    • blend_duration: number — The 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
    • track: number — The track number for the animation (1-based). Defaults to track 1. Multiple tracks allow for layered animations.
  • callback_function: function(self, node, message_id, message) — function to call when the animation has completed or when spine events occur. ⚠️ track is 1-based; passed to spine.gui unchanged.
    • self: object — The context of the calling script
    • node: node — The spine node that completed the animation or triggered the event
    • message_id: hash — The name of the message ("spine_animation_done" or "spine_event")
    • message: table — A table that contains the response
      • animation_id: hash — The animation that was completed or triggered the event
      • track: number — The track index of the animation
      • playback: constant — (spine_animation_done only!) The playback mode for the animation
      • event_id: hash — (spine_event only!) the event that was triggered.
      • blend_weight: float — (spine_event only!) Deprecated. Always 0.
      • t: float — (spine_event only!) the time at which the event occurred (seconds)
      • integer: int — (spine_event only!) a custom integer associated with the event (0 by default).
      • float: float — (spine_event only!) a custom float associated with the event (0 by default)
      • string: hash — (spine_event only!) a custom string associated with the event (hash("") by default)

gui.cancel_spine(node: node, options: table)

cancel a spine animation

Parameters

  • node: node — spine node that should cancel its animation
  • options: table — optional table with properties. ⚠️ track is 1-based; passed to spine.gui unchanged.
    • track: number — The track number to cancel (1-based). If not specified, cancels all tracks.

gui.get_spine_bone(node: node, bone_id: string | hash): node

The returned node 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.

Parameters

  • node: node — spine node to query for bone node
  • bone_id: string | hash — id of the corresponding bone

Returns

  • bone: node — node corresponding to the spine bone

gui.set_spine_scene(node: node, spine_scene: string | hash)

Set the spine scene on a spine node. The spine scene must be mapped to the gui scene in the gui editor.

Parameters

  • node: node — node to set spine scene for
  • spine_scene: string | hash — spine scene id

gui.get_spine_scene(node: node): hash

Returns the spine scene id of the supplied node. This is currently only useful for spine nodes. The returned spine scene must be mapped to the gui scene in the gui editor.

Parameters

  • node: node — node to get texture from

Returns

  • spine_scene: hash — spine scene id

gui.set_spine_skin(node: node, spine_skin: string | hash)

Sets the spine skin on a spine node.

Change skin of a Spine node

function init(self)
  gui.set_spine_skin(gui.get_node("spine_node"), "monster")
end

Parameters

  • node: node — node to set the spine skin on
  • spine_skin: string | hash — spine skin id

gui.add_spine_skin(node: node, spine_skin_a: string | hash, spine_skin_b: string | hash)

Add a spine skin on a spine node to another skin on the same node.

Add skin of a Spine node to another skin

function init(self)
  gui.add_spine_skin(gui.get_node("spine_node"), "monster_head", "monster_body")
end

Parameters

  • node: node — node having both skins
  • spine_skin_a: string | hash — spine skin id that recieves other skin
  • spine_skin_b: string | hash — spine skin id that will be added

gui.copy_spine_skin(node: node, spine_skin_a: string | hash, spine_skin_b: string | hash)

Copy a spine skin on a spine node to another skin on the same node.

Copy skin of a Spine node to another skin

function init(self)
  gui.copy_spine_skin(gui.get_node("spine_node"), "monster_head", "monster_body")
end

Parameters

  • node: node — node having both skins
  • spine_skin_a: string | hash — spine skin id that copies other skin
  • spine_skin_b: string | hash — spine skin id that will be copied

gui.clear_spine_skin(node: node, spine_skin: string | hash)

Clear a spine skin on a spine node of all attachments and constraints

Clear skin of a Spine node

function init(self)
  gui.clear_spine_skin(gui.get_node("spine_node"), "monster")
end

Parameters

  • node: node — node having both skins
  • spine_skin: string | hash — spine skin id

gui.get_spine_skin(node: node): hash

Gets the spine skin of a spine node

Parameters

  • node: node — node to get spine skin from

Returns

  • id: hash — spine skin id, 0 if no explicit skin is set

gui.get_spine_animation(node: node, options: table): hash

Gets the playing animation on a spine node

Parameters

  • node: node — node to get spine animation from
  • options: table — optional table with properties. ⚠️ track is 1-based; passed to spine.gui unchanged.
    • track: number — The track number to get animation from (1-based). Defaults to track 1.

Returns

  • id: hash — spine animation id, 0 if no animation is playing

gui.set_spine_cursor(node: node, cursor: number, options: table)

This is only useful for spine nodes. The cursor is normalized.

Parameters

  • node: node — spine node to set the cursor for
  • cursor: number — cursor value
  • options: table — optional table with properties. ⚠️ track is 1-based; passed to spine.gui unchanged.
    • track: number — The track number to set cursor for (1-based). Defaults to track 1.

gui.get_spine_cursor(node: node, options: table): number

This is only useful for spine nodes. Gets the normalized cursor of the animation on a spine node.

Parameters

  • node: node — spine node to get the cursor for
  • options: table — optional table with properties. ⚠️ track is 1-based; passed to spine.gui unchanged.
    • track: number — The track number to get cursor from (1-based). Defaults to track 1.

Returns

  • cursor_value: number — cursor value

gui.set_spine_playback_rate(node: node, playback_rate: number, options: table)

This is only useful for spine nodes. Sets the playback rate of the animation on a spine node. Must be positive.

Parameters

  • node: node — spine node to set the playback rate for
  • playback_rate: number — playback rate
  • options: table — optional table with properties. ⚠️ track is 1-based; passed to spine.gui unchanged.
    • track: number — The track number to set playback rate for (1-based). Defaults to track 1.

gui.get_spine_playback_rate(node: node, options: table): number

This is only useful for spine nodes. Gets the playback rate of the animation on a spine node.

Parameters

  • node: node — spine node to get the playback rate for
  • options: table — optional table with properties. ⚠️ track is 1-based; passed to spine.gui unchanged.
    • track: number — The track number to get playback rate from (1-based). Defaults to track 1.

Returns

  • rate: number — playback rate

gui.set_spine_attachment(node: node, slot: string | hash, attachment: string | hash)

This is only useful for spine nodes. Sets an attachment to a slot on a spine node.

Parameters

  • node: node — spine node to set the slot for
  • slot: string | hash — slot name
  • attachment: string | hash — attachment name. May be nil.

gui.set_spine_slot_color(node: node, slot: string | hash, color: vector4)

This is only useful for spine nodes. Sets a tint for all attachments on a slot

Parameters

  • node: node — spine node to set the slot for
  • slot: string | hash — slot name
  • color: vector4 — target color.

gui.spine_physics_translate(node: node, translation: vector3)

Apply a physics-based translation to the Spine GUI node.

Parameters

  • node: node — The Spine GUI node to translate.
  • translation: vector3 — The translation vector to apply to the Spine GUI node.

gui.spine_physics_rotate(node: node, center: vector3, degrees: number)

Apply a physics-based rotation to the Spine GUI node.

Parameters

  • node: node — The Spine GUI node to rotate.
  • center: vector3 — The center point around which to rotate.
  • degrees: number — The rotation angle in degrees.

gui.set_spine_ik_target_position(node: node, ik_constraint_id: string | hash, position: vector3)

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

The following example assumes that the Spine GUI node has id "spine_node".

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, 0)
  gui.set_spine_ik_target_position(gui.get_node("spine_node"), "right_hand_constraint", pos)
end

Parameters

  • node: node — the Spine GUI node containing the object
  • ik_constraint_id: string | hash — id of the corresponding IK constraint object
  • position: vector3 — target position

gui.set_spine_ik_target(node: node, ik_constraint_id: string | hash, target_node: node)

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

The following example assumes that the Spine GUI node has id "spine_node".

How to set the target IK position of the right_hand_constraint constraint object to follow the position of GUI node with id "target_node"

function init(self)
  local spine_node = gui.get_node("spine_node")
  local target_node = gui.get_node("target_node")
  gui.set_spine_ik_target(spine_node, "right_hand_constraint", target_node)
end

Parameters

  • node: node — the Spine GUI node containing the object
  • ik_constraint_id: string | hash — id of the corresponding IK constraint object
  • target_node: node — target GUI node

gui.reset_spine_ik_target(node: node, ik_constraint_id: string | hash)

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

The following example assumes that the Spine GUI node has id "spine_node".

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)
  gui.reset_spine_ik_target(gui.get_node("spine_node"), "right_hand_constraint")
end

Parameters

  • node: node — the Spine GUI node containing the object
  • ik_constraint_id: string | hash — id of the corresponding IK constraint object

On this page

Functionsgui.new_spine_node(pos: vector3 | vector4, spine_scene: string | hash): nodegui.play_spine_anim(node: node, animation_id: string | hash, playback: constant, play_properties: table, callback_function: function(self, node, message_id, message))gui.cancel_spine(node: node, options: table)gui.get_spine_bone(node: node, bone_id: string | hash): nodegui.set_spine_scene(node: node, spine_scene: string | hash)gui.get_spine_scene(node: node): hashgui.set_spine_skin(node: node, spine_skin: string | hash)gui.add_spine_skin(node: node, spine_skin_a: string | hash, spine_skin_b: string | hash)gui.copy_spine_skin(node: node, spine_skin_a: string | hash, spine_skin_b: string | hash)gui.clear_spine_skin(node: node, spine_skin: string | hash)gui.get_spine_skin(node: node): hashgui.get_spine_animation(node: node, options: table): hashgui.set_spine_cursor(node: node, cursor: number, options: table)gui.get_spine_cursor(node: node, options: table): numbergui.set_spine_playback_rate(node: node, playback_rate: number, options: table)gui.get_spine_playback_rate(node: node, options: table): numbergui.set_spine_attachment(node: node, slot: string | hash, attachment: string | hash)gui.set_spine_slot_color(node: node, slot: string | hash, color: vector4)gui.spine_physics_translate(node: node, translation: vector3)gui.spine_physics_rotate(node: node, center: vector3, degrees: number)gui.set_spine_ik_target_position(node: node, ik_constraint_id: string | hash, position: vector3)gui.set_spine_ik_target(node: node, ik_constraint_id: string | hash, target_node: node)gui.reset_spine_ik_target(node: node, ik_constraint_id: string | hash)