Skip to main content
██████╗ ██╗   ██╗██████╗ ██████╗  ██████╗  █████╗ ███╗   ███╗███████╗
██╔══██╗╚██╗ ██╔╝╚════██╗██╔══██╗██╔════╝ ██╔══██╗████╗ ████║██╔════╝
██████╔╝ ╚████╔╝  █████╔╝██║  ██║██║  ███╗███████║██╔████╔██║█████╗  
██╔═══╝   ╚██╔╝   ╚═══██╗██║  ██║██║   ██║██╔══██║██║╚██╔╝██║██╔══╝  
██║        ██║   ██████╔╝██████╔╝╚██████╔╝██║  ██║██║ ╚═╝ ██║███████╗
╚═╝        ╚═╝   ╚═════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚═╝     ╚═╝╚══════╝

⚡ THE LIVING PYTHON GAME ENGINE ⚡

A Python-native systemic world and 3D game development engine inspired by Ubisoft's Dunia (Far Cry) architecture.

Python Dependencies Tests Architecture License


"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.

py3dgame — Create Games. Write Python. Simulate Living Worlds.

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)

Source distribution for py3dgames 1.0.0
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)

Table of built distributions (wheels) for py3dgames 1.0.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page