Debugger
The Debugger is a built-in tool that lets you inspect and control your game while it runs. You can view actor positions, check variable values, step through scripts one instruction at a time, and profile CPU performance — all without leaving the editor.
To open the Debugger, use the menu or run your game in debug mode. The debugger connects to the running game and updates in real-time.
Current State
The Current State pane provides information about the game.
- FPS - Displays the current Frames Per Second when running.
- CPU Load - The current CPU load of the game.
- Free RAM - The current amount of free RAM of the game.
- Scene - The current scene running in the game.
- Actors - The current number of actors loaded on the game.
- Triggers - The current number of triggers loaded on the game.
- Threads - The current number of threads running on the game.
- Tiles Preloaded - The current number of tiles preloaded by Sprites.
Actors
The Actors pane provides information about the current actors in the scene and their X and Y positions. You can also type in new coordinates which will be live updated in your running game.
Variables
The Variables pane allows you to see the current value of the variables used within your game. You can also type in new values which will be live updated in your running game.
Arrays
The Arrays pane provides information about the current arrays in the scene and their values. You can also type in new values which will be live updated in your running game.
Cheat Mode & Platform
You can enable the Cheat Mode by ticking the Cheat Mode Enabled box, after that the If Cheat Mode is Enabled event would become True and run the code normally.
You can select the Platform you want on the selector, after that the If Running on Platform event would match the selected platform.
Step Buttons
When your game is paused you can use the Step Buttons or keyboard shortcuts to slowly step through your game to follow the progress of any running scripts.
- Pause/Resume - Toggles between playing and paused modes.
- Step Forward One Instruction - Run the game until the next instruction. This is useful for stepping through event scripts one command at a time.
- Step Forward One Frame - Run the game until the next frame of animation starts. This is useful for understanding what is happening every frame during events that take time such as Actor Move To.
- Restart - Restarts the game.
Keyboard Shortcuts
When the debugger is enabled, you can use the following keyboard shortcuts in both the Project Window and Play Window:
Pause/Resume - F8
Step Forward One Instruction - F9
Step Forward One Frame - F10
CPU Profiler
The CPU Profiler tab provides a detailed breakdown of how the Mega Drive's M68K CPU time is spent each frame. It helps you identify performance bottlenecks in your game.
The profiler is split into two columns: Overall Timing on the left and Per-Script Timing (Update Loop) on the right.
Overall Timing (Left Column)
Shows how many scanlines each engine section consumes per frame. The Mega Drive has a budget of 262 scanlines (NTSC) or 312 scanlines (PAL) per frame.
Main Sections
| Section | Description |
|---|---|
| INP | Input processing |
| PRE | Pre-update logic |
| TMR | Timer callbacks |
| TWN | Tween animations |
| TAN | Tile animations |
| ULP | Update Loop — contains all script execution, collision, motion, etc. |
| CAM | Camera updates |
| SCL | Scroll updates |
| SYN | Actor sync (position/animation to sprites) |
| SPR | Sprite update (DMA preparation) |
| AUD | Audio driver update |
| VBL | VBlank Wait — idle time waiting for vertical blank (not real processing) |
| DBG | Debugger Update — debug-only overhead (CPU load, FPS, RAM queries) |
Update Loop Sub-Sections
When the Update Loop (ULP) section is expanded, you can see its internal breakdown:
| Section | Description |
|---|---|
| SCN | Scene script update |
| ACT | Actor script updates |
| ASY | Async script execution |
| MOT | Motion / physics |
| GRP | Grid preparation |
| COL | Collision detection |
| CHT | Collision hit callbacks |
| TRG | Trigger checks |
| PRJ | Projectile updates |
| TMP | Temporary triggers |
| PST | Post-update logic |
Column Values
Each section row displays:
- Lines — Current scanline count for this section
- Min — Minimum scanlines observed across recent frames
- Avg — Average scanlines across recent frames
- Peak — Highest scanline count observed (resets on scene change)
- % — Percentage of total frame budget
- +/- — Delta from frozen snapshot (only visible when Freeze + Deltas are enabled)
- Budget icon (circle) — Click to set a max scanline budget; the row highlights red when exceeded and a budget line appears on the sparkline
- Sparkline — Visual history of recent frame values
- Bar — Visual bar showing relative cost
Total Row
The total row shows:
- Scanline total — Sum of all processing sections (excludes VBlank Wait and Debugger Update)
- % — Percentage of frame budget used by actual processing
- Avg. CPU — Average CPU load reported by the engine over the last 8 frames
- p95 — 95th percentile: 95% of recent frames were at or below this value (shows your worst typical frame, filtering out rare spikes)
- max — Highest CPU load observed across recent frames
- Spike — Warning badge that appears when the current frame exceeds the average by more than 2 standard deviations
Other Row
Shows unaccounted time — the gap between the sum of all sections and the total frame budget. A small value (0–2 scanlines) is normal.
Per-Script Timing (Right Column)
Shows individual script execution times within the Update Loop. Scripts are split into Sync Scripts and Async Scripts sections.
Each script row displays:
- Name — Entity name and script key (e.g.
Player.onUpdate,Elevator.tween) - Lines — Current scanline count
- Min / Avg / Peak — Same as section columns
- % — Percentage of total frame budget
- Cost/Call — Average scanlines per call (only meaningful when a script is called multiple times per frame)
- Call count — Shown as a multiplier badge (e.g. ×3) when a script runs more than once per frame
Stack Depth
When scripts call other scripts (e.g. via custom events), the Depth indicator next to the header shows the maximum call-stack depth reached. A warning color appears at depth 5 or higher.
Parent Chain
When call-chain tracking is available, hovering over a script row shows its caller hierarchy in the tooltip (e.g. ← scene.onUpdate ← MainLoop).
Toolbar Controls
| Control | Description |
|---|---|
| Sort by cost | Sort sections by scanline cost (highest first) |
| Freeze | Freeze the display on the current frame's data. Press F as a keyboard shortcut |
| Normalize | Scale all sparklines to the total frame budget instead of auto-scaling |
| Timeline | Show a flame-style timeline of recent frames. Click a bar to freeze on that frame's data |
| Deltas | Show the difference between frozen and live values (requires Freeze) |
| Show All / Hide 0 | Toggle visibility of sections with zero values |
| Copy | Copy current profiler data as JSON to clipboard |
| CSV | Copy frame history as CSV to clipboard (includes per-script columns) |
Script Toolbar Controls
| Control | Description |
|---|---|
| Sort | Sort scripts by Cost, Name, Type, Scene, or Calls |
| Filter | Filter scripts by entity type (actor, scene, trigger) |
| Group by Entity | Group scripts by their parent entity with expandable rows |
| Inclusive | Toggle between self-time (excludes nested calls) and inclusive time (full duration including nested calls) |
Detached Window
The profiler can be detached into its own window using the detach button in the profiler tab header. The detached window closes automatically when the debugger disconnects.
Script Budgets
Like section budgets, you can set per-script scanline budgets by clicking the budget icon (circle) next to each script. When exceeded, the row highlights red and a budget line appears on the sparkline. Budgets persist in localStorage across sessions.
Navigation
Clicking on a script row navigates to the corresponding entity (scene, actor, or trigger) in the editor and opens the matching script tab.
Planes
The Plane Viewer lets you visualize the different planes in their entirety, as well as the current scroll position. You can view a single plane at a time based on the selected value.
Memory Viewer
The Memory Viewer lets you inspect the Mega Drive's 64KB of 68000 RAM in real time. Select a memory zone and starting offset to browse hex values. This is useful for debugging custom C plugins, checking variable values at specific addresses, or understanding the memory layout of your running game.
VDP Registers
The VDP Registers tab displays all 24 Video Display Processor registers with their current values and human-readable descriptions. This shows the active display mode, nametable addresses, scroll settings, sprite table location, auto-increment value, DMA state, and more. Values update in real time as the game runs.
Sprite Table
The Sprite Table viewer shows all active hardware sprites with their position, size, tile index, palette, flip flags, priority, and link chain order. Each sprite entry includes a small preview thumbnail. This is useful for debugging sprite limits, checking sprite ordering, and verifying sprite attributes.
CRAM (Color RAM)
The CRAM viewer shows the VDP's Color RAM — all 4 palette lines (64 colors total). Colors are displayed as swatches. When scanline palette mode is enabled, you can view per-scanline palette changes, which is useful for debugging HBlank palette effects.
Debugger Log
The Debugger Log showcases the log produced by the engine as well as the log you send with the Log Message event.
Layers
The Layers pane provides a way to show / hide the different layers.
Palettes
The Palette Viewer pane provides a way to consult the palettes per frame and per scanline.
VRAM
The VRAM Viewer shows the current video memory used by graphics in your running game.
You can use this pane to get a visual preview of how many additional sprite and background tiles are available in the current scene and to help debug issues when you have used too many unique tiles in the scene.
You can also choose the palette you want the tiles to use during render.