mvbg

VM_SET_SPRITE_VISIBLE

VM_SET_SPRITE_VISIBLE is a GBVM instruction used to globally control the visibility of the entire sprite layer on the Game Boy screen. This affects all sprites rendered by the hardware.

Purpose: While individual actors can be hidden or shown using VM_ACTOR_SET_HIDDEN, VM_SET_SPRITE_VISIBLE operates at a higher level, affecting all sprites simultaneously. It is essential for:

• Global visual effects: Instantly making all characters, enemies, and projectiles disappear or reappear.
• Scene transitions: Hiding all sprites during a screen fade or a scene change to prevent visual artifacts or to create a clean transition.
• Cutscenes: Temporarily removing all interactive sprites to focus on background elements or dialogue, or to create a dramatic reveal.
• Menu overlays: When a full-screen menu or dialogue box is displayed, you might want to hide all gameplay sprites underneath it.
• Debugging: Quickly toggling sprite visibility to isolate rendering issues or to inspect background layers without sprite interference.

This instruction directly manipulates a hardware register that controls the sprite display. It has priority over individual actor visibility settings; if the sprite layer is hidden, no sprites will be visible, regardless of their individual VM_ACTOR_SET_HIDDEN state.

Syntax:

VM_SET_SPRITE_VISIBLE MODE

• MODE: A constant that specifies the desired visibility state for the entire sprite layer:
  • .SPRITES_SHOW: Makes the entire sprite layer visible, allowing individual sprites to be drawn according to their own visibility settings.
  • .SPRITES_HIDE: Hides the entire sprite layer, making all sprites invisible.

Usage Example: Hiding All Sprites During a Screen Fade

Imagine your game needs to fade to black before loading a new scene. To ensure a clean fade, you should hide all sprites before the fade begins.

; In your script, before initiating a scene change or screen fade:

; Define sprite visibility constants
.SPRITES_SHOW:
  .R_INT8 0 ; Example value for showing sprites
.SPRITES_HIDE:
  .R_INT8 1 ; Example value for hiding sprites

START_SCENE_TRANSITION:
  ; Hide all sprites globally
  VM_SET_SPRITE_VISIBLE .SPRITES_HIDE

  ; Initiate a screen fade to black
  VM_FADE_OUT 1 ; Fade to black over 1 second

  ; Now, load the new scene (which might involve loading new actors and maps)
  VM_CALL LOAD_NEW_GAME_SCENE

  ; After the new scene is loaded and ready, show sprites again
  VM_SET_SPRITE_VISIBLE .SPRITES_SHOW

  ; Initiate a screen fade in from black
  VM_FADE_IN 1 ; Fade in from black over 1 second

  VM_RET

LOAD_NEW_GAME_SCENE:
  ; ... logic to load new map, actors, etc. ...
  VM_RET

In this example, VM_SET_SPRITE_VISIBLE .SPRITES_HIDE is called before the screen fade. This ensures that no sprites are visible during the fade, preventing any visual artifacts. Once the new scene is loaded and the fade-in begins, VM_SET_SPRITE_VISIBLE .SPRITES_SHOW is called to make the sprites of the new scene visible. This creates a smooth and professional scene transition.

Analogy to Game Boy Development: This is akin to toggling the display enable bit for sprites in the Game Boy’s LCDC register. It’s a low-level hardware control that affects the entire sprite rendering pipeline, making it a powerful tool for global visual management.