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)
| Method | Description |
|---|---|
.gravity(force=9.8, direction=None) |
Constant acceleration in a direction (default: down) |
.fluid(density=1.0, drag=0.1) |
Velocity-proportional drag (air/water resistance) |
.friction(coefficient=0.3, normal_force=9.8) |
Kinetic friction opposing motion |
.custom(force) |
Attach your own Force subclass |
.remove(force) |
Detach a previously attached force |
.clear() |
Detach all forces |
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/
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)
- Create a PyPI account if you don't have one.
- 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
- PyPI project name:
- 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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file pydamics-0.1.0.tar.gz.
File metadata
- Download URL: pydamics-0.1.0.tar.gz
- Upload date:
- Size: 9.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9b10a0e51670244b115d482a916e43d279155d970497d8f0dcdb4728d83f6ed1
|
|
| MD5 |
d776066b6b3ae315e953564d33a0863a
|
|
| BLAKE2b-256 |
1bcce8c0fee63c14ff9e8402d00b740f99bf2541c7625d0677c2a8c0eb559b2b
|
Provenance
The following attestation bundles were made for pydamics-0.1.0.tar.gz:
Publisher:
publish.yml on Reeed-cell/Pydamics
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pydamics-0.1.0.tar.gz -
Subject digest:
9b10a0e51670244b115d482a916e43d279155d970497d8f0dcdb4728d83f6ed1 - Sigstore transparency entry: 2280791816
- Sigstore integration time:
-
Permalink:
Reeed-cell/Pydamics@57ab23ee4831b2820405ae11e2f3fde2bb93fd65 -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/Reeed-cell
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@57ab23ee4831b2820405ae11e2f3fde2bb93fd65 -
Trigger Event:
release
-
Statement type:
File details
Details for the file pydamics-0.1.0-py3-none-any.whl.
File metadata
- Download URL: pydamics-0.1.0-py3-none-any.whl
- Upload date:
- Size: 8.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
516123979a9d25c06f295e967e0377f8377eb30680f89f533dae6f8626488643
|
|
| MD5 |
3e80ad2dd6662b57cc8d571b73f51aba
|
|
| BLAKE2b-256 |
178e8e1d48beb17c3a9ad32af31f050ee1d12654073c8435a8fce8ce8030888a
|
Provenance
The following attestation bundles were made for pydamics-0.1.0-py3-none-any.whl:
Publisher:
publish.yml on Reeed-cell/Pydamics
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pydamics-0.1.0-py3-none-any.whl -
Subject digest:
516123979a9d25c06f295e967e0377f8377eb30680f89f533dae6f8626488643 - Sigstore transparency entry: 2280791821
- Sigstore integration time:
-
Permalink:
Reeed-cell/Pydamics@57ab23ee4831b2820405ae11e2f3fde2bb93fd65 -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/Reeed-cell
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@57ab23ee4831b2820405ae11e2f3fde2bb93fd65 -
Trigger Event:
release
-
Statement type:
