tween.py

tween.py - Tween Animation System for LunaEngine (Inspired by Roblox Studio)

ENGINE PATH:
lunaengine -> ui -> tween.py

DESCRIPTION:
A comprehensive tween animation system inspired by Roblox Studio, providing
smooth property animations with various easing functions, sequencing,
and lifecycle management.

FEATURES:
- 25+ easing types (Linear, Quadratic, Cubic, Elastic, Bounce, etc.)
- Property animations: position, size, rotation, opacity, colors, custom properties
- Lifecycle callbacks: on_start, on_update, on_complete, on_loop
- Animation control: play, pause, resume, cancel, stop
- Sequencing: parallel and sequential animation groups
- Looping: finite loops, infinite loops, yoyo effect
- Progress tracking: get current animation progress percentage
- Global management: AnimationHandler for engine-wide animation control

USAGE EXAMPLES:
# Simple animation
tween = Tween.create(button)
tween.to(x=100, y=200, duration=1.0, easing=EasingType.QUAD_IN_OUT)
tween.play()

# Sequence of animations
sequence = Tween.sequence([
   Tween.create(element).to(x=100, duration=0.5),
   Tween.create(element).to(y=200, duration=0.5),
])

# Animation with callbacks and loops
tween = Tween.create(element)
tween.to(rotation=360, duration=2.0, easing=EasingType.ELASTIC_OUT)
tween.set_loops(3, yoyo=True)
tween.set_callbacks(
   on_start=lambda: print("Animation started"),
   on_complete=lambda: print("Animation completed")
)
tween.play()

class EasingType

Description

Easing function types inspired by Roblox Studio.

Attributes
LINEAR: Any = 'Linear'
QUAD_IN: Any = 'QuadIn'
QUAD_OUT: Any = 'QuadOut'
QUAD_IN_OUT: Any = 'QuadInOut'
CUBIC_IN: Any = 'CubicIn'
CUBIC_OUT: Any = 'CubicOut'
CUBIC_IN_OUT: Any = 'CubicInOut'
QUART_IN: Any = 'QuartIn'
QUART_OUT: Any = 'QuartOut'
QUART_IN_OUT: Any = 'QuartInOut'
QUINT_IN: Any = 'QuintIn'
QUINT_OUT: Any = 'QuintOut'
QUINT_IN_OUT: Any = 'QuintInOut'
SINE_IN: Any = 'SineIn'
SINE_OUT: Any = 'SineOut'
SINE_IN_OUT: Any = 'SineInOut'
EXPO_IN: Any = 'ExpoIn'
EXPO_OUT: Any = 'ExpoOut'
EXPO_IN_OUT: Any = 'ExpoInOut'
CIRC_IN: Any = 'CircIn'
CIRC_OUT: Any = 'CircOut'
CIRC_IN_OUT: Any = 'CircInOut'
ELASTIC_IN: Any = 'ElasticIn'
ELASTIC_OUT: Any = 'ElasticOut'
ELASTIC_IN_OUT: Any = 'ElasticInOut'
BACK_IN: Any = 'BackIn'
BACK_OUT: Any = 'BackOut'
BACK_IN_OUT: Any = 'BackInOut'
BOUNCE_IN: Any = 'BounceIn'
BOUNCE_OUT: Any = 'BounceOut'
BOUNCE_IN_OUT: Any = 'BounceInOut'
Methods

No methods defined.

class TweenProperty

Description

Represents a property to be animated with its start and end values.

Attributes
start: Any = None
end: Any = None
original_start: Any = None
original_end: Any = None
Methods

No methods defined.

class Tween

Description

Main tween class for animating object properties.

Provides Roblox Studio-like API for creating and controlling animations.

Attributes
_active_tweens: List['Tween'] = []
Methods
def __init__(self: Any, target: Any) -> Any
Initialize a new tween animation.

Args:
   target: The object to animate (UIElement or any object with properties)
def create(cls: Any, target: Any) -> 'Tween'
Factory method to create a new tween (Roblox Studio style).

Args:
   target: Object to animate
   
Returns:
   Tween: New tween instance
def to(self: Any, **kwargs: dict) -> 'Tween'
Set target values for the animation (Roblox Studio style).

Args:
   **kwargs: Properties to animate with their target values
            Special parameters: duration, easing
            Example: x=100, y=200, duration=1.0, easing=EasingType.QUAD_IN_OUT
   
Returns:
   Tween: Self for method chaining
def set_delay(self: Any, delay: float) -> 'Tween'
Add a delay to the animation.

Args:
   delay: Delay in seconds
   
Returns:
   Tween: Self for method chaining
def play(self: Any) -> 'Tween'
Start playing the animation.

Returns:
   Tween: Self for method chaining
def pause(self: Any) -> 'Tween'
Pause the animation.

Returns:
   Tween: Self for method chaining
def resume(self: Any) -> 'Tween'
Resume a paused animation.

Returns:
   Tween: Self for method chaining
def cancel(self: Any) -> 'Tween'
Cancel the animation and reset properties to initial state.

Returns:
   Tween: Self for method chaining
def stop(self: Any, reset: bool = False) -> 'Tween'
Stop the animation.

Args:
   reset: If True, reset properties to initial values
   
Returns:
   Tween: Self for method chaining
def set_duration(self: Any, duration: float) -> 'Tween'
Change the duration of the animation.

Args:
   duration: New duration in seconds (must be positive)
   
Returns:
   Tween: Self for method chaining
   
Raises:
   ValueError: If duration is not positive
def _get_elapsed_time(self: Any) -> float
Get elapsed time since animation started.

Returns:
   float: Elapsed time in seconds
def get_progress(self: Any) -> float
Get current animation progress as a percentage (0.0 to 1.0).

Returns:
   float: Animation progress (0.0 = start, 1.0 = end)
def get_progress_percentage(self: Any) -> float
Get current animation progress as a percentage (0 to 100).

Returns:
   float: Animation progress percentage (0 to 100)
def update(self: Any, dt: Optional[float] = None) -> bool
Update the animation state.

Args:
   dt: Delta time in seconds (optional, uses real time if None)
   
Returns:
   bool: True if animation is complete, False otherwise
def _update_property(self: Any, prop_name: str, prop: TweenProperty, progress: float) -> Any
Update a specific property based on animation progress.

Args:
   prop_name: Name of the property
   prop: TweenProperty object
   progress: Eased animation progress (0.0 to 1.0)
def _complete_animation(self: Any) -> Any
Mark animation as complete and fire callbacks.
def _apply_easing(self: Any, t: float) -> float
Apply easing function to raw progress.

Args:
   t: Raw progress (0.0 to 1.0)
   
Returns:
   float: Eased progress
def _bounce_out(t: float) -> float
Bounce out easing function.

Args:
   t: Input value (0.0 to 1.0)
   
Returns:
   float: Bounced value
def set_easing(self: Any, easing: Union[EasingType, str]) -> 'Tween'
Set the easing function for the animation.

Args:
   easing: EasingType enum or string name
   
Returns:
   Tween: Self for method chaining
def set_loops(self: Any, loops: int, yoyo: bool = False) -> 'Tween'
Set number of loops and yoyo mode.

Args:
   loops: Number of loops (0 = no loop, -1 = infinite)
   yoyo: If True, reverse animation on each loop
   
Returns:
   Tween: Self for method chaining
def set_callbacks(self: Any, on_start: Optional[Callable] = None, on_update: Optional[Callable[['Tween', float], None]] = None, on_complete: Optional[Callable] = None, on_loop: Optional[Callable[[int], None]] = None, on_stop: Optional[Callable] = None) -> 'Tween'
Set lifecycle callbacks for the animation.

Args:
   on_start: Called when animation starts
   on_update: Called each frame with (tween, progress)
   on_complete: Called when animation completes
   on_loop: Called after each loop with loop number
   on_stop: Called when animation is stopped
   
Returns:
   Tween: Self for method chaining
def update_all(cls: Any, dt: Optional[float] = None) -> Any
Update all active tweens.

Args:
   dt: Delta time in seconds (optional)
def cancel_all(cls: Any) -> Any
Cancel all active tweens.
def pause_all(cls: Any) -> Any
Pause all active tweens.
def resume_all(cls: Any) -> Any
Resume all paused tweens.
def get_active_count(cls: Any) -> int
Get number of active tweens.

Returns:
   int: Number of active tweens
def sequence(cls: Any, tweens: List['Tween']) -> 'TweenSequence'
Create a sequence of tweens (executes one after another).

Args:
   tweens: List of tweens to execute sequentially
   
Returns:
   TweenSequence: Sequence controller
def parallel(cls: Any, tweens: List['Tween']) -> 'TweenParallel'
Create a parallel group of tweens (executes all simultaneously).

Args:
   tweens: List of tweens to execute in parallel
   
Returns:
   TweenParallel: Parallel group controller

class AnimationHandler

Description

Global animation handler for managing all tweens in the engine.

Integrates with LunaEngine to provide centralized animation control.

Methods
def __init__(self: Any, engine: Any = None) -> Any
Initialize the animation handler.

Args:
   engine: Reference to LunaEngine instance (optional)
def add(self: Any, name: str, tween: Tween, auto_play: bool = True) -> Tween
Add a tween to the handler with a name.

Args:
   name: Unique name for the animation
   tween: Tween instance
   auto_play: If True, start playing immediately
   
Returns:
   Tween: The added tween
def get(self: Any, name: str) -> Optional[Tween]
Get a tween by name.

Args:
   name: Animation name
   
Returns:
   Optional[Tween]: Tween instance or None if not found
def remove(self: Any, name: str, stop: bool = True) -> bool
Remove a tween by name.

Args:
   name: Animation name
   stop: If True, stop the animation before removing
   
Returns:
   bool: True if animation was found and removed
def pause(self: Any, name: str) -> bool
Pause a specific animation.

Args:
   name: Animation name
   
Returns:
   bool: True if animation was found and paused
def resume(self: Any, name: str) -> bool
Resume a specific animation.

Args:
   name: Animation name
   
Returns:
   bool: True if animation was found and resumed
def stop(self: Any, name: str, reset: bool = False) -> bool
Stop a specific animation.

Args:
   name: Animation name
   reset: If True, reset properties to initial values
   
Returns:
   bool: True if animation was found and stopped
def cancel(self: Any, name: str) -> bool
Cancel a specific animation (stops and resets).

Args:
   name: Animation name
   
Returns:
   bool: True if animation was found and canceled
def is_playing(self: Any, name: str) -> bool
Check if an animation is currently playing.

Args:
   name: Animation name
   
Returns:
   bool: True if animation exists and is playing
def is_paused(self: Any, name: str) -> bool
Check if an animation is paused.

Args:
   name: Animation name
   
Returns:
   bool: True if animation exists and is paused
def update(self: Any, dt: Optional[float] = None) -> Any
Update all animations managed by this handler.

Args:
   dt: Delta time in seconds
def _cleanup_completed(self: Any) -> Any
Remove completed animations from the named dictionary.
def pause_all(self: Any) -> Any
Pause all animations.
def resume_all(self: Any) -> Any
Resume all animations.
def stop_all(self: Any, reset: bool = False) -> Any
Stop all animations.
def cancel_all(self: Any) -> Any
Cancel all animations (stop and reset).
def get_active_count(self: Any) -> int
Get number of active animations.

Returns:
   int: Number of active animations
def clear(self: Any) -> Any
Clear all animations from the handler.

class TweenGroup

Description

Base class for groups of tweens (sequential or parallel).

Methods
def __init__(self: Any, tweens: List[Tween]) -> Any
Initialize a tween group.

Args:
   tweens: List of tweens in the group
def play(self: Any) -> Any
Start playing the tween group.
def _play_current(self: Any) -> Any
Start playing the current tween in the group.
def update(self: Any, dt: Optional[float] = None) -> bool
Update the tween group.

Args:
   dt: Delta time
   
Returns:
   bool: True if group is complete
def cancel(self: Any) -> Any
Cancel the tween group.

class TweenSequence

Description

Plays tweens in sequence (one after another).

Methods
def _play_current(self: Any) -> Any
Start playing the current tween in sequence.
def update(self: Any, dt: Optional[float] = None) -> bool
Update the tween sequence.

Args:
   dt: Delta time
   
Returns:
   bool: True if sequence is complete

class TweenParallel

Description

Plays tweens in parallel (all at the same time).

Methods
def play(self: Any) -> Any
Start playing all tweens in parallel.
def update(self: Any, dt: Optional[float] = None) -> bool
Update all tweens in parallel.

Args:
   dt: Delta time
   
Returns:
   bool: True if all tweens are complete
Back to Ui Module