UnityMirror/spine-runtimes
1
0
Fork 0
mirror of https://github.com/EsotericSoftware/spine-runtimes.git synced 2026-03-26 22:49:01 +08:00
Code Issues Packages Projects Releases Wiki Activity

[workflows] Fix dart format check workflow - use && instead of &

Browse Source
This commit is contained in:
Mario Zechner 2025-07-31 21:28:31 +02:00
parent 7eb414e2f7
commit 86f888b1fc
6 changed files with 2601 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/format-check-dart.yml vendored
View File

@ -25,4 +25,4 @@ jobs:
- name: Check for changes
run: |
git ls-files -m
if [[ `git ls-files -m` ]]; then echo "Detected Dart formatting errors!" & exit 1; fi
if [[ `git ls-files -m` ]]; then echo "Detected Dart formatting errors!" && exit 1; fi

1011
spine-cpp/docs.md Normal file
View File

File diff suppressed because it is too large Load Diff

595
spine-flutter/docs-new.md Normal file
View File

@ -0,0 +1,595 @@
# spine-flutter Runtime Documentation
> **Licensing**
>
> Please see the [Spine Runtimes License](/spine-runtimes-license) before integrating the Spine Runtimes into your applications.
# Getting Started
The spine-flutter runtime is implemented as a [Flutter FFI plugin](https://docs.flutter.dev/development/packages-and-plugins/developing-packages#plugin-ffi) on top of [spine-cpp](/spine-cpp). It supports all platforms supported by Flutter (desktop, Android, iOS, web), and supports all Spine features except tint black and screen blend mode.
## Installation
spine-flutter is supported from Flutter 3.16.0 onwards. To use spine-flutter in your Flutter project, add the following dependency to your project's `pubspec.yaml` file:
```yaml
dependencies:
...
spine_flutter: ^4.3.0
```
See [spine_flutter on pub.dev](https://pub.dev/packages/spine_flutter) for the latest version.
Ensure that the `major.minor` version of spine-flutter matches the `major.minor` Spine Editor version you are exporting from. See [Spine Versioning](/spine-versioning#Synchronizing-versions) for more information.
In your `main()` function, add these two lines in the beginning to initialize the spine-flutter runtime:
```dart
void main() async {
await initSpineFlutter(enableMemoryDebugging: false);
...
}
```
> **Note:** the `main()` method must be `async`.
## Samples
The spine-flutter runtime includes several samples that showcase its feature set.
You can run the example project following these steps:
1. Install the [Flutter SDK](https://docs.flutter.dev/get-started/install), then run `flutter doctor` which will instruct you what other dependencies to install.
2. Clone the spine-runtimes repository: `git clone https://github.com/esotericsoftware/spine-runtimes`
3. Run the `setup.sh` script in the `spine-flutter/` folder. On Windows, you can use [Git Bash](https://gitforwindows.org/) included in Git for Window to run the `setup.sh` Bash script.
You can then open `spine-flutter` in an IDE or editor of your choice that supports Flutter, like [IntelliJ IDEA/Android Studio](https://docs.flutter.dev/get-started/editor?tab=androidstudio) or [Visual Studio Code](https://docs.flutter.dev/get-started/editor?tab=vscode) to inspect and run the example.
Alternatively, you can run the example from the [command line](https://docs.flutter.dev/get-started/test-drive?tab=terminal).
The example project contains the following examples:
* [`example/lib/simple_animation.dart`](/git/spine-runtimes/spine-flutter/example/lib/simple_animation.dart): demonstrates the basic use of `SpineWidget` and `SpineWidgetController` to load an exported Spine skeleton, display it in the widget, and playback a specific animation.
* [`example/lib/pause_play_animation.dart`](/git/spine-runtimes/spine-flutter/example/lib/pause_play_animation.dart): demonstrates how to pause and resume an animation.
* [`example/lib/animation_state_events.dart`](/git/spine-runtimes/spine-flutter/example/lib/animation_state_events.dart): demonstrates how set a slot's color, how to queue multiple animations, and how to to listen for animation state events.
* [`example/lib/debug_rendering.dart`](/git/spine-runtimes/spine-flutter/example/lib/debug_rendering.dart): shows how to perform custom drawing on top of the rendered skeleton via the `SpineWidgetController` `onAfterPaint` callback.
* [`example/lib/dress_up.dart`](/git/spine-runtimes/spine-flutter/example/lib/dress_up.dart): demonstrates Spine's skins feature as well as rendering a skeleton to a thumbnail for use in a character creation UI.
* [`example/lib/ik_following.dart`](/git/spine-runtimes/spine-flutter/example/lib/ik_following.dart): demonstrates how to let the user drag one of the skeleton's bones via mouse or touch input.
* [`example/lib/physics.dart`](/git/spine-runtimes/spine-flutter/example/lib/physics.dart): demonstrates physics constraints in action.
* [`example/lib/animated_login.dart`](/git/spine-runtimes/spine-flutter/example/lib/animated_login.dart): shows how to integrate spine animations into a login form UI.
* [`example/lib/flame_example.dart`](/git/spine-runtimes/spine-flutter/example/lib/flame_example.dart): demonstrates how to write a simple [Flame](https://flame-engine.org/) component to use spine-flutter with the Flame game engine.
## Updating the spine-flutter Runtime
Before updating your project's spine-flutter runtime, please consult our [guide on Spine editor and runtime version management](/spine-runtime-architecture#Versioning).
To update the spine-flutter runtime, simply modify the version string of the `spine_flutter` package in your `pubspec.yaml`.
> **Note:** If you change the `major.minor` version of the `spine_flutter` package, you have to re-export your Spine skeletons with the same Spine Editor `major.minor` version!
# Using spine-flutter
The spine-flutter runtime is an idiomatic [Dart FFI wrapper](https://dart.dev/guides/libraries/c-interop) around the generic [spine-cpp](/spine-cpp) which supports loading, playback and manipulation of animations created with Spine. The spine-flutter runtime exposes almost all of the spine-cpp API as idiomatic Dart and provides Flutter and [Flame](https://flame-engine.org/) specific classes to easily display and interact with Spine skeletons.
The spine-flutter runtime supports all Spine features except tint black and screen blend mode.
## Asset Management
### Exporting for spine-flutter
![](/img/spine-runtimes-guide/spine-ue4/export.png)
Please follow the instructions in the Spine User Guide on how to
1. [Export skeleton & animation data](/spine-export)
2. [Export texture atlases containing the images of your skeleton](/spine-texture-packer)
An export of the skeleton data and texture atlas of your skeleton will yield the following files:
![](/img/spine-runtimes-guide/spine-ue4/exported-files.png)
1. `skeleton-name.json` or `skeleton-name.skel`, containing your skeleton and animation data.
2. `skeleton-name.atlas`, containing information about the texture atlas.
3. One or more `.png` files, each representing on page of 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.
The files can be loaded via spine-flutter classes like `AtlasFlutter`, `SkeletonDataFlutter`, `SkeletonDrawableFlutter`, `SpineWidget`.
> **Note**: The spine-flutter runtime currently does not support atlases exported using pre-multiplied alpha due to technical limitations in Flutter. Flutter's rendering engine ensures that common non-premultiplied alpha artifacts are avoided.
### 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 replacing the existing files in your Flutter project.
Ensure that the `major.minor` version of spine-flutter matches the `major.minor` Spine Editor version you are exporting from. See [Spine Versioning](/spine-versioning#Synchronizing-versions) for more information.
## Core classes
The spine-flutter API is built on top of the generic [spine-cpp](/spine-cpp) runtime, which provides platform independent core classes and algorithms to load, query, modify, and animate Spine skeletons. The core classes are wrapped via Dart FFI and exposed as idiomatic Dart classes.
Here, we will briefly discuss the most important core classes that you will encounter in your day-to-day use of spine-flutter. Please consult the [Spine Runtimes Guide](/spine-runtimes-guide) for a detailed overview of the Spine Runtimes architecture, core classes, and API usage.
### spine-dart classes
The [`Atlas`](/git/spine-runtimes/spine-flutter/lib/generated/atlas.dart) class stores the data loaded from an `.atlas` file. This is the base class used internally by spine-flutter.
The [`SkeletonData`](/git/spine-runtimes/spine-flutter/lib/generated/skeleton_data.dart) class stores the data loaded from a `.json` or `.skel` skeleton file. The skeleton data contains information about the bone hierarchy, slots, attachments, constraints, skins, and animations. A `SkeletonData` instance is usually loaded by also providing an `Atlas` from which it sources the images to be used by the skeleton it represents. It serves as a blueprint for creating `Skeleton` instances. Multiple skeletons can be instantiated from the same atlas and skeleton data, which then share the loaded data, minimizing both load times and memory consumption at runtime.
The [`Skeleton`](/git/spine-runtimes/spine-flutter/lib/generated/skeleton.dart) class stores an instance of a skeleton, created from a `SkeletonData` instance. A skeleton stores its current pose, that is the position of bones and the current configuration of slots, attachments, and active skin. The current pose can be computed by either manually modifying the bone hierarchy, or, more commonly, by applying animations via an `AnimationState`.
The [`AnimationState`](/git/spine-runtimes/spine-flutter/lib/generated/animation_state.dart) class is responsible for keeping track of which animation(s) should be applied to a skeleton, advancing and mixing those animations based on the elapsed time between the last and current rendering frame, and applying the animations to a skeleton instance, thereby setting its current pose. The `AnimationState` queries an [`AnimationStateData`](/git/spine-runtimes/spine-flutter/lib/generated/animation_state_data.dart) instance to retrieve mixing times between animations, or fetches the default mix time if no mixing time is available for a pair of animations.
### Flutter-specific classes
spine-flutter provides Flutter-specific wrapper classes that handle texture loading, rendering, and lifecycle management:
The [`AtlasFlutter`](/git/spine-runtimes/spine-flutter/lib/spine_flutter.dart#L28) class extends the base `Atlas` class and additionally manages Flutter `Image` objects and `Paint` objects for each atlas page and blend mode. It provides static methods to load atlases from assets, files, or URLs:
```dart
final atlas = await AtlasFlutter.fromAsset("assets/skeleton.atlas");
```
The [`SkeletonDataFlutter`](/git/spine-runtimes/spine-flutter/lib/spine_flutter.dart#L122) class extends the base `SkeletonData` class and provides convenient loading methods that work with `AtlasFlutter`:
```dart
final skeletonData = await SkeletonDataFlutter.fromAsset(atlas, "assets/skeleton.skel");
```
The [`SkeletonDrawableFlutter`](/git/spine-runtimes/spine-flutter/lib/spine_flutter.dart#L304) class extends the base `SkeletonDrawable` and provides Flutter-specific rendering capabilities, including the ability to render to `Canvas`, `PictureRecorder`, PNG, or raw image data.
The spine-flutter runtime builds on top of these core classes.
## SpineWidget
![/img/spine-runtimes-guide/spine-flutter/simple-animation.png](/img/spine-runtimes-guide/spine-flutter/simple-animation.png)
A [`SpineWidget`](/git/spine-runtimes/spine-flutter/lib/spine_widget.dart#L261) is a [StatefulWidget](https://api.flutter.dev/flutter/widgets/StatefulWidget-class.html) responsible for loading and displaying a Spine skeleton. At a minimum, the widget needs to know from where to load the skeleton and atlas files, and it must receive a `SpineWidgetController` instance that is responsible for modifying the state of the widget, such as setting an animation, or changing the skin of the skeleton.
In the simplest case, a `SpineWidget` can be instantiated inside another widget's `build()` method like this:
```dart
@override
Widget build(BuildContext context) {
final controller = SpineWidgetController(onInitialized: (controller) {
// Set the walk animation on track 0, let it loop
controller.animationState.setAnimation(0, "walk", true);
});
return Scaffold(
appBar: AppBar(title: const Text('Simple Animation')),
body: SpineWidget.fromAsset("assets/spineboy.atlas", "assets/spineboy-pro.skel", controller)
);
}
```
Upon instantiation, the `SpineWidget` will asynchronously load the specified files and construct the underlying core class instances from them, namely instances of `AtlasFlutter`, `SkeletonDataFlutter`, `Skeleton`, `AnimationStateData`, and `AnimationState`.
Once loading is complete, the `SpineWidgetController` is called, allowing it to modify the state of the widget, such as setting one or more animations, manipulating the bone hierarchy, or modifying the skin of the skeleton. See the section on `SpineWidgetController` below.
The `SpineWidget` class provides multiple static factory methods to load skeleton and atlas files from different sources:
* `SpineWidget.fromAsset()` loads files from the root bundle, or a provided bundle.
* `SpineWidget.fromFile()` loads files from the file system.
* `SpineWidget.fromHttp()` loads files from URLs.
* `SpineWidget.fromDrawable()` constructs a widget from a `SkeletonDrawableFlutter`. This is useful when the skeleton data should be preloaded, cached, and/or shared between `SpineWidget` instances. See the section "Pre-loading and sharing skeleton data" below.
All factory methods have optional arguments that let you further define how the Spine skeleton is fitted and aligned inside the widget, and how the widget is sized.
* `fit`, the [BoxFit](https://api.flutter.dev/flutter/painting/BoxFit.html) to use to fit the skeleton inside the widget.
* `alignment`, the [Alignment](https://api.flutter.dev/flutter/painting/Alignment-class.html) to use to align the skeleton inside the widget.
* `BoundsProvider`, used to calculate the pixel size of the bounding box to be used for the skeleton when computing the fit and alignment. By default, the skeleton's setup pose bounding box is used. See the class documentation for [`SetupPoseBounds`](/git/spine-runtimes/spine-flutter/lib/spine_widget.dart#L173), [`RawBounds`](/git/spine-runtimes/spine-flutter/lib/spine_widget.dart#L183), and [`SkinAndAnimationBounds`](/git/spine-runtimes/spine-flutter/lib/spine_widget.dart#L196) for additional information.
* `sizedByBounds`, defines whether to size the widgets by the bounds computed by the `BoundsProvider`, or have it sized by its parent widget.
## Pre-loading and sharing skeleton data
Pre-loading allows you to share atlas and skeleton data between multiple `SpineWidget` instances, saving both load time and memory. The key is understanding the ownership parameter when creating drawables.
### Sharing data across multiple widgets
When you want multiple widgets to share the same atlas and skeleton data:
```dart
// Pre-load the atlas and skeleton data once
final atlas = await AtlasFlutter.fromAsset("assets/test.atlas");
final skeletonData = await SkeletonDataFlutter.fromAsset(atlas, "assets/test.skel");
// Create drawables without taking ownership (pass false)
final drawable1 = SkeletonDrawableFlutter(atlas, skeletonData, false);
final drawable2 = SkeletonDrawableFlutter(atlas, skeletonData, false);
// Use in multiple widgets
SpineWidget.fromDrawable(drawable1, controller1);
SpineWidget.fromDrawable(drawable2, controller2);
```
With `ownsAtlasAndSkeletonData: false`, the drawables will NOT dispose the atlas and skeleton data when they are disposed. You must manually manage their lifecycle:
```dart
// Dispose drawables when done
drawable1.dispose();
drawable2.dispose();
// Manually dispose shared data when completely done
skeletonData.dispose();
atlas.dispose();
```
### Single-use with ownership
If you only need one widget and want automatic cleanup:
```dart
final atlas = await AtlasFlutter.fromAsset("assets/test.atlas");
final skeletonData = await SkeletonDataFlutter.fromAsset(atlas, "assets/test.skel");
// Create drawable with ownership (pass true)
final drawable = SkeletonDrawableFlutter(atlas, skeletonData, true);
SpineWidget.fromDrawable(drawable, controller);
// When disposed, this will also dispose atlas and skeletonData
drawable.dispose();
```
## SpineWidgetController
A [`SpineWidgetController`](/git/spine-runtimes/spine-flutter/lib/spine_widget.dart#L64) controls how the skeleton of a `SpineWidget` is animated and rendered. The controller is provided with a set of optional callbacks as constructor arguments, which are called at specific times during the life-time of the `SpineWidget`.
The controller exposes the skeleton state through getters returning Spine Runtimes API objects such as the `AtlasFlutter`, `SkeletonDataFlutter`, `Skeleton`, and `AnimationState`, through which the state can be manipulated. See the [Spine Runtimes Guide](/spine-runtimes-guide), and the [class documentation](/git/spine-runtimes/spine-flutter/lib/generated/api.dart) for more information.
Upon initialization of a `SpineWidget`, the controller's `onInitialized()` callback method is invoked once. This method can be used to setup the initial animation(s) to be played back, or set the skin of the skeleton, among other things.
After initialization is complete, the `SpineWidget` is rendered continuously at the screen refresh rate. Each frame, the `AnimationState` is updated based on the currently queued animations, and applied to the `Skeleton`.
Next, the optional `onBeforeUpdateWorldTransforms()` callback is invoked, which can modify the skeleton before its current pose is calculated using `Skeleton.updateWorldTransform()`.
After the current pose has been calculated, the optional `onAfterUpdateWorldTransforms()` callback is invoked, which can further modify the current pose before the skeleton is rendered. This is a good place to manually position bones.
Before the skeleton is rendered by the `SpineWidget`, the optional `onBeforePaint()` callback is invoked, which allows rendering backgrounds or other objects that should go behind the skeleton on the [`Canvas`](https://api.flutter.dev/flutter/dart-ui/Canvas-class.html).
After the `SpineWidget` has rendered the current skeleton pose to the `Canvas`, the optional `onAfterPaint()` callback is invoked, which allows rendering additional objects on top of the skeleton.
By default, the widget updates and renders the skeleton every frame. The `SpineWidgetController.pause()` method can be used to pause updating and rendering the skeleton. The `SpineWidgetController.resume()` method resumes updating and rendering the skeleton. The `SpineWidgetController.isPlaying()` getter reports the current playback state. See the [`example/lib/pause_play_animation.dart`](/git/spine-runtimes/spine-flutter/example/lib/pause_play_animation.dart) example.
## SkeletonDrawableFlutter
A `SkeletonDrawableFlutter` bundles loading, storing, updating, and rendering a `Skeleton` and its associated `AnimationState` into a single, easy to use class. The class can be used as the basis for a custom widget implementation. The `SpineWidget` encapsulates the state of the skeleton it displays via an instance of a `SkeletonDrawableFlutter`.
Use the static `fromAsset()`, `fromFile()`, or `fromHttp()` methods to construct a `SkeletonDrawableFlutter` from file assets. To share `AtlasFlutter` and `SkeletonDataFlutter` among multiple `SkeletonDrawableFlutter` instances, instantiate the drawables via the constructor, passing the same atlas and skeleton data to each of them.
The `SkeletonDrawableFlutter` exposes the `atlasFlutter`, `skeletonData`, `skeleton`, `animationStateData`, and `animationState` to query, modify, and animate the skeleton.
To animate the skeleton, queue animations on one or more tracks via the `AnimationState` API, such as `AnimationState.setAnimation()` or `AnimationState.addAnimation()`.
To update the animation state, apply it to the skeleton, and update the current skeleton pose, call the `SkeletonDrawableFlutter.update()` method, providing it a delta time in seconds to advance the animations.
To render the current pose of the skeleton, use the rendering methods `SkeletonDrawableFlutter.renderFlutter()`, `SkeletonDrawableFlutter.renderToCanvas()`, `SkeletonDrawableFlutter.renderToPictureRecorder()`, `SkeletonDrawableFlutter.renderToPng()`, or `SkeletonDrawableFlutter.renderToRawImageData()`.
The `SkeletonDrawableFlutter` stores objects allocated on the native heap. The native objects need to be manually disposed of via a call to `SkeletonDrawableFlutter.dispose()` if the `SkeletonDrawableFlutter` is no longer needed. Not doing so will result in a native memory leak.
> **Note:** when using `SpineWidget`, you do not have to manually dispose of the `SkeletonDrawableFlutter` the widget uses. The widget will dispose the `SkeletonDrawableFlutter` when it is disposed itself.
## Applying Animations
Applying animations to a skeleton displayed by a `SpineWidget` is done through the `AnimationState` in the callbacks of a `SpineWidgetController`.
> **Note:** See [Applying Animations](/spine-applying-animations#AnimationState-API) in the Spine Runtimes Guide for more in-depth information, specifically about animation tracks and animation queueing.
To set a specific animation on track 0, call `AnimationState.setAnimation()`:
```dart
final controller = SpineWidgetController(onInitialized: (controller) {
// Set the walk animation on track 0, let it loop
controller.animationState.setAnimation(0, "walk", true);
});
```
The first parameter specifies the track, the second parameter is the name of the animation, and the third parameter defines whether to loop the animation.
You can queue multiple animations:
```dart
controller.animationState.setAnimation(0, "walk", true);
controller.animationState.addAnimation(0, "jump", false, 2);
controller.animationState.addAnimation(0, "run", true, 0);
```
The first parameter to `addAnimation()` is the track. The second parameter is the name of the animation. The third parameter specifies whether to loop the animation. The final parameter defines the delay in seconds, after which this animation should replace the previous animation on the track.
In the example above, the `"walk"` animation is played back first. 2 seconds later, the `"jump"` animation is played back once, followed by a transition to the `"run"` animation, which will be looped.
When transitioning from one animation to another, `AnimationState` will mix the animations for a specificable duration. These mix times are defined in an `AnimationStateData` instance, from which the `AnimationState` retrieves mix times.
The `AnimationStateData` instance is also available through the controller. You can set the default mix time, or the mix time for a specific pair of animations:
```dart
controller.animationStateData.defaultMix = 0.2;
controller.animationStateData.setMix("walk", "jump", 0.1);
```
When setting or adding an animation, a `TrackEntry` object is returned, which allows further modification of that animation's playback. For example, you can set the track entry to reverse the animation playback:
```dart
final entry = controller.animationState.setAnimation(0, "walk", true);
entry.reverse = true;
```
See the [`TrackEntry` class documentation](/git/spine-runtimes/spine-flutter/lib/generated/track_entry.dart) for more options.
> **Note:** Do not hold on to `TrackEntry` instances outside the function you are using them in. Track entries are re-used internally and will thus become invalid once the animation it represents has been completed.
You can set or queue empty animations on an animation track to smoothly reset the skeleton back to its setup pose:
```dart
controller.animationState.setEmptyAnimation(0, 0.5);
controller.animationState.addEmptyAnimation(0, 0.5, 0.5);
```
The first parameter to `setEmptyAnimation()` specifies the track. The second parameter specifies the mix duration in seconds used to mix out the previous animation and mix in the "empty" animation.
The first parameter to `addEmptyAnimation()` specifies the track. The second parameter is the mix duration. The third parameter specifies the delay in seconds, after which the empty animation should replace the previous animation on the track via mixing.
All animations on a track can be cleared immediately via `AnimationState.clearTrack()`. To clear all tracks at once, `AnimationState.clearTracks()` can be used. This will leave the skeleton in the last pose it was in.
To reset the pose of a skeleton to the setup pose, use `Skeleton.setupPose()`:
```dart
controller.skeleton.setupPose();
```
This will reset both the bones and slots to their setup pose configuration. Use `Skeleton.setupPoseSlots()` to only reset the slots to their setup pose configuration.
## AnimationState Events
An `AnimationState` emits events during the life-cycle of an animation that is being played back. You can listen for this events to react as needed. The Spine Runtimes API defines the following [event types](/git/spine-runtimes/spine-flutter/lib/generated/event_type.dart):
* `start`: emitted when an animation is started.
* `interrupt`: emitted when an animation's track was cleared, or a new animation was set.
* `complete`: emitted when an animation completes a loop.
* `end`: emitted when an animation will never be applied again.
* `dispose`: emitted when the animation's track entry is disposed.
* `event`: emitted when a user defined [event](/spine-events#Events) happened.
To receive events, you can register an [`AnimationStateListener`](/git/spine-runtimes/spine-flutter/lib/spine_dart.dart#L229) callback with either the `AnimationState` to receive events across all animations, or with the `TrackEntry` of a specific animation queued for playback:
```dart
final entry = controller.animationState.setAnimation(0, "walk", true);
entry.setListener((type, trackEntry, event) {
if (type == EventType.event) {
print("User defined event: ${event?.data.name}");
}
});
controller.animationState.setListener((type, trackEntry, event) {
print("Animation state event $type");
});
```
See the [`example/lib/animation_state_events.dart`](/git/spine-runtimes/spine-flutter/example/lib/animation_state_events.dart) example.
## Skins
![/img/spine-runtimes-guide/spine-flutter/skins.png](/img/spine-runtimes-guide/spine-flutter/skins.png)
Many applications and games allow users to create custom avatars out of many individual items, such as hair, eyes, pants, or accessories like earrings or bags. With Spine, this can be achieved by [mixing and matching skins](/spine-examples-mix-and-match).
You can create custom skins from other skins like this:
```dart
final data = controller.skeletonData;
final skeleton = controller.skeleton;
final customSkin = Skin("custom-skin");
customSkin.addSkin(data.findSkin("skin-base")!);
customSkin.addSkin(data.findSkin("nose/short")!);
customSkin.addSkin(data.findSkin("eyelids/girly")!);
customSkin.addSkin(data.findSkin("eyes/violet")!);
customSkin.addSkin(data.findSkin("hair/brown")!);
customSkin.addSkin(data.findSkin("clothes/hoodie-orange")!);
customSkin.addSkin(data.findSkin("legs/pants-jeans")!);
customSkin.addSkin(data.findSkin("accessories/bag")!);
customSkin.addSkin(data.findSkin("accessories/hat-red-yellow")!);
skeleton.setSkin2(customSkin);
skeleton.setupPoseSlots();
```
Create a custom skin with the `Skin()` constructor.
Next, fetch the `SkeletonData` from the controller. It is used to look up skins by name via `SkeletonData.findSkin()`.
Add all the skins you want to combine into the new custom skin via `Skin.addSkin()`.
Finally, set the new skin on the `Skeleton` using `Skeleton.setSkin2()` and call `Skeleton.setupPoseSlots()` to ensure no attachments from previous skins and/or animations are left over.
> **Note:** A `Skin` wraps an underlying C++ object. It needs to be manually disposed via a call to `Skin.dispose()` when it is no longer in use.
See the [`example/lib/dress_up.dart`](/git/spine-runtimes/spine-flutter/example/lib/dress_up.dart) example, which also demonstrate how to render thumbnail previews of skins using `SkeletonDrawableFlutter`.
## Setting Bone Transforms
![/img/spine-runtimes-guide/spine-flutter/simple-animation.png](/img/spine-runtimes-guide/spine-flutter/bone-transform.png)
When authoring a skeleton in the Spine Editor, the skeleton is defined in what is called the skeleton coordinate system. This coordinate system may not align with the coordinate system of the `SpineWidget` the skeleton is rendered by. Touch coordinates relative to the `SpineWidget` need thus be converted to the skeleton coordinate system, e.g. if a user should be able to move a bone by touch.
The `SpineWidgetController` offers the method `toSkeletonCoordinates()` which takes an [`Offset`](https://api.flutter.dev/flutter/dart-ui/Offset-class.html) relative to the `SpineWidget` it is associated with, and converts it to the skeleton's coordinate system.
See the [`example/lib/ik_following.dart`](/git/spine-runtimes/spine-flutter/example/lib/ik_following.dart) example.
## Flame Integration
![/img/spine-runtimes-guide/spine-flutter/flame.png](/img/spine-runtimes-guide/spine-flutter/flame.png)
spine-flutter includes an example that shows how to load and renderer Spine skeletons in [Flame Engine](https://flame-engine.org/). See the [`example/lib/flame_example.dart`](/git/spine-runtimes/spine-flutter/example/lib/flame_example.dart) source file.
The example features a simple `SpineComponent` that extends Flame's `PositionComponent`. The `SpineComponent` can be instantiated through the static `SpineComponent.fromAsset()` method, or through the constructor.
The static method can be used as a quick, one-off loading mechanism when the skeleton and atlas data doesn't have to be shared with other components. The example contains a `FlameGame` implementation called `SimpleFlameExample` which demonstrates this simple way of getting a Spine skeleton on screen as part of a Flame game.
Creating a `SpineComponent` via the constructor allows more fine-grained management of the data loading and sharing by taking a `SkeletonDrawableFlutter`. E.g. you can pre-load the skeleton data and atlas, then share it across multiple `SpineComponent` instances. This will both improve memory usage and rendering performance, as data is shared, and rendering can be batched. See the `FlameGame` implementation called `PreloadAndShareSpineDataExample` for an example.
By design, Flame can not know when a component has reached its end of life. However, a `SpineComponent` handles native resources that need to be released at the end of its life. It is thus your responsibility to either call `SpineComponent.dispose()` if a `SpineComponent` is no longer in use. If the `SpineComponent` was constructed from a `SkeletonDrawableFlutter`, you may also have to manually dispose the `SkeletonDataFlutter` and `AtlasFlutter` from which it was constructed, like in the `PreloadAndShareSpineDataExample` example.
# Spine Runtimes API access
spine-flutter maps almost all of the Spine Runtime API to Dart. Objects returned by `SpineWidgetController` or `SkeletonDrawableFlutter`, like `Skeleton` or `AnimationState` are 1:1 translations of the spine-cpp API to Dart. You can thus apply almost all of the materials in the generic [Spine Runtimes Guide](/spine-runtimes-guide) to your Dart code.
Due to the nature of the spine-cpp to Dart FFI bridge, there are some considerations:
* Arrays returned by the API (like `ArrayFloat`, `ArrayInt`) are direct wrappers around native memory. They provide List-like access to the underlying C++ data and modifications through the array's methods will affect the native data.
* You can create bones and slots using their factory constructors (e.g., `Bone(boneData, parent)`, `Slot(slotData, skeleton)`). However, you are responsible for disposing any manually created objects.
* The C++ class hierarchy is fully translated to Dart, including all timeline and constraint classes with proper inheritance relationships and the same nullability patterns as the Java reference implementation.
## Development
This section details the development workflow and architecture of spine-flutter, including code generation, building, and testing.
### Architecture Overview
spine-flutter is built on a multi-layer architecture:
```
┌─────────────────────────────────────────────────────────────┐
│ spine-cpp │
│ Core C++ Spine runtime implementation │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ spine-c │
│ C wrapper API around spine-cpp │
│ (Auto-generated + manual extensions) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ FFI Bindings Layer │
│ Low-level Dart FFI bindings to spine-c │
│ (Generated by Dart's ffigen) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Dart Wrapper Classes │
│ Idiomatic, type-safe Dart API │
│ (Generated by custom codegen) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Flutter Integration Layer │
│ Flutter-specific classes (SpineWidget, rendering) │
│ (Hand-written) │
└─────────────────────────────────────────────────────────────┘
```
### Binding Generation
The binding generation process is automated through the `generate-bindings.sh` script, which orchestrates several steps:
#### 1. Generate spine-c Bindings
First, the spine-c bindings are generated from spine-cpp headers:
```bash
cd ../spine-c && ./build.sh codegen
```
This uses Clang's AST to parse C++ headers and generate:
- C wrapper functions for all spine-cpp classes
- Type information in JSON format
- Header and implementation files
#### 2. Copy Source Files
The `setup.sh` script copies necessary source files:
- spine-cpp sources to `src/spine-cpp/`
- spine-c sources to `src/spine-c/`
- Platform-specific setup for iOS/macOS CocoaPods
#### 3. Generate Dart Bindings
The custom TypeScript-based code generator creates idiomatic Dart wrappers:
```bash
npx tsx codegen/src/index.ts
```
This generates:
- Dart wrapper classes for all Spine types (`lib/generated/*.dart`)
- FFI bindings configuration (`ffigen.yaml`)
- Low-level FFI bindings (`spine_dart_bindings_generated.dart`)
See the [codegen README](codegen/README.md) for detailed information about the code generation architecture.
#### 4. Build Test Library
For headless testing, a native shared library is built:
```bash
cd test && ./build.sh
```
### WASM Compilation
Web platform support requires compiling spine-cpp to WebAssembly:
```bash
./compile-wasm.sh
```
This script:
1. Creates the assets directory structure
2. Compiles all spine-cpp and spine-c sources using Emscripten
3. Generates `libspine_flutter.js` and `libspine_flutter.wasm`
4. Places them in `lib/assets/` for web platform loading
Key Emscripten flags:
- `-O2`: Optimization level that preserves function names
- `--closure 1`: Closure compiler for size optimization
- `-s MODULARIZE=1`: Creates a module-based output
- `-s EXPORT_ALL=1`: Exports all functions for FFI access
- `-s ALLOW_MEMORY_GROWTH=1`: Dynamic memory allocation
### Testing
spine-flutter includes both Flutter widget tests and headless Dart tests:
#### Headless Testing
Pure Dart tests that don't require Flutter:
```bash
cd test
dart headless_test.dart
```
These tests verify:
- Atlas and skeleton data loading
- Core API functionality
- Memory management
- Extension functions
#### Flutter Testing
Widget and integration tests:
```bash
flutter test
```
#### Running Examples
The example app showcases all features:
```bash
cd example
flutter run
```
### Build Scripts
Several utility scripts facilitate development:
- **`setup.sh`**: Prepares the project structure
- Copies spine-cpp sources for native builds
- Sets up iOS/macOS specific files
- Creates necessary directories
- **`clean.sh`**: Cleans all build artifacts
- Removes CocoaPods installations
- Cleans Flutter dependencies
- Deletes generated files
- Useful for resolving build issues
- **`generate-bindings.sh`**: Complete binding generation
- Runs spine-c code generation
- Executes Dart code generation
- Builds test libraries
- **`compile-wasm.sh`**: Web platform compilation
- Compiles C++ to WebAssembly
- Generates JavaScript module
> **Note:** On Windows, use [Git Bash](https://gitforwindows.org/) to run these bash scripts.
### Code Generation Details
The code generation system is central to spine-flutter's maintainability. For detailed information about:
- How C++ types are transformed to Dart
- Nullability handling
- RTTI-based type instantiation
- Method overloading resolution
- Extension system architecture
Please refer to the comprehensive [codegen README](codegen/README.md).
### Contributing
When contributing to spine-flutter:
1. **Core API changes**: Modify spine-cpp, then regenerate bindings
2. **Extension functions**: Add to spine-c `extensions.h/.cpp`, then wrap in `spine_dart.dart`
3. **Flutter integration**: Modify Flutter-specific classes in `lib/`
4. **Examples**: Add to the example app to showcase new features
Always run the full test suite and ensure examples work on all platforms before submitting changes.

370
spine-flutter/docs.md Normal file
View File

@ -0,0 +1,370 @@
# spine-flutter Runtime Documentation
> **Licensing**
>
> Please see the [Spine Runtimes License](/spine-runtimes-license) before integrating the Spine Runtimes into your applications.
# Getting Started
The spine-flutter runtime is implemented as a [Flutter FFI plugin](https://docs.flutter.dev/development/packages-and-plugins/developing-packages#plugin-ffi) on top of [spine-cpp](/spine-cpp). It supports all platforms supported by Flutter (desktop, Android, iOS, web), and supports all Spine features except tint black and screen blend mode.
## Installation
spine-flutter is supported from Flutter 3.10.5 onwards. To use spine-flutter in your Flutter project, add the following dependency to your project's `pubspec.yaml` file:
```yaml
dependencies:
...
spine_flutter: ^4.2.36
```
See [spine_flutter on pub.dev](https://pub.dev/packages/spine_flutter) for the latest version.
Ensure that the `major.minor` version of spine-flutter matches the `major.minor` Spine Editor version you are exporting from. See [Spine Versioning](/spine-versioning#Synchronizing-versions) for more information.
In your `main()` function, add these two lines in the beginning to initialize the spine-flutter runtime:
```dart
void main() async {
await initSpineFlutter(enableMemoryDebugging: false);
...
}
```
> **Note:** the `main()` method must be `async`.
## Samples
The spine-flutter runtime includes several samples that showcase its feature set.
You can run the example project following these steps:
1. Install the [Flutter SDK](https://docs.flutter.dev/get-started/install), then run `flutter doctor` which will instruct you what other dependencies to install.
2. Clone the spine-runtimes repository: `git clone https://github.com/esotericsoftware/spine-runtimes`
3. Run the `setup.sh` script in the `spine-flutter/` folder. On Windows, you can use [Git Bash](https://gitforwindows.org/) included in Git for Window to run the `setup.sh` Bash script.
You can then open `spine-flutter` in an IDE or editor of your choice that supports Flutter, like [IntelliJ IDEA/Android Studio](https://docs.flutter.dev/get-started/editor?tab=androidstudio) or [Visual Studio Code](https://docs.flutter.dev/get-started/editor?tab=vscode) to inspect and run the example.
Alternatively, you can run the example from the [command line](https://docs.flutter.dev/get-started/test-drive?tab=terminal).
The example project contains the following examples:
* [`example/lib/simple_animation.dart`](/git/spine-runtimes/spine-flutter/example/lib/simple_animation.dart): demonstrates the basic use of `SpineWidget` and `SpineWidgetController` to load an exported Spine skeleton, display it in the widget, and playback a specific animation.
* [`example/lib/pause_play_animation.dart`](/git/spine-runtimes/spine-flutter/example/lib/pause_play_animation.dart): demonstrates how to pause and resume an animation.
* [`example/lib/animation_state_events`](/git/spine-runtimes/spine-flutter/example/lib/animation_state_events.dart): demonstrates how set a slot's color, how to queue multiple animations, and how to to listen for animation state events.
* [`example/lib/debug_rendering.dart`](/git/spine-runtimes/spine-flutter/example/lib/debug_rendering.dart): shows how to perform custom drawing on top of the rendered skeleton via the `SpineWidgetController` `onAfterPaint` callback.
* [`example/lib/dress_up.dart`](/git/spine-runtimes/spine-flutter/example/lib/dress_up.dart): demonstrates Spine's skins feature as well as rendering a skeleton to a thumbnail for use in a character creation UI.
* [`example/lib/ik_following.dart`](/git/spine-runtimes/spine-flutter/example/lib/ik_following.dart): demonstrates how to let the user drag one of the skeleton's bones via mouse or touch input.
* [`example/lib/flame_example.dart`](/git/spine-runtimes/spine-flutter/example/lib/flame_example.dart): demonstrates how to write a simple [Flame](https://flame-engine.org/) component to use spine-flutter with the Flame game engine.
## Updating the spine-flutter Runtime
Before updating your project's spine-flutter runtime, please consult our [guide on Spine editor and runtime version management](/spine-runtime-architecture#Versioning).
To update the spine-flutter runtime, simply modify the version string of the `spine_flutter` package in your `pubspec.yaml`.
> **Note:** If you change the `major.minor` version of the `spine_flutter` package, you have to re-export your Spine skeletons with the same Spine Editor `major.minor` version!
# Using spine-flutter
The spine-flutter runtime is an idiomatic [Dart FFI wrapper](https://dart.dev/guides/libraries/c-interop) around the generic [spine-cpp](/spine-cpp) which supports loading, playback and manipulation of animations created with Spine. The spine-flutter runtime exposes almost all of the spine-cpp API as idiomatic Dart and provides Flutter and [Flame](https://flame-engine.org/) specific classes to easily display and interact with Spine skeletons.
The spine-flutter runtime supports all Spine features except tint black and screen blend mode.
## Asset Management
### Exporting for spine-flutter
![](/img/spine-runtimes-guide/spine-ue4/export.png)
Please follow the instructions in the Spine User Guide on how to
1. [Export skeleton & animation data](/spine-export)
2. [Export texture atlases containing the images of your skeleton](/spine-texture-packer)
An export of the skeleton data and texture atlas of your skeleton will yield the following files:
![](/img/spine-runtimes-guide/spine-ue4/exported-files.png)
1. `skeleton-name.json` or `skeleton-name.skel`, containing your skeleton and animation data.
2. `skeleton-name.atlas`, containing information about the texture atlas.
3. One or more `.png` files, each representing on page of 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.
The files can be loaded via spine-flutter classes like `Atlas`, `SkeletonData`, `SkeletonDrawable`, `SpineWidget`.
> **Note**: The spine-flutter runtime currently does not support atlases exported using pre-multiplied alpha due to technical limitations in Flutter. Flutter's rendering engine ensures that common non-premultiplied alpha artifacts are avoided.
### 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 replacing the existing files in your Flutter project.
Ensure that the `major.minor` version of spine-flutter matches the `major.minor` Spine Editor version you are exporting from. See [Spine Versioning](/spine-versioning#Synchronizing-versions) for more information.
## Core classes
The spine-flutter API is built on top of the generic [spine-cpp](/spine-cpp) runtime, which provides platform independent core classes and algorithms to load, query, modify, and animate Spine skeletons. The core classes are wrapped via Dart FFI and exposed as idiomatic Dart classes.
Here, we will briefly discuss the most important core classes that you will encounter in your day-to-day use of spine-flutter. Please consult the [Spine Runtimes Guide](/spine-runtimes-guide)
for a detailed overview of the Spine Runtimes architecture, core classes, and API usage.
The [`Atlas`](/git/spine-runtimes/spine-flutter/lib/spine_flutter.dart#L102) class stores the data loaded from an `.atlas` file and its corresponding `.png` image files.
The [`SkeletonData`](/git/spine-runtimes/spine-flutter/lib/spine_flutter.dart#L199) class stores the data loaded from a `.json` or `.skel` skeleton file. The skeleton data contains information about the bone hierarchy, slots, attachments, constraints, skins, and animations. A `SkeletonData` instance is usually loaded by also providing an `Atlas` from which it sources the images to be used by the skeleton it represents. It serves as a blueprint for creating `Skeleton` instances. Multiple skeletons can be instantiated from the same atlas and skeleton data, which then share the loaded data, minimizing both load times and memory consumption at runtime.
The [`Skeleton`](/git/spine-runtimes/spine-flutter/lib/spine_flutter.dart#L2734) class stores an instance of a skeleton, created from a `SkeletonData` instance. A skeleton stores its current pose, that is the position of bones and the current configuration of slots, attachments, and active skin. The current pose can be computed by either manually modifying the bone hierarchy, or, more commonly, by applying animations via an `AnimationState`.
The [`AnimationState`](/git/spine-runtimes/spine-flutter/lib/spine_flutter.dart#L3663) class is responsible for keeping track of which animation(s) should be applied to a skeleton, advancing and mixing those animations based on the elapsed time between the last and current rendering frame, and applying the animations to a skeleton instance, thereby setting its current pose. The `AnimationState` queries an [`AnimationStateData`](/git/spine-runtimes/spine-flutter/lib/spine_flutter.dart#L3600) instance to retrieve mixing times between animations, or fetches the default mix time if no mixing time is available for a pair of animations.
The spine-flutter runtime builds on top of these core classes.
## SpineWidget
![/img/spine-runtimes-guide/spine-flutter/simple-animation.png](/img/spine-runtimes-guide/spine-flutter/simple-animation.png)
A [`SpineWidget`](/git/spine-runtimes/spine-flutter/lib/spine_widget.dart#L261) is a [StatefulWidget](https://api.flutter.dev/flutter/widgets/StatefulWidget-class.html) responsible for loading and displaying a Spine skeleton. At a minimum, the widget needs to know from where to load the skeleton and atlas files, and it must receive a `SpineWidgetController` instance that is responsible for modifying the state of the widget, such as setting an animation, or changing the skin of the skeleton.
In the simplest case, a `SpineWidget` can be instantiated inside another widget's `build()` method like this:
```dart
@override
Widget build(BuildContext context) {
final controller = SpineWidgetController(onInitialized: (controller) {
// Set the walk animation on track 0, let it loop
controller.animationState.setAnimationByName(0, "walk", true);
});
return Scaffold(
appBar: AppBar(title: const Text('Simple Animation')),
body: SpineWidget.fromAsset("assets/spineboy.atlas", "assets/spineboy-pro.skel", controller)
);
}
```
Upon instantiation, the `SpineWidget` will asynchronously load the specified files and construct the underlying core class instances from them, namely instances of `Atlas`, `SkeletonData`, `Skeleton`, `AnimationStateData`, and `AnimationState`.
Once loading is complete, the `SpineWidgetController` is called, allowing it to modify the state of the widget, such as setting one or more animations, manipulating the bone hierarchy, or modifying the skin of the skeleton. See the section on `SpineWidgetController` below.
The `SpineWidget` class provides multiple static factory methods to load skeleton and atlas files from different sources:
* `SpineWidget.fromAsset()` loads files from the root bundle, or a provided bundle.
* `SpineWidget.fromFile()` loads files from the file system.
* `SpineWidget.fromHttp()` loads files from URLs.
* `SpineWidget.fromDrawable()` constructs a widget from a `SkeletonDrawable`. This is useful when the skeleton data should be preloaded, cached, and/or shared between `SpineWidget` instances. See the section "Pre-loading and sharing skeleton data" below.
All factory methods have optional arguments that let you further define how the Spine skeleton is fitted and aligned inside the widget, and how the widget is sized.
* `fit`, the [BoxFit](https://api.flutter.dev/flutter/painting/BoxFit.html) to use to fit the skeleton inside the widget.
* `alignment`, the [Alignment](https://api.flutter.dev/flutter/painting/Alignment-class.html) to use to align the skeleton inside the widget.
* `BoundsProvider`, used to calculate the pixel size of the bounding box to be used for the skeleton when computing the fit and alignment. By default, the skeleton's setup pose bounding box is used. See the class documentation for [`SetupPoseBounds`](/git/spine-runtimes/spine-flutter/lib/spine_widget.dart#L173), [`RawBounds`](/git/spine-runtimes/spine-flutter/lib/spine_widget.dart#L183), and [`SkinAndAnimationBounds`](/git/spine-runtimes/spine-flutter/lib/spine_widget.dart#L196) for additional information.
* `sizedByBounds`, defines whether to size the widgets by the bounds computed by the `BoundsProvider`, or have it sized by its parent widget.
## Pre-loading and sharing skeleton data
If you want to share the atlas and skeleton data between multiple `SpineWidget` instances, you can manually pre-load the assets:
```
final atlas = await Atlas.fromAsset("assets/test.atlas");
final skeletonData = await SkeletonData.fromAsset("assets/test.json", atlas);
```
You can then instantiate one or more `SpineWidget` instances from the same data, saving on load time and memory:
```
SpineWidget.fromDrawable(SkeletonDrawable(skeletonData, atlas));
```
You are responsible for disposing of the atlas and skeleton data one no `SpineWidget` (or `SkeletonDrawable`) refercing them exists anymore.
```
skeletonData.dispose();
atlas.dispose();
```
## SpineWidgetController
A [`SpineWidgetController`](/git/spine-runtimes/spine-flutter/lib/spine_widget.dart#L64) controls how the skeleton of a `SpineWidget` is animated and rendered. The controller is provided with a set of optional callbacks as constructor arguments, which are called at specific times during the life-time of the `SpineWidget`.
The controller exposes the skeleton state through getters returning Spine Runtimes API objects such as the `Atlas`, `SkeletonData`, `Skeleton`, and `AnimationState`, through which the state can be manipulated. See the [Spine Runtimes Guide](/spine-runtimes-guide), and the [class documentation](/git/spine-runtimes/spine-flutter/lib/spine_flutter.dart) for more information.
Upon initialization of a `SpineWidget`, the controller's `onInitialized()` callback method is invoked once. This method can be used to setup the initial animation(s) to be played back, or set the skin of the skeleton, among other things.
After initialization is complete, the `SpineWidget` is rendered continuously at the screen refresh rate. Each frame, the `AnimationState` is updated based on the currently queued animations, and applied to the `Skeleton`.
Next, the optional `onBeforeUpdateWorldTransforms()` callback is invoked, which can modify the skeleton before its current pose is calculated using `Skeleton.updateWorldTransform()`.
After the current pose has been calculated, the optional `onAfterUpdateWorldTransforms()` callback is invoked, which can further modify the current pose before the skeleton is rendered. This is a good place to manually position bones.
Before the skeleton is rendered by the `SpineWidget`, the optional `onBeforePaint()` callback is invoked, which allows rendering backgrounds or other objects that should go behind the skeleton on the [`Canvas`](https://api.flutter.dev/flutter/dart-ui/Canvas-class.html).
After the `SpineWidget` has rendered the current skeleton pose to the `Canvas`, the optional `onAfterPaint()` callback is invoked, which allows rendering additional objects on top of the skeleton.
By default, the widget updates and renders the skeleton every frame. The `SpineWidgetController.pause()` method can be used to pause updating and rendering the skeleton. The `SpineWidgetController.resume()` method resumes updating and rendering the skeleton. The `SpineWidgetController.isPlaying()` getter reports the current playback state. See the [`example/lib/animation_state_events.dart`](/git/spine-runtimes/spine-flutter/example/lib/animation_state_events.dart) example.
## SkeletonDrawable
A `SkeletonDrawable` bundles loading, storing, updating, and rendering a `Skeleton` and its associated `AnimationState` into a single, easy to use class. The class can be used as the basis for a custom widget implementation. The `SpineWidget` encapsulates the state of the skeleton it displays via an instance of a `SkeletonDrawable`.
Use the `fromAsset()`, `fromFile()`, or `fromHttp()` methods to construct a `SkeletonDrawable` from file assets. To share `Atlas` and `SkeletonData` among multiple `SkeletonDrawable` instances, instantiate the drawables via the constructor, passing the same atlas and skeleton data to each of them.
The `SkeletonDrawable` exposes the `Skeleton` and `AnimationState` to query, modify, and animate the skeleton. It also exposes the `Atlas` and `SkeletonData` from which the skeleton and animation state have been constructed.
To animate the skeleton, queue animations on one or more tracks via the `AnimationState` API, such as `AnimationState.setAnimation()` or `AnimationState.addAnimation()`.
To update the animation state, apply it to the skeleton, and update the current skeleton pose, call the `SkeletonDrawable.update()` method, providing it a delta time in seconds to advance the animations.
To render the current pose of the skeleton, use the rendering methods `SkeletonDrawable.render()`, `SkeletonDrawable.renderToCanvas()`, `SkeletonDrawable.renderToPictureRecorder()`, `SkeletonDrawable.renderToPng()`, or `SkeletonDrawable.renderToRawImageData()`.
The `SkeletonDrawable` stores objects allocated on the native heap. The native objects need to be manually disposed of via a call to `SkeletonDrawable.dispose()` if the `SkeletonDrawable` is no longer needed. Not doing so will result in a native memory leak.
> **Note:** when using `SpineWidget`, you do not have to manually dispose of the `SkeletonDrawable` the widget uses. The widget will dispose the `SkeletonDrawable` when it is disposed itself.
## Applying Animations
Applying animations to a skeleton displayed by a `SpineWidget` is done through the `AnimationState` in the callbacks of a `SpineWidgetController`.
> **Note:** See [Applying Animations](/spine-applying-animations#AnimationState-API) in the Spine Runtimes Guide for more in-depth information, specifically about animation tracks and animation queueing.
To set a specific animation on track 0, call `AnimationState.setAnimation()`:
```dart
final controller = SpineWidgetController(onInitialized: (controller) {
// Set the walk animation on track 0, let it loop
controller.animationState.setAnimationByName(0, "walk", true);
});
```
The first parameter specifies the track, the second parameter is the name of the animation, and the third parameter defines whether to loop the animation.
You can queue multiple animations:
```dart
controller.animationState.setAnimationByName(0, "walk", true);
controller.animationState.addAnimationByName(0, "jump", false, 2);
controller.animationState.addAnimationByName(0, "run", true, 0);
```
The first parameter to `addAnimationByName()` is the track. The second parameter is the name of the animation. The third parameter specifies the delay in seconds, after which this animation should replace the previous animation on the track. The final parameter defines whether to loop the animation.
In the example above, the `"walk"` animation is played back first. 2 seconds later, the `"jump"` animation is played back once, followed by a transition to the `"run"` animation, which will be looped.
When transitioning from one animation to another, `AnimationState` will mix the animations for a specificable duration. These mix times are defined in an `AnimationStateData` instance, from which the `AnimationState` retrieves mix times.
The `AnimationStateData` instance is also available through the controller. You can set the default mix time, or the mix time for a specific pair of animations:
```dart
controller.animationStateData.setDefaultMix(0.2);
controller.animationStateData.setMixByName("walk", "jump", 0.1);
```
When setting or adding an animation, a `TrackEntry` object is returned, which allows further modification of that animation's playback. For example, you can set the track entry to reverse the animation playback:
```dart
final entry = controller.animationState.setAnimationByName(0, "walk", true);
entry.setReverse(true);
```
See the [`TrackEntry` class documentation](/git/spine-runtimes/spine-flutter/lib/spine_flutter.dart#L3100) for more options.
> **Note:** Do not hold on to `TrackEntry` instances outside the function you are using them in. Track entries are re-used internally and will thus become invalid once the animation it represents has been completed.
You can set or queue empty animations on an animation track to smoothly reset the skeleton back to its setup pose:
```dart
controller.animationState.setEmptyAnimation(0, 0.5);
controller.animationState.addEmptyAnimation(0, 0.5, 0.5);
```
The first parameter to `setEmptyAnimation()` specifies the track. The second parameter specifies the mix duration in seconds used to mix out the previous animation and mix in the "empty" animation.
The first parameter to `addEmptyAnimation()` specifies the track. The second parameter specifies the mix duration. The third parameter is the delay in seconds, after which the empty animation should replace the previous animation on the track via mixing.
All animations on a track can be cleared immediately via `AnimationState.clearTrack()`. To clear all tracks at once, `AnimationState.clearTracks()` can be used. This will leave the skeleton in the last pose it was in.
To reset the pose of a skeleton to the setup pose, use `Skeleton.setToSetupPose()`:
```dart
controller.skeleton.setToSetupPose();
```
This will reset both the bones and slots to their setup pose configuration. Use `Skeleton.setSlotsToSetupPose()` to only reset the slots to their setup pose configuration.
## AnimationState Events
An `AnimationState` emits events during the life-cycle of an animation that is being played back. You can listen for this events to react as needed. The Spine Runtimes API defines the following [event types](/git/spine-runtimes/spine-flutter/lib/spine_flutter.dart#L3429):
* `Start`: emitted when an animation is started.
* `Interrupted`: emitted when an animation's track was cleared, or a new animation was set.
* `Completed`: emitted when an animation completes a loop.
* `Ended`: emitted when an animation will never be applied again.
* `Disposed`: emitted when the animation's track entry is disposed.
* `Event`: emitted when a user defined [event](/spine-events#Events) happened.
To receive events, you can register an [`AnimationStateListener`](/git/spine-runtimes/spine-flutter/lib/spine_flutter.dart#L3597) callback with either the `AnimationState` to receive events across all animations, or with the `TrackEntry` of a specific animation queued for playback:
```dart
final entry = controller.animationState.setAnimationByName(0, "walk", true);
entry.setListener((type, trackEntry, event) {
if (type == EventType.event) {
print("User defined event: ${event?.getData().getName()}");
}
});
controller.animationState.setListener((type, trackEntry, event) {
print("Animation state event $type");
});
```
See the [`example/lib/animation_state_events.dart`](/git/spine-runtimes/spine-flutter/example/lib/animation_state_events.dart) example.
## Skins
![/img/spine-runtimes-guide/spine-flutter/skins.png](/img/spine-runtimes-guide/spine-flutter/skins.png)
Many applications and games allow users to create custom avatars out of many individual items, such as hair, eyes, pants, or accessories like earrings or bags. With Spine, this can be achieved by [mixing and matching skins](/spine-examples-mix-and-match).
You can create custom skins from other skins like this:
```dart
final data = controller.skeletonData;
final skeleton = controller.skeleton;
final customSkin = Skin("custom-skin");
customSkin.addSkin(data.findSkin("skin-base")!);
customSkin.addSkin(data.findSkin("nose/short")!);
customSkin.addSkin(data.findSkin("eyelids/girly")!);
customSkin.addSkin(data.findSkin("eyes/violet")!);
customSkin.addSkin(data.findSkin("hair/brown")!);
customSkin.addSkin(data.findSkin("clothes/hoodie-orange")!);
customSkin.addSkin(data.findSkin("legs/pants-jeans")!);
customSkin.addSkin(data.findSkin("accessories/bag")!);
customSkin.addSkin(data.findSkin("accessories/hat-red-yellow")!);
skeleton.setSkin(customSkin);
skeleton.setSlotsToSetupPose();
```
Create a custom skin with the `Skin()` constructor.
Next, fetch the `SkeletonData` from the controller. It is used to look up skins by name via `SkeletonData.findSkin()`.
Add all the skins you want to combine into the new custom skin via `Skin.addSkin()`.
Finally, set the new skin on the `Skeleton` and call `Skeleton.setSlotsToSetupPose()` to ensure no attachments from previous skins and/or animations are left over.
> **Note:** A `Skin` wraps an underlying C++ object. It needs to be manually disposed via a call to `Skin.dispose()` when it is no longer in use.
See the [`example/lib/dress_up.dart`](/git/spine-runtimes/spine-flutter/example/lib/dress_up.dart) example, which also demonstrate how to render thumbnail previews of skins using `SkeletonDrawable`.
## Setting Bone Transforms
![/img/spine-runtimes-guide/spine-flutter/simple-animation.png](/img/spine-runtimes-guide/spine-flutter/bone-transform.png)
When authoring a skeleton in the Spine Editor, the skeleton is defined in what is called the skeleton coordinate system. This coordinate system may not align with the coordinate system of the `SpineWidget` the skeleton is rendered by. Touch coordinates relative to the `SpineWidget` need thus be converted to the skeleton coordinate system, e.g. if a user should be able to move a bone by touch.
The `SpineWidgetController` offers the method `toSkeletonCoordinates()` which takes an [`Offset`](https://api.flutter.dev/flutter/dart-ui/Offset-class.html) relative to the `SpineWidget` it is associated with, and converts it to the skeleton's coordinate system.
See the [`example/lib/ik_following.dart`](/git/spine-runtimes/spine-flutter/example/lib/ik_following.dart) example.
## Flame Integration
![/img/spine-runtimes-guide/spine-flutter/flame.png](/img/spine-runtimes-guide/spine-flutter/flame.png)
spine-flutter includes an example that shows how to load and renderer Spine skeletons in [Flame Engine](https://flame-engine.org/). See the [`example/lib/flame_example.dart`](/git/spine-runtimes/spine-flutter/example/lib/flame_example.dart) source file.
The example features a simple `SpineComponent` that extends Flame's `PositionComponent`. The `SpineComponent` can be instantiated through the static `SpineComponent.fromAsset()` method, or through the constructor.
The static method can be used as a quick, one-off loading mechanism when the skeleton and atlas data doesn't have to be shared with other components. The example contains a `FlameGame` implementation called `SimpleFlameExample` which demonstrates this simple way of getting a Spine skeleton on screen as part of a Flame game.
Creating a `SpineComponent` via the constructor allows more fine-grained management of the data loading and sharing by taking a `SkeletonDrawable`. E.g. you can pre-load the skeleton data and atlas, then share it across multiple `SpineComponent` instances. This will both improve memory usage and rendering performance, as data is shared, and rendering can be batched. See the `FlameGame` implementation called `PreloadAndShareSpineDataExample` for an example.
By design, Flame can not know when a component has reached its end of life. However, a `SpineComponent` handles native resources that need to be released at the end of its life. It is thus your responsibility to either call `SpineComponent.dispose()` if a `SpineComponent` is no longer in use. If the `SpineComponent` was constructed from a `SkeletonDrawable`, you may also have to manually dispose the `SkeletonData` and `Atlas` from which it was constructed, like in the `PreloadAndShareSpineDataExample` example.
# Spine Runtimes API access
spine-flutter maps almost all of the Spine Runtime API to Dart. Objects returned by `SpineWidgetController` or `SkeletonDrawable`, like `Skeleton` or `AnimationState` are 1:1 translations of the spine-cpp API to Dart. You can thus apply almost all of the materials in the generic [Spine Runtimes Guide](/spine-runtimes-guide) to your Dart code.
Due to the nature of the spine-cpp to Dart FFI bridge, there are however a few limitations:
* Any returned array or map is a copy of the internal array. Modification will not have an effect. However, returned `Float32List` or `Int32List` instances are wrappers around the underlying native memory, and can thus be used to modify the native data.
* You can not create, add or remove bones, slots, and other Spine objects directly.
* The C++ class hierarchies of timelines are not exposed in Dart.

548
todos/work/2025-07-31-16-50-17-generate-swift-bindings/analysis.md Normal file
View File

@ -0,0 +1,548 @@
# Swift Bindings Generator Analysis
## spine-c Codegen System Analysis
### Purpose and Architecture of the spine-c Codegen System
The spine-c codegen system is a sophisticated TypeScript-based code generator that automatically creates a complete C wrapper API for the Spine C++ runtime. Its primary purpose is to:
1. **Automatic API Wrapping**: Parse spine-cpp headers using Clang's AST and generate a systematic C API with opaque types
2. **Multi-language Binding Support**: Build inheritance maps and interface information to support binding generation for languages like Dart, Swift, Java, and others
3. **Type Safety and Consistency**: Apply systematic type conversion rules and extensive validation to ensure correctness
#### Architecture Overview
The system follows a **multi-stage pipeline architecture**:
1. **Type Extraction** - Uses Clang's `-ast-dump=json` to parse C++ headers
2. **Type Processing** - Filters and validates extracted types
3. **Validation** - Extensive checks for conflicts and unsupported patterns
4. **Array Scanning** - Detects and generates specialized array types
5. **IR Generation** - Converts C++ types to C intermediate representation
6. **Code Writing** - Generates header and implementation files
7. **Inheritance Analysis** - Builds inheritance maps for multi-language bindings
### Structure of Types Available from generate()
The `generate()` method returns a comprehensive data structure containing:
```typescript
{
cTypes, // Generated C wrapper types for classes
cEnums, // Generated C enum types
cArrayTypes, // Specialized array types (Array<T> → spine_array_T)
inheritance, // extends/implements map for single-inheritance languages
supertypes, // Legacy RTTI supertypes map
subtypes, // Legacy RTTI subtypes map
isInterface // Pure interface detection map
}
```
#### Key Type Definitions
From `types.ts`, the system defines several core interfaces:
- **ClassOrStruct**: Represents C++ classes/structs with members, inheritance, template info
- **Method**: Method definitions with parameters, virtuality, const-ness
- **Field**: Public fields with type and location information
- **Constructor/Destructor**: Special member functions
- **Enum**: Enumeration types with values
- **ArraySpecialization**: Specialized array type information
### Information Extracted from C Headers
The system extracts comprehensive information from spine-cpp headers:
#### Class/Struct Information:
- **Members**: All public methods, fields, constructors, destructors
- **Inheritance**: Supertype relationships and template inheritance
- **Properties**: Abstract status, template parameters, virtual methods
- **Location**: File and line number information for each member
#### Method Details:
- **Signatures**: Return types, parameter types and names
- **Modifiers**: Static, virtual, pure virtual, const qualifiers
- **Inheritance**: Which supertype the method comes from
#### Type Analysis:
- **Template Detection**: Identifies and handles template types
- **Interface Classification**: Distinguishes pure interfaces from concrete classes
- **Inheritance Mapping**: Builds complete inheritance hierarchies
#### Validation Information:
- **Conflict Detection**: Const/non-const method conflicts
- **Type Support**: Multi-level pointers, unsupported patterns
- **Name Conflicts**: Method/type name collisions
### How This Information Can Be Used for Generating Bindings
The extracted information enables sophisticated binding generation for multiple target languages:
#### 1. **Type System Mapping**
- **Opaque Types**: C++ classes become opaque pointers (`Skeleton*` → `spine_skeleton`)
- **Primitive Passthrough**: Direct mapping for int, float, bool, etc.
- **Special Conversions**: `String` → `const char*`, `PropertyId` → `int64_t`
- **Array Specializations**: `Array<T>` → `spine_array_T` with full CRUD operations
#### 2. **Inheritance Support**
The inheritance maps enable proper class hierarchies in target languages:
- **Single Inheritance**: `extends` relationships for concrete parent classes
- **Interface Implementation**: `mixins` for pure interface types
- **Conflict Detection**: Prevents multiple concrete inheritance (unsupported in many languages)
#### 3. **Memory Management**
- **Constructor Wrapping**: Generates `spine_type_create()` functions
- **Destructor Wrapping**: Generates `spine_type_dispose()` functions
- **RTTI Support**: Maintains Spine's custom RTTI system for type checking
#### 4. **Method and Field Access**
- **Method Wrapping**: `Class::method()` → `spine_class_method()`
- **Field Accessors**: Automatic getter/setter generation for public fields
- **Parameter Marshaling**: Proper conversion between C++ and C calling conventions
#### 5. **Language-Specific Features**
- **Nullability**: Identifies nullable pointer types vs non-null references
- **Array Operations**: Complete CRUD operations for specialized array types
- **Enum Conversion**: Systematic enum name conversion with prefixes
#### 6. **Validation and Safety**
The extensive validation ensures generated bindings are safe and correct:
- **Type Safety**: Prevents unsupported type patterns
- **Name Conflicts**: Ensures no function name collisions
- **Interface Compliance**: Verifies inheritance patterns work in target languages
This comprehensive system allows binding generators for languages like Dart, Swift, Java, etc. to automatically create type-safe, idiomatic APIs that properly expose the full Spine C++ functionality while respecting each language's conventions and constraints.
## Dart Codegen Implementation Analysis
Based on my analysis of the Dart codegen implementation in spine-flutter, here's a comprehensive breakdown of how it works and the patterns that would be applicable to Swift:
### **1. Architecture Overview**
The Dart codegen follows a clean layered architecture:
1. **Input**: Uses the `generate()` function from spine-c's codegen to get the C Intermediate Representation (CIR)
2. **Transform**: Converts CIR to clean Dart model using `DartWriter`
3. **Generate**: Creates idiomatic Dart code from the model
4. **Output**: Writes individual files plus arrays and exports
### **2. How It Uses the generate() Output**
From `/Users/badlogic/workspaces/spine-runtimes/spine-flutter/codegen/src/index.ts`:
```typescript
const { cTypes, cEnums, cArrayTypes, inheritance, supertypes, subtypes, isInterface } = await generate();
```
The codegen consumes:
- **cTypes**: All C wrapper types with nullability information
- **cEnums**: Enum definitions
- **cArrayTypes**: Array specializations
- **inheritance**: Extends/implements relationships
- **isInterface**: Map of which types are pure interfaces
- **supertypes**: Type hierarchy for RTTI-based instantiation
### **3. Type Hierarchy and Inheritance Handling**
The implementation elegantly handles complex inheritance:
#### **Concrete Classes** (like `Skeleton`)
```dart
class Skeleton {
final Pointer<spine_skeleton_wrapper> _ptr;
Skeleton.fromPointer(this._ptr);
Pointer get nativePtr => _ptr;
// ... methods
}
```
#### **Abstract Classes** (like `Attachment`)
```dart
abstract class Attachment {
final Pointer<spine_attachment_wrapper> _ptr;
Attachment.fromPointer(this._ptr);
Pointer get nativePtr => _ptr;
// ... concrete methods with RTTI switching
}
```
#### **Interfaces** (like `Constraint`)
```dart
abstract class Constraint implements Update {
@override
Pointer get nativePtr;
ConstraintData get data; // abstract getters
void sort(Skeleton skeleton); // abstract methods
static Rtti rttiStatic() { /* implementation */ }
}
```
**Key Pattern**: The implementation uses single inheritance (`extends`) for concrete parent classes and multiple interface implementation (`implements`) for mixins.
### **4. Nullability Handling**
The nullability system is comprehensive and automatic:
#### **Nullable Return Values**
```dart
Bone? get rootBone {
final result = SpineBindings.bindings.spine_skeleton_get_root_bone(_ptr);
return result.address == 0 ? null : Bone.fromPointer(result);
}
```
#### **Nullable Parameters**
```dart
void sortBone(Bone? bone) {
SpineBindings.bindings.spine_skeleton_sort_bone(
_ptr,
bone?.nativePtr.cast() ?? Pointer.fromAddress(0)
);
}
```
#### **Non-nullable Types**
```dart
String get name { // No '?' - guaranteed non-null
final result = SpineBindings.bindings.spine_attachment_get_name(_ptr);
return result.cast<Utf8>().toDartString();
}
```
The nullability information flows from:
1. **C++ analysis**: Pointers can be null, references cannot
2. **CIR encoding**: `returnTypeNullable` and `parameter.isNullable` flags
3. **Dart generation**: Automatic `?` types and null checks
### **5. Generated Code Structure**
#### **Class Structure**
Each generated class follows a consistent pattern:
- License header
- Imports (FFI, bindings, related types)
- Class declaration with inheritance
- Pointer field (`_ptr`)
- Pointer constructor (`fromPointer`)
- Native pointer getter
- Factory constructors
- Properties (getters/setters)
- Methods
- Dispose method (for concrete classes)
#### **Method Generation**
The codegen intelligently detects:
- **Getters**: `spine_skeleton_get_data` → `SkeletonData get data`
- **Setters**: `spine_skeleton_set_x` → `set x(double value)`
- **Methods**: `spine_skeleton_update` → `void update(double delta)`
- **Constructors**: `spine_skeleton_create` → `factory Skeleton()`
#### **Method Overloading**
Handles C's numbered method pattern:
```dart
// spine_skeleton_set_skin_1 → setSkin(String)
void setSkin(String skinName) { ... }
// spine_skeleton_set_skin_2 → setSkin2(Skin?)
void setSkin2(Skin? newSkin) { ... }
```
### **6. RTTI-Based Instantiation**
For abstract types, the codegen generates runtime type checking:
```dart
Attachment? getAttachment(String slotName, String attachmentName) {
final result = SpineBindings.bindings.spine_skeleton_get_attachment_1(...);
if (result.address == 0) return null;
final rtti = SpineBindings.bindings.spine_attachment_get_rtti(result);
final className = SpineBindings.bindings.spine_rtti_get_class_name(rtti)
.cast<Utf8>().toDartString();
switch (className) {
case 'spine_region_attachment':
return RegionAttachment.fromPointer(result.cast());
case 'spine_mesh_attachment':
return MeshAttachment.fromPointer(result.cast());
// ... other concrete types
default:
throw UnsupportedError('Unknown concrete type: $className');
}
}
```
### **7. Array Types**
Arrays get specialized wrapper classes extending `NativeArray<T>`:
```dart
class ArrayFloat extends NativeArray<double> {
final bool _ownsMemory;
ArrayFloat.fromPointer(Pointer<spine_array_float_wrapper> ptr, {bool ownsMemory = false})
: _ownsMemory = ownsMemory, super(ptr);
factory ArrayFloat() { /* create constructor */ }
@override
int get length { /* implementation */ }
@override
double operator [](int index) { /* implementation */ }
void dispose() { /* only if _ownsMemory */ }
}
```
**Key Features**:
- Memory ownership tracking
- Bounds checking
- Null handling for object arrays
- Factory constructors for creation
### **8. Enum Generation**
Enums use Dart's modern enum syntax with values:
```dart
enum BlendMode {
normal(0),
additive(1),
multiply(2),
screen(3);
const BlendMode(this.value);
final int value;
static BlendMode fromValue(int value) {
return values.firstWhere(
(e) => e.value == value,
orElse: () => throw ArgumentError('Invalid BlendMode value: $value'),
);
}
}
```
### **9. Special Patterns for Swift**
Several patterns from the Dart implementation would translate well to Swift:
#### **Memory Management**
```swift
// Swift equivalent of pointer wrapping
class Skeleton {
private let ptr: OpaquePointer
init(fromPointer ptr: OpaquePointer) {
self.ptr = ptr
}
var nativePtr: OpaquePointer { ptr }
deinit {
spine_skeleton_dispose(ptr)
}
}
```
#### **Optional Handling**
```swift
// Swift's optionals map naturally to Dart's nullability
var rootBone: Bone? {
let result = spine_skeleton_get_root_bone(ptr)
return result == nil ? nil : Bone(fromPointer: result!)
}
```
#### **RTTI Switching**
```swift
// Swift's switch with associated values
func getAttachment(_ slotName: String, _ attachmentName: String) -> Attachment? {
guard let result = spine_skeleton_get_attachment_1(ptr, slotName, attachmentName) else {
return nil
}
let rtti = spine_attachment_get_rtti(result)
let className = String(cString: spine_rtti_get_class_name(rtti))
switch className {
case "spine_region_attachment":
return RegionAttachment(fromPointer: result)
case "spine_mesh_attachment":
return MeshAttachment(fromPointer: result)
default:
fatalError("Unknown concrete type: \(className)")
}
}
```
#### **Protocol-Based Interfaces**
```swift
// Swift protocols map well to Dart interfaces
protocol Constraint: Update {
var nativePtr: OpaquePointer { get }
var data: ConstraintData { get }
func sort(_ skeleton: Skeleton)
var isSourceActive: Bool { get }
}
```
### **10. Key Takeaways for Swift Implementation**
1. **Consistent Architecture**: Use the same 3-step process (input CIR → transform → generate)
2. **Nullability Mapping**: Leverage Swift's optionals to match CIR nullability exactly
3. **Memory Management**: Use automatic reference counting with `deinit` for cleanup
4. **Type Safety**: Generate compile-time safe wrappers around C pointers
5. **RTTI Handling**: Use Swift's powerful switch statements for type resolution
6. **Protocol Orientation**: Use Swift protocols for interfaces/mixins
7. **Value Types**: Use Swift enums with raw values for C enums
8. **Collection Types**: Create Array wrapper classes similar to Dart's approach
9. **Method Overloading**: Swift's native overloading can handle numbered C methods more elegantly
10. **Property Synthesis**: Use Swift's computed properties for getters/setters
The Dart implementation provides an excellent blueprint for creating idiomatic, type-safe wrappers around the C API while maintaining full compatibility with the underlying spine-c layer.
## Existing Swift Implementation Analysis
### 1. Current Code Generation Approach (Python-based)
**File**: `/Users/badlogic/workspaces/spine-runtimes/spine-cpp/spine-cpp-lite/spine-cpp-lite-codegen.py`
The current generator uses a Python script that:
- **Parses C++ header file** (`spine-cpp-lite.h`) using regex patterns to extract:
- Opaque types (between `@start: opaque_types` and `@end: opaque_types`)
- Function declarations (between `@start: function_declarations` and `@end: function_declarations`)
- Enums (between `@start: enums` and `@end: enums`)
- **Type mapping** approach:
```python
supported_types_to_swift_types = {
'void *': 'UnsafeMutableRawPointer',
'const utf8 *': 'String?',
'uint64_t': 'UInt64',
'float *': 'Float?',
'float': 'Float',
'int32_t': 'Int32',
'utf8 *': 'String?',
'int32_t *': 'Int32?',
'uint16_t *': 'UInt16',
'spine_bool': 'Bool'
}
```
- **Swift class generation pattern**:
- Each opaque type becomes a Swift class inheriting from `NSObject`
- Uses `@objc` and `@objcMembers` for Objective-C compatibility
- Internal `wrappee` property holds the C++ pointer
- Automatic generation of `isEqual` and `hash` methods
- Smart getter/setter detection for computed properties
### 2. Current Generated Code Structure
**File**: `/Users/badlogic/workspaces/spine-runtimes/spine-ios/Sources/Spine/Spine.Generated.swift`
The generated code follows these patterns:
- **Type aliases for enums**:
```swift
public typealias BlendMode = spine_blend_mode
public typealias MixBlend = spine_mix_blend
// etc.
```
- **Class structure**:
```swift
@objc(SpineTransformConstraintData)
@objcMembers
public final class TransformConstraintData: NSObject {
internal let wrappee: spine_transform_constraint_data
internal init(_ wrappee: spine_transform_constraint_data) {
self.wrappee = wrappee
super.init()
}
public override func isEqual(_ object: Any?) -> Bool {
guard let other = object as? TransformConstraintData else { return false }
return self.wrappee == other.wrappee
}
public override var hash: Int {
var hasher = Hasher()
hasher.combine(self.wrappee)
return hasher.finalize()
}
}
```
- **Smart property generation**:
- Detects getter/setter pairs and creates computed properties
- Handles array types with companion `get_num_*` functions
- Boolean conversion (`spine_bool` ↔ Swift `Bool`)
- Optional handling with `flatMap`
### 3. Extensions and Manual Code
**File**: `/Users/badlogic/workspaces/spine-runtimes/spine-ios/Sources/Spine/Spine.Generated+Extensions.swift`
Contains manually written extensions that provide:
- Async loading methods (`fromBundle`, `fromFile`, `fromHttp`)
- Swift-friendly error handling with `SpineError`
- Integration with iOS types (`UIImage`, `CGRect`)
- Memory management and resource disposal
- SwiftUI integration
### 4. Module Map Setup
**Files**:
- `/Users/badlogic/workspaces/spine-runtimes/spine-ios/Sources/SpineCppLite/include/module.modulemap`
- `/Users/badlogic/workspaces/spine-runtimes/spine-ios/Sources/SpineShadersStructs/module.modulemap`
Simple module maps that expose C++ headers to Swift:
```
module SpineCppLite {
header "spine-cpp-lite.h"
export *
}
```
### 5. TypeScript Infrastructure (Newer)
The codebase shows transition to TypeScript-based generation:
- Uses shared `spine-c-codegen` package
- More sophisticated parsing and IR generation
- Better type safety and maintainability
## Recommendations
### What to Keep:
1. **Module map approach** - Simple and effective for C++ interop
2. **Opaque pointer wrapping pattern** - Safe and follows Swift best practices
3. **NSObject inheritance** - Good for Objective-C compatibility
4. **Smart getter/setter detection** - Creates idiomatic Swift APIs
5. **Array handling with num functions** - Proper memory management
6. **Extensions pattern** - Separates generated from manual code
### What Needs Improvement:
1. **Move from Python to TypeScript** - Align with other runtimes
2. **Better error handling** - More sophisticated null analysis
3. **Memory management** - Explicit lifetime management
4. **Documentation generation** - Add doc comments to generated code
5. **Testing integration** - Generate test scaffolding
### Swift-Specific Patterns to Maintain:
1. **Sendable conformance** - For modern Swift concurrency
2. **@objc compatibility** - For mixed Objective-C/Swift projects
3. **Result types** - For better error handling
4. **Async/await integration** - Already present in extensions
5. **Property wrappers** - Could be useful for resource management
### Suggested Architecture:
1. Use the existing TypeScript infrastructure from `spine-c-codegen`
2. Create Swift-specific type mappings and templates
3. Generate both the main classes and extension scaffolding
4. Maintain backward compatibility with existing APIs
5. Add modern Swift features (Sendable, async/await, Result types)
The current implementation is solid but could benefit from modernization and alignment with the TypeScript-based generation approach used elsewhere in the codebase.

76
todos/work/2025-07-31-16-50-17-generate-swift-bindings/task.md Normal file
View File

@ -0,0 +1,76 @@
# Generate bindings for Swift from spine-c
**Status:** InProgress
**Agent PID:** 43132
## Original Todo
Generate bindings for Swift from spine-c generate() like dart-writer.ts
## Description
Create a TypeScript-based Swift bindings generator that uses the spine-c codegen infrastructure to generate idiomatic Swift code. The generator will replace the existing Python-based generator and produce type-safe Swift wrappers around the spine-c API, similar to how the Dart generator works. It will generate classes with proper inheritance hierarchy, nullability annotations, memory management, and maintain compatibility with the existing Swift API while adding modern Swift features.
Read [analysis.md](./analysis.md) in full for analysis results and context.
## Implementation Plan
- [x] Create the Swift codegen package structure (spine-ios/codegen/)
- Set up TypeScript project with package.json, tsconfig.json
- Add dependency on spine-c-codegen package
- Create src/index.ts as entry point
- Create src/swift-writer.ts for Swift code generation
- [x] Implement SwiftWriter class (spine-ios/codegen/src/swift-writer.ts)
- Use DartWriter as reference for structure but implement Swift-specific patterns
- Map C types to Swift types (OpaquePointer, String, Bool, etc.)
- Handle nullability with Swift optionals
- Generate proper class/protocol inheritance
- [ ] Generate Swift classes from CIR
- Concrete classes with NSObject inheritance and @objc annotations
- Abstract classes with proper subclass requirements
- Protocols for interface types (like Constraint, Update)
- Proper memory management with deinit methods
- [ ] Generate Swift enums
- Use Swift enums with raw values for C enums
- Add fromValue static methods for reverse lookup
- Generate proper case names from C enum values
- [ ] Generate array wrapper types
- Create Swift array wrapper classes for each spine_array_* type
- Implement subscript operators and collection protocols
- Handle memory ownership and disposal
- [ ] Handle RTTI-based instantiation
- Generate switch statements for abstract type instantiation
- Map C++ class names to Swift concrete types
- Handle unknown types gracefully
- [ ] Generate method implementations
- Convert C function calls to Swift methods
- Handle method overloading (numbered C methods)
- Generate computed properties for getter/setter pairs
- Add proper null checking and optional unwrapping
- [ ] Create output file structure
- Generate individual .swift files per type
- Create Arrays.swift for all array types
- Create Enums.swift for all enum types
- Generate main exports file
- [ ] Add build integration
- Create build script to run the generator
- Update spine-ios Package.swift to include generated files
- [ ] Create minimal test package (spine-ios/test/) inspired by spine-flutter/test
- Minimal Package.swift for quick iteration
- Test harness without full spine-ios dependencies
- Basic examples to verify generated bindings work
- [ ] Test the generated code
- Verify compilation with Swift compiler
- Test against the minimal test package
- Ensure backward compatibility with existing API
- [ ] User test: Generate Swift bindings and verify they compile and work correctly in the test package
## Notes
[Implementation notes]