PixelRoot32 Tilemap Editor - Complete User Guide¶

Table of Contents¶

1. Introduction
2. Getting Started
3. Project Configuration
4. Working with Tilesets
5. Scene System
6. Editing Tools
7. Layer Management
8. Onion Skinning
9. C++ Export
10. Advanced Configuration
11. Keyboard Shortcuts
12. Technical Specifications

1. Introduction¶

The PixelRoot32 Tilemap Editor is a specialized tool for creating and editing tile-based maps for the PixelRoot32 engine, specifically optimized for ESP32 hardware constraints.

Key Features¶

• Visual Tilemap Editor with multi-layer support
• Tileset Management with automatic import
• Scene System to organize levels/rooms
• C++ Export with ESP32 optimization
• Onion Skinning to align elements between scenes
• Undo/Redo System with history compression
• Binary Format for large projects (up to 335x smaller)

2. Getting Started¶

2.1 Starting the Application¶

# From the PixelRoot32 Suite launcher
python main.py

# Or run directly
python -m modules.tilemap_editor

2.2 Welcome Screen¶

When starting without a project, you will see the welcome screen with two options:

• Create New Project: Create a new project from scratch
• Open Existing Project: Open an existing project (.pr32scene or .pr32scene.bin)

3. Project Configuration¶

3.1 Creating a New Project¶

Step 1: Click on "Create New Project"

Step 2: Configure the project parameters:

Step 3: Click on "Create Project"

Step 4: Select an empty folder to save the project

Note: If the folder is not empty, you will be asked if you want to create a subfolder.

3.2 "Fit Map to Hardware Limit" Button¶

This automatic button calculates map dimensions to completely fill the ESP32 screen (320x240 or 240x320 depending on orientation) based on the selected tile size.

Example: With 16px tiles in Landscape mode: - Map Width = 320 ÷ 16 = 20 tiles - Map Height = 240 ÷ 16 = 15 tiles

3.3 Modifying Project Configuration¶

To edit the configuration after creating the project:

1. Click the Settings button (gear icon) in the toolbar
2. Or use the menu File → Project Settings
3. Modify the necessary values
4. Click OK to save

Important: Changing the tile size will affect all existing tilesets.

4. Working with Tilesets¶

4.1 Importing a Tileset¶

Method 1 - Import Button: 1. In the TILESET panel (left sidebar), click Import tileset 2. Select a PNG, JPG, or BMP image 3. The image will be automatically copied to assets/tilesets/

Method 2 - File Menu: 1. Go to File → Import Tileset 2. Select the image

Recommended Format: - Resolution: Multiples of the tile size - Supported formats: PNG (recommended), JPG, BMP - Colors: Up to 16 colors for 4bpp

4.2 Selecting Tiles¶

Individual Selection: - Click on a tile in the TILESET panel - The selected tile is highlighted with a cyan border

Rectangular Selection: - Click on the starting tile - Drag to the final tile - Release to confirm the selection

The rectangular selection appears semi-transparent and allows you to paint full patterns at once.

4.3 Zoom in the Tileset Panel¶

• Zoom In: Mouse wheel up
• Zoom Out: Mouse wheel down
• Zoom adjusts in 0.5x increments (min 1x, max 10x)

4.4 Multiple Tilesets¶

You can import several tilesets in the same project: 1. Import the first tileset normally 2. Repeat the process for additional tilesets 3. Tilesets are displayed one after another in the panel 4. The tile index is global (accumulated between tilesets)

Example:

Tileset A: 10 tiles (indices 0-9)
Tileset B: 8 tiles (indices 10-17)
Tileset C: 5 tiles (indices 18-22)

5. Scene System¶

5.1 What are Scenes?¶

Scenes are independent levels or "rooms" within a project. Each scene has: - Its own dimensions - Its own layers - Access to the same project tilesets

5.2 Creating a New Scene¶

1. In the SCENE panel, click the + (Add Scene) button
2. The new scene is created with the same dimensions as the active scene
3. A "Background" layer is automatically added

5.3 Switching Between Scenes¶

• Click on the name of any scene in the SCENE panel
• The canvas updates automatically
• The layers panel updates to show those of the selected scene

5.4 Renaming a Scene¶

1. Right-click on the scene
2. Select Rename
3. Type the new name
4. Press Enter to confirm

5.5 Duplicating a Scene¶

1. Right-click on the scene
2. Select Duplicate
3. An exact copy is created with the suffix "(Copy)"

5.6 Deleting a Scene¶

1. Right-click on the scene
2. Select Delete
3. Confirm deletion

Note: You cannot delete the last scene in the project.

6. Editing Tools¶

6.1 Brush Tool¶

Basic Use: 1. Select the Brush tool (key B) 2. Select a tile from the TILESET panel 3. Click on the canvas to paint 4. Drag to paint continuously

Painting Multiple Selections: 1. Select a rectangular area in the tileset 2. Paint on the canvas - the full pattern will be applied

6.2 Rectangle Tool¶

1. Select the Rectangle tool (key R)
2. Click and drag on the canvas
3. Release to fill the area with the selected tile

6.3 Eraser Tool¶

Method 1 - Dedicated Tool: 1. Select the Eraser tool (key E) 2. Click or drag to erase tiles

Method 2 - Right Click: - In any tool, right-click to erase - This is a universal shortcut that always works

6.4 Pipette Tool (Eyedropper)¶

1. Select the Pipette tool (key P)
2. Click on any tile on the canvas
3. That tile is automatically selected in the TILESET panel

Useful for quickly copying tiles already placed.

6.5 Pan Tool (Move Canvas)¶

1. Hold down the Space key
2. Drag to move the canvas view
3. Release Space to return to the previous tool

6.6 Zoom in the Canvas¶

6.7 Tool Preview¶

When you move the mouse over the canvas: - A dotted rectangle appears showing where it will paint - Preview tiles appear semi-transparent (50% opacity) - This allows you to position precisely before clicking

7. Layer Management¶

7.1 What are Layers?¶

Layers allow organizing map elements at different depth levels: - Top layer: Rendered above the others - Bottom layer: Rendered below the others - Maximum: 8 layers (ESP32 engine limit)

7.2 Layer Operations¶

Add a layer: 1. Click + in the LAYER panel 2. The new layer is inserted above the selected one

Delete a layer: 1. Click the 🗑️ (delete) icon on the layer 2. Confirm deletion 3. You cannot delete the last layer

Duplicate a layer: 1. Click the 📄 (duplicate) icon on the layer 2. A copy is created with the suffix "(Copy)"

Change layer order: - Drag and drop layers in the LAYER panel - Or use the ordering commands

Rename a layer: 1. Double-click on the layer name 2. Type the new name 3. Press Enter

7.3 Layer Visibility¶

• Click the 👁️ (eye) icon to show/hide a layer
• Hidden layers are not exported
• Useful for working on specific layers without distractions

7.4 Selecting Active Layer¶

Click on any layer in the panel to select it as the working layer: - The active layer is highlighted - All painting operations affect this layer

8. Onion Skinning¶

8.1 What is Onion Skinning?¶

Onion skinning shows other translucent scenes over the active scene. It is useful for: - Aligning exits between levels - Checking platform consistency - Comparing designs between scenes

8.2 Activating Onion Skinning¶

Per individual scene: 1. In the SCENE panel, click the 🧅 (onion) icon next to a scene 2. The selected scene will appear translucent on the canvas

Global control: 1. Activate the "Show Onion Skin" checkbox in the SCENE panel 2. This shows/hides all scenes with onion activated

8.3 Adjusting Opacity¶

• Use the "Opacity" slider in the SCENE panel
• Recommended value: 0.3 - 0.5 (30% - 50%)
• Default value: 0.4 (40%)

8.4 Practical Use¶

Example - Aligning an exit: 1. Activate onion on the scene of the previous level 2. Adjust opacity to see both scenes 3. Place the exit in the current scene aligned with the entrance of the other 4. Deactivate onion when finished

Note: Scenes with onion skin are non-interactive (visual only).

9. C++ Export¶

9.1 Requirements¶

C++ export requires a valid license. Without a license, the export button will show 🔒 and redirect to the upgrade dialogue.

9.2 Export Process¶

Step 1: Click on Export (Ctrl+E) or go to File → Export to C++

Step 2: Configure options in the export panel:

Step 3: Click on Export Now

Step 4: Select destination folder

9.3 Generated Files¶

For a scene named "Level1":

level1.h        # Header with declarations
level1.cpp      # Implementation with data

The .cpp file contains: - Palette data: Colors in RGB565 format - Tileset pool: Tiles in compressed format - Layer indices: Index maps per layer - Initialization code: Loading functions

9.4 Automatic BPP Detection¶

The editor automatically analyzes used colors:

9.5 Integration with your Game¶

#include "level1.h"

// In your initialization code
level1::init();

// In your rendering loop
renderer.drawTileMap(level1::layer_background, x, y);
renderer.drawTileMap(level1::layer_foreground, x, y);

9.6 Export Optimizations¶

The editor automatically performs: 1. Deduplication: Removes identical tiles 2. Compression: Reduces data size 3. Reserved Index 0: Empty tile for transparency 4. Palette Mapping: Optimizes color indices

10. Advanced Configuration¶

10.1 Editor Preferences¶

Access through File → Preferences:

Grid Settings: - Canvas Grid Intensity: Grid opacity (0-255) - Tileset Grid Intensity: Grid opacity in tileset

Auto-save: - Enabled: Activate/deactivate auto-save - Interval: Minutes between auto-saves (1-60)

Optimization: - History Compression: Compresses consecutive operations - Use Binary Format: Uses .bin format by default

10.2 File Formats¶

JSON (.pr32scene): - ✅ Human readable - ✅ Easy to version with git - ❌ Large files - ❌ Slower loading

Binary (.pr32scene.bin): - ✅ Small files (up to 335x smaller) - ✅ Fast Load/Save - ✅ Recommended for large projects - ❌ Not directly readable

10.3 Configure Workspace¶

1. Go to File → Select Workspace
2. Select the root folder of your PixelRoot32 projects
3. This helps the editor locate assets and examples

10.4 Memory Management¶

The editor includes optimizations for limited hardware: - Lazy Loading: Scenes load on demand - Chunk Caching: Rendering by chunks for better performance - History Compression: Reduces RAM usage in long sessions

11. Keyboard Shortcuts¶

11.1 Tools¶

11.2 Navigation and Zoom¶

11.3 Editing¶

11.4 Mouse Shortcuts¶

Note: On macOS, use Cmd instead of Ctrl.

12. Technical Specifications¶

12.1 Engine Limits¶

To ensure ESP32 compatibility:

12.2 Screen Resolutions¶

Landscape Mode: - Maximum: 320x240 px - Aspect ratio: 4:3

Portrait Mode: - Maximum: 240x320 px - Aspect ratio: 3:4

12.3 Data Formats¶

Palette: - Format: RGB565 - Size: 16 colors (maximum) - Index 0: Transparent (for multi-bpp)

Tiles: - 1 bpp: 1 byte per row (8 pixels) - 2 bpp: 2 bytes per row (8 pixels) - 4 bpp: 4 bytes per row (8 pixels)

Index Map: - 1 byte per cell (uint8_t) - Value -1 (editor) = Index 0 (exported) = Empty

12.4 Project Structure¶

my_project/
├── my_project.pr32scene      # Main file
├── my_project.pr32scene.bin  # Binary version (optional)
└── assets/
    └── tilesets/
        ├── tileset1.png
        └── tileset2.png

12.5 Compatibility¶

• Python: 3.8+
• Tkinter: 8.6+
• ttkbootstrap: 1.0+
• Pillow: 9.0+

Appendix: Troubleshooting¶

Problem: The tileset does not display correctly¶

Solution: Verify that the image is a multiple of the configured tile size.

Problem: Export is very large¶

Solution: - Use fewer colors (max 16) - Remove duplicate tiles - Consider using 2bpp or 1bpp if possible

Problem: The editor becomes slow¶

Solution: - Enable "History Compression" in preferences - Use binary format (.bin) - Save and close unused scenes

Problem: Changes are not saved¶

Solution: - Verify you have write permissions in the folder - Try "Save As" to a different location - Check if there are error messages in the console

Happy mapping with PixelRoot32!

Documentation updated for Tilemap Editor v1.0.0