Skip to main content

Build Process

Overview​

When you press Play or Export, MD Engine compiles your project through several stages:

  1. Visual Scripts to C Code — Your visual event scripts, scene data, actor definitions, and asset references are translated into C source files.
  2. C Code to 68000 Assembly — The SGDK-based compiler processes the generated C code and produces Motorola 68000 assembly.
  3. Assembly to ROM Binary — The assembler and linker combine all object files into a final .bin ROM file that runs on real hardware or an emulator.

This entire pipeline runs automatically. You can monitor its progress and diagnose issues through the Build Log.

Between stages 1 and 2, several compiler optimization passes run on the generated code to reduce ROM size and improve runtime performance. These can be toggled in Settings > Build Options.

Build Log​

The Build Log window displays detailed output from the compilation pipeline. It shows:

  • Asset processing progress (sprites, backgrounds, music, palettes).
  • C compiler output, including any warnings or errors in generated code or plugin code.
  • Linker output with the final ROM size.
  • Timing information for how long each stage took.

To open the Build Log, check the output panel after pressing Play or Export. Warnings appear in yellow and errors in red.

Common Errors​

Too Many Unique Tiles​

Scenes have a limited number of unique 8x8 tiles available for backgrounds. The Mega Drive VDP can address a fixed amount of VRAM for tile data, and each unique tile pattern consumes one slot.

What causes it:

  • Highly detailed or noisy background images with many unique 8x8 pixel patterns.
  • Using multiple complex backgrounds in a single scene.

How to fix:

  • Reduce the number of unique tiles by simplifying background art.
  • Share tiles between layers — reuse the same 8x8 patterns where possible.
  • Use simpler backgrounds with repeated tile patterns.
  • Check the VRAM Viewer in the Debugger to see how many tiles are in use.

Palette Overflow​

Each scene can use up to 4 palette lines (64 colors total). Sprites and backgrounds share this palette space.

What causes it:

  • Too many sprites or backgrounds each requesting their own palette line.
  • Assets that use colors not present in any existing palette line.

How to fix:

  • Reduce the number of distinct palette lines by sharing palettes between sprites.
  • Edit your assets to use colors from existing palette lines.
  • Check the Palettes documentation for palette management tips.

ROM Size Exceeded​

The ROM has a maximum size of 4MB by default (8MB with a custom PCB configuration). As you add assets, the ROM grows.

How to monitor:

  • After each build, the Build Log shows the total ROM size.
  • Keep an eye on this value as you add sprites, backgrounds, music, and scenes.

Tips to reduce ROM size:

  • Compress or simplify assets (fewer unique tiles, smaller sprite sheets).
  • Reduce the number of scenes or consolidate similar scenes.
  • Use shared tilesets and palettes to avoid duplicating data.
  • Remove unused assets from your project.

Build Timeout / Compilation Failed​

If the build takes too long or fails outright:

  • Check the Build Log for the specific error message — it usually points to the exact file and line.
  • Try cleaning the build folder and rebuilding (the editor handles this automatically in most cases).
  • If the error is in plugin code, check the plugin's C source files for syntax errors.
  • Verify your project doesn't exceed the hardware limits listed in Settings.

ROM Size Monitoring​

After each successful build, the Build Log reports the total ROM size in bytes. As you add assets (sprites, backgrounds, music, sound effects, scenes), the ROM grows. Regularly checking this value helps you catch size issues early rather than discovering them when you are close to the limit.

tip

If your ROM is approaching the 4MB limit, review your largest assets first — background images and music tracks tend to consume the most space.