https://github.com/trivox-io/mini-arcade
Python-first mini game engine for building small arcade games and reusable gameplay systems.
https://github.com/trivox-io/mini-arcade
cpp game-development game-framework python
Last synced: 3 months ago
JSON representation
Python-first mini game engine for building small arcade games and reusable gameplay systems.
- Host: GitHub
- URL: https://github.com/trivox-io/mini-arcade
- Owner: trivox-io
- License: mit
- Created: 2026-02-12T12:25:12.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-03-31T12:35:08.000Z (3 months ago)
- Last Synced: 2026-03-31T13:31:39.414Z (3 months ago)
- Topics: cpp, game-development, game-framework, python
- Language: Python
- Homepage: http://mini-arcade.trivox.io/
- Size: 1 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Mini Arcade
> A Python-first mini game engine and toolkit for building small arcade games.
[](https://github.com/trivox-io/mini-arcade/actions/workflows/ci.yml)
[](./LICENSE)
[](https://pypi.org/project/mini-arcade/)
[](./docs)
Mini Arcade is a monorepo with a simulation-first engine core, swappable backends
(native SDL2 and pygame), runnable examples, and reference games.
## Status
Current status: alpha.
The project is actively developed and APIs may still evolve.
## Quick Start
Install:
```bash
pip install mini-arcade
```
Run from an installed environment:
```bash
mini-arcade run --example config/engine_config_basics
mini-arcade run --game deja-bounce
```
Equivalent module form:
```bash
python -m mini_arcade.main run --example config/engine_config_basics
python -m mini_arcade.main run --game deja-bounce
```
## Local Development
From the monorepo root:
```powershell
./scripts/dev_install.ps1
python .\manage.py run --example config/engine_config_basics
python .\manage.py run --game space-invaders
```
Notes:
- `manage.py` is the preferred local entrypoint for games and examples.
- The runner prepends local `packages/*/src` paths so workspace code wins over
installed wheel metadata.
- When `backend.provider: native` is selected, Mini Arcade now honors that
choice strictly. It does not silently fall back to `pygame`.
- The native backend uses Python source from the repo plus a compiled `_native`
extension from the active environment. If Python and C++ changes drift out of
sync, rebuild with:
```powershell
python -m pip install -e .\packages\mini-arcade-native-backend
```
## Core Features
- Scene registry and scene stack with overlays
- System pipeline with ordered phases
- Command queue for scene/game actions
- Runtime services (window, input, render, audio, capture, files)
- Render pipeline passes (begin, world, lighting, ui, postfx, end)
- Built-in capture hooks (screenshot, replay, video frame capture)
- Swappable backends:
- `mini-arcade-pygame-backend`
- `mini-arcade-native-backend`
## CLI Usage
Run a game:
```bash
mini-arcade run --game asteroids
```
Run an example:
```bash
mini-arcade run --example config/backend_swap
```
Run all examples as a tour:
```bash
mini-arcade run tour
```
Forward args to the example runner:
```bash
mini-arcade run --example config/backend_swap --pass-through --backend native --fps 72
```
## API Usage (Core)
```python
from mini_arcade_core import EngineConfig, SceneConfig, run_game
from mini_arcade_pygame_backend import PygameBackend, PygameBackendSettings
backend_settings = PygameBackendSettings.from_dict(
{
"window": {"width": 960, "height": 540, "title": "My Game"},
"renderer": {"background_color": (20, 20, 20)},
}
)
backend = PygameBackend(settings=backend_settings)
engine_config = EngineConfig(
fps=60,
virtual_resolution=(960, 540),
enable_profiler=False,
)
scene_config = SceneConfig(
initial_scene="menu",
discover_packages=["my_game.scenes", "mini_arcade_core.scenes"],
)
run_game(
engine_config=engine_config,
scene_config=scene_config,
backend=backend,
)
```
## Create Your Own Game
Use the detailed guide:
- [docs/source/tutorials/create_game.md](./docs/source/tutorials/create_game.md)
That guide includes:
- required folder and metadata layout
- complete `settings.yml` template
- minimal runnable scene and commands
- full bootstrap (`manage.py` + `app.py`) pattern used by current games
## Monorepo Layout
```text
mini-arcade/
|- packages/
| |- mini-arcade/
| |- mini-arcade-core/
| |- mini-arcade-pygame-backend/
| `- mini-arcade-native-backend/
|- games/
|- examples/
|- docs/
`- scripts/
```
## Documentation
- [Quickstart](./docs/source/quickstart.md)
- [Architecture](./docs/source/concepts/architecture.md)
- [Capabilities](./docs/source/concepts/capabilities.md)
- [Backends](./docs/source/concepts/backends.md)
- [Tutorials](./docs/source/tutorials/index.md)
- [Games](./docs/source/games/index.md)
- [Contributing](./docs/source/contributing/index.md)
## Contributing
See:
- [docs/source/contributing/dev_setup.md](./docs/source/contributing/dev_setup.md)
- [docs/source/contributing/release_process.md](./docs/source/contributing/release_process.md)
## License
MIT. See [LICENSE](./LICENSE).