Version: stable
FUNCTION | |
---|---|
spine.play_anim() | play an animation on a spine model |
spine.cancel() | cancel all animation on a spine model |
spine.get_go() | retrieve the game object corresponding to a spine model skeleton bone |
spine.set_skin() | sets the spine skin |
spine.set_ik_target_position() | set the target position of an IK constraint object |
spine.set_ik_target() | set the IK constraint object target position to follow position of a game object |
spine.reset_ik_target() | reset the IK constraint target position to default of a spinemodel |
MESSAGE | |
---|---|
spine_animation_done | reports the completion of a Spine animation |
spine_event | reports an incoming event from the Spine animation |
PROPERTIES | |
---|---|
cursor | number spine cursor |
playback_rate | number spine playback_rate |
animation | hash spine animation |
skin | hash spine skin |
material | hash spine material |
spine.play_anim(url,anim_id,playback,[play_properties],[complete_function])
go.PLAYBACK_ONCE_FORWARD
go.PLAYBACK_ONCE_BACKWARD
go.PLAYBACK_ONCE_PINGPONG
PARAMETERS
url |
the spine model for which to play the animation |
anim_id |
id of the animation to play |
playback |
playback mode of the animation
|
[play_properties] |
optional table with properties:
|
[complete_function] |
function to call when the animation has completed.
|
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(sender, "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.cancel(url)
PARAMETERS
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(url,bone_id)
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 |
the spine model to query |
bone_id |
id of the corresponding bone |
RETURNS
id |
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.set_skin(url,spine_skin,[spine_slot])
PARAMETERS
url |
the spine model for which to set skin |
spine_skin |
spine skin id |
[spine_slot] |
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 modelfunction init(self) spine.set_skin("#spinemodel", "monster") end
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
spine.set_ik_target_position(url,ik_constraint_id,position)
PARAMETERS
url |
the spine model containing the object |
ik_constraint_id |
id of the corresponding IK constraint object |
position |
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 objectfunction init(self) local pos = vmath.vector3(1, 2, 3) spine.set_ik_target_position("player#spinemodel", "right_hand_constraint", pos) end
spine.set_ik_target(url,ik_constraint_id,target_url)
PARAMETERS
url |
the spine model containing the object |
ik_constraint_id |
id of the corresponding IK constraint object |
target_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.reset_ik_target(url,ik_constraint_id)
PARAMETERS
url |
the spine model containing the object |
ik_constraint_id |
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
reports the completion of a Spine animation
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
animation_id |
the id of the completed animation |
playback |
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
reports an incoming event from the Spine animation
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
.
event_id |
the id of the event. |
animation_id |
the id of the animation. |
t |
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 |
user defined integer value for the event |
float |
user defined floating point value for the event |
string |
user defined string value (hashed) for the event |
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
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.
number spine cursor
EXAMPLES
How to get the normalized cursor value:function init(self) -- Get the cursor value on component "spine" cursor = go.get("#spine", "cursor") end
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
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.
number spine playback_rate
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
READ ONLY The current animation set on the component. The type of the property is hash.
hash spine animation
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
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.
hash spine skin
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
The material used when rendering the spine model. The type of the property is hash.
hash spine material
EXAMPLES
How to set material using a script property (see resource.material)go.property("my_material", resource.material("/material.material")) function init(self) go.set("#spinemodel", "material", self.my_material) end