Prerequisite: Exporting Spine Animations for GameBuilder Studio
Once you have your Spine animation exported just import the ".skel" data file into GameBuilder Studio (GBs). When you drag the Spine asset onto the scene everything will be wired up for you. A Spine Animation Renderer, Sprite Sheet, and either a Spine Collision Spatial or Basic Spatial.
Bounding Box Collision Shapes
If your character has a bounding box defined in Spine then GBs will automatically add a Spine Collision Spatial onto the Spine entity which will handle creating and moving the collision shapes to represent the skeletons' bounding boxes.
**Note: You will not see these shapes in the collision shape editor inside of GBs because they are defined by the Bounding Box in Spine. However you can add additional collision shapes to the spatial.
Spine Animation Renderer
The Spine Renderer will display the available animations and skins in the selected Spine Skeleton data file for you to choose as defaults. The size of the renderer and attached spatial will be overridden for you automatically whenever you change one of these settings.
By default if you define a default animation the Spine Renderer will clear all previous animations on track 0 and start playing the default animation on track 0. So if you want to transition from the default animation set here to another animation use the "Additive" setting in the Spine Animation action.
Defining Animation Transitions (Mixing)
Whenever you move from one animation to another using the Spine Animation action you will notice an abrupt change in the animation. You can smooth that transition out between animations on the same animation track by defining the amount of time between transitions here.
Spine Animation Action
The Spine Animation action has two types. The "Set Animation" and "Add Animation". The "Set Animation" will clear the specified track and start playing the animation based on the delay. The "Add Animation" will append the animation to the end of the specified track and only start playing when the animation right before it on the track has reached the delay time before its end. So if the delay is 0 the added animation will not play until the previous animation added to the track has finished. If the delay is 2 then the animation being added will start 2 seconds before the previous animation is scheduled to finish. There is more information on animation mixing on the Spine site.
Layering animations can be achieved by triggering an "Add Animation" action type on top of an existing animation that is playing where the added animation only has keys for say the top half of the character. The other way to layer animations is to play animations on different tracks. The 0 track index is the default track used by the Spine Renderer so if you want to layer an upper body animation on top of a base walk animation to maybe have the character walk and shoot you can play the shooting animation in a loop on track 1.
Spine Skinning Action
Changing the entire look and feel of a character while using the same animation can be achieved by defining a different skin in Spine. You can change out the skin easily during runtime using the Spine Skinning action.
It is important to understand that the Spine Skinning action is a persistent action that can remain active even after the condition it is triggered under is no longer valid.
You can also equip item upgrades or just change wardrobe of a character by swapping out attachments on a skeleton. To define multiple attachments for a given slot just add multiple attachments on a slot in Spine and turn them off. The drop down of attachments will only return the attachments specified for the selected slot. You can also use an attachment defined in a slot on another skin.
The "Clear On Stop" checkbox will determine if the change effected by the current action should remain applied whether the condition it is under is no longer valid. If selected then the effect of the action can be overridden by an animation applied to the skeleton once the condition controlling the action is no longer valid. If the condition is to check for the Mouse down then this action will change the attachment as long as the mouse is down once the mouse is up the attachment can be overridden by another operation.
Also keep in mind that all the skinning actions are cumulative in the order that they have been executed. So if you change an attachment to show a sword then change it to show a gun and uncheck the "Clear On Stop" for the sword change then when the condition for the gun change is no longer valid the sword will then be shown again until the entity or component the sword change action was on is removed or deleted.
Clearing A Slot
Clearing a slot on a skeleton can be done very easily by telling the action which slot on a Spine Renderer should be cleared.
Manipulating Spine Skeleton Bones Manually At Runtime
In your game you may want to manipulate the angle of rotation of the characters gun or change where the eyes are pointing. You can do this by changing the bind pose data of a bone. There is a property on the Spine Animation Renderer called "bones".
**Note: This property may take some time to load so you want to make sure you only reference values on this property after you receive the Game Event "Level Loaded".
To reference the data of a bone access it like this: @Renderer.bones.torso.data.rotation. Use a change property action to change the bones' original (bind pose) values. If there are any spaces in your bone names they will be replaced with underscores "_". By accessing the properties on the "data" property of a bone you are affecting the base values that animations are applied on top of so it will not break your animations.
If you want to reference the current value of a bone leave out the "data" portion and access a property like this: @Renderer.bones.torso.rotation. Keep in mind that there is a difference in coordinate space as well. Bones have local coordinate values and world coordinate values. Only the local values are changed by the underlying Spine animation runtime. The world values are exposed as read only and have the key word "world" in front of the property name. It refers to the global position of the bone after all inherited transformations from parent bones have been applied to the bone.
- x - local x position relative to bone
- y - local Y position relative to bone
- rotation - local bone rotation
- scaleX - the scale of the bone on the x axis
- scaleY - the scale of the bone on the y axis
- worldX (readonly) - the X position relative to the scene
- worldY (readonly) - the Y position relative to the scene
- worldRotation (readonly) - the rotation angle
- worldScaleX (readonly)
- worldScaleY (readonly)
- data (readonly) - the original bind pose data as defined in Spine
- parent (readonly) - the parent bone
What if you wanted to get the exact position of a bone in the scene maybe to match up a projectile coming out of the gun in the player's hand or to hover a health bar over the character's head that matches the animation, rotation, etc.? You will need to combine a few values. in GameBuilder Studio there are a number of additional transformations like the registration point, position offset, etc. that can be applied to a renderer on top of the transformations that are applied to the underlying Spine skeleton so you will need to take all those into account when determining the bones' world (scene) position. To help you calculate this exact scene position information we have exposed the Renderers' internal transformation object which holds the scene position of the Renderer after all the transformations have been applied to it.
Add the Spine Renderer's calculated position to the "worldX" or "worldY" position of the Skeleton's bone to get its exact location in the scene. It is just a matter of adding up the values in an expression like such for the X values: (Self.Renderer.bones.hand.worldX + Self.Renderer.transformationMatrix.tx) * Self.Renderer.scale.x. or (Self.Renderer.bones.hand.worldY + Self.Renderer.transformationMatrix.ty) * Self.Renderer.scale.y for the Y values. You could leave off the scale value if the Renderer has not been scaled because scale would just be 1.
Currently a skinned mesh attachment is not fully supported inside of the GBs editor. You will see just the triangulated outline of the skinned attachment from Spine. Only the GPU Spine Renderer currently supports rendering skinned meshes from Spine. This is a limitation in the Spine-AS3 runtime. When they update the AS3 runtime we will update the Spine plugin. IK animations are also currently not supported in the underlying runtime yet.