timer.py

Timer system for LunaEngine

LOCATION: lunaengine/utils/timer.py

This module provides a timer management system for the LunaEngine framework.
It allows creating, managing, and triggering timers with callbacks.

class TimeCounter

Description

Represents a single timer instance.

Attributes:
   name (str): Unique identifier for the timer
   start_time (float): When the timer was started (in seconds since epoch)
   duration (float): How long the timer runs (in seconds)
   callback (Optional[Callable]): Function to call when timer completes
   callback_args (tuple): Arguments to pass to the callback function
   callback_kwargs (dict): Keyword arguments to pass to the callback function
   repeats (bool): Whether the timer should restart after completion
   paused (bool): Whether the timer is currently paused
   paused_time (float): How long the timer has been paused
   destroyed (bool): Whether the timer has been marked for removal

Attributes
name: str = None
start_time: float = None
duration: float = None
callback: Optional[Callable] = None
callback_args: tuple = field(default_factory=tuple)
callback_kwargs: dict = field(default_factory=dict)
repeats: bool = False
paused: bool = False
paused_time: float = 0.0
destroyed: bool = False
Methods

No methods defined.

class Timer

Description

Main timer manager for LunaEngine.

Manages multiple timers, updates them, and triggers callbacks.
Should be updated every frame in the game loop via update() method.

Example:
   >>> timer = Timer()
   >>> timer.add("enemy_spawn", 2.0, spawn_enemy, repeats=True)
   >>> # In game loop:
   >>> while running:
   >>>     timer.update()

Methods
def __init__(self: Any) -> None
Initialize a new Timer manager with empty timer dictionary.
def add(self: Any, name: str, duration: float, callback: Optional[Callable] = None, callback_args: tuple = (), callback_kwargs: dict = None, repeats: bool = False) -> bool
Add a new timer to the system.

Args:
   name (str): Unique identifier for the timer
   duration (float): Timer duration in seconds
   callback (Optional[Callable]): Function to call when timer completes
   callback_args (tuple): Arguments to pass to the callback function
   callback_kwargs (dict): Keyword arguments to pass to the callback function
   repeats (bool): Whether the timer should restart after completion
   
Returns:
   bool: True if timer was added, False if a timer with this name already exists
   
Example:
   >>> timer.add("powerup", 10.0, remove_powerup, repeats=False)
def add_timer_to(self: Any, duration: float, callback: Callable, callback_args: tuple = (), callback_kwargs: dict = None, repeats: bool = False) -> str
Add a timer with an auto-generated name and return its name.

Args:
   duration (float): Timer duration in seconds
   callback (Callable): Function to call when timer completes
   callback_args (tuple): Arguments to pass to the callback function
   callback_kwargs (dict): Keyword arguments to pass to the callback function
   repeats (bool): Whether the timer should restart after completion
   
Returns:
   str: The auto-generated name of the timer
   
Example:
   >>> timer_id = timer.add_timer_to(5.0, lambda: print("5 seconds passed"))
def remove(self: Any, name: str) -> bool
Remove a timer from the system.

Args:
   name (str): Name of the timer to remove
   
Returns:
   bool: True if timer was removed, False if timer didn't exist
def destroy(self: Any, name: str) -> bool
Mark a timer for destruction (will be removed on next update).

Args:
   name (str): Name of the timer to destroy
   
Returns:
   bool: True if timer was marked for destruction, False if timer didn't exist
def pause(self: Any, name: str) -> bool
Pause a running timer.

Args:
   name (str): Name of the timer to pause
   
Returns:
   bool: True if timer was paused, False if timer didn't exist or was already paused
def resume(self: Any, name: str) -> bool
Resume a paused timer.

Args:
   name (str): Name of the timer to resume
   
Returns:
   bool: True if timer was resumed, False if timer didn't exist or wasn't paused
def reset(self: Any, name: str) -> bool
Reset a timer to start counting from now.

Args:
   name (str): Name of the timer to reset
   
Returns:
   bool: True if timer was reset, False if timer didn't exist
def get_elapsed(self: Any, name: str) -> Optional[float]
Get elapsed time for a timer.

Args:
   name (str): Name of the timer
   
Returns:
   Optional[float]: Elapsed time in seconds, or None if timer doesn't exist
def get_remaining(self: Any, name: str) -> Optional[float]
Get remaining time for a timer.

Args:
   name (str): Name of the timer
   
Returns:
   Optional[float]: Remaining time in seconds, or None if timer doesn't exist
def is_done(self: Any, name: str) -> Optional[bool]
Check if a timer has completed.

Args:
   name (str): Name of the timer
   
Returns:
   Optional[bool]: True if timer is done, False if still running, None if timer doesn't exist
def exists(self: Any, name: str) -> bool
Check if a timer exists.

Args:
   name (str): Name of the timer
   
Returns:
   bool: True if timer exists
def is_paused(self: Any, name: str) -> Optional[bool]
Check if a timer is paused.

Args:
   name (str): Name of the timer
   
Returns:
   Optional[bool]: True if timer is paused, False if running, None if timer doesn't exist
def clear(self: Any) -> None
Remove all timers from the system.
def update(self: Any) -> List[str]
Update all timers. Should be called every frame in the game loop.

Checks all timers for completion, triggers callbacks, and removes destroyed timers.

Returns:
   List[str]: Names of timers that completed during this update
   
Example:
   >>> completed_timers = timer.update()
   >>> for timer_name in completed_timers:
   >>>     print(f"Timer {timer_name} completed!")
def wait_for_end(self: Any, name: str, timeout: float = 0.0) -> bool
Block until a timer completes.

Warning: This blocks the main thread! Use sparingly.

Args:
   name (str): Name of the timer to wait for
   timeout (float): Maximum time to wait in seconds (0 = no timeout)
   
Returns:
   bool: True if timer completed, False if timeout reached or timer doesn't exist
   
Example:
   >>> timer.add("wait_test", 3.0)
   >>> timer.wait_for_end("wait_test")  # Blocks for 3 seconds
def get_all_timers(self: Any) -> List[str]
Get names of all active timers.

Returns:
   List[str]: List of timer names
def get_timer_count(self: Any) -> int
Get the number of active timers.

Returns:
   int: Number of timers

Global Functions

def get_global_timer() -> Timer

Get or create the global singleton timer instance.

Returns:
   Timer: Global timer instance
   
Example:
   >>> from lunaengine.utils.timer import get_global_timer
   >>> timer = get_global_timer()
   >>> timer.add("global_timer", 1.0, lambda: print("Global timer fired!"))

Back to Utils Module