mvbg

VM_PRINT_OVERLAY

VM_PRINT_OVERLAY is a GBVM instruction used to send a specified portion of the Game Boy’s overlay window to a connected Game Boy Printer for physical output.

Purpose: The Game Boy Printer was an accessory that allowed players to print out images from compatible Game Boy games. VM_PRINT_OVERLAY enables your GBVM script to utilize this feature, allowing for unique in-game functionalities such as:

Printing high scores: Players can print a physical record of their achievements.
Character profiles: Generating printouts of character stats, inventory, or custom drawings.
In-game photos: If your game has a camera feature, players can print their captured images.
Certificates or rewards: Providing tangible proof of completing a challenge or reaching a milestone.

This instruction takes a rectangular section of the overlay (which is typically used for UI elements like dialogue boxes or menus) and formats it for output to the Game Boy Printer. The printer then physically prints the image on thermal paper.

Syntax:

VM_PRINT_OVERLAY ERROR, START, HEIGHT, MARGIN

ERROR: A target variable that will receive the result of the printing operation. This variable can be checked to determine if the printing was successful or if an error occurred (e.g., printer not connected, out of paper).
START: The starting line (Y-coordinate) of the overlay window from which to begin printing. This is in pixel units, typically relative to the top of the overlay.
HEIGHT: The number of lines (height in pixels) of the overlay window to print. This value must be a multiple of 2 due to the Game Boy Printer’s hardware requirements.
MARGIN: The number of lines to feed (advance the paper) after the printing is finished. This creates a blank space after the printed image.

Usage Example: Printing a High Score Screen

Imagine your game has a high score screen displayed on the overlay. You want to allow the player to print this screen as a souvenir.

; In your high score screen script, when the player presses a "Print" button:

; Assume VAR_PRINT_ERROR is a variable to store the print result
VAR_PRINT_ERROR:
  .R_INT8 0

; Assume the high score display starts at Y-pixel 16 on the overlay
; and is 80 pixels tall (a multiple of 2).
PRINT_AREA_START_Y:
  .R_INT16 16
PRINT_AREA_HEIGHT:
  .R_INT16 80
PRINT_MARGIN_LINES:
  .R_INT8 8 ; Feed 8 lines after printing

; ... code to display the high score screen on the overlay ...

PLAYER_PRESSES_PRINT_BUTTON:
  ; Attempt to print the overlay section
  VM_PRINT_OVERLAY VAR_PRINT_ERROR, PRINT_AREA_START_Y, PRINT_AREA_HEIGHT, PRINT_MARGIN_LINES

  ; Check if printing was successful
  VM_IF_CONST .EQ, VAR_PRINT_ERROR, 0, PRINT_SUCCESS, 0
    VM_LOAD_TEXT TEXT_PRINT_FAILED
    VM_DISPLAY_TEXT
    VM_IDLE 60
    VM_JUMP END_PRINT_CHECK

PRINT_SUCCESS:
  VM_LOAD_TEXT TEXT_PRINT_SUCCESS
  VM_DISPLAY_TEXT
  VM_IDLE 60

END_PRINT_CHECK:
  VM_RET

TEXT_PRINT_FAILED:
  .TEXT "Printer error!"
  .TEXT_END

TEXT_PRINT_SUCCESS:
  .TEXT "Printing complete!"
  .TEXT_END

In this example, VM_PRINT_OVERLAY is called with the starting Y-coordinate, height, and margin for the printout. The VAR_PRINT_ERROR variable is then checked to provide feedback to the player about the success or failure of the printing operation. This allows players to create physical mementos of their game progress.

Analogy to Game Boy Development: This is a direct interface with a specific Game Boy peripheral. There isn’t a direct analogy in modern general-purpose programming, as physical printing is usually handled by operating system APIs. However, within the context of Game Boy development, it’s similar to sending raw pixel data to a specialized hardware device. It’s a unique feature that leverages the Game Boy’s ecosystem to provide an interactive, real-world output from the game.