Add "Animation-System"

Animation-System.-.md

@@ -0,0 +1,159 @@
+# Animation System
+
+The Animation System provides property-based animations with 24+ easing functions for smooth transitions on all UI elements.
+
+## Quick Reference
+
+**Related Issues:**
+- [#120](../../issues/120) - Animation Property Locking (Tier 1 - Active)
+- [#119](../../issues/119) - Animation Completion Callbacks (Closed - Implemented)
+- [#100](../../issues/100) - Add Rotation Support
+
+**Key Files:**
+- `src/AnimationManager.h` / `src/AnimationManager.cpp` - Animation execution engine
+- `src/Animation.h` - Base Animation class  
+- `src/UIDrawable.h` - Animatable properties defined here
+
+**API Reference:**
+- See [mcrfpy.animate()](../../docs/api_reference_dynamic.html#animate) in generated API docs
+
+## Architecture Overview
+
+### Property-Based Animation
+
+Animations modify any numeric property on UI objects over time:
+
+```python
+import mcrfpy
+
+sprite = mcrfpy.Sprite("player.png", 100, 100)
+
+# Animate position with easing
+mcrfpy.animate(sprite, "x", 300, 1000, "ease_in_out_cubic")
+
+# Animate multiple properties
+mcrfpy.animate(sprite, "opacity", 0.5, 500, "ease_out_quad")
+mcrfpy.animate(sprite, "scale_x", 2.0, 800, "bounce_out")
+```
+
+**Supported Properties:**
+- Position: `x`, `y`, `pos`
+- Size: `w`, `h`, `size`, `scale_x`, `scale_y`
+- Colors: `r`, `g`, `b`, `a`, `fill_color`, `outline_color`
+- Grid-specific: `zoom`, `left_edge`, `top_edge`
+- Caption-specific: `font_size`
+
+**Implementation:** See `src/AnimationManager.cpp::createAnimation()`
+
+### Easing Functions
+
+24+ easing functions available:
+
+**Families:**
+- Linear
+- Quad, Cubic, Quart, Quint
+- Sine, Expo, Circ
+- Elastic, Back, Bounce
+
+**Variants:** `ease_in_*`, `ease_out_*`, `ease_in_out_*`
+
+**Implementation:** All easing functions in `src/Animation.cpp`
+
+### Execution Model
+
+**Pure C++ Execution:**
+- Animations run in C++ update loop - no Python callbacks per frame
+- High performance: thousands of concurrent animations possible
+- Frame-independent: adjusts for variable frame times
+
+**Lifecycle:**
+1. Created via `mcrfpy.animate()`
+2. AnimationManager updates each frame
+3. Auto-destroyed on completion or target destruction
+4. Weak pointer tracking prevents use-after-free
+
+**See:** `src/AnimationManager.cpp::update()` for frame update logic
+
+## Current Issues & Limitations
+
+**Known Issues:**
+- API inconsistency: position vs frame animation differs (see [FINAL_RECOMMENDATIONS.md](../../FINAL_RECOMMENDATIONS.md))
+- Property locking: Multiple animations can conflict on same property ([#120](../../issues/120))
+- Rotation not yet supported ([#100](../../issues/100))
+
+**Recommendations from Strategic Review:**
+Per FINAL_RECOMMENDATIONS.md, animation bugs contributed to tutorial burnout. Current system is feature-complete but needs:
+1. API consistency audit
+2. Bug fixes for known issues
+3. Comprehensive testing
+
+## Common Tasks
+
+### Basic Animation
+
+```python
+# Linear movement
+mcrfpy.animate(entity, "x", 500, 2000, "linear")
+
+# Smooth bounce
+mcrfpy.animate(frame, "y", 300, 1000, "ease_out_bounce")
+```
+
+### Color Fades
+
+```python
+# Fade to red
+mcrfpy.animate(caption, "r", 255, 500, "ease_in_quad")
+
+# Fade out
+mcrfpy.animate(sprite, "a", 0, 1000, "ease_out_cubic")
+```
+
+### Delta Animations
+
+```python
+# Move relative to current position
+current_x = entity.x
+mcrfpy.animate(entity, "x", current_x + 100, 500, "ease_in_out_quad")
+```
+
+### Completion Callbacks
+
+```python
+def on_complete(runtime_ms):
+    print(f"Animation completed after {runtime_ms}ms")
+    # Trigger next action
+
+mcrfpy.animate(sprite, "x", 400, 1000, "linear", callback=on_complete)
+```
+
+**Implementation:** [#119](../../issues/119) - Callbacks fire when animation completes
+
+## Related Systems
+
+- [[UI-Component-Hierarchy]] - All UIDrawable objects are animatable
+- [[Grid-System]] - Grid viewport animations (zoom, pan)
+- [[Performance-and-Profiling]] - Animation time tracked separately
+
+## Design Decisions
+
+**Why Property-Based?**
+- Flexible: Any numeric property animatable
+- Type-safe: Properties validated at C++ level
+- Performant: No Python overhead during animation
+
+**Why Weak Pointers?**
+- Prevents crashes when animated objects destroyed
+- Automatic cleanup on target death
+- See: `src/AnimationManager.cpp` RAII overhaul (commit e9e9cd2)
+
+**Tradeoffs:**
+- More complex than tween libraries
+- Requires property exposure in Python bindings
+- API surface larger than simple position tweening
+
+---
+
+**Historical Notes:**
+- ANIMATION_FIX_IMPLEMENTATION.md documents segfault fix (race conditions resolved)
+- Major refactor July 2025: Weak pointer tracking eliminated use-after-free bugs