Update project-description.md

todos/project-description.md

@@ -1,137 +1,153 @@
 # Project: Spine Runtimes
 
-Multi-language runtime libraries for Spine 2D skeletal animations. The project provides core runtimes for different programming languages and integrations for various game engines and frameworks.
+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.
 
-## Core Runtimes (Language-specific implementations)
+## Features
 
-### spine-libgdx (Java) - Reference Implementation
+### Core Animation Features
-- **Build**: `./gradlew build`
+- **Skeletal Animation**: Hierarchical bone-based animation system
-- **Publish**: `./gradlew publishToMavenLocal`
+- **Inverse Kinematics (IK)**: 1-2 bone IK constraints for natural positioning
-- All other runtimes are ports of this reference implementation
+- **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
 
-### spine-cpp (C++)
+### Visual System
-- **Build**: `cmake -B build && cmake --build build`
+- **Attachments**: Regions, meshes, clipping, bounding boxes, paths, points, nested skeletons
-- Port of spine-libgdx
+- **Skins System**: Dynamic attachment swapping and layering
-- Uses custom RTTI (no C++ exceptions/RTTI)
+- **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
 
-### spine-csharp (C#)
+## Tech Stack
-- **Build**: `msbuild spine-csharp.csproj` or `dotnet build`
-- Port of spine-libgdx
-- Targets .NET Framework 4.8
 
-### spine-ts (TypeScript/JavaScript)
+### Languages
-- **Build**: `npm install && npm run build`
+- **Java** (spine-libgdx) - Reference implementation
-- **Dev**: `npm run dev`
+- **C++** (spine-cpp) - C++11 with custom RTTI
-- Port of spine-libgdx
+- **C#** (spine-csharp) - .NET Framework 4.8, Unity 2018.3+
-- Core module at spine-ts/spine-core/
+- **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)
 
-### spine-haxe (Haxe)
+### Build Systems
-- **Build**: `./build.sh`
+- **Gradle** (Kotlin DSL) - Java/Android projects
-- Port of spine-libgdx
+- **CMake** - C/C++ projects with presets
-- Uses Haxelib package manager
+- **npm/esbuild** - TypeScript ecosystem
+- **MSBuild/.NET CLI** - C# projects
+- **Swift Package Manager** - iOS packages
+- **SCons** - Godot extension builds
+- **Flutter pub** - Dart package management
 
-### spine-c (C)
+### Frameworks & Engines
-- **Build**: `cmake -B build && cmake --build build`
+- **Game Engines**: Unity, Unreal Engine (4.27-5.5), Godot, Cocos2d-x, libGDX
-- Actively maintained C implementation
+- **Web**: Phaser.js (v3/v4), PixiJS (v7/v8), Three.js, HTML5 Canvas, WebGL
-- Different structure from other runtimes due to C language constraints
+- **Mobile/Desktop**: Flutter, MonoGame, SDL, SFML, GLFW
+- **Graphics**: OpenGL/ES, WebGL, Metal, DirectX (UE)
 
-## Integration Runtimes (Engine/Framework-specific)
+## Structure
 
-### Using spine-cpp:
+### Core Runtimes (Language-specific)
-- **spine-cocos2dx** - Cocos2d-x engine
+- **spine-libgdx** (Java) - Reference implementation
-- **spine-flutter** - Flutter (via spine-cpp-lite C wrapper + Dart FFI)
+- **spine-cpp** (C++) - Complete port with spine-cpp-lite FFI wrapper
-- **spine-glfw** - GLFW/OpenGL example
+- **spine-csharp** (C#) - .NET implementation
-- **spine-godot** - Godot Engine
+- **spine-ts** (TypeScript) - Modular web ecosystem
-- **spine-ios** - iOS native (via spine-cpp-lite C wrapper + Swift codegen)
+- **spine-c** (C) - Auto-generated from spine-cpp
-- **spine-sdl** - SDL (optional, can use spine-c)
+- **spine-haxe** (Haxe) - Cross-platform port
-- **spine-sfml/cpp** - SFML C++ version
-- **spine-ue** - Unreal Engine 4.27-5.4
 
-### Using spine-csharp:
+### Integration Runtimes (Engine-specific)
-- **spine-unity** - Unity game engine
+**Using spine-cpp:**
-- **spine-monogame** - MonoGame framework
+- spine-cocos2dx, spine-flutter, spine-glfw, spine-godot, spine-ios, spine-sdl, spine-sfml, spine-ue
-- **spine-xna** - XNA Framework (legacy)
 
-### Using spine-libgdx:
+**Using spine-csharp:**
-- **spine-android** - Android native
+- spine-unity, spine-monogame, spine-xna
 
-### Using spine-c:
+**Using spine-ts:**
-- **spine-sdl** - SDL (optional, can use spine-cpp)
+- spine-canvas, spine-webgl, spine-phaser, spine-pixi, spine-threejs, spine-player, spine-canvaskit, spine-webcomponents
-- **spine-sfml/c** - SFML C version
 
-### Using spine-core (TypeScript):
+**Using spine-libgdx:**
-- **spine-canvas** - HTML5 Canvas
+- spine-android
-- **spine-webgl** - Direct WebGL
-- **spine-phaser** - Phaser.js (v3 & v4)
-- **spine-pixi** - PixiJS (v7 & v8)
-- **spine-threejs** - Three.js
-- **spine-player** - Embeddable web player
-- **spine-canvaskit** - Skia CanvasKit
-- **spine-webcomponents** - Web Components
 
-## Special Cases
+### 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
 
-### spine-cpp-lite
+## Architecture
-- C wrapper around spine-cpp for FFI-friendly bindings
-- Located in spine-cpp/spine-cpp-lite/
-- Provides simplified C API consumed by:
-  - spine-flutter (via Dart FFI)
-  - spine-ios (via Swift code generation)
 
-## Commands Summary
+### Reference Implementation Pattern
-- **Check spine-cpp**: `cd spine-cpp && cmake -B build && cmake --build build`
+- **spine-libgdx** serves as authoritative reference
-- **Check spine-ts**: `cd spine-ts && npm install && npm run build`
+- All other core runtimes are systematic ports maintaining API compatibility
-- **Check spine-libgdx**: `cd spine-libgdx && ./gradlew build`
+- Changes originate in spine-libgdx and are ported to other languages
-- **Check spine-csharp**: `cd spine-csharp && msbuild spine-csharp.csproj`
+
-- **Check spine-c**: `cd spine-c && cmake -B build && cmake --build build`
+### 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
-- All changes start in spine-libgdx (reference implementation)
-- Port changes to other core runtimes using git diffs
-- Integration runtimes automatically inherit changes from their core runtime
 
-## Type System Documentation
+1. **Changes begin in spine-libgdx** (reference implementation)
-For a complete reference of all types in the Spine runtime, see [spine-runtimes-types.md](spine-runtimes-types.md).
+2. **Port to core runtimes** using git diffs and systematic translation
-To regenerate this documentation, run: `node docs/generate-type-hierarchy.js`
+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.)
 
-## Spine Type System Overview (from spine-libgdx)
+## Version Management
-
+- **Current**: 4.3-beta (development branch)
-### Core Types
+- **Stable**: 4.2 (main branch for PRs)
-- **Skeleton** - Stores the current pose for a skeleton
-- **SkeletonData** - Stores setup pose and stateless data
-- **Bone/BoneData** - Current pose and setup data for bones
-- **Slot/SlotData** - Manages attachments and drawing order
-- **Skin** - Collection of attachments keyed by slot and name
-
-### Animation System
-- **Animation** - List of timelines to animate skeleton pose
-- **AnimationState** - Applies animations, handles mixing and layering
-- **AnimationStateData** - Stores mix (crossfade) durations
-
-### Attachment Types (Visual Elements)
-- **Attachment** - Base class for all attachments
-- **RegionAttachment** - Textured quadrilateral
-- **MeshAttachment** - Textured mesh with vertices
-- **BoundingBoxAttachment** - Polygon for hit detection
-- **ClippingAttachment** - Polygon for clipping rendering
-- **PathAttachment** - Composite Bezier curve
-- **PointAttachment** - Single point with rotation
-- **SkeletonAttachment** - Nested skeleton
-
-### Constraint Types
-- **IkConstraint** - Inverse kinematics (1-2 bones)
-- **TransformConstraint** - Copy/mix transform from target
-- **PathConstraint** - Follow path attachment
-- **PhysicsConstraint** - Apply physics simulation
-
-### Pose System (new in 4.2+)
-- **Pose** - Interface for pose data
-- **BoneLocal/BonePose** - Local and world bone transforms
-- **Update** - Interface for updateable elements
-- **PosedActive/PosedData** - Base classes for runtime/setup data
-
-### Other Core Types
-- **Event/EventData** - Animation events system
-- **Sequence** - Frame-by-frame texture sequences
-- **SkeletonBounds** - Hit detection utilities
-- **SkeletonLoader** - Base for JSON/Binary loaders