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)- Pick a release from defold/extension-spine releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Call it through the global
gui— no import. It adds members to the engineguinamespace.
- Pick a release from defold/extension-spine releases and add its Source code (zip) URL (or a packaged
Functions
gui.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)
gui.new_spine_node(pos: vector3 | vector4, spine_scene: string | hash): node
Dynamically create a new spine node.
Parameters
pos:vector3 | vector4— node positionspine_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 animationanimation_id:string | hash— id of the animation to playplayback: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_PINGPONGplay_properties:table— optional table with properties. ⚠️trackis 1-based; passed tospine.guiunchanged.blend_duration:number— The duration of a linear blend between the current and new animationoffset:number— The normalized initial value of the animation cursor when the animation starts playingplayback_rate:number— The rate with which the animation will be played. Must be positivetrack: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. ⚠️trackis 1-based; passed tospine.guiunchanged.self:object— The context of the calling scriptnode:node— The spine node that completed the animation or triggered the eventmessage_id:hash— The name of the message ("spine_animation_done" or "spine_event")message:table— A table that contains the responseanimation_id:hash— The animation that was completed or triggered the eventtrack:number— The track index of the animationplayback:constant— (spine_animation_done only!) The playback mode for the animationevent_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 animationoptions:table— optional table with properties. ⚠️trackis 1-based; passed tospine.guiunchanged.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 nodebone_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 forspine_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")
endParameters
node:node— node to set the spine skin onspine_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")
endParameters
node:node— node having both skinsspine_skin_a:string | hash— spine skin id that recieves other skinspine_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")
endParameters
node:node— node having both skinsspine_skin_a:string | hash— spine skin id that copies other skinspine_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")
endParameters
node:node— node having both skinsspine_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 fromoptions:table— optional table with properties. ⚠️trackis 1-based; passed tospine.guiunchanged.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 forcursor:number— cursor valueoptions:table— optional table with properties. ⚠️trackis 1-based; passed tospine.guiunchanged.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 foroptions:table— optional table with properties. ⚠️trackis 1-based; passed tospine.guiunchanged.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 forplayback_rate:number— playback rateoptions:table— optional table with properties. ⚠️trackis 1-based; passed tospine.guiunchanged.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 foroptions:table— optional table with properties. ⚠️trackis 1-based; passed tospine.guiunchanged.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 forslot:string | hash— slot nameattachment: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 forslot:string | hash— slot namecolor: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)
endParameters
node:node— the Spine GUI node containing the objectik_constraint_id:string | hash— id of the corresponding IK constraint objectposition: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)
endParameters
node:node— the Spine GUI node containing the objectik_constraint_id:string | hash— id of the corresponding IK constraint objecttarget_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")
endParameters
node:node— the Spine GUI node containing the objectik_constraint_id:string | hash— id of the corresponding IK constraint object