animpy 2.5.0

A simple terminal animation library

Animpy

Make cool terminal animations without the pain. Move text around, use RGB colors, play audio, and build actual animations. Animpy is meant for utilizing the terminal in many different ways. There is even a feature where you can make your own minigames right in the terminal! Works great on modern terminals. If you like this please star my project, it helps out a ton!

Examples

Basic & Beginner

• Linear interpolation - Learn smooth value transitions with the lerp function
• Loading screen - Create a simple loading animation
• The zen of python - Animated text display with color effects

Visual Effects & Particles

• Collision example - Detect and handle text collisions
• Physics demo - Build gravity, bounce, and force-based motion with PhysicsScene

Interactive & Games

• Player Controls - Real-time keyboard input with movement and boundaries
• Tag game - Interactive tag game with collision detection
• Audio example - Load and play background music with effects

And many more!

Install

pip install animpy

Quick Start

import animpy

scene = animpy.Scene()
text = animpy.Text("Hello!", 10, 5, r=255, g=100, b=50)
scene.add(text)
scene.render()

How It Works

Text – Create animated text:

text = animpy.Text("Hi", 0, 0, r=255, g=0, b=0)
text.moveX(10)  # Move right
text.moveY(5)   # Move down
text.slide_to_pos(animpy.Coords(20, 10), speed=1)  # Move toward a target position
text.centerX()  # Center horizontally
text.centerY()  # Center vertically
text.change_rgb_values(0, 255, 0)  # Change color
text.collides_with(other_text)  # Check collision with another text
text.on_collide_callback(other_text, callback)  # Run a callback when collision occurs
text.width, text.height  # Get dimensions
text.change_frame()  # Cycle through frames (if text was created from a list)

Particle – Create and manage particles with velocity and lifetime:

particle = animpy.Particle("💥", 10, 5, r=255, g=100, b=50, lifetime=3.0)
particle.burst(scene, count=20, speed=2.0)  # Emit burst of particles in all directions
particle.emit(scene)  # Emit a single particle
particle.change_rgb_values(0, 255, 0)  # Change particle color
particle.update_all(delta_time)  # Update all emitted particles
particle.is_dead()  # Check if all particles have expired
particle.velocity_x = 1.5
particle.velocity_y = -2.0

EffectText – Text with advanced built-in effects:

effect_text = animpy.EffectText("Shaky!", 10, 5)
effect_text.shaking_text(intensity=2)  # Shake the text horizontally and vertically
effect_text.gravity_text(floor=15, gravity=0.5)  # Apply gravity toward a floor
effect_text.decaying_text(time=3.0, decay_rate=0.5)  # Shrink text over time
effect_text.fade_out_text(time=2.0, fade_rate=0.5)  # Fade text color to black
effect_text.lerp_text(20, 10, t=0.1)  # Move smoothly toward a target
effect_text.pulse_text(time=1.2, pulse_rate=0.5)  # Pulse brightness over time

Shapes – Create basic shapes as text:

rect = animpy.Shapes.rectangle(20, 5, "#")
circle = animpy.Shapes.circle(4, "*")
polygon = animpy.Shapes.polygon([(0,0), (10,0), (5,5)], "@")
line = animpy.Shapes.line(0, 0, 20, 10, "-")
heart = animpy.Shapes.heart(5, "♥")
triangle = animpy.Shapes.triangle(0, 0, 10, 0, 5, 5, "^")
ellipse = animpy.Shapes.ellipse(10, 5, 8, 4, "o")

box = animpy.Text(rect, 5, 3, r=100, g=200, b=255)
ball = animpy.Text(circle, 40, 10, r=255, g=120, b=120)
triangle = animpy.Text(polygon, 20, 10, r=200, g=200, b=0)
line_text = animpy.Text(line, 0, 0, r=255, g=255, b=255)
heart_text = animpy.Text(heart, 30, 15, r=255, g=0, b=255)
triangle_text = animpy.Text(triangle, 10, 20, r=0, g=255, b=255)
ellipse_text = animpy.Text(ellipse, 50, 5, r=255, g=255, b=0)

Group – Group multiple texts together:

group = animpy.Group(text1, text2, text3)
group.add(text4)  # Add another text to the group
group.remove(text2)  # Remove text2 from the group
group.position(5, 0)  # Move the entire group by a vector
group.change_rgb_values(255, 0, 0)  # Change the color of all items
group.change_rgb_values_one(text1, 0, 255, 0)  # Change a single item in the group

Coords - Named tuple helper for keyframe coordinates:

coords = animpy.Coords(10, 5)

Keyframe - Helper object for path-based motion:

frame = animpy.Keyframe(animpy.Coords(20, 10))

Keychains - Follow a path of keyframes:

path = animpy.Keychains(frame1, frame2, frame3)
path.follow_path(text, speed=1)

Scene – Render everything:

scene = animpy.Scene()
scene.add(text1, text2, text3)
scene.remove(text2)
scene.render()
scene.update(delta_time)  # Update particles and clean expired items
scene.set_bg_rgb(0, 0, 255)
scene.clear()
scene.shake(intensity=2)
scene.dt  # Get time since last frame

PhysicsScene – Add gravity, bounce, and force-based motion:

scene = animpy.PhysicsScene()
scene.add(text)
scene.apply_gravity(text)
scene.apply_friction(text, friction=0.1)
scene.bounce(text, bounce_factor=0.7)
scene.apply_physics(text)  # Apply gravity, friction, and bounce in one call
scene.angular_motion(text, angle=45, speed=2.0)
scene.push(text, force_x=1.0, force_y=-0.5)

InteractiveScene – Handle real-time input and callbacks:

scene = animpy.InteractiveScene()
scene.add(text1, text2)
scene.key_pressed("w")
scene.key_released("w")
scene.on_key_press_callback("w", callback)
scene.on_key_release_callback("w", callback)
scene.mouse_pressed("left")
scene.mouse_position()
scene.on_mouse_press_callback("left", callback)
scene.mouse_release("left", callback)
scene.mouse_release_callback("left", callback)
scene.quick_exit("esc")
scene.quick_exit_callback("esc", callback)
scene.limit_to_bounds(text)
scene.limit_group_to_bounds(group)

Audio – Play sounds:

audio = animpy.Audio()
audio.load("bg", "music.mp3")
audio.play("bg", loop=-1)
audio.set_volume("bg", 0.5)
audio.stop("bg")
audio.stop_all()
audio.is_playing("bg")
audio.play_for_time("bg", duration=5.0)

Animpy (extras) – Utility helpers:

animpy.lerp(start, end, t)
animpy.hide_cursor()
animpy.show_cursor()
animpy.clear_screen()
animpy.print_centered("Hello, World!")
animpy.print_with_color("Colored Text", r=255, g=0, b=0)

Support the project

Version History

v2.5.0

• Release bump to v2.5.0 — consolidation release that adds small helpers and improves stability.

• Highlights and added helpers:

  • Coords: distance_to(other), offset(dx, dy) — easy coordinate math return new Coords.
  • Keyframe / KeyChains: Keyframe.set_pos(pos), Keyframe.distance_to(other); KeyChains.append(keyframe), clear(), reverse_path(), is_complete — path composition and inspection.
  • Audio: pause(name), resume(name), fade_in(name, duration), fade_out(name, duration) — smoother playback controls.
  • Group: clear(), contains(item), find_by_color(r,g,b) — group management and querying.
  • Particle: set_velocity(vx,vy), apply_force(fx,fy), set_color(r,g,b), reset(x,y,lifetime=None), is_alive() — runtime control for particle systems.
  • Scene / PhysicsScene: clear_items(), count_items(), find_items_at(x,y), set_gravity(g), apply_wind(obj, wind_x), plus floor/wall helpers and bind_key/bind_mouse for callbacks.
  • Shapes: added square(size,char) and donut(outer,inner,char), and fixed newline handling across shape builders.
  • Text / EffectText: convenience setters set_frame, set_text, set_position, move_to, set_color, plus type_out(text,speed,scene) and fall(velocity,floor). EffectText also exposes set_velocity, reset_velocity, apply_force, and fade_in_text(time,fade_rate).

For full method list see the API reference and release notes in the docs.

v2.1.0

• Added 4 new shapes to Shapes class:
  • line(x1, y1, x2, y2, char) for creating a line shape
  • ellipse(center_x, center_y, radius_x, radius_y, char) for creating an ellipse shape
  • heart(size, char) for creating a heart shape
  • triangle(x1, y1, x2, y2, x3, y3, char) for creating a triangle shape
• Added 3 new utility functions to the main namespace:
  • clear_screen() for clearing the terminal screen
  • print_centered(text) for printing text centered in the terminal
  • print_with_color(text, r, g, b) for printing text with custom RGB colors

v2.0.0

• Added new PhysicsScene class for gravity, friction, bounce, and force-driven motion
  • apply_gravity(obj)
  • apply_friction(obj, friction=0.1)
  • bounce(obj, bounce_factor=0.5)
  • apply_physics(obj)
  • angular_motion(obj, angle, speed)
  • push(obj, force_x, force_y)
• Expanded EffectText with more text motion and visual effects:
  • fade_out_text(time, fade_rate)
  • lerp_text(target_x, target_y, t)
  • pulse_text(time, pulse_rate)
• Added 4 new InteractiveScene helpers and callbacks:
  • limit_to_bounds(text)
  • quick_exit(key)
  • quick_exit_callback(key, callback)
  • limit_group_to_bounds(group)
• Added a new physics.py example for motion, bouncing, and force-driven text animation

v1.8.5

• Added new Shapes class for creating basic shapes like rectangles and circles as text objects
  • rectangle(width, height, char) for creating a rectangle shape
  • circle(radius, char) for creating a circle shape
  • polygon(points, char) for creating a polygon shape from a list of Coords
• Changed rendering logic to support shapes as text objects, allowing you to use them like regular Text with position, color, and effects

v1.8.0

• Added new Coords and Keyframe as helper classes for Keychains
• Added brand new Keychains class for animating with keyframes, methods include:
  • follow_path for making text follow a keyframe path
• Added new method slide_to_pos for Text as a helper function for follow_path
• Added one new example to examples folder (keyframes.py)

v1.7.0

• Added new EffectText class that extends Text with built-in support for various text effects like shaking
  • gravity_text(floor, gravity) for simulating gravity with velocity and floor collision
  • shaking_text(intensity) for shaking the text randomly within a certain intensity
  • decaying_text(time, decay_rate) for creating a text that fades out and disappears after a certain lifetime
• Added more mouse controls such as mouse_released(button) to check if a specific mouse button was released since the last update, and mouse_release_callback(button, callback) to set a callback function that triggers when a specific mouse button is released

v1.6.5

• Added six new methods to InteractiveScene:
  • mouse_pressed(button="left")
  • mouse_position()
  • key_released(key)
  • on_key_press_callback(key, callback)
  • on_key_release_callback(key, callback)
  • on_mouse_press_callback(button, callback)

v1.6.0

• Added new Particle class for creating particle effects with velocity and lifetime support
• Added burst() method to create particles that scatter in all directions with configurable speed
• Added emit() method to emit a single particle from another particle
• Added update_all() method to update all emitted particles
• Added is_dead() method to check if all particles have expired
• Added Scene.update() method to automatically update and remove expired particles
• Particles now support RGB color, velocity, and lifetime tracking
• Added new example for particle simulation
• Added two new methods to Group class: change_rgb_values_one() and position()
• Added three new methods to Audio class: is_playing(), play_for_time(), and stop_all()
• Added two new methods for the main namespace: hide_cursor()/show_cursor()

v1.5.8

• Added exclusive floor, wall, and ceiling properties to InteractiveScene for better control over movement boundaries

v1.5.5

• Added new Group class for grouping multiple Text objects together and moving them as a unit
• Added collision detection method on_collide_callback to Text class for triggering callbacks when two Text objects collide

v1.5.1

• Added full guide to project folder

v1.5.0

• Added linear interpolation function lerp to animpy for smooth animations
• Added dt property to Scene for easy frame timing and smooth movement
• Added z-index support to Text for layering items in the scene
• Added scene shaking effect with shake method for dramatic animations

v1.4.5

• Added background color support to Scene with set_bg_rgb method

v1.4.1

• Added scene.remove method to remove items from the scene

v1.4.0

• Added three new examples to Github example folder
• Added new class InteractiveScene that allows for real-time keyboard input
• Added collision detection method collides_with to Text class

v1.3.8

• Added audio.is_playing() method to check if audio is currently playing
• Added two more examples to Github example folder

v1.3.5

• Added scene.clear method to clear the scene
• Added version history to README

Made with ❤️ by a human.