spine-runtimes/todos/project-description.md

Project: Spine Runtimes

Multi-language runtime libraries for Spine 2D skeletal animations. Provides core runtimes for different programming languages and integrations for game engines and frameworks, supporting advanced skeletal animation with physics, constraints, and dynamic content.

Features

Core Animation Features

• Skeletal Animation: Hierarchical bone-based animation system
• Inverse Kinematics (IK): 1-2 bone IK constraints for natural positioning
• Path Constraints: Bones follow Bezier curve paths for complex motion
• Transform Constraints: Copy/mix transformations between bones
• Physics Constraints: Real-time physics simulation (4.2+)
• Animation Mixing/Crossfading: Smooth transitions with configurable durations
• Animation Layering: Multiple animations on different tracks

Visual System

• Attachments: Regions, meshes, clipping, bounding boxes, paths, points, nested skeletons
• Skins System: Dynamic attachment swapping and layering
• Blend Modes: Normal, additive, multiply, screen rendering
• Two-Color Tinting: Advanced color effect
• Sequences: Frame-by-frame texture animation within skeletal structure
• Events System: Timeline-based event triggering for game logic

Tech Stack

Languages

• Java (spine-libgdx) - Reference implementation
• C++ (spine-cpp) - C++11 with custom RTTI
• C# (spine-csharp) - .NET Framework 4.8, Unity 2018.3+
• TypeScript/JavaScript (spine-ts) - ES2015+ with ESM modules
• C (spine-c) - Standalone implementation with codegen
• Haxe (spine-haxe) - Cross-platform runtime
• Swift (spine-ios) - iOS native (5.0+)
• Dart (spine-flutter) - Flutter runtime (>=3.16.0)

Build Systems

• Gradle (Kotlin DSL) - Java/Android projects
• CMake - C/C++ projects with presets
• npm/esbuild - TypeScript ecosystem
• MSBuild/.NET CLI - C# projects
• Swift Package Manager - iOS packages
• SCons - Godot extension builds
• Flutter pub - Dart package management

Frameworks & Engines

• Game Engines: Unity, Unreal Engine (4.27-5.5), Godot, Cocos2d-x, libGDX
• Web: Phaser.js (v3/v4), PixiJS (v7/v8), Three.js, HTML5 Canvas, WebGL
• Mobile/Desktop: Flutter, MonoGame, SDL, SFML, GLFW
• Graphics: OpenGL/ES, WebGL, Metal, DirectX (UE)

Structure

Core Runtimes (Language-specific)

• spine-libgdx (Java) - Reference implementation
• spine-cpp (C++) - Complete port with spine-cpp-lite FFI wrapper
• spine-csharp (C#) - .NET implementation
• spine-ts (TypeScript) - Modular web ecosystem
• spine-c (C) - Auto-generated from spine-cpp
• spine-haxe (Haxe) - Cross-platform port

Integration Runtimes (Engine-specific)

Using spine-cpp:

• spine-cocos2dx, spine-flutter, spine-glfw, spine-godot, spine-ios, spine-sdl, spine-sfml, spine-ue

Using spine-csharp:

• spine-unity, spine-monogame, spine-xna

Using spine-ts:

• spine-canvas, spine-webgl, spine-phaser, spine-pixi, spine-threejs, spine-player, spine-canvaskit, spine-webcomponents

Using spine-libgdx:

• spine-android

Special Components

• spine-cpp-lite: C FFI wrapper enabling Dart/Swift bindings
• formatters/: Universal code formatting for all languages
• tests/: Cross-runtime serialization validation
• examples/: Rich animation examples and educational content

Architecture

Reference Implementation Pattern

• spine-libgdx serves as authoritative reference
• All other core runtimes are systematic ports maintaining API compatibility
• Changes originate in spine-libgdx and are ported to other languages

Data/Instance Separation

• Data Classes (SkeletonData, BoneData): Immutable setup pose
• Instance Classes (Skeleton, Bone): Mutable runtime state
• Pose Classes: Applied transformations and constraints (4.3+)

Update Pipeline

1. Animation update (AnimationState.update())
2. Apply animation to skeleton (AnimationState.apply())
3. Skeleton update with physics (Skeleton.update())
4. World transform update (Skeleton.updateWorldTransform(Physics))

Commands

Build Commands

• spine-libgdx: ./gradlew build
• spine-cpp: ./build.sh [release|clean|nofileio]
• spine-c: ./build.sh [release|clean|codegen]
• spine-ts: npm install && npm run build
• spine-csharp: dotnet build
• spine-flutter: ./setup.sh && flutter build
• spine-godot: scons [platform=linux|windows|macos]
• spine-haxe: ./build.sh
• spine-ios: swift build

Test Commands

• Cross-runtime: ./tests/test.sh
• spine-cpp: ./tests/test.sh
• spine-libgdx: ./gradlew test
• spine-ts: npx tsx src/headless-test-runner.ts
• spine-flutter: flutter test

Utility Commands

• Format all: ./formatters/format.sh
• Format specific: ./formatters/format.sh [java|ts|cpp|csharp|dart|haxe|swift]

Testing

Cross-Runtime Validation

• Serialization consistency tests between Java, C++, C, and TypeScript
• Headless test runners for automated validation
• Output comparison for JSON/binary format validation

Language-Specific Testing

• Java: JUnit tests via Gradle
• C++: Custom headless tests with multiple build variants
• TypeScript: Custom test runner with tsx
• Flutter: Flutter test framework
• C#: .NET test framework

CI/CD Testing

• GitHub Actions workflows for all runtimes
• Automated formatting validation
• Cross-platform compatibility testing
• Automated publishing pipelines

Development Workflow

1. Changes begin in spine-libgdx (reference implementation)
2. Port to core runtimes using git diffs and systematic translation
3. Integration runtimes inherit changes from their core runtime
4. Validate with cross-runtime tests to ensure consistency
5. Format code using universal formatting tools
6. Publish to appropriate package repositories (Maven, NPM, NuGet, etc.)

Version Management

• Current: 4.3-beta (development branch)
• Stable: 4.2 (main branch for PRs)