# kitao/pyxel architecture

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

- Interactive diagram: https://gitdiagram.com/kitao/pyxel
- Repository: https://github.com/kitao/pyxel

## Overview

Pyxel is a Python retro-game engine. A developer writes a game using the Python API; its native binding exposes Rust engine functionality, which handles graphics, input, audio, resources, and the platform loop. The repository also provides a resource editor and command-line workflows for running and packaging apps, plus a browser runtime. The README and tree establish these product capabilities, but the sampled source does not expose all internal core call paths, so uncertain engine-to-subsystem links are omitted.

Main entry points: [`crates/pyxel-binding/src/lib.rs`](https://github.com/kitao/pyxel/blob/main/crates/pyxel-binding/src/lib.rs) (PyO3 binding), [`python/pyxel/editor/app.py`](https://github.com/kitao/pyxel/blob/main/python/pyxel/editor/app.py) (Editor application), [`python/pyxel/__init__.py`](https://github.com/kitao/pyxel/blob/main/python/pyxel/__init__.py) (Python API), [`web/mml-studio/mml_studio.py`](https://github.com/kitao/pyxel/blob/main/web/mml-studio/mml_studio.py) (MML Studio)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Game authoring"]
  node_python_api["Python API<br/>[__init__.py]"]
end

subgraph group_engine["Engine runtime"]
  node_binding["PyO3 binding<br/>[lib.rs]"]
  node_engine_main["Engine core<br/>[pyxel.rs]"]
  node_graphics["Graphics and canvas<br/>[graphics.rs]"]
  node_input["Input handling<br/>[input.rs]"]
  node_audio["Audio playback<br/>[audio.rs]"]
  node_mml["MML parsing<br/>[mml_parser.rs]"]
  node_platform["Platform backend<br/>[facade.rs]"]
  node_sdl["SDL2 backend<br/>[platform_sdl2.rs]"]
end

subgraph group_assets["Resources and editor"]
  node_resource_api["Resource API"]
  node_resource_data["Resource data<br/>[resource_data.rs]"]
  node_resource_files["Resource handling<br/>[resource.rs]"]
end

subgraph group_interfaces["User interfaces"]
  node_editor_cli["Editor launcher<br/>[cli.py]"]
  node_editor_app["Editor application<br/>[app.py]"]
  node_image_editor["Image editor<br/>[image_editor.py]"]
  node_tilemap_editor["Tilemap editor<br/>[tilemap_editor.py]"]
  node_sound_editor["Sound editor<br/>[sound_editor.py]"]
  node_music_editor["Music editor<br/>[music_editor.py]"]
  node_browser_runtime["Browser runtime<br/>[pyxel.js]"]
  node_mml_studio["MML Studio<br/>[mml_studio.py]"]
end

node_developer(("Game developer"))
node_web_user(("Browser user"))

node_developer -->|"calls"| node_python_api
node_python_api -->|"invokes native API"| node_binding
node_binding -->|"exposes engine"| node_engine_main
node_binding -->|"registers functions"| node_resource_api
node_resource_api -->|"loads and saves"| node_resource_files
node_resource_files -->|"reads and writes"| node_resource_data
node_engine_main -->|"uses platform"| node_platform
node_platform -->|"dispatches"| node_sdl
node_editor_cli -->|"launches editor"| node_editor_app
node_editor_app -->|"uses engine API"| node_python_api
node_editor_app -->|"hosts editor"| node_image_editor
node_editor_app -->|"hosts editor"| node_tilemap_editor
node_editor_app -->|"hosts editor"| node_sound_editor
node_editor_app -->|"hosts editor"| node_music_editor
node_web_user -->|"starts app"| node_browser_runtime
node_browser_runtime -->|"loads Pyxel"| node_python_api
node_mml_studio -->|"uses engine API"| node_python_api
node_mml_studio -->|"supplies MML"| node_mml
node_binding -->|"wraps API"| node_graphics
node_binding -->|"wraps API"| node_input
node_binding -->|"wraps API"| node_audio
node_audio -->|"parses sound text"| node_mml

click node_python_api "https://github.com/kitao/pyxel/blob/main/python/pyxel/__init__.py"
click node_binding "https://github.com/kitao/pyxel/blob/main/crates/pyxel-binding/src/lib.rs"
click node_engine_main "https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/pyxel.rs"
click node_graphics "https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/graphics.rs"
click node_input "https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/input.rs"
click node_audio "https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/audio.rs"
click node_mml "https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/mml_parser.rs"
click node_platform "https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/platform/facade.rs"
click node_sdl "https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/platform/sdl2/platform_sdl2.rs"
click node_resource_api "https://github.com/kitao/pyxel/blob/main/crates/pyxel-binding/src/resource_wrapper.rs"
click node_resource_data "https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/resource_data.rs"
click node_resource_files "https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/resource.rs"
click node_editor_cli "https://github.com/kitao/pyxel/blob/main/python/pyxel/cli.py"
click node_editor_app "https://github.com/kitao/pyxel/blob/main/python/pyxel/editor/app.py"
click node_image_editor "https://github.com/kitao/pyxel/blob/main/python/pyxel/editor/image_editor.py"
click node_tilemap_editor "https://github.com/kitao/pyxel/blob/main/python/pyxel/editor/tilemap_editor.py"
click node_sound_editor "https://github.com/kitao/pyxel/blob/main/python/pyxel/editor/sound_editor.py"
click node_music_editor "https://github.com/kitao/pyxel/blob/main/python/pyxel/editor/music_editor.py"
click node_browser_runtime "https://github.com/kitao/pyxel/blob/main/wasm/pyxel.js"
click node_mml_studio "https://github.com/kitao/pyxel/blob/main/web/mml-studio/mml_studio.py"

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_python_api,node_web_user toneBlue
class node_binding,node_engine_main,node_graphics,node_input,node_audio,node_mml,node_platform,node_sdl toneAmber
class node_resource_api,node_resource_data,node_resource_files toneMint
class node_editor_cli,node_editor_app,node_image_editor,node_tilemap_editor,node_sound_editor,node_music_editor,node_browser_runtime,node_mml_studio toneRose
class node_developer toneIndigo
```

## Components

### Game authoring

- [Python API](https://github.com/kitao/pyxel/blob/main/python/pyxel/__init__.py): `python/pyxel/__init__.py`

### Engine runtime

- [PyO3 binding](https://github.com/kitao/pyxel/blob/main/crates/pyxel-binding/src/lib.rs): `crates/pyxel-binding/src/lib.rs`
- [Engine core](https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/pyxel.rs): `crates/pyxel-core/src/pyxel.rs`
- [Graphics and canvas](https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/graphics.rs): `crates/pyxel-core/src/graphics.rs`
- [Input handling](https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/input.rs): `crates/pyxel-core/src/input.rs`
- [Audio playback](https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/audio.rs): `crates/pyxel-core/src/audio.rs`
- [MML parsing](https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/mml_parser.rs): `crates/pyxel-core/src/mml_parser.rs`
- [Platform backend](https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/platform/facade.rs): `crates/pyxel-core/src/platform/facade.rs`
- [SDL2 backend](https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/platform/sdl2/platform_sdl2.rs): `crates/pyxel-core/src/platform/sdl2/platform_sdl2.rs`

### Resources and editor

- [Resource API](https://github.com/kitao/pyxel/blob/main/crates/pyxel-binding/src/resource_wrapper.rs): `crates/pyxel-binding/src/resource_wrapper.rs`
- [Resource data](https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/resource_data.rs): `crates/pyxel-core/src/resource_data.rs`
- [Resource handling](https://github.com/kitao/pyxel/blob/main/crates/pyxel-core/src/resource.rs): `crates/pyxel-core/src/resource.rs`

### User interfaces

- [Editor launcher](https://github.com/kitao/pyxel/blob/main/python/pyxel/cli.py): `python/pyxel/cli.py`
- [Editor application](https://github.com/kitao/pyxel/blob/main/python/pyxel/editor/app.py): `python/pyxel/editor/app.py`
- [Image editor](https://github.com/kitao/pyxel/blob/main/python/pyxel/editor/image_editor.py): `python/pyxel/editor/image_editor.py`
- [Tilemap editor](https://github.com/kitao/pyxel/blob/main/python/pyxel/editor/tilemap_editor.py): `python/pyxel/editor/tilemap_editor.py`
- [Sound editor](https://github.com/kitao/pyxel/blob/main/python/pyxel/editor/sound_editor.py): `python/pyxel/editor/sound_editor.py`
- [Music editor](https://github.com/kitao/pyxel/blob/main/python/pyxel/editor/music_editor.py): `python/pyxel/editor/music_editor.py`
- [Browser runtime](https://github.com/kitao/pyxel/blob/main/wasm/pyxel.js): `wasm/pyxel.js`
- [MML Studio](https://github.com/kitao/pyxel/blob/main/web/mml-studio/mml_studio.py): `web/mml-studio/mml_studio.py`

### Other components

- **Game developer**
- **Browser user**

## Connections

- Game developer → Python API: calls
- Python API → PyO3 binding: invokes native API
- PyO3 binding → Engine core: exposes engine
- PyO3 binding → Resource API: registers functions
- Resource API → Resource handling: loads and saves
- Resource handling → Resource data: reads and writes
- Engine core → Platform backend: uses platform
- Platform backend → SDL2 backend: dispatches
- Editor launcher → Editor application: launches editor
- Editor application → Python API: uses engine API
- Editor application → Image editor: hosts editor
- Editor application → Tilemap editor: hosts editor
- Editor application → Sound editor: hosts editor
- Editor application → Music editor: hosts editor
- Browser user → Browser runtime: starts app
- Browser runtime → Python API: loads Pyxel
- MML Studio → Python API: uses engine API
- MML Studio → MML parsing: supplies MML
- PyO3 binding → Graphics and canvas: wraps API
- PyO3 binding → Input handling: wraps API
- PyO3 binding → Audio playback: wraps API
- Audio playback → MML parsing: parses sound text