swirengine 2.0.0

Install · Quick Start · 2.0 Roadmap · Examples · Releases

📊 Project status

Active source scope: SwirEngine 2.0 — Release-Quality Python-First Game Production
Verified source progress: 10/10 milestones = 100.0% — RELEASE PREP
Latest public stable release: SwirEngine 1.5.0
Release readiness: 2.0.0 finalization candidate; public release still requires exact-head green CI, merge, immutable tag publication and fresh public-PyPI verification.

Release/PyPI: frozen until SwirEngine 2.0

SwirEngine is a Python-first 2D/3D game engine focused on complete creator workflows: runtime systems, real rendering validation, deterministic tooling, multiplayer foundations, production project manifests, diagnostics, export staging and host-native desktop shipping. The repository completed source-only checkpoints 1.6–1.9 without publishing them; the 2.0 source roadmap is now candidate-complete.

All ten 2.0 source milestones lock the published 1.5.0 compatibility floor, integrate project creation/validation/run/shipping preparation, add a production-facing multiplayer contract, harden runtime scalability/resource lifecycle behavior, establish the verified base-engine Python/platform matrix, prove representative 2D/3D/multiplayer production workflows, verify exact-source wheel/sdist clean installs plus host-native packaged-game execution on Windows/Linux/macOS, establish reproducible performance evidence, add deterministic staged-export/build identity plus privacy-safe support-bundle verification, and arm the guarded 2.0.0 release candidate. This does not claim that 2.0.0 is already published.

✨ Highlights

📦 Install

The latest public stable package is 1.5.0.

Published 1.5.0 validation covers Python 3.10-3.13 on Windows, Linux and macOS, plus Python 3.14 on Windows x86-64 through the documented native-wheel path. Separately, the current 2.0.0 release-candidate source matrix is verified on 64-bit CPython 3.10–3.14 across the hosted Windows, Linux and macOS runner families. That source evidence is not yet a public 2.0 package claim. See docs/SUPPORT_MATRIX_2_0.md for architecture boundaries and non-claims.

python -m pip install -U swirengine==1.5.0

Optional audio support:

python -m pip install -U "swirengine[audio]==1.5.0"

Current source release candidate:

git clone https://github.com/Swir/SwirEngine.git
cd SwirEngine
git fetch --tags
python -m pip install -e ".[dev]"

pyproject.toml and swirengine.__version__ are armed at 2.0.0 only for the guarded finalization candidate. The latest public package remains 1.5.0 until the immutable v2.0.0 release workflow and public-install verification succeed. No 1.6, 1.7, 1.8 or 1.9 package/tag/release is created.

🚀 Quick Start

2D

from swirengine import Color, Game, Rectangle2D

game = Game("My 2D Game", 1280, 720, mode="2d")
player = game.add(Rectangle2D(0, 0, 120, 70, Color(0.1, 0.75, 1.0, 1.0)))

@game.update
def update(dt):
    speed = 380
    if game.key("A"):
        player.x -= speed * dt
    if game.key("D"):
        player.x += speed * dt

game.run()

3D

from swirengine import Color, Cube3D, Game, Vec3

game = Game("My 3D Game", 1280, 720, mode="3d")
cube = game.add(Cube3D(position=Vec3(0, 0, -4), color=Color(0.2, 0.7, 1.0, 1.0)))

@game.update
def update(dt):
    cube.rotation.y += 50 * dt
    cube.rotation.x += 25 * dt

game.run()

🧭 Current 2.0 development workflow

The active roadmap is ROADMAP_2_0.md. Its ten release-quality milestones cover:

1. public API and migration compatibility;
2. creator workflow and integrated tooling;
3. multiplayer and dedicated-server production behavior;
4. renderer/runtime scalability and resource lifecycle;
5. the final Python/platform support matrix;
6. representative 2D/3D/multiplayer shipping workflows;
7. packaging, clean installs and native desktop shipping;
8. reproducible performance/competitive evidence;
9. export/build integrity, diagnostics and release safety;
10. the final 2.0 release-candidate gate followed by guarded public verification.

Milestone 1 locks compatibility to the actual published v1.5.0 root API rather than a hand-written subset. Milestone 2 adds one integrated creator inspection/preparation path over the existing project, run-session, scene/prefab, content-build, input/settings and save/profile policies. New projects receive editable controls/settings defaults automatically, while existing projects can be prepared without overwriting user files. Milestone 3 adds deterministic client/server compatibility checks, a production session facade, reconnect token rotation with forced full resynchronization, explicit authoritative versus player-local state boundaries and a validated fixed-tick headless dedicated-server path. Milestone 4 hardens streaming/cache lifecycle semantics, explicit resource teardown and pressure diagnostics while locking representative 16,384-tile, 4,096-sprite and 4,096-object scene workloads to bounded/reuse/pruning invariants instead of unsupported shared-runner FPS claims. Milestone 5 verifies all 15 Windows/Linux/macOS × CPython 3.10–3.14 base-engine cells through platform probes, wheel construction, isolated clean installs and maintained headless 2D/3D runtime fixtures. Milestone 6 drives maintained 2D, 3D and multiplayer projects through the same production creator/shipping contracts, including real focus/navigation/activation, player-local data isolation, privacy-safe diagnostic evidence, deterministic export staging, source/staged runtime entrypoints and deliberate missing-scene/asset/entrypoint failure probes. Milestone 7 builds the exact candidate source as wheel and sdist, performs bounded archive safety/inventory validation, installs each artifact into isolated environments, runs the maintained fixtures from those installs and then builds, validates and executes host-native desktop packages on Windows, Linux and macOS from the clean wheel. Milestone 8 locks six existing deterministic performance/scalability workloads to their source thresholds, captures exact commit/Python/platform runner context in ephemeral CI evidence and performs an official-doc workflow audit for Arcade, Panda3D and Ursina without publishing technically invalid cross-engine FPS, latency, memory or superiority rankings. Milestone 9 verifies staged export bytes against the canonical inventory/checksums, seals a deterministic build identity including generated native build inputs and audits opt-in support bundles for bounded content, integrity, redaction, safe paths and expected build identity. Milestone 10 validates the guarded release workflows and only arms 2.0.0 metadata after the 9/10 exact-head preflight is green; the resulting 10/10 candidate must re-pass the complete exact-head matrix before merge, tagging or publication.

git fetch --tags
python tools/verify_2_0_release_candidate.py --require-final
python tools/verify_2_0_public_api.py
python tools/verify_platform_matrix_2_0.py
python tools/verify_real_game_shipping_2_0.py
python tools/verify_performance_evidence_2_0.py --validate-only
python tools/verify_release_safety_2_0.py
swirengine new MyGame --mode 3d
swirengine workflow MyGame --profile windows
swirengine workflow MyGame --json
swirengine run MyGame --dry-run

For an older source project missing creator directories or editable defaults:

swirengine workflow . --prepare

See:

• docs/MIGRATING_TO_2_0.md
• docs/public_api_2_0.json
• docs/API_STABILITY.md
• docs/CREATOR_WORKFLOW_2_0.md
• docs/MULTIPLAYER_PRODUCTION_2_0.md
• docs/RUNTIME_SCALABILITY_2_0.md
• docs/SUPPORT_MATRIX_2_0.md
• docs/REAL_GAME_SHIPPING_2_0.md
• docs/PACKAGING_SHIPPING_2_0.md
• docs/PERFORMANCE_EVIDENCE_2_0.md
• docs/RELEASE_SAFETY_2_0.md
• docs/RELEASE_GATE_2_0.md
• docs/SWIRENGINE_2_0_READINESS_AUDIT.md
• ROADMAP_2_0.md

🎮 Real-game integration fixtures

Representative projects are source-only engine integration fixtures and do not receive separate releases:

• SwirEngine 2D Game Demo — examples/2d_game_demo/
• SwirEngine 3D Game Demo — examples/3d_game_demo/
• SwirEngine Multiplayer Game Demo — examples/multiplayer_game_demo/
• Neon Frontier 1.3 — locked historical compatibility fixture
• Neon Frontier 1.4 — locked compatibility/showcase fixture
• Neon Cube Hunt 3D — OpenGL + packaged-runtime regression arena
• Neon Snake 3D — complete 3D regression project

The verified 2.0 real-game shipping gate drives the maintained 2D, 3D and multiplayer fixtures through creator preparation, source runtime, deterministic staged export, staged runtime, settings/save boundaries, scene/content integrity, real UI focus/navigation/activation and privacy-safe runtime diagnostics. Fixture failures are treated as engine integration failures rather than demo-only issues.

🧪 Development and verification

python -m pip install -e ".[dev]"
pytest
ruff check src tests examples demo_projects tools
python -m compileall -q src tests examples demo_projects tools
python tools/verify_2_0_release_candidate.py --require-final
python tools/verify_creator_workflow_2_0.py
pytest -q tests/test_multiplayer_2_0.py
python examples/multiplayer_game_demo/run_game.py
python tools/verify_runtime_scalability_2_0.py
python tools/verify_platform_matrix_2_0.py
python -m pytest -q tests/test_platform_matrix_2_0.py
python tools/verify_real_game_shipping_2_0.py
python -m pytest -q tests/test_real_game_shipping_2_0.py
python -m pytest -q tests/test_packaging_shipping_2_0.py
python tools/verify_performance_evidence_2_0.py --output build/performance-evidence.json
python -m pytest -q tests/test_performance_evidence_2_0.py
python tools/verify_release_safety_2_0.py
python -m pytest -q tests/test_release_safety_2_0.py

Progress assets are generated from the authoritative 2.0 roadmap:

python tools/generate_progress_svg.py
python tools/generate_progress_svg.py --check

The generator owns one README card, one active-roadmap mini graphic and one reusable SVG marked TEMPLATE / NOT PROJECT DATA. Only the card and mini are embedded as live progress.

The SVG layer visualizes verified roadmap math; it never replaces CI, release, compatibility or runtime gates.

🧱 Architecture and technology

SwirEngine keeps a high-level Python creator surface over modular runtime systems. The repository contains rendering, scene/ECS, assets, serialization, physics, audio, input/UI, networking, editor, diagnostics and export/shipping modules with focused regression workflows. Advanced systems remain available as explicit APIs instead of being hidden behind a single monolithic game object.

The 2.0 architecture work is evaluated against real-game integration, resource lifetime, deterministic tooling, failure handling and package/export behavior—not feature count alone.

🔒 API and release policy

• v1.4.0 and v1.5.0 are immutable published historical releases except for genuine maintenance fixes.
• 1.5.0 remains the latest public stable package.
• 1.6, 1.7, 1.8 and 1.9 are completed source-only checkpoints and are not published.
• The 2D, 3D and multiplayer game demos remain source-only integration fixtures.
• The published 1.5.0 swirengine.__all__ surface is the starting compatibility floor for 2.0.
• Deliberate 2.0 breaking changes require a documented migration, tests and explicit engineering justification.
• The next GitHub Release, release tag and PyPI publication must be SwirEngine 2.0.
• Publication is forbidden until the exact 2.0.0 finalization candidate passes the dedicated Milestone 10 release gate.
• A 10/10 source roadmap does not itself prove that the public v2.0.0 tag, GitHub Release or PyPI artifact exists.

Historical locked compatibility evidence remains explicit: SwirEngine 1.4 is released and locked. The published 1.5.0 gate verified Python 3.10-3.13 cross-platform and Python 3.14 on Windows x86-64. Its locked 1.5 capability evidence includes Deterministic Simulation & Replay, Save & Profile 2.0, World Streaming 2.0, UI Toolkit 2.0 and Runtime Diagnostics & Profiling 2.0. These statements describe published historical release evidence and remain separate from the verified source-development SwirEngine 2.0 base-engine support matrix.

See docs/API_STABILITY.md, docs/MIGRATING_TO_2_0.md and docs/SUPPORT_MATRIX_2_0.md.

🗺 Roadmaps

⚠️ Current limitations

• The public PyPI package is still 1.5.0; the 2.0.0 source candidate is not a public release until the guarded publication workflow succeeds.
• SwirEngine 2.0.0 is in release prep; exact-head finalization CI, immutable tag publication and fresh public-install verification remain mandatory.
• The verified 2.0 base-engine matrix covers only the 64-bit hosted runner architectures exercised by CI; 32-bit Python, PyPy, free-threaded CPython and unverified architectures are not claimed.
• Optional extras such as audio are not automatically covered by the base-engine support claim without their own evidence.
• Desktop build plans are host-native; unsupported cross-compilation is intentionally rejected.
• The dedicated-server contract is headless and deterministic but does not claim public matchmaking, hosting infrastructure or universal transport support.
• Cross-engine FPS, latency and memory rankings remain intentionally unclaimed without an identical maintained comparison harness.
• Visual editor ergonomics remain an area for later creator-tooling hardening even though the integrated Milestone 2 workflow is verified.

🔎 Search Keywords

Python game engine · Python 2D engine · Python 3D engine · Python multiplayer engine · pip game engine · game development Python · OpenGL Python game engine · scene prefab engine · Python ECS · Python physics engine · Python game editor · desktop game packaging · PyInstaller game build · game engine networking · SwirEngine