physim 0.1.3

Python library for the bouncing and growing object animations you see on social media.
Every frame is rendered offline, so the exported video never stutters or drops frames.

What it does

• Balls, polygons, stars and rects bouncing inside rings and arenas
• Rings with spinning gaps that objects escape through, plus stacked concentric rings
• Objects that grow, speed up, change color, clone themselves or vanish on any event
• Trails, glow, motion blur and gradient or image backgrounds
• Styled text with fonts, weights, italics, underline, strikethrough, gradients and backgrounds
• Shapes defined by math expressions, parametric and implicit
• Sound: synthesized tones, sample files and melodies that play the next note on every bounce
• MP4 and MKV export at any resolution and framerate, plus a live preview window
• Debug overlay with fps, frametime, object count, collisions and timings, all readable from code
• Third party addons through the physim.plugins entry point

Install

pip install physim[all]

Core stays lean if you would rather opt in:

Run it

# scene.py
from physim import Circle, HollowCircle, RGBCycle, Scene
from physim.actions import Grow, SpeedUp
from physim.effects import Glow, Trail
from physim.events import Bounce


class Bouncy(Scene):
    """A ball that grows and speeds up on every bounce."""

    def construct(self):
        self.add(HollowCircle(radius=420, stroke="#ffffff"))

        ball = Circle(radius=16, fill=RGBCycle(), velocity=(280, 60))
        ball.add_effect(Trail(length=28), Glow(strength=0.6))
        ball.on(Bounce, Grow(3, max_size=380))
        ball.on(Bounce, SpeedUp(1.02, max_speed=2200))
        self.add(ball)

        self.run(seconds=15)

physim render scene.py Bouncy --debug

Or skip the CLI entirely:

python -c "from scene import Bouncy; Bouncy().render()"

Examples

pip install physim[examples]

python -m physim_examples                     # list them all
python -m physim_examples.bouncing_ball
python -m physim_examples.escape_ring --debug
python -m physim_examples.ring_stack --seconds 5 -o out.mp4

CLI

physim render scene.py [Scene]   # render to video
physim list scene.py             # show the scenes in a file
physim preview scene.py          # live window
physim info                      # version, installed features, presets

For AI agents

ai-tutorial.md is a complete reference written for coding agents: the API surface, the coordinate system, the common mistakes, and a worked example.

Development

poetry install --all-extras
poetry run pytest
poetry run ruff check .
poetry run ruff format .

This repo also holds packages/physim-presets and packages/physim-examples.

License

MIT