From b9743fde4681f2bb9d839d97bdc7ce03b020cb1c Mon Sep 17 00:00:00 2001 From: Mario Zechner Date: Thu, 28 Aug 2025 18:18:36 +0200 Subject: [PATCH] Update README.mds --- spine-c/README.md | 51 ++++++++++-------- spine-flutter/README.md | 10 ++-- spine-glfw/README.md | 2 +- spine-ios/README.md | 113 ++++++++++++++++++++++++++++++++-------- spine-sfml/README.md | 2 +- 5 files changed, 127 insertions(+), 51 deletions(-) diff --git a/spine-c/README.md b/spine-c/README.md index 54b6ffbe8..7884c1a11 100644 --- a/spine-c/README.md +++ b/spine-c/README.md @@ -1,8 +1,10 @@ # spine-c -The spine-c runtime provides basic functionality to load and manipulate [spine](http://esotericsoftware.com) skeletal animation data using C. It does not perform rendering but can be extended to enable spine animations for other projects that utilize C. +The spine-c runtime provides basic functionality to load and manipulate [Spine](http://esotericsoftware.com) skeletal animation data using C. It contains a generic `SkeletonRenderer` that returns render commands that can be easily fed into any rendering API that supports textured triangle meshes with blend modes. See [spine-glfw](../spine-glfw), [spine-sdl](../spine-sdl), or [spine-sfml](../spine-sfml) for examples. -**Note:** The spine-c code is generated using a code generator. For details on the code generation process, please see the [codegen/README.md](codegen/README.md). +**Note:** spine-c is a C wrapper around [spine-cpp](../spine-cpp) for use in environments that cannot easily interact with C++ code. The spine-c code is generated using a code generator. For details on the code generation process, please see the [codegen/README.md](codegen/README.md). + +# See the [spine-c documentation](http://esotericsoftware.com/spine-c) for in-depth information ## Licensing @@ -16,41 +18,46 @@ For the official legal terms governing the Spine Runtimes, please read the [Spin ## Spine version -spine-c works with data exported from spine 4.3.xx. +spine-c works with data exported from Spine 4.3.xx. -spine-c supports all spine features. +spine-c supports all Spine features. ## Usage -### [Please see the spine-c guide for full documentation](http://esotericsoftware.com/spine-c) +### Integration with CMake (Recommended) -## Setup - -### Manual Copy - -1. Download the spine Runtimes source using [git](https://help.github.com/articles/set-up-git) or by downloading it as a zip via the download button above. -2. Copy the contents of the `spine-c/src` and `spine-c/include` directories into your project. Be sure your header search is configured to find the contents of the `spine-c/include` directory. - -### CMake - -You can use CMake's FetchContent to include spine-c in your project: +The easiest way to integrate spine-c into your project is via CMake FetchContent: ```cmake include(FetchContent) FetchContent_Declare( - spine-runtimes - GIT_REPOSITORY https://github.com/EsotericSoftware/spine-runtimes.git - GIT_TAG 4.3 + spine-c + GIT_REPOSITORY https://github.com/esotericsoftware/spine-runtimes.git + GIT_TAG 4.3 + SOURCE_SUBDIR spine-c ) -FetchContent_MakeAvailable(spine-runtimes) +FetchContent_MakeAvailable(spine-c) -add_subdirectory(${spine-runtimes_SOURCE_DIR}/spine-c ${spine-runtimes_BINARY_DIR}/spine-c) -target_link_libraries(your_target PRIVATE spine-c) +# Link against spine-c +target_link_libraries(your_target spine-c) ``` +This will automatically fetch and build spine-c along with its dependency (spine-cpp). + +### Manual Integration + +If you prefer manual integration: + +1. Download the Spine Runtimes source using git (`git clone https://github.com/esotericsoftware/spine-runtimes`) or download it as a zip. +2. Add the required source files to your project: + - Add sources from `spine-cpp/src`, `spine-c/src` +3. Add the include directories: `spine-cpp/include`, `spine-c/include` + +See the [Spine Runtimes documentation](http://esotericsoftware.com/spine-documentation#runtimes) for detailed API usage. + ## Runtimes extending spine-c + - [spine-ios](../spine-ios) - [spine-flutter](../spine-flutter) -- [spine-sfml/c](../spine-sfml/c) - [spine-sdl](../spine-sdl) - [spine-glfw](../spine-glfw) \ No newline at end of file diff --git a/spine-flutter/README.md b/spine-flutter/README.md index 22a582343..9eeb7adbb 100644 --- a/spine-flutter/README.md +++ b/spine-flutter/README.md @@ -1,6 +1,6 @@ # spine-flutter -The spine-flutter runtime provides functionality to load, manipulate and render [Spine](https://esotericsoftware.com) skeletal animation data using [Flutter](https://flutter.dev/). spine-flutter is based on [spine-cpp](../spine-cpp) and supports desktop and mobile Flutter deployment targets. spine-flutter does not support Flutter's web deployment target. +The spine-flutter runtime provides functionality to load, manipulate and render [Spine](https://esotericsoftware.com) skeletal animation data using [Flutter](https://flutter.dev/). spine-flutter is based on [spine-c](../spine-c) and supports desktop, mobile, and web Flutter deployment targets. # See the [spine-flutter documentation](https://esotericsoftware.com/spine-flutter) for in-depth information. @@ -54,10 +54,12 @@ You can then open `spine-flutter` in an IDE or editor of your choice that suppor Alternatively, you can run the example from the [command line](https://docs.flutter.dev/get-started/test-drive?tab=terminal). ## Development +Run `./setup.sh` to copy over the spine-cpp and spine-c sources. This step needs to be executed every time spine-cpp or spine-c changes. + If all you modify are the Dart sources of the plugin, then the development setup is the same as the setup described under "Example" above. -If you need to work on the `dart:ffi` bindings for `spine-cpp`, you will also need to install [Emscripten](https://emscripten.org/docs/getting_started/downloads.html). +If you need to update or modify the bindings generated from spine-c, run `./generate-bindings.sh`. If you regenerate the bindings, you must also compile the WASM binaries via `./compile-wasm.sh`. -To generate the bindings based on the `src/spine_flutter.h` header, run `dart run ffigen --config ffigen.yaml`. After the bindings have been generated, you must replace the line `import 'dart:ffi' as ffi;` with `import 'ffi_proxy.dart' as ffi;` in the file `src/generated/spine_dart_bindings_generated.dart`. Otherwise the bindings will not compile for the web. +Run `./publish.sh` to publish spine-flutter to pub.dev. -If you made changes to `spine-cpp` or the source files in `src/`, you must run `compile-wasm.sh`. This will compile `spine-cpp` and the bindings for the Web and place updated versions of `libspine_flutter.js` and `libspine_flutter.wasm` in the `lib/assets/` folder. For web builds, the `initSpineDartFFI()` function in `lib/spine_dart_init_web.dart` will load these files from the package's asset bundle. +The `./tests` folder contains headless tests that exercise the bindings to [spine-c](../spine-c). diff --git a/spine-glfw/README.md b/spine-glfw/README.md index 2c06a91b5..8440e1805 100644 --- a/spine-glfw/README.md +++ b/spine-glfw/README.md @@ -2,7 +2,7 @@ The spine-glfw runtime provides functionality to load, manipulate and render [Spine](http://esotericsoftware.com) skeletal animation data using [GLFW](https://www.glfw.org/) and OpenGL. spine-glfw is based on [spine-c](../spine-c) and [spine-cpp](../spine-cpp). Note that spine-c depends on spine-cpp, so both are required regardless of which API you choose to use. -# See the [Spine Runtimes documentation](http://esotericsoftware.com/spine-documentation#runtimes) for in-depth information +# See the [spine-glfw documentation](http://esotericsoftware.com/spine-glfw) for in-depth information ## Licensing diff --git a/spine-ios/README.md b/spine-ios/README.md index 38dc1f26f..556ca2849 100644 --- a/spine-ios/README.md +++ b/spine-ios/README.md @@ -1,8 +1,8 @@ # spine-ios -The spine-ios runtime provides functionality to load, manipulate and render [Spine](http://esotericsoftware.com) skeletal animation data for iOS using Swift or Objective-C. +The spine-ios runtime provides functionality to load, manipulate and render [Spine](http://esotericsoftware.com) skeletal animation data for iOS, tvOS, macOS, and visionOS using Swift or Objective-C. spine-ios is based on [spine-c](../spine-c) and [spine-cpp](../spine-cpp). -See the [spine-ios documentation](https://esotericsoftware.com/spine-ios) for more information. +# See the [spine-ios documentation](http://esotericsoftware.com/spine-ios) for in-depth information ## Licensing @@ -16,41 +16,108 @@ For the official legal terms governing the Spine Runtimes, please read the [Spin ## Spine version -spine-ios works with data exported from Spine 4.2.xx. +spine-ios works with data exported from Spine 4.3.xx. spine-ios supports all Spine features except two-color tinting. -## Building +## Usage -### SpineC bindings +### Integration with Swift Package Manager +Add spine-ios to your Xcode project or Package.swift: -### SpineC and SpineSwift +#### Via Xcode + +1. Open your project in Xcode +2. Go to File → Add Package Dependencies +3. Enter the repository URL: `https://github.com/esotericsoftware/spine-runtimes.git` +4. Choose the version (e.g., branch "4.3") +5. Select the libraries you need: + - `SpineC` - C API for low-level access + - `SpineSwift` - Swift API for Swift projects + - `SpineiOS` - iOS/tvOS rendering with Metal + +#### Via Package.swift + +```swift +dependencies: [ + .package(url: "https://github.com/esotericsoftware/spine-runtimes.git", branch: "4.3") +], +targets: [ + .target( + name: "YourTarget", + dependencies: [ + .product(name: "SpineiOS", package: "spine-runtimes"), + // Or use SpineSwift for cross-platform Swift-only code: + // .product(name: "SpineSwift", package: "spine-runtimes"), + ] + ) +] +``` + +## Examples + +The repository includes comprehensive example code demonstrating various features: +- Simple animation playback +- Animation state events +- Physics simulation +- IK following +- Mix-and-match skins +- Debug rendering +- Objective-C integration + +### Running the Examples + +#### Requirements +- Xcode 14.0 or later +- iOS 13.0+ / tvOS 13.0+ / macOS 10.15+ device or simulator + +#### Steps +1. Clone the repository: `git clone https://github.com/esotericsoftware/spine-runtimes` +2. Open the example project: + ```bash + cd spine-runtimes/spine-ios + open Example/Spine\ iOS\ Example.xcodeproj + ``` +3. Select your target device (simulator or physical device) +4. Press Run (⌘R) to build and run the examples + +The example app includes multiple tabs showcasing different spine-ios features. + +## Development + +For developers who want to modify or build spine-ios from source: + +### Building the Modules -Build on any platform: ```bash -./setup.sh # Copy spine-c and spine-cpp sources +cd spine-runtimes/spine-ios + +# Build SpineC (C API) swift build --product SpineC + +# Build SpineSwift (Swift API) swift build --product SpineSwift + +# Build SpineiOS (requires iOS/tvOS SDK) +# Use Xcode for SpineiOS as it requires platform-specific SDKs ``` -### SpineiOS - -Requires iOS/tvOS. Use Xcode: +### Running Tests ```bash -# Open in Xcode (recommended) -open Example/Spine\ iOS\ Example.xcodeproj - -# Or build from command line (requires iOS Simulator runtime) -# Install iOS Simulator: Xcode > Settings > Platforms > iOS Simulator > Download -xcodebuild -project Example/Spine\ iOS\ Example.xcodeproj -scheme "Spine iOS Example" -sdk iphonesimulator -destination "generic/platform=iOS Simulator" build -``` - -### Tests - -```bash -cd test +cd spine-runtimes/spine-ios/test swift build swift run SpineTest ``` + +### Generating Swift Bindings + +If you need to regenerate the Swift bindings after modifying spine-c: + +```bash +cd spine-runtimes/spine-ios +./generate-bindings.sh +``` + +This will regenerate the Swift wrapper code in `Sources/SpineSwift/Generated/`. \ No newline at end of file diff --git a/spine-sfml/README.md b/spine-sfml/README.md index 11464f645..654c549d8 100644 --- a/spine-sfml/README.md +++ b/spine-sfml/README.md @@ -2,7 +2,7 @@ The spine-sfml runtime provides functionality to load, manipulate and render [Spine](http://esotericsoftware.com) skeletal animation data using [SFML](https://www.sfml-dev.org/). spine-sfml is based on [spine-cpp](../spine-cpp). -# See the [Spine Runtimes documentation](http://esotericsoftware.com/spine-documentation#runtimes) for in-depth information +# See the [spine-sfml documentation](http://esotericsoftware.com/spine-sfml) for in-depth information ## Licensing