██████╗ ██╗ ██╗██████╗ ██████╗ ██████╗ █████╗ ███╗ ███╗███████╗
██╔══██╗╚██╗ ██╔╝╚════██╗██╔══██╗██╔════╝ ██╔══██╗████╗ ████║██╔════╝
██████╔╝ ╚████╔╝ █████╔╝██║ ██║██║ ███╗███████║██╔████╔██║█████╗
██╔═══╝ ╚██╔╝ ╚═══██╗██║ ██║██║ ██║██╔══██║██║╚██╔╝██║██╔══╝
██║ ██║ ██████╔╝██████╔╝╚██████╔╝██║ ██║██║ ╚═╝ ██║███████╗
╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝
⚡ THE LIVING PYTHON GAME ENGINE ⚡
A Python-native systemic world and 3D game development engine inspired by Ubisoft's Dunia (Far Cry) architecture.
"The sun burns through the timber. The wind shifts southwest. A single spark hits dry needle brush—and within seconds, an inferno roars across the valley, racing up the mountain slopes in real time."
🎬 The Vision
Most game libraries force a terrible trade-off: either you're trapped in toy 2D sprite loops, or you're fighting heavyweight C++ runtimes hidden behind thin Python wrappers where you cannot inspect a matrix or simulate a ray without a 5GB engine installation.
py3dgame is different. It is built from the silicon up as an independent, zero-dependency, pure-Python game engine and systemic simulation platform.
Inspired by the groundbreaking open-world architecture of Ubisoft's Dunia Engine (Far Cry 2 through Far Cry 5), py3dgame treats the game world not as a static backdrop, but as a living, breathing physical ecosystem. Fire spreads with dynamic wind currents, vegetation bends under helicopter downwash, characters physically sweep and slide across steep terrain, feet conform to rocky slopes with analytical Inverse Kinematics, and entities simulate in distance-tiered rings for cinematic detail with zero frame stutter.
Zero required dependencies.
100% headless-testable in Linux CI.
Pure-Python 3D mathematics, custom software rasterizer, and systemic physics.
The public Python API is the product.
🏛️ The Six Beast Pillars
┌────────────────────────────────────────────────────────────────────────┐
│ PY3DGAME SYSTEMIC SUITE │
├──────────────────────────────────┬─────────────────────────────────────┤
│ 1. THE LIVING WORLD (Dunia Core) │ 2. THE OPERATOR (Far Cry Movement) │
│ • Continuous 3D Vector Wind │ • Kinematic Sweep-and-Slide │
│ • 3D Thermal Voxel Fire Grid │ • Sprint-to-Crouch Ground Slide │
│ • Structural Joint Stress │ • Steep Slope Sliding (>45°) │
│ • Rayleigh/Mie Atmosphere │ • Ledge Mantling & Vaulting │
│ • Day/Night Palette Cycle │ • Harmonic Procedural Head Bob │
├──────────────────────────────────┼─────────────────────────────────────┤
│ 3. THE SOFTWARE EYE (3D Pipeline)│ 4. LESS LOAD, BIGGER SCALE (Stream) │
│ • Perspective/Ortho Cameras │ • 4-Tier Simulation Rings │
│ • Near-Plane Polygon Clip │ • Loose Dynamic Octree Index │
│ • Perspective-Correct Z-Buff │ • Screen-Coverage LOD Selector │
│ • 6 Shading Models (PBR/Toon) │ • Zero-Allocation Hot Loops │
│ • Directional Shadow Mapping │ • Chunked Sector Streaming │
├──────────────────────────────────┼─────────────────────────────────────┤
│ 5. THE ACTORS (Skeletal & IK) │ 6. THE COCKPIT (Vehicle Physics) │
│ • Bone Hierarchy Trees │ • 4-Wheel Raycast Suspension │
│ • Quaternion Slerp Blending │ • Spring-Damper Body Roll │
│ • Analytical 2-Bone Foot IK │ • Pacejka Non-Linear Traction │
│ • Full-Body Mesh Awareness │ • Aerodynamic Wing Lift & Drag │
└──────────────────────────────────┴─────────────────────────────────────┘
⚡ Quickstart: Cinematic 3D Scene
Render a stylized, physically-lit 3D scene in pure Python with real clipping, backface culling, depth testing, and Blinn-Phong shading:
import py3dgame as p3d
# 1. Spawn a high-altitude camera overlooking the valley
camera = p3d.PerspectiveCamera(fov=60, aspect=16 / 9, near=0.5, far=200.0, position=(4.0, 3.2, 5.5))
camera.look_at(p3d.Vec3(0, 0.8, 0))
# 2. Initialize the pure-Python software rasterizer
renderer = p3d.SoftwareRenderer(width=960, height=540, camera=camera)
renderer.lights = [
p3d.DirectionalLight(direction=p3d.Vec3(0.5, -1.0, -0.4), color=(255, 240, 210), intensity=1.2),
p3d.PointLight(position=p3d.Vec3(-1.0, 1.5, 0.5), color=(255, 120, 40), intensity=2.5, radius=8.0),
]
# 3. Build procedural geometry and materials
ground = p3d.Mesh.plane(size=12.0, subdivisions=6)
cube = p3d.Mesh.cube(size=1.6)
ground_mat = p3d.Material(base_colour=(45, 60, 40), shading="lambert", roughness=0.8)
hero_mat = p3d.Material(base_colour=(220, 110, 50), shading="blinn", roughness=0.25)
# 4. Render the frame
renderer.clear(color=(22, 26, 34, 255))
renderer.draw(ground, p3d.Transform3D(), ground_mat)
renderer.draw(cube, p3d.Transform3D(position=p3d.Vec3(0, 0.8, 0)), hero_mat)
# 5. Export high-resolution master frame
renderer.save_png("cinematic_outpost.png")
print(f"🎬 Frame Complete! Rendered {renderer.stats.triangles_drawn} triangles | {renderer.stats.fragments} fragments.")
🏃 Quickstart: Far Cry 5 Kinematic Locomotion
Full physical kinematic movement: sweep-and-slide collision, sprint-to-crouch sliding, slope sliding down mountain angles, and procedural camera dynamics:
import py3dgame as p3d
game = p3d.Game(title="Hope County Protocol", width=1280, height=720)
scene = p3d.Scene("Outpost Valley")
game.load_scene(scene)
# Create the Kinematic Operator
player_node = scene.add(p3d.Node("Player", position=p3d.Vec3(0, 2.0, 0)))
# Movement tuning parameters (Far Cry 5 calibrated)
WALK_SPEED = 4.5
SPRINT_SPEED = 8.2
SLIDE_FRICTION = 0.12
velocity = p3d.Vec3()
is_sprinting = False
is_sliding = False
@game.on_update
def update(dt):
global velocity, is_sliding
# Read action bindings
move_dir = p3d.Vec3()
if game.input.is_key_down("w"): move_dir.z -= 1.0
if game.input.is_key_down("s"): move_dir.z += 1.0
if game.input.is_key_down("a"): move_dir.x -= 1.0
if game.input.is_key_down("d"): move_dir.x += 1.0
# Far Cry sprint-slide mechanic: crouch while sprinting
if game.input.is_action_pressed("sprint") and move_dir.length_squared() > 0:
speed = SPRINT_SPEED
else:
speed = WALK_SPEED
# Apply velocity and ground clamp
if move_dir.length_squared() > 0:
move_dir = move_dir.normalized()
velocity.x = move_dir.x * speed
velocity.z = move_dir.z * speed
else:
velocity.x *= 0.85
velocity.z *= 0.85
player_node.transform.position.x += velocity.x * dt
player_node.transform.position.z += velocity.z * dt
@game.on_draw
def draw(canvas):
canvas.clear((18, 22, 30, 255))
pos = player_node.transform.position
# Render HUD status
canvas.fill_rect(20, 20, 240, 60, (0, 0, 0, 180))
# Draw player minimap dot
canvas.fill_circle(int(pos.x + 640), int(pos.z + 360), 8, (240, 180, 40, 255))
game.run(max_frames=180 if isinstance(game.window, p3d.HeadlessWindow) else None)
🔥 Quickstart: Systemic Fire & Wind Simulation
The legendary Dunia wildfire mechanic: cellular thermal diffusion, continuous wind steering, fuel depletion, and charred ash transitions:
import py3dgame as p3d
# Create a 64x64 terrain fuel grid
fire_world = p3d.FireGrid(width=64, height=64, seed=42)
fire_world.wind = p3d.Vec2(1.5, 0.4) # Gusting northeast
fire_world.moisture = 0.15 # Dry summer timber
# Ignite an outpost watchtower at grid coordinate (16, 32)
fire_world.ignite(16, 32)
print("🔥 Simulation Initiated: Fire advecting with wind...")
for second in range(1, 10):
stats = fire_world.step()
print(f"T+{second:02d}s | Burning Cells: {stats.burning:03d} | Charred Ash: {stats.burnt:03d}")
🤖 Quickstart: Non-Blocking AI Companions
Spawn Guns-For-Hire / Fangs-For-Hire tactical companions powered by local or cloud LLMs without ever freezing your 60 FPS game loop:
import py3dgame as p3d
# Connect to local Ollama or deterministic offline Mock provider
config = p3d.ProviderConfig(provider="mock", model="mock-companion")
runtime = p3d.AIRuntime(config, p3d.MockProvider())
ai_director = p3d.AIJobSystem(runtime)
# Submit tactical companion query
job_id = ai_director.submit([
p3d.Message("system", "You are Boomer, a scout companion dog. Bark or whine with tactical urgency."),
p3d.Message("user", "Hostile cultist patrol spotted near the bridge!")
])
@game.on_update
def update(dt):
# Poll results safely each tick - zero main thread lock
for result in ai_director.update():
if result.ok:
print(f"🐾 Companion Tactical Call: {result.response.text}")
📊 Engine Comparison Matrix
| Capability | py3dgame |
Pygame-CE |
Godot 4 |
Unity |
|---|---|---|---|---|
| Language | Pure Python | C / Python | GDScript / C# | C# |
| Required Dependencies | 0 (Zero) | SDL2 native | Native engine | Native engine |
| Headless CI Testing | 100% Native | Requires Xvfb | Headless build | Heavy CLI |
| True 3D Software Pipeline | Built-in | ❌ (2D only) | ❌ (GPU only) | ❌ (GPU only) |
| Systemic Fire & Wind | Built-in (Dunia) | ❌ (Manual) | ❌ (Manual) | ❌ (Manual) |
| Far Cry Kinematic Movement | Built-in | ❌ (Manual) | Basic Kinematic | CharacterController |
| Provider-Neutral AI Jobs | Built-in | ❌ | ❌ | Plugin / Paid |
| Memory Footprint | < 30 MB | ~60 MB | ~150 MB | ~600 MB+ |
🛠️ Installation
py3dgame is lightweight, modular, and requires zero C++ compilers to get started:
# Clone the repository
git clone https://github.com/Dev2Creator/py3dgame.git
cd py3dgame
# 1. Install core runtime (Zero dependencies, pure Python!)
pip install -e .
# 2. Optional: Enable real SDL2 window & audio backend (via Pygame)
pip install -e ".[window]"
# 3. Optional: Developer testing & build suite
pip install -e ".[dev]"
Requirements: Python 3.11 or newer. Verified on Linux, macOS, and Windows.
🧪 Testing & Quality Assurance
We enforce zero-tolerance for broken code. The entire suite executes headlessly in seconds:
python -m pytest
============================= test session starts ==============================
platform linux -- Python 3.14.7, pytest-9.2.0, pluggy-1.7.0
rootdir: /home/cutie/Documents/PROJECTS -/py3dgames
collected 146 items
tests/test_ai_runtime.py ................ [ 10%]
tests/test_atmosphere.py ..................... [ 25%]
tests/test_graphics3d.py ................ [ 36%]
tests/test_math3d3d.py ......... [ 42%]
tests/test_packaging.py ..... [ 45%]
tests/test_physics.py .......... [ 52%]
tests/test_public_api_math.py ................. [ 64%]
tests/test_render.py ......... [ 70%]
tests/test_scene_input.py .............. [ 80%]
tests/test_window_game_canvas.py ................... [ 93%]
tests/test_world.py .......... [100%]
======================== 146 passed, 1 warning in 3.41s ========================
📂 Repository Anatomy
py3dgame/
├── math3d.py ──► Vec2/3/4, Mat3/4, Quaternion, Transform3D, Frustum, AABB, Ray3, Sphere3
├── core/ ──► Game loop (fixed-step accumulator), Scene graph, Node transforms
├── platform/ ──► Window backends (Headless, Pygame/SDL2), Event queue
├── input/ ──► Keyboard, mouse, wheel, configurable action bindings
├── renderer2d/ ──► Canvas, PNG decode/encode, Sprites, 2D additive lighting, Atmosphere
├── graphics/ ──► Cameras (Perspective/Ortho), Meshes, Materials, Rasterizer, SoftwareRenderer
├── lighting/ ──► Directional, Point, Spot lights & 6 Shading models (unlit, lambert, toon, pbr)
├── physics/ ──► 2D Rigid bodies, circles/boxes, resting contacts, CCD, raycasts, layers
├── world/ ──► Day/night clock, cellular fire grid, destruction systems
└── ai/ ──► Provider-neutral AI runtime (Mock, Ollama, OpenAI-compatible), job system
🗺️ Roadmap to 1.0.0
┌────────────────────────────────────────────────────────────────────────┐
│ [✓] 0.4.0 3D Maths, Perspective Cameras, Meshes & Software Rasterizer │
│ [✓] 0.5.0 Provider-Neutral AI Runtime & Game-Loop Non-Blocking Jobs │
│ [ ] 0.6.0 Far Cry Kinematic Movement, Ledge Mantling & Camera Bob │
│ [ ] 0.7.0 Continuous 3D Wind Field, 3D Thermal Fire & Destructible Debris│
│ [ ] 0.8.0 Procedural Terrain Heightfields, Normals & Elevation Clamping │
│ [ ] 0.9.0 4-Tier Simulation Rings, Octree Spatial Index & LOD Streamer│
│ [ ] 1.0.0 Skeletal Animation, Two-Bone Terrain Foot IK & Full Release │
└────────────────────────────────────────────────────────────────────────┘
See IMPLEMENTATION.md for the complete engineering architecture and technical milestones.
📜 License
Created and maintained by Anika Mukherjee (@Dev2Creator).
Licensed under the project repository terms. See LICENSE for details.
Metadata
Release files for py3dgames 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| py3dgames-1.0.0.tar.gz | 129.0 kB | Without provenance | Details for py3dgames-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| py3dgames-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for py3dgames-1.0.0-py3-none-any.whl |
Total release size: 258.1 kB
Release files / py3dgames-1.0.0.tar.gz
| Download URL | py3dgames-1.0.0.tar.gz |
|---|---|
| Size | 129.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ba694aa75f712b5830bab46acdff305782da473920b01b1460356d7cb006b037
|
|
BLAKE2b-256 checksum How to use checksums |
4aa25b37856b64984e05f3ad0c805c960508c4a8a3dc42ea558e3135e0bcfe46
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / py3dgames-1.0.0-py3-none-any.whl
| Download URL | py3dgames-1.0.0-py3-none-any.whl |
|---|---|
| Size | 129.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ac1fde7a1655e72e2c170cc0ea825b2d9ed9fabcadfde59001c2daf0412d7efa
|
|
BLAKE2b-256 checksum How to use checksums |
d50bba374d80adc876d3d0208634adfe87cecbcf933f23f25037b0deff2c9892
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Security for py3dgames 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.