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