How nalqit/py-engine works
1. Repository shape
This is a monorepo with three major surfaces: the reusable Python engine in src/pyengine2D, multiple example games in src/games, and authoring tools (draw2d.py plus the Flutter-based src/the_editor). The shared engine is the central dependency; games and tools sit on top of it rather than duplicating infrastructure.
2. Runtime core
The engine’s execution base is in pyengine2D/core and pyengine2D/time. It provides the main game loop, delta timing, input, rendering, audio, and signals, with MasterClock handling fixed-step scheduling. Everything else hangs off this runtime layer through scene updates and frame ticks.
3. Scene graph as the primary composition model
pyengine2D/scene is the core abstraction boundary. Nodes, Node2D, Camera2D, sprite and primitive nodes, particles, tweens, parallax, and tilemaps are all scene-tree participants. Parent/child transform propagation and lifecycle updates make the scene tree the shared structure for both games and editor-driven content.
4. Serialization and content loading
The engine includes scene_serializer.py and scene_manager.py, and the editor uses .scene files as its saved scene format. Separately, tilemap content is loaded from JSON and TMX into TilemapNode. This repo relies heavily on file-based content pipelines rather than hardcoded level construction.
5. Collision and physics stack
The lower simulation layers are split cleanly: pyengine2D/collision handles narrow-phase and overlap resolution, while pyengine2D/physics handles movement, forces, rigid bodies, and constraints. PhysicsBody2D is oriented toward platformer-style axis-separated movement, while RigidBody2D and PhysicsWorld2D support more dynamic simulation and sub-stepping. Collision filters and shape types are explicit architectural boundaries.
6. Gameplay layer sits above physics
Games generally bridge player intent into movement through controllers and state machines rather than talking directly to engine internals. The README highlights PlayerController as engine-agnostic input-to-physics glue, plus FSM states like idle/walk/fall. That separation is important: gameplay logic is not the same layer as simulation.
7. Rendering and visual effects
Rendering is centralized under pyengine2D/rendering, with batch rendering, atlases, surface caching, and pixel/grid helpers. Visual composition then happens in the scene layer via sprites, animated sprites, tweens, particles, and parallax backgrounds. The design suggests a renderer that consumes scene nodes rather than game-specific draw code.
8. UI is its own subsystem
pyengine2D/ui is a separate tree from gameplay UI. It includes controls, containers, widgets, event propagation, data binding, font caching, and debug/stat overlays. Game HUDs in specific titles sit above this generic UI layer, which keeps interface logic decoupled from game entities.
9. Game examples as thin vertical slices
The sample games (frog_hop, neon_odyssey, neon_tank, neon_heights, breakout, newtons_cradle, test_game) demonstrate different combinations of the same engine services. For example, frog_hop uses entities, tilemap levels, HUD, and map JSON; neon_tank emphasizes projectiles/spawning; newtons_cradle exercises physics; breakout is a minimal gameplay example. These are not separate engines, just different application layers on the same core.
10. Authoring and editing tools
draw2d.py is a standalone tilemap editor that writes JSON consumed by TilemapNode. src/the_editor is a separate Flutter application for scene editing, with scene tree, viewport, inspector, and bottom panel widgets. This means content creation is split between a Python tile editor and a richer cross-platform scene editor.
11. Assets and content packs
The src/Free directory contains categorized art/content assets such as terrain, traps, UI elements, characters, checkpoints, and menu art. These assets are organized by gameplay use rather than by engine subsystem, and they feed the sample games and editor-driven scenes.
12. Testing, validation, and benchmarking
tests/ contains headless engine and gameplay verification, including collision, physics, UI, input, event propagation, state, scene manager, and performance tests. src/pyengine2D/benchmark and top-level scripts like run_all_tests.py, check_levels.py, and fuzzer.py show that the repo treats architecture quality and stability as first-class concerns. SDL_VIDEODUMMY headless execution indicates the engine is designed to initialize and run without a visible display for CI-style validation.
13. Key architectural boundaries
The most important boundaries to draw are: engine core vs. game code; scene graph vs. physics/collision; gameplay controllers/FSM vs. low-level movement; runtime engine vs. authoring tools; and reusable UI/runtime systems vs. per-game HUDs and entities. Those boundaries explain how the repository stays reusable while supporting multiple games and editors.
Main entry points: scene Scene tree · core Core runtime · physics Physics · main.py Frog Hop
Components 21
Engine
Reusable Python runtime and subsystems
- Core runtime · Main loop, input, rendering, audio, and signals
src/pyengine2D/core - Master clock · Fixed-step scheduling and frame pacing
src/pyengine2D/time/master_clock.py - Scene tree · Nodes, transforms, lifecycle, cameras, sprites, particles, tweens, parallax, and tilemaps
src/pyengine2D/scene - Scene I/O · Scene manager and serializer for saved content
src/pyengine2D/scene/scene_serializer.py - Collision · Colliders, overlap checks, and resolution
src/pyengine2D/collision - Physics · Bodies, forces, constraints, and world stepping
src/pyengine2D/physics - Rendering · Batching, atlases, surface cache, and pixel helpers
src/pyengine2D/rendering - UI system · Controls, containers, widgets, data binding, and overlays
src/pyengine2D/ui - FSM · Reusable state machine and gameplay states
src/pyengine2D/fsm - Utilities · Asset loading, object pooling, pathfinding, and profiling
src/pyengine2D/utils
Games
Sample game surfaces built on the engine
- Game apps · Top-level game launchers and integration code
src/games - Frog Hop · Entity, level, and JSON map-driven sample
src/games/frog_hop/main.py - Neon Odyssey · Scene-driven game with HUD and moving platforms
src/games/neon_odyssey/main.py - Neon Tank · Tank, spawner, enemy, and projectile gameplay
src/games/neon_tank/main.py - Neon Heights · Scene-file based example with player and hazards
src/games/neon_heights/main.py - Breakout · Minimal vertical slice example
src/games/breakout/main.py - Newton's Cradle · Physics-focused scene example
src/games/newtons_cradle/newtons_cradle.scene - Free assets · Reusable art and menu content organized by gameplay use
src/Free
Tools
Python authoring and validation scripts
- draw2d · Python tilemap authoring tool producing JSON maps
draw2d.py - Validation · Test runner, fuzzing, level checks, and benchmark harness
run_all_tests.py
Editor
Flutter-based scene editor
- The editor · Cross-platform scene editor UI and preview tooling
src/the_editor/lib/main.dart
Connections 24
- Core runtime → Master clock: ticks · The engine loop is paced by master clock scheduling
- Core runtime → Rendering: renders · Core runtime drives frame rendering
- Core runtime → UI system: hosts · UI runs inside the core runtime
- Scene tree → Collision: uses · Scene nodes participate in collision and overlap behavior
- Scene tree → Physics: uses · Scene entities often wrap physics bodies
- Scene I/O → Scene tree: loads · Scene files restore node trees and editor content
- Physics → Collision: resolves · Physics depends on collision queries and contacts
- Rendering → Scene tree: consumes · Renderer draws scene nodes and visual effects
- UI system → Scene tree: embeds · UI tree is distinct but can coexist with scene-driven content
- FSM → Game apps: drives · Gameplay states coordinate player intent and movement
- Game apps → Core runtime: builds on · Games are application layers on the shared engine
- Frog Hop → Scene tree: uses · Frog Hop relies on scene nodes and tilemap-driven levels
- Frog Hop → FSM: uses · Player behavior is structured with shared states
- Neon Odyssey → UI system: uses · HUD and UI presentation are built on the reusable UI system
- Neon Tank → Physics: uses · Projectile and tank movement rely on simulation
- Neon Heights → Scene I/O: loads · Scene example is authored as a saved .scene file
- Newton's Cradle → Physics: demonstrates · Physics demo exercises the simulation layer
- draw2d → Scene tree: exports · Tile editor writes content consumed by tilemap nodes
- The editor → Scene I/O: edits · Editor manages scene assets and saved scene files
- The editor → Scene tree: previews · Live preview reflects scene-tree structure
- Validation → Core runtime: verifies · Test and benchmark tooling checks runtime stability
- Validation → Physics: verifies · Validation covers simulation correctness
- Free assets → Frog Hop: feeds · Shared art assets support sample game content
- Free assets → The editor: feeds · Reusable assets also support authoring workflows