spine-construct3 Runtime Documentation

Licensing

See the Spine Runtimes License before integrating the Spine Runtimes into your applications.

Getting Started

spine-construct3 is the official Spine runtime addon for Construct 3. It allows you to load, display, and animate Spine skeletons directly in your Construct 3 projects using the event sheet system.

The spine-construct3 addon is built on top of spine-ts core, the TypeScript implementation of the renderer-agnostic Spine Runtimes core APIs. It supports all Spine features, except tint black.

Note: Ensure that the major.minor version of spine-construct3 matches the major.minor Spine Editor version you are exporting from. See Synchronizing versions for more information.

Installation

Download the latest version of spine-construct3: spine-construct3.zip

To download a specific version, use: https://esotericsoftware.com/files/spine-construct3/c3/spine-construct3-4.y.z.zip, replacing y.z with the desired version number. For example, version 4.3.10 would be: spine-construct3-4.3.10.zip

To install the addon:

1. Unzip the downloaded file. It contains the addon file EsotericSoftware_SpineConstruct3.c3addon.
2. Open the Construct 3 editor.
3. Go to Menu > View > Addon manager.
4. Click Install new addon... in the bottom left.
5. Select the .c3addon file and click Install.
6. Click Ok and refresh the editor as prompted.

The Spine plugin should now appear in the Addon manager list.

TODO: add images.

Asset Management

Exporting for spine-construct3

Follow the instructions in the Spine User Guide on how to:

1. Export skeleton & animation data
2. Export texture atlases containing the images for your skeletons

An export of the skeleton data and texture atlas will yield the following files:

1. skeleton-name.json or skeleton-name.skel, containing your skeleton and animation data, either in the JSON or binary format.
2. skeleton-name.atlas, containing information about the texture atlas.
3. One or more .png files, each representing a page in your texture atlas containing the packed images your skeleton uses.

Note: You should prefer binary skeleton exports over JSON exports, as they are smaller in size and faster to load.

Updating Spine Assets

During development, you may frequently update your Spine skeleton data and texture atlas files. You can simply overwrite these source files (.json, .skel, .atlas, .png) by re-exporting from the Spine Editor and re-importing them into your Construct 3 project.

Ensure that the major.minor version of spine-construct3 matches the major.minor Spine Editor version you are exporting from. See Synchronizing versions for more information.

Plugin Overview

The spine-construct3 addon adds a Spine object type to Construct 3, available in the Insert New Object dialog under the General category.

The Spine object is a world instance that can be placed on a layout, positioned, scaled, and rotated. It renders a Spine skeleton and provides Actions, Conditions, and Expressions (ACEs) to control animations, skins, bones, and more through the event sheet.

Properties Panel

When you select a Spine object, the Properties panel displays the following options:

Bounds provider (group):

Actions

Animation

Skins

Attachments & Slots

Skeleton

Bones

Bone Follower Actions

Interactive Handles

Bounds

Conditions

Triggers

State Checks

Expressions

Bone Queries

State Queries

Event Data

Valid field values for GetEventData:

Adding a Spine Object

Importing Assets

To import Spine assets into a Construct 3 project:

1. Right-click the Files folder in the Project panel and select Import files.
2. Select all exported files (skeleton, atlas, and images).

TODO: Add image

Creating the Object Type

1. In the Project panel, right-click on Object types and select Add new object type.
2. Choose Spine from the General category.
3. Enter a name for the object type and click Create.

This creates an object type named Spine by default. You can create multiple object types based on the Spine plugin, each representing a different character or animated element in your game (e.g., Player, Enemy, NPC).

TODO: Add image

Adding to Layout

1. In the Project panel, expand Object types and drag the Spine object type onto the layout.

Alternatively, you can create an object type and place an instance in one step: double-click on the layout, choose Spine from the General category, and click to place an instance of the newly created object type.

The Spine logo appears as a placeholder until you assign a skeleton.

TODO: Add image

Configuring the Object

Basic Configuration

With the Spine object selected:

1. In the Properties panel, click the Atlas property and select your .atlas file.
2. Click the Skeleton property and select your .json or .skel file.

The skeleton now renders in the editor in its setup pose.

If the setup pose is empty, an error message is displayed. In this case, set a skin that contains visible attachments.

TODO: Add image TODO: Add image of empty setup pose error

Bounds

By default, the bounds are calculated from the setup pose. You can change the Bounds provider property to Animation/Skin bounds to calculate bounds based on the selected skin and animation instead.

If neither option produces the desired bounds, enable the Position bounds property to manually resize, move, and rotate the bounds while keeping the skeleton fixed. To reset the bounds to the current bounds provider settings, click the Reset bounds button.

Collisions

Enabling the Enable collision property creates a Sprite object type named ObjectTypeName_CollisionBody (e.g., Player_CollisionBody). This sprite is not placed in the layout at design time and should not be placed manually; it is created automatically at runtime for each instance of the Spine object type. The collision sprite's size and position automatically match the bounds of its corresponding Spine instance. This sprite object type is shared among all instances of the same Spine object type.

This approach is necessary because Construct 3 does not allow plugins to declare themselves as having collision capabilities. Without this, the collision-related ACEs and the SOL (Selected Object List) API for filtering instances involved in collisions would not be available.

When disabling collision on the last instance that uses it, a prompt asks whether to keep or delete the collision sprite. Deleting it will also remove any ACEs in event sheets that reference it.

See the Properties Panel section for all available configuration options.

Advanced Features

Drag Handles

Drag handles allow users to interactively drag bones or slots with the mouse or touch input. This is useful for creating interactive characters, ragdoll effects, or allowing users to pose characters.

To add a drag handle:

1. Use the Add handle action, specifying the type (Bone or Slot), the bone/slot name, and the interaction radius.
2. Enable the debug parameter to visualize the handle area.

When a bone handle is added, clicking and dragging within the specified radius will move the bone to follow the pointer. For slot handles, the clickable area is determined by the slot's attachment polygon instead of a radius.

To remove a handle, use the Remove handle action.

Bone Followers

Bone followers allow you to attach any Construct 3 object instance to a skeleton bone. The attached instance automatically follows the bone's position and rotation each frame. Multiple instances can follow the same bone.

To attach an instance to a bone:

• Use Attach instance to bone to attach by UID (e.g., Sprite.UID).
• Use Attach object to bone to attach picked instances from conditions (works with SOL).

The offsets (offsetX, offsetY, offsetAngle) are applied in the bone's local space, meaning they rotate with the bone.

To detach instances:

• Use Detach object from bone to detach picked instances.
• Use Detach all from bone to detach all followers from a bone.

The detached instances remain at their current position.

Use cases include attaching weapons, accessories, or effects to character bones.

Bone Pose Override

The Set bone pose action allows you to programmatically control bone positions, rotations, and scales. This can be used for:

• Aiming weapons or eyes at a target
• Procedural animation adjustments
• Blending user input with animations

Two apply modes are available:

• Once: The pose is applied for the current frame only. The animation resumes control on the next frame.
• Hold: The pose is continuously applied every frame, overriding the animation. Use Release bone hold to stop.

Two coordinate modes are available:

• Local: Values are applied directly as the bone's local pose.
• Game: Values are in game world coordinates and are converted to bone-local space.

Leave parameters as empty string to keep their current values. In hold mode, this allows you to override only specific properties (e.g., only rotation) while preserving others.

Runtime Bounds

The bounds configured in the editor may not always fit every animation. For example, a character's idle animation may have smaller bounds than a jump or attack animation.

There are two approaches to adjust bounds at runtime:

• Set bounds for skin/animation: Automatically calculates bounds by stepping through the specified animation frames. This is the easiest approach as the plugin computes the correct values for you.
• Set bounds for setup pose: Resets bounds to the skeleton's setup pose.
• Set bounds: Manually sets bounds using coordinates and size in Spine skeleton world space. These values can be easily derived from within the Spine Editor.

You can use the On animation event condition with the start event to detect when an animation begins, then call the appropriate bounds action. Use the bounds expressions (BoundsX, BoundsY, BoundsWidth, BoundsHeight) to query the current bounds.

Spine Runtimes API

For advanced use cases not covered by the built-in Actions, Conditions, and Expressions, you can access Spine instances and the full spine-core API directly through Construct 3 scripting.

Accessing a Spine Instance

In a script, you can access a Spine instance through the Construct 3 runtime API:

To iterate over multiple instances of the same Spine object type, use getAllInstances():

Key Properties

Each Spine instance exposes these properties:

The spine Global Object

The spine object is available globally and contains all exports from spine-construct3.

Example: Custom Animation Listener

This example shows how to register callbacks for animation events directly through the API. This is useful when you need more control than the built-in On animation event condition provides.

Example: Procedural Attachment Control

This example shows how to manipulate attachments programmatically. This is useful for dynamically showing or hiding equipment, accessories, or visual effects based on game logic.