mvbg

VM_LOAD_PALETTE

VM_LOAD_PALETTE is a GBVM instruction used to dynamically load a color palette into the Game Boy’s hardware, thereby changing the colors displayed on the screen.

Purpose: Color palettes are fundamental to the visual presentation of Game Boy games. VM_LOAD_PALETTE allows you to change these palettes at runtime, enabling a wide range of visual effects and dynamic environments:

• Day/Night Cycles: Gradually shifting the color scheme to simulate time of day.
• Status Effects: Applying a red tint when the player is damaged, or a green tint for poison.
• Area Transitions: Changing the overall mood or environment colors when entering a new zone.
• Special Abilities: Visualizing power-ups or temporary invincibility with unique color schemes.
• Fading Effects: Creating smooth fades to black, white, or other colors by rapidly changing palette entries.

This instruction is crucial for bringing dynamic and expressive visuals to your Game Boy game, especially on the Game Boy Color (CGB) which supports a much wider range of colors than the original Game Boy (DMG).

Syntax:

VM_LOAD_PALETTE MASK, OPTIONS

• MASK: Specifies which hardware palette register to load the new palette into. This determines whether the palette applies to backgrounds or sprites, and which specific palette index (for CGB) or type (for DMG) it is.
  • For Game Boy Color (CGB), MASK can range from 0 to 7 for background palettes (BGP0 to BGP7) and 0 to 7 for sprite palettes (OBP0 to OBP7). These are often represented by constants like .PALETTE_BACKGROUND_0, .PALETTE_SPRITE_0, etc.
  • For Original Game Boy (DMG), MASK typically refers to the background palette (.PALETTE_BACKGROUND) or sprite palettes (.PALETTE_SPRITE_0, .PALETTE_SPRITE_1).
• OPTIONS: This is the actual palette data to be loaded. It must be defined using either .DMG_PAL or .CGB_PAL directives.
  • .DMG_PAL COL1, COL2, COL3, COL4: Used for original Game Boy palettes. Defines 4 shades of gray (0-3, where 0 is lightest, 3 is darkest).
  • .CGB_PAL R1,G1,B1 R2,G2,B2 R3,G3,B3 R4,G4,B4: Used for Game Boy Color palettes. Defines 4 colors, each with 5-bit Red, Green, and Blue components (0-31).

Usage Example: Applying a Damage Tint to the Screen

Imagine you want the screen to briefly flash red when the player takes damage. You can define a normal palette and a red-tinted palette, then swap between them.

; Define your normal game background palette (CGB example)
PALETTE_NORMAL_BG:
  .CGB_PAL 31,31,31  ; White
             20,20,20  ; Light Gray
             10,10,10  ; Dark Gray
             0,0,0     ; Black

; Define a red-tinted background palette (CGB example)
PALETTE_DAMAGE_BG:
  .CGB_PAL 31,10,10  ; Light Red
             20,0,0    ; Medium Red
             10,0,0    ; Dark Red
             0,0,0     ; Black

; In your script, when the player takes damage:

PLAYER_TAKES_DAMAGE:
  ; Play damage sound effect
  VM_SFX_PLAY SFX_HIT

  ; Load the red-tinted background palette into background palette 0
  VM_LOAD_PALETTE .PALETTE_BACKGROUND_0, PALETTE_DAMAGE_BG

  VM_IDLE 10 ; Keep red tint for a short duration (e.g., 10 frames)

  ; Load the normal background palette back
  VM_LOAD_PALETTE .PALETTE_BACKGROUND_0, PALETTE_NORMAL_BG

  ; ... continue game logic ...
  VM_RET

; Palette mask constants (these would be defined globally)
.PALETTE_BACKGROUND_0:
  .R_INT8 0 ; Corresponds to BGP0

SFX_HIT:
  ; ... sound effect data ...

In this example, when PLAYER_TAKES_DAMAGE is called, VM_LOAD_PALETTE .PALETTE_BACKGROUND_0, PALETTE_DAMAGE_BG instantly changes the background colors to the red-tinted palette. After a brief pause (VM_IDLE 10), the original PALETTE_NORMAL_BG is loaded back, creating a quick visual flash effect. This demonstrates how VM_LOAD_PALETTE can be used to create dynamic and responsive visual feedback in your game.

Analogy to other programming languages/graphics: This is analogous to swapping out a color lookup table (CLUT) or modifying the color values in a shader program at runtime. In modern game development, you might achieve similar effects with post-processing effects or by manipulating color matrices. On the Game Boy, directly loading palettes is the primary way to achieve such dynamic color changes.