Comprehensive animation system providing built-in effects like banners, stars, matrix rain, snow, fire, and custom animations. The effects system enables both simple text animations and complex visual scenes with timing control, transitions, and interactive elements.
The Effect class serves as the foundation for all animations, providing lifecycle management, timing control, and screen integration.
class Effect:
"""Abstract base class for all visual effects"""
def __init__(self, screen, start_frame=0, stop_frame=0):
"""
Initialize effect with timing parameters.
Parameters:
- screen (Screen): Target screen for rendering
- start_frame (int): Frame number to start effect (0 = immediately)
- stop_frame (int): Frame number to stop effect (0 = infinite)
"""
def reset(self):
"""Reset effect to initial state for replay"""
def update(self, frame_no):
"""
Update effect for current animation frame.
Parameters:
- frame_no (int): Current frame number
Returns:
bool: True if effect should continue, False if finished
"""
def stop_frame(self):
"""Get the frame number when effect should stop"""
@property
def frame_update_count(self):
"""Number of frames between updates"""
@property
def safe_to_default_unhandled_input(self):
"""Whether effect handles its own input"""Scene provides container functionality for managing multiple effects with duration control and lifecycle coordination.
class Scene:
"""Container for effects with duration and lifecycle management"""
def __init__(self, effects, duration, clear=True, name=None):
"""
Initialize scene with effects and timing.
Parameters:
- effects (list): List of Effect objects to include
- duration (int): Scene duration in frames (-1 = infinite)
- clear (bool): Whether to clear screen before scene
- name (str): Optional scene name for identification
"""
def add_effect(self, effect):
"""
Add effect to scene.
Parameters:
- effect (Effect): Effect to add to scene
"""
def remove_effect(self, effect):
"""
Remove effect from scene.
Parameters:
- effect (Effect): Effect to remove from scene
"""
@property
def name(self):
"""Scene name"""
@property
def duration(self):
"""Scene duration in frames"""
@property
def effects(self):
"""List of effects in scene"""Animated text effects for banners, scrolling, and visual text treatments.
class Print(Effect):
"""Simple text printing effect with customizable appearance"""
def __init__(self, screen, renderer, y, x=None, colour=7, attr=0, bg=0, clear=False, transparent=True, speed=4, **kwargs):
"""
Initialize text printing effect.
Parameters:
- screen (Screen): Target screen
- renderer (Renderer): Text content renderer
- y (int): Y position for text
- x (int): X position (None = centered)
- colour (int): Text color (default: 7)
- attr (int): Text attributes (default: 0)
- bg (int): Background color (default: 0)
- clear (bool): Whether to clear text before stopping (default: False)
- transparent (bool): Whether to print spaces for overlay (default: True)
- speed (int): Refresh rate in frames between updates (default: 4)
- **kwargs: Additional keyword arguments passed to Effect
"""
class BannerText(Effect):
"""Scrolling banner text effect"""
def __init__(self, screen, renderer, y, colour=7, attr=2, bg=0, speed=1, transparent=True):
"""
Initialize scrolling banner.
Parameters:
- screen (Screen): Target screen
- renderer (Renderer): Text content renderer
- y (int): Y position for banner
- colour (int): Text color
- attr (int): Text attributes
- bg (int): Background color
- speed (int): Scrolling speed
- transparent (bool): Whether background is transparent
"""
class Scroll(Effect):
"""Scrolling text effect for long content"""
def __init__(self, screen, renderer, y, colour=7, attr=2, bg=0, speed=1, transparent=True):
"""
Initialize scrolling text effect.
Parameters:
- screen (Screen): Target screen
- renderer (Renderer): Text content renderer
- y (int): Y position for scrolling area
- colour (int): Text color
- attr (int): Text attributes
- bg (int): Background color
- speed (int): Scrolling speed
- transparent (bool): Whether background is transparent
"""
class Cycle(Effect):
"""Color cycling effect for text"""
def __init__(self, screen, renderer, y, colour=7, bg=0, speed=1):
"""
Initialize color cycling effect.
Parameters:
- screen (Screen): Target screen
- renderer (Renderer): Text content renderer
- y (int): Y position for text
- colour (int): Base color for cycling
- bg (int): Background color
- speed (int): Cycling speed
"""
class Mirage(Effect):
"""Text shimmering/mirage effect"""
def __init__(self, screen, renderer, y, colour=7, bg=0, start_frame=0, stop_frame=0):
"""
Initialize mirage shimmering effect.
Parameters:
- screen (Screen): Target screen
- renderer (Renderer): Text content renderer
- y (int): Y position for text
- colour (int): Text color
- bg (int): Background color
- start_frame (int): Start frame
- stop_frame (int): Stop frame
"""Built-in visual effects for creating dynamic backgrounds and atmospheric elements.
class Stars(Effect):
"""Starfield animation effect"""
def __init__(self, screen, count, stop_frame=0):
"""
Initialize starfield effect.
Parameters:
- screen (Screen): Target screen
- count (int): Number of stars to display
- stop_frame (int): Frame to stop effect (0 = infinite)
"""
class Matrix(Effect):
"""Matrix-style falling characters effect"""
def __init__(self, screen, stop_frame=0):
"""
Initialize Matrix rain effect.
Parameters:
- screen (Screen): Target screen
- stop_frame (int): Frame to stop effect (0 = infinite)
"""
class Snow(Effect):
"""Falling snow particle effect"""
def __init__(self, screen, stop_frame=0):
"""
Initialize snow effect.
Parameters:
- screen (Screen): Target screen
- stop_frame (int): Frame to stop effect (0 = infinite)
"""
class RandomNoise(Effect):
"""Random pixel noise effect"""
def __init__(self, screen, stop_frame=0):
"""
Initialize random noise effect.
Parameters:
- screen (Screen): Target screen
- stop_frame (int): Frame to stop effect (0 = infinite)
"""
class Wipe(Effect):
"""Screen wipe transition effect"""
def __init__(self, screen, bg=0, start_frame=0):
"""
Initialize screen wipe effect.
Parameters:
- screen (Screen): Target screen
- bg (int): Background color for wipe
- start_frame (int): Frame to start effect
"""More complex effects including fractals, clocks, and geometric animations.
class Clock(Effect):
"""Digital clock display effect"""
def __init__(self, screen, x, y, colour=7, attr=2, bg=0, start_frame=0):
"""
Initialize digital clock effect.
Parameters:
- screen (Screen): Target screen
- x (int): X position
- y (int): Y position
- colour (int): Clock color
- attr (int): Text attributes
- bg (int): Background color
- start_frame (int): Frame to start effect
"""
class Cog(Effect):
"""Rotating cog/gear animation"""
def __init__(self, screen, x, y, radius, colour=7, bg=0, start_frame=0, stop_frame=0):
"""
Initialize rotating cog effect.
Parameters:
- screen (Screen): Target screen
- x (int): Center X position
- y (int): Center Y position
- radius (int): Cog radius
- colour (int): Cog color
- bg (int): Background color
- start_frame (int): Frame to start effect
- stop_frame (int): Frame to stop effect
"""
class Julia(Effect):
"""Julia set fractal visualization"""
def __init__(self, screen, stop_frame=0):
"""
Initialize Julia set effect.
Parameters:
- screen (Screen): Target screen
- stop_frame (int): Frame to stop effect (0 = infinite)
"""
class Background(Effect):
"""Static background effect"""
def __init__(self, screen, bg=0, start_frame=0):
"""
Initialize static background.
Parameters:
- screen (Screen): Target screen
- bg (int): Background color
- start_frame (int): Frame to start effect
"""
class Scroll(Effect):
"""Scrolling text effect for long content"""
def __init__(self, screen, rate=1, start_frame=0, stop_frame=0):
"""
Initialize scrolling effect.
Parameters:
- screen (Screen): Target screen
- rate (int): Scrolling rate in frames per line
- start_frame (int): Frame to start effect
- stop_frame (int): Frame to stop effect
"""
class Wipe(Effect):
"""Screen wipe transition effect"""
def __init__(self, screen, bg=0, start_frame=0):
"""
Initialize screen wipe effect.
Parameters:
- screen (Screen): Target screen
- bg (int): Background color for wipe
- start_frame (int): Frame to start effect
"""Moving sprite effects for character-based animations and custom objects.
class Sprite(Effect):
"""Moving sprite animation effect"""
def __init__(self, screen, renderer_dict, path, colour=7, attr=2, bg=0, clear=True, start_frame=0, stop_frame=0):
"""
Initialize sprite animation.
Parameters:
- screen (Screen): Target screen
- renderer_dict (dict): Dictionary mapping animation states to renderers
- path (Path): Animation path for sprite movement
- colour (int): Sprite color
- attr (int): Text attributes
- bg (int): Background color
- clear (bool): Whether to clear sprite trail
- start_frame (int): Frame to start animation
- stop_frame (int): Frame to stop animation
"""
def overlaps(self, other_sprite, use_new_pos=False):
"""
Check if sprite overlaps with another sprite.
Parameters:
- other_sprite (Sprite): Other sprite to check collision with
- use_new_pos (bool): Whether to use new position for check
Returns:
bool: True if sprites overlap
"""from asciimatics.screen import ManagedScreen
from asciimatics.scene import Scene
from asciimatics.effects import Print, Stars
from asciimatics.renderers import FigletText
from asciimatics.exceptions import ResizeScreenError
def demo(screen):
effects = [
Stars(screen, 200), # Background stars
Print(screen,
FigletText("HELLO WORLD", font='big'),
screen.height // 2 - 3,
colour=Screen.COLOUR_GREEN)
]
scenes = [Scene(effects, 500)]
screen.play(scenes, stop_on_resize=True)
try:
ManagedScreen(demo).run()
except ResizeScreenError:
passfrom asciimatics.screen import ManagedScreen
from asciimatics.scene import Scene
from asciimatics.effects import BannerText, Matrix
from asciimatics.renderers import FigletText
def banner_demo(screen):
effects = [
Matrix(screen), # Background effect
BannerText(screen,
FigletText("*** SCROLLING BANNER ***", font='slant'),
screen.height // 2,
colour=Screen.COLOUR_YELLOW)
]
screen.play([Scene(effects, -1)], stop_on_resize=True)
ManagedScreen(banner_demo).run()from asciimatics.screen import ManagedScreen
from asciimatics.scene import Scene
from asciimatics.effects import Print, Snow, Wipe
from asciimatics.renderers import FigletText
def multi_scene_demo(screen):
# Scene 1: Introduction with snow
scene1_effects = [
Snow(screen),
Print(screen, FigletText("SCENE 1"), screen.height // 2)
]
# Transition wipe
wipe_effects = [
Wipe(screen, bg=Screen.COLOUR_BLACK)
]
# Scene 2: Different content
scene2_effects = [
Print(screen, FigletText("SCENE 2"), screen.height // 2,
colour=Screen.COLOUR_RED)
]
scenes = [
Scene(scene1_effects, 200),
Scene(wipe_effects, 20),
Scene(scene2_effects, 200)
]
screen.play(scenes, stop_on_resize=True)
ManagedScreen(multi_scene_demo).run()from asciimatics.effects import Effect
from asciimatics import constants
class BouncingBall(Effect):
"""Custom bouncing ball effect"""
def __init__(self, screen, start_frame=0):
super().__init__(screen, start_frame=start_frame)
self._x = 0
self._y = screen.height // 2
self._dx = 1
self._dy = 1
def update(self, frame_no):
# Clear previous position
self._screen.print_at(" ", self._x, self._y)
# Update position
self._x += self._dx
self._y += self._dy
# Bounce off walls
if self._x <= 0 or self._x >= self._screen.width - 1:
self._dx = -self._dx
if self._y <= 0 or self._y >= self._screen.height - 1:
self._dy = -self._dy
# Draw ball
self._screen.print_at("O", self._x, self._y,
constants.COLOUR_RED, constants.A_BOLD)
return True # Continue animation
def reset(self):
self._x = 0
self._y = self._screen.height // 2
# Usage
def bouncing_demo(screen):
effects = [BouncingBall(screen)]
screen.play([Scene(effects, -1)], stop_on_resize=True)
ManagedScreen(bouncing_demo).run()