pydamics

A small, chainable-syntax 2D physics engine for Python. 3D support planned.

Install

pip install pydamics          # once published to PyPI
# or, from source:
pip install -e .

Usage

from pydamics import Entity, World

ball = Entity(mass=2.0, position=(0, 10))
ball.physics2d.gravity(force=9.8)
ball.physics2d.fluid(density=1.2, drag=0.3)

world = World()
world.add(ball)

# Option 1: step it yourself
for _ in range(120):
    world.step(dt=1/60)
    print(ball.position)

# Option 2: let the engine run itself on a background thread
world.run(dt=1/60)
...
world.stop()

Attachable forces (entity.physics2d)

Every attach method returns the Force object, so you can hold onto it and remove/tweak it later:

g = ball.physics2d.gravity(force=9.8)
ball.physics2d.remove(g)

Integration

Uses Velocity Verlet integration (not simple Euler, not full RK4) — it's the standard for force-based particle sims: stable, and integrates naturally with drag and future collision impulses.

Tests

pip install -e ".[dev]"
pytest tests/

Visual demos

Install the extra deps first:

pip install -e ".[visual]"

Matplotlib (headless, renders a GIF) -- great for servers, CI, or just sharing a result without needing a display:

python examples/visual_matplotlib.py
# -> saves examples/falling_balls.gif

Pygame (interactive window) -- click anywhere to drop a new ball, watch gravity/drag/floor-bounces play out live:

python examples/visual_pygame.py
# click to drop balls, ESC or close window to quit

Note: the floor-bounce behavior in both demos is demo-level logic (a simple world.on_step hook), not part of the core engine yet -- proper collision detection/response is still on the roadmap below.

Roadmap

• Collision detection/response
• More force types (springs, wind, etc.)
• 3D physics namespace (entity.physics3d)

Publishing (for maintainers)

1. Push to GitHub

git init
git add .
git commit -m "Initial commit: pydamics 2D physics engine"
git branch -M main
git remote add origin https://github.com/<your-username>/pydamics.git
git push -u origin main

The .github/workflows/tests.yml workflow will auto-run the test suite on every push.

2. One-time PyPI setup (Trusted Publishing — no API tokens needed)

1. Create a PyPI account if you don't have one.
2. Go to pypi.org → Your account → Publishing and add a new "trusted publisher":
   • PyPI project name: pydamics
   • Owner: <your-github-username>
   • Repository name: pydamics
   • Workflow name: publish.yml
   • Environment name: pypi
3. In your GitHub repo, go to Settings → Environments and create an environment named pypi (this matches the workflow file — no secrets needed, trusted publishing handles auth).

3. Ship a release

Bump the version in pyproject.toml, commit, then on GitHub: Releases → Draft a new release → tag v0.1.0 → Publish release.

That triggers .github/workflows/publish.yml, which builds the package and uploads it to PyPI automatically. From then on, anyone can:

pip install pydamics