Skip to main content

HBlank & VBlank

The Mega Drive draws the screen one horizontal line at a time, from top to bottom. After drawing each line, there is a brief pause called the Horizontal Blank (HBlank). After all lines are drawn, there is a longer pause called the Vertical Blank (VBlank) before the next frame begins.

During these pauses the CPU is free to make changes (like swapping colors or adjusting scroll positions) that will take effect on the next line or frame. This is how many classic effects like gradient skies, water reflections, and split-screen UIs are achieved.

In MD Engine, you can attach scripts to these intervals:

  • HBlank — Runs once per scanline (or every N scanlines). Use it for per-line effects like palette gradients or wavy scroll.
  • VBlank — Runs once per frame. Use it for per-frame changes that need to happen during the blanking period.

You can enable these with the OnStart: Set Horizontal Blank Script event for HBlank and OnStart: Set Vertical Blank Script event for VBlank.

info

These events can only be placed inside a Scene On Start script.

There are some operations that can be done during these periods, such as changing palette colors, adjusting Window Plane or changing scroll values.

You can review the HBlank - Palette example for a palette effect, and HBlank - Window Plane for a Window Plane effect.

The HBlank script can be triggered every scanline if a Scanline Counter of 0 is used on the OnStart: Set Horizontal Blank Script event. Any other value will make the script trigger every (value + 1) scanlines. For example, setting 5 means that the script will occur each (5+1) scanline.

Allowed events inside HBlank & VBlank scripts​

Inside these scripts there is a limited amount of events you can use, all the possible events start with Blank: if they can be used inside both scripts or with HBlank: for Horizontal Blank scripts only, and VBlank: for Vertical Blank events.

This is because the events inside these scripts are compiled to ASM instead of C code due to performance needs.

A full list of events can be seen below:

warning

Using events that are not on this list will result in the game not building!