PixelRoot32 Documentation

This repository contains the source files of PixelRoot32 Game Engine's documentation, in Markdown format.

They are meant to be parsed with MkDocs and the Material theme to build the HTML documentation on PixelRoot32's documentation site.

Download for Offline Use

To browse the documentation offline, you can:

1. Clone this repository:

   git clone https://github.com/PixelRoot32-Game-Engine/pixelroot32-game-engine.github.io.git
   cd pixelroot32-game-engine.github.io

2. Install dependencies:

   pip install mkdocs mkdocs-material

3. Build the documentation:

   mkdocs build

   The HTML files will be generated in the site/ directory. Open site/index.html in your web browser.

4. Serve locally (for development):

   mkdocs serve

   The documentation will be available at http://127.0.0.1:8000

Theming

The PixelRoot32 documentation uses the Material theme for MkDocs with custom styling. It supports:

• Light mode: Default theme
• Dark mode: Automatic switching based on browser/OS preference
• Mobile-friendly: Responsive design for all devices
• Search: Full-text search across all documentation

Documentation Structure

The documentation is organized into the following sections:

Getting Started

• What is PixelRoot32?
• Why PixelRoot32?
• Fundamental Concepts
• Your First Project
• Installation

Manual

• Game Development: Scenes, Entities, Rendering, Input, Audio, Physics, UI
• Advanced Graphics: Sprites, Palettes, Cameras, Tilemaps, Particles
• Optimization: Memory Management, Performance, Platforms, Extensibility

Reference

• API Overview
• Code Examples
• Game Examples Guide

API Reference

Complete technical reference organized by modules:

• Core (Engine, Scene, Entity, Actor, PhysicsActor, Input)
• Graphics (Renderer, Camera2D, Color, Font, Sprite, TileMap)
• Audio (AudioEngine, MusicPlayer, AudioTypes, AudioConfig)
• Physics (CollisionSystem, CollisionTypes)
• UI (UIElement, UIButton, UILabel, Layouts)

Examples (Game Samples)

Documentación de los juegos y demos incluidos en PixelRoot32 Game Samples:

Ejemplo	Descripción	Motor / características
Pong	Clásico con física y colisiones	PhysicsActor, Audio (PICO8)
BrickBreaker	Estilo Breakout, partículas	PhysicsActor, ParticleEmitter, Audio (GBC)
Snake	Juego en rejilla, pool de entidades	Entity pooling, rejilla discreta
Space Invaders	Shooter completo	1bpp sprites, colisiones swept, música dinámica, starfield
TicTacToe	Turnos y IA simple	UI, lógica de tablero
Metroidvania	Plataformas 2D, tilemap multicapa	4bpp sprites, TileMap4bpp, colisión tile-based, escaleras, optimizaciones ESP32 (sin cámara/scroll)
CameraDemo	Scroll horizontal y parallax	Camera2D, plataformas, capas
SpritesDemo	Formatos 2bpp y 4bpp	Sprite2bpp, Sprite4bpp, animación
TileMapDemo	Tilemaps 4bpp	TileMap4bpp, viewport culling

Herramientas e implementaciones del motor

Herramientas usadas en los ejemplos:

Herramienta	Uso	Repositorio / notas
PixelRoot32 Sprite Compiler	Convierte PNG a datos 1bpp/2bpp/4bpp (C++ headers)	PixelRoot32 Sprite Compiler (Python)
PixelRoot32 Tilemap Editor	Edición visual de tilemaps, export a C++	PixelRoot32 Tilemap Editor (opcional; algunos fondos se generan en código)

Implementaciones del motor en Game Samples:

Componente	ESP32	Native (PC)
Display	TFT_eSPI (ST7789 240×240), buffer + DMA	SDL2, ventana 240×240
Input	5 botones digitales (InputConfig)	Teclado → scancodes
Audio	DAC interno o I2S (ESP32_DAC / ESP32_I2S)	SDL2 audio
Sprites	1bpp (siempre), 2bpp/4bpp con PIXELROOT32_ENABLE_*	Igual
Escenas	Scene, SceneArena (arena opcional), MAX_ENTITIES configurable	Igual

Opciones de build relevantes (en platformio.ini de Game Samples):

• PIXELROOT32_ENABLE_2BPP_SPRITES / PIXELROOT32_ENABLE_4BPP_SPRITES: sprites 2bpp y 4bpp.
• PIXELROOT32_ENABLE_SCENE_ARENA: asignación desde arena en escena (menos new/delete).
• MAX_ENTITIES, MAX_LAYERS: límites de entidades y capas de render.

Tools

• Sprite Compiler: Overview, instalación, guía de uso y características avanzadas (1bpp, 2bpp, 4bpp).
• Tilemap Editor: Edición visual de tilemaps y export a C++ (referencia en docs cuando esté habilitada).

Resources

• Available Tools
• Troubleshooting
• Limitations and Considerations
• FAQ

Contributing

All contributors are welcome to help improve the PixelRoot32 documentation.

Quick Start

1. Fork and clone the repository:

   git clone https://github.com/PixelRoot32-Game-Engine/pixelroot32-game-engine.github.io.git
   cd pixelroot32-game-engine.github.io

2. Set up development environment:

   pip install mkdocs mkdocs-material

3. Make your changes:

   • Edit Markdown files in docs/
   • Add new files as needed
   • Update mkdocs.yml if adding new pages

4. Preview locally:

   mkdocs serve

   Visit http://127.0.0.1:8000 to see your changes

5. Build to verify:

   mkdocs build

6. Submit a Pull Request

Documentation Guidelines

• Language: Spanish (as per project rule)
• Format: Markdown with Material theme extensions
• Code: Use code blocks with syntax highlighting
• Links: Use relative paths between documents
• Examples: Include complete, functional code
• Accuracy: All documented APIs must exist in the codebase
• Completeness: Code examples must compile and work

Areas to Contribute

1. Manual Sections: Expand existing guides or add new topics
2. API Reference: Verify and update API documentation
3. Code Examples: Add practical, working examples
4. Game Examples: Document complete game implementations
5. Troubleshooting: Add solutions to common problems
6. Translations: Help translate to other languages (future)

Building the Documentation

Requirements

• Python 3.8 or higher
• pip (Python package manager)
• MkDocs and Material theme

Installation

pip install mkdocs mkdocs-material

Build Commands

Serve locally (development):

mkdocs serve

Build static site:

mkdocs build

Deploy to GitHub Pages:

mkdocs gh-deploy

Project Structure

PixelRoot32-Docs/
├── docs/                          # Documentation source (Markdown)
│   ├── getting_started/          # Getting started guides
│   ├── manual/                    # User manual
│   │   ├── game_development/     # Core game development
│   │   ├── advanced_graphics/    # Advanced graphics
│   │   └── optimization/         # Optimization guides
│   ├── reference/                 # Reference documentation (incl. Game Examples Guide)
│   ├── api_reference/            # Complete API reference
│   ├── tools/                     # Tool documentation
│   └── resources/                 # Resources (FAQ, troubleshooting, etc.)
├── site/                          # Generated HTML (git-ignored)
├── mkdocs.yml                     # MkDocs configuration
└── README.md                      # This file

Related Repositories

• Engine: PixelRoot32-Game-Engine - Main game engine repository
• Samples: PixelRoot32-Game-Samples - Example games and demos
• Sprite Compiler: PixelRoot32-Sprite-Sheet-Compiler - Sprite conversion tool

License

The documentation content in this repository is licensed under the MIT License, the same as the PixelRoot32 Game Engine.

See individual source files for license details.

---

Last updated: January 29, 2026