Culverin Physics

Culverin is a middleware bridge between the Jolt Physics engine and the Python Virtual Machine. It is designed for 3D games and simulations that require high performance and multi-threaded execution, for the Python game engine developers.

Key Concepts

Free-Threading Support: Designed for Python 3.13t and 3.14t. The engine releases the Global Interpreter Lock (GIL) during physics updates and raycast batches.
Shadow Buffers: All body positions, rotations, and velocities are stored in contiguous C-arrays. You can access this data via memoryview, NumPy or any dependency that supports the buffer protocol without the overhead of creating Python objects for every body.
Thread-Safe API: The engine uses a priority-based locking system. Simulation steps, state mutations, and queries can run on different threads without causing deadlocks or memory corruption.
Generational Handles: Bodies are referenced by 64-bit handles rather than pointers. This ensures that using a handle for a deleted object will not crash the program.
Double-Precision Positions: Uses double-precision floats (float64) for world positions to prevent physics jitter in massive open worlds, while using float32 for rotations and velocities to save memory and computing resources.

Features

Standard Primitives: Box, Sphere, Capsule, Cylinder, and Plane shapes.
Complex Shapes: Support for Convex Hulls, Heightfields (Terrain), and static Meshes.
Compound Bodies: Create single bodies composed of multiple child shapes.
Character Controller: A virtual character controller with built-in support for climbing stairs, sliding down slopes, and pushing objects.
Vehicles: Support for wheeled vehicles and tracked vehicles (tanks) with physical treads and skid-steering.
Ragdolls & Skeletons: Multi-body articulated physics with active motorized poses.
Constraints: Fixed, Point, Hinge, Slider, Distance, Swing-Twist, and Cone constraints.
Queries: Efficient single and batch Raycasting, Shapecasting (sweeps), and Overlap queries.
Collision Events: Native event buffer for contact added, persisted, and removed events.
Soft Bodies: Support for soft bodies from Jolt Physics, with fine-grained configurations.

Installation

pip install culverin

📚 Documentation

Detailed API references for every class and method are available:

Online Docs: View the Interactive API Reference
In-Engine: Use the standard Python help() system: help(culverin.PhysicsWorld.create_body) or help(culverin)

Quick Start

import numpy as np

import culverin

# Initialize the world with a capacity limit
world = culverin.PhysicsWorld(settings={"max_bodies": 1000})

# Create a static ground plane
# a plane normal of default (0.577, 0.577, 0.577) represents an infinite 45-degree tilted ramp.
world.create_body(pos=(0, 0, 0), shape=culverin.SHAPE_PLANE, motion=culverin.MOTION_STATIC)

# Create a dynamic box
handle = world.create_body(
    pos=(0, 10, 0), size=(1, 1, 1), shape=culverin.SHAPE_BOX, motion=culverin.MOTION_DYNAMIC
)

# Simulation loop
for _ in range(1000):
    world.step(1 / 60)

    # Zero-Copy Data Access
    # Wrap the internal engine memory in NumPy without copying a single byte.
    # This gives you O(1) access to all 1,000+ bodies at once.
    positions = np.frombuffer(world.positions, dtype=np.float64).reshape(-1, 4)

    # Print the Y position of our box
    idx = world.get_index(handle)
    print(f"Box Height: {positions[idx, 1]:.2f}m")

Technical Specifications

Spec	Standard
Units	Metric (1.0 = 1 meter)
Coordinate System	Right-Handed (Y-Up)
Angle Units	Radians
Quaternion Format	`(x, y, z, w)`
Position Buffer	`Float64` (Stride 4: x, y, z, pad)
Rotation/Velocity Buffers	`Float32` (Stride 4: x, y, z, w/pad)
Minimum Python	3.12 (3.13t+ recommended for multi-threading)

Performance & Rendering Note

For maximum performance when updating a renderer (like OpenGL or Vulkan), do not loop through individual handles in Python. Instead, use the interpolating export method:

# Returns a single, tightly packed bytes object of Float32s 
# formatted as [px, py, pz, rx, ry, rz, rw] for every active body.
# The 'alpha' parameter (0.0 to 1.0) interpolates between the previous 
# and current physics steps for buttery-smooth rendering.
render_data = world.get_render_state(alpha=0.5)

To read data for gameplay logic, use numpy.frombuffer(world.positions, dtype=np.float64) and numpy.frombuffer(world.rotations, dtype=np.float32) to wrap the internal engine memory without making copies.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

culverin-0.14.0-cp315-cp315t-win_amd64.whl (1.4 MB view details)

Uploaded Jul 17, 2026 CPython 3.15tWindows x86-64

culverin-0.14.0-cp315-cp315t-manylinux_2_39_x86_64.whl (1.4 MB view details)

Uploaded Jul 17, 2026 CPython 3.15tmanylinux: glibc 2.39+ x86-64

culverin-0.14.0-cp315-cp315t-macosx_26_0_arm64.whl (1.4 MB view details)

Uploaded Jul 17, 2026 CPython 3.15tmacOS 26.0+ ARM64

culverin-0.14.0-cp315-cp315-win_amd64.whl (1.3 MB view details)

Uploaded Jul 17, 2026 CPython 3.15Windows x86-64

culverin-0.14.0-cp315-cp315-manylinux_2_39_x86_64.whl (1.4 MB view details)

Uploaded Jul 17, 2026 CPython 3.15manylinux: glibc 2.39+ x86-64

culverin-0.14.0-cp315-cp315-macosx_26_0_arm64.whl (1.4 MB view details)

Uploaded Jul 17, 2026 CPython 3.15macOS 26.0+ ARM64

culverin-0.14.0-cp314-cp314t-win_amd64.whl (1.6 MB view details)

Uploaded Jul 17, 2026 CPython 3.14tWindows x86-64

culverin-0.14.0-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.6 MB view details)

Uploaded Jul 17, 2026 CPython 3.14tmanylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

culverin-0.14.0-cp314-cp314t-macosx_13_0_arm64.whl (1.4 MB view details)

Uploaded Jul 17, 2026 CPython 3.14tmacOS 13.0+ ARM64

culverin-0.14.0-cp314-cp314-win_amd64.whl (1.5 MB view details)

Uploaded Jul 17, 2026 CPython 3.14Windows x86-64

culverin-0.14.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.5 MB view details)

Uploaded Jul 17, 2026 CPython 3.14manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

culverin-0.14.0-cp314-cp314-macosx_13_0_arm64.whl (1.4 MB view details)

Uploaded Jul 17, 2026 CPython 3.14macOS 13.0+ ARM64

culverin-0.14.0-cp313-cp313-win_amd64.whl (1.5 MB view details)

Uploaded Jul 17, 2026 CPython 3.13Windows x86-64

culverin-0.14.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.5 MB view details)

Uploaded Jul 17, 2026 CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

culverin-0.14.0-cp313-cp313-macosx_13_0_arm64.whl (1.4 MB view details)

Uploaded Jul 17, 2026 CPython 3.13macOS 13.0+ ARM64

culverin-0.14.0-cp312-cp312-win_amd64.whl (1.5 MB view details)

Uploaded Jul 17, 2026 CPython 3.12Windows x86-64

culverin-0.14.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.5 MB view details)

Uploaded Jul 17, 2026 CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

culverin-0.14.0-cp312-cp312-macosx_13_0_arm64.whl (1.4 MB view details)

Uploaded Jul 17, 2026 CPython 3.12macOS 13.0+ ARM64

File details

Details for the file culverin-0.14.0-cp315-cp315t-win_amd64.whl.

File metadata

Download URL: culverin-0.14.0-cp315-cp315t-win_amd64.whl
Upload date: Jul 17, 2026
Size: 1.4 MB
Tags: CPython 3.15t, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for culverin-0.14.0-cp315-cp315t-win_amd64.whl
Algorithm	Hash digest
SHA256	`aed4489185e28f631e0d091b50edd357728542680e391a1086afca3290324568`
MD5	`e18b861f1d02051e84b873a6bfff66fd`
BLAKE2b-256	`be4691af46ffc6c83e8b107e2ad875756a4818582e623a401d44c06c926fd994`

Algorithm	Hash digest
SHA256	`3fe654e7d5dde98527c34ce9d1fab23a80ad146ac1a821f5166192949328eb06`
MD5	`ef2b0cdbcf77c34c350536cb73dabc51`
BLAKE2b-256	`6729ff0e4f2c9fa6b43582a70781309ce7ee3eec33c6db3a83c9a932e976e6b3`

Algorithm	Hash digest
SHA256	`1a4e660bf4af8fef22f8f370cf06b6785e251b3e892564ca05fd38b053efd6f6`
MD5	`fe2f6fbb4d15fb562079613234c7a6d8`
BLAKE2b-256	`04a76a7e79328d2404b73e4d890f7cba59415382ed2399cbe0a461cf5c821f26`

Algorithm	Hash digest
SHA256	`18c439d365e0f940eabbe2e3303c898133988759c6785028aa280f5eec59e756`
MD5	`d1c9099ac609d391aca98a973bad57da`
BLAKE2b-256	`ac2e87db04af2eaf43005ebb18a6f25cf176013511fc8951d2f84a918ad6555a`

Algorithm	Hash digest
SHA256	`331b7cb3669467ec87cf336edaaebbd9c6e536b604873d6aef4cb1e0cce37a3c`
MD5	`b33865670fe83f3fc3d7d10cc04366c9`
BLAKE2b-256	`b604a4d9df9289e64ff1eb27ac28b013acd1ff999fdb0fcca618ea9b35b88dff`

Algorithm	Hash digest
SHA256	`90ba2c240c2bad8055c5bfb9869c523845eec7558ff0e5f4dbd02ee6f37c75d3`
MD5	`a0b0fd0fb08ecc9e8f801f2cafa5357a`
BLAKE2b-256	`7f9fd6c7421ce53e765ff7682aa9c71c7fd2ed2c346c74ec6b1e10250d66684b`

Algorithm	Hash digest
SHA256	`4fe8a72aea216437e8a37ba326d544a584a5a722e57e58f2454c94762171dc49`
MD5	`9731368bfbb41eed8ed2b982eed77161`
BLAKE2b-256	`79086856f484b3ed328247207335ca2621070caac4f1f34fcfeef95d01dd3142`

Algorithm	Hash digest
SHA256	`cb6eb3923f3ef348aa7f090f014af9ae6bb48bcde00f1b8f0a93d453efa5947c`
MD5	`cc983440061dfce04addacaecfdd104a`
BLAKE2b-256	`f447c024870102d56cc9f8a6b72c3425865ae778c064b7a744a78be894695b67`

Algorithm	Hash digest
SHA256	`e41bb043efb5d7478d65d77eacc567e5f62135ad002df8c89222ccbdfbceee5d`
MD5	`37a12e6e6d6d8783df9c09262f3d000c`
BLAKE2b-256	`8b79b219c0bcc94a2abdba19eff9b133b2f75e345e013f061bab53389fe31e75`

Algorithm	Hash digest
SHA256	`33855beb7a410467e71e75c3da5384d06fd4df6be6f48d9ed99cf4925179001d`
MD5	`c709fbe7f917afee90eed53c2c590341`
BLAKE2b-256	`732ae6f2dd87b79f42bc1e19c5a7686847a005a86094f7d193090898aa28d69b`

Algorithm	Hash digest
SHA256	`abdf078fd01a2de24adcdc844fbd6b2819ac95b0ffcfc5aa4fc40f2378874142`
MD5	`c7b4cb39bd55694018711936797efb57`
BLAKE2b-256	`cd8f373fee123798b7f331c196b3c62ee6ec3729eb8acbeeed4bdf075b5e82b3`

Algorithm	Hash digest
SHA256	`d991b168eacd14fc45caa124e42637e660d4232699a5e8f88d72f14a60302531`
MD5	`ec1816a2156c1e672e197066d25df5c6`
BLAKE2b-256	`7d2af7be0df627ad0f89e36f9c1e22792c54b55e337d89f64d02486e604dfc90`

Algorithm	Hash digest
SHA256	`a8abb8ae629f0181aba5dac9a2e24a967030defab05668f88f09aaddd004152d`
MD5	`a419007cb355ad816ef45e290e896122`
BLAKE2b-256	`e55989c236ba421698a997102eb5cea619e848c82b38c486968115b60b29d861`

Algorithm	Hash digest
SHA256	`a298686a54862a1e119791e4d1d1fcd910047fa2fe3750fa3447054ac6b26f74`
MD5	`1c3e0fa5977698269750568e59ea508e`
BLAKE2b-256	`435db2e037561e3933cb8895167859e1ab0c1be792fd1a604c6bc4fa25ec21a6`

Algorithm	Hash digest
SHA256	`89ca5b7db60121c0a97c428f7f5293d44764b314c646b98cc3fb81d7dbaa3403`
MD5	`f4cb5c8631b485af60892b30c8add60a`
BLAKE2b-256	`3ea66df6bbec70bff3ceded9c7efde6064eb8a386af3b5573218394d02029169`

Algorithm	Hash digest
SHA256	`6f9d851877907a712300d8535c0cbdc8d190652b274846a44b02fdb013712e96`
MD5	`fbcc6e50faf9c7ad809279d809380a24`
BLAKE2b-256	`33f3091bb691561cad285be7947b304d00926720bdbef6d13f240d855a11d296`

Algorithm	Hash digest
SHA256	`933b9a02a55941e043cad22016f1181027525997c20c96ebff3bd0e3c165a0db`
MD5	`932c16e7d8801328471203fb1d3f3894`
BLAKE2b-256	`29a8a9c33faa5eecf5107d912a9ebd89d5e34f47f992a3020ca27ba9c8f77d56`

Algorithm	Hash digest
SHA256	`8186c7fa8082f6b045645d5919bae2558f0462e7edf3dfb899e109161c9ec26b`
MD5	`7a2cdc263f07af439247a0f0705c2c1a`
BLAKE2b-256	`237753e1ca093f85d8ff866e760636f8b59b0c0e742d38b1019b0a95cc65441c`

culverin 0.14.0

Culverin Physics

Key Concepts

Features

Installation

📚 Documentation

Quick Start

Technical Specifications

Performance & Rendering Note

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Tags

Classifiers

Download files

Source Distributions

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes