# nalqit/py-engine architecture

> Architecture diagram of the GitHub repository nalqit/py-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nalqit/py-engine
- Repository: https://github.com/nalqit/py-engine

## Overview

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: [`src/pyengine2D/scene`](https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/scene) (Scene tree), [`src/pyengine2D/core`](https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/core) (Core runtime), [`src/pyengine2D/physics`](https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/physics) (Physics), [`src/games/frog_hop/main.py`](https://github.com/nalqit/py-engine/blob/main/src/games/frog_hop/main.py) (Frog Hop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Engine"]
  node_engine_core["Core runtime<br/>engine base"]
  node_engine_clock(("Master clock<br/>timing<br/>[master_clock.py]"))
  node_engine_scene["Scene tree<br/>composition"]
  node_engine_serialization["Scene I/O<br/>serialization"]
  node_engine_collision{{"Collision<br/>narrow-phase"}}
  node_engine_physics{{"Physics<br/>simulation"}}
  node_engine_rendering["Rendering<br/>renderer"]
  node_engine_ui["UI system<br/>ui framework"]
  node_engine_fsm{{"FSM<br/>state layer"}}
  node_engine_utils["Utilities<br/>support"]
end

subgraph group_games["Games"]
  node_game_main["Game apps<br/>app entrypoints"]
  node_game_frog_hop["Frog Hop<br/>platformer<br/>[main.py]"]
  node_game_neon_odyssey["Neon Odyssey<br/>action game<br/>[main.py]"]
  node_game_neon_tank["Neon Tank<br/>shooter<br/>[main.py]"]
  node_game_neon_heights["Neon Heights<br/>scene demo<br/>[main.py]"]
  node_game_breakout["Breakout<br/>arcade demo<br/>[main.py]"]
  node_game_newtons["Newton's Cradle<br/>physics demo"]
  node_content_free["Free assets<br/>asset pack"]
end

subgraph group_tools["Tools"]
  node_tools_draw2d["draw2d<br/>tile editor<br/>[draw2d.py]"]
  node_tools_validation["Validation<br/>test and bench<br/>[run_all_tests.py]"]
end

subgraph group_editor["Editor"]
  node_editor_flutter["The editor<br/>flutter app<br/>[main.dart]"]
end

node_engine_core -->|"ticks"| node_engine_clock
node_engine_core -->|"renders"| node_engine_rendering
node_engine_core -->|"hosts"| node_engine_ui
node_engine_scene -->|"uses"| node_engine_collision
node_engine_scene -->|"uses"| node_engine_physics
node_engine_serialization -->|"loads"| node_engine_scene
node_engine_physics -->|"resolves"| node_engine_collision
node_engine_rendering -->|"consumes"| node_engine_scene
node_engine_ui -->|"embeds"| node_engine_scene
node_engine_fsm -->|"drives"| node_game_main
node_game_main -->|"builds on"| node_engine_core
node_game_frog_hop -->|"uses"| node_engine_scene
node_game_frog_hop -->|"uses"| node_engine_fsm
node_game_neon_odyssey -->|"uses"| node_engine_ui
node_game_neon_tank -->|"uses"| node_engine_physics
node_game_neon_heights -->|"loads"| node_engine_serialization
node_game_newtons -->|"demonstrates"| node_engine_physics
node_tools_draw2d -->|"exports"| node_engine_scene
node_editor_flutter -->|"edits"| node_engine_serialization
node_editor_flutter -->|"previews"| node_engine_scene
node_tools_validation -->|"verifies"| node_engine_core
node_tools_validation -->|"verifies"| node_engine_physics
node_content_free -->|"feeds"| node_game_frog_hop
node_content_free -->|"feeds"| node_editor_flutter

click node_engine_core "https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/core"
click node_engine_clock "https://github.com/nalqit/py-engine/blob/main/src/pyengine2D/time/master_clock.py"
click node_engine_scene "https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/scene"
click node_engine_serialization "https://github.com/nalqit/py-engine/blob/main/src/pyengine2D/scene/scene_serializer.py"
click node_engine_collision "https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/collision"
click node_engine_physics "https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/physics"
click node_engine_rendering "https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/rendering"
click node_engine_ui "https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/ui"
click node_engine_fsm "https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/fsm"
click node_engine_utils "https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/utils"
click node_game_main "https://github.com/nalqit/py-engine/tree/main/src/games"
click node_game_frog_hop "https://github.com/nalqit/py-engine/blob/main/src/games/frog_hop/main.py"
click node_game_neon_odyssey "https://github.com/nalqit/py-engine/blob/main/src/games/neon_odyssey/main.py"
click node_game_neon_tank "https://github.com/nalqit/py-engine/blob/main/src/games/neon_tank/main.py"
click node_game_neon_heights "https://github.com/nalqit/py-engine/blob/main/src/games/neon_heights/main.py"
click node_game_breakout "https://github.com/nalqit/py-engine/blob/main/src/games/breakout/main.py"
click node_game_newtons "https://github.com/nalqit/py-engine/blob/main/src/games/newtons_cradle/newtons_cradle.scene"
click node_tools_draw2d "https://github.com/nalqit/py-engine/blob/main/draw2d.py"
click node_tools_validation "https://github.com/nalqit/py-engine/blob/main/run_all_tests.py"
click node_editor_flutter "https://github.com/nalqit/py-engine/blob/main/src/the_editor/lib/main.dart"
click node_content_free "https://github.com/nalqit/py-engine/tree/main/src/Free"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_engine_core,node_engine_clock,node_engine_scene,node_engine_serialization,node_engine_collision,node_engine_physics,node_engine_rendering,node_engine_ui,node_engine_fsm,node_engine_utils toneBlue
class node_game_main,node_game_frog_hop,node_game_neon_odyssey,node_game_neon_tank,node_game_neon_heights,node_game_breakout,node_game_newtons,node_content_free toneAmber
class node_tools_draw2d,node_tools_validation toneMint
class node_editor_flutter toneRose
```

## Components

### Engine

Reusable Python runtime and subsystems

- [Core runtime](https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/core): engine base · Main loop, input, rendering, audio, and signals · `src/pyengine2D/core`
- [Master clock](https://github.com/nalqit/py-engine/blob/main/src/pyengine2D/time/master_clock.py): timing · Fixed-step scheduling and frame pacing · `src/pyengine2D/time/master_clock.py`
- [Scene tree](https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/scene): composition · Nodes, transforms, lifecycle, cameras, sprites, particles, tweens, parallax, and tilemaps · `src/pyengine2D/scene`
- [Scene I/O](https://github.com/nalqit/py-engine/blob/main/src/pyengine2D/scene/scene_serializer.py): serialization · Scene manager and serializer for saved content · `src/pyengine2D/scene/scene_serializer.py`
- [Collision](https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/collision): narrow-phase · Colliders, overlap checks, and resolution · `src/pyengine2D/collision`
- [Physics](https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/physics): simulation · Bodies, forces, constraints, and world stepping · `src/pyengine2D/physics`
- [Rendering](https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/rendering): renderer · Batching, atlases, surface cache, and pixel helpers · `src/pyengine2D/rendering`
- [UI system](https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/ui): ui framework · Controls, containers, widgets, data binding, and overlays · `src/pyengine2D/ui`
- [FSM](https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/fsm): state layer · Reusable state machine and gameplay states · `src/pyengine2D/fsm`
- [Utilities](https://github.com/nalqit/py-engine/tree/main/src/pyengine2D/utils): support · Asset loading, object pooling, pathfinding, and profiling · `src/pyengine2D/utils`

### Games

Sample game surfaces built on the engine

- [Game apps](https://github.com/nalqit/py-engine/tree/main/src/games): app entrypoints · Top-level game launchers and integration code · `src/games`
- [Frog Hop](https://github.com/nalqit/py-engine/blob/main/src/games/frog_hop/main.py): platformer · Entity, level, and JSON map-driven sample · `src/games/frog_hop/main.py`
- [Neon Odyssey](https://github.com/nalqit/py-engine/blob/main/src/games/neon_odyssey/main.py): action game · Scene-driven game with HUD and moving platforms · `src/games/neon_odyssey/main.py`
- [Neon Tank](https://github.com/nalqit/py-engine/blob/main/src/games/neon_tank/main.py): shooter · Tank, spawner, enemy, and projectile gameplay · `src/games/neon_tank/main.py`
- [Neon Heights](https://github.com/nalqit/py-engine/blob/main/src/games/neon_heights/main.py): scene demo · Scene-file based example with player and hazards · `src/games/neon_heights/main.py`
- [Breakout](https://github.com/nalqit/py-engine/blob/main/src/games/breakout/main.py): arcade demo · Minimal vertical slice example · `src/games/breakout/main.py`
- [Newton's Cradle](https://github.com/nalqit/py-engine/blob/main/src/games/newtons_cradle/newtons_cradle.scene): physics demo · Physics-focused scene example · `src/games/newtons_cradle/newtons_cradle.scene`
- [Free assets](https://github.com/nalqit/py-engine/tree/main/src/Free): asset pack · Reusable art and menu content organized by gameplay use · `src/Free`

### Tools

Python authoring and validation scripts

- [draw2d](https://github.com/nalqit/py-engine/blob/main/draw2d.py): tile editor · Python tilemap authoring tool producing JSON maps · `draw2d.py`
- [Validation](https://github.com/nalqit/py-engine/blob/main/run_all_tests.py): test and bench · Test runner, fuzzing, level checks, and benchmark harness · `run_all_tests.py`

### Editor

Flutter-based scene editor

- [The editor](https://github.com/nalqit/py-engine/blob/main/src/the_editor/lib/main.dart): flutter app · Cross-platform scene editor UI and preview tooling · `src/the_editor/lib/main.dart`

## Connections

- 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
