mvbg

VM_SOUND_MASTERVOL

VM_SOUND_MASTERVOL is a GBVM instruction used to set the global master volume for all audio output on the Game Boy.

Purpose: Controlling the overall volume of the game’s audio is a fundamental feature for player comfort and accessibility. VM_SOUND_MASTERVOL is essential for:

• Volume settings: Allowing players to adjust the game’s volume through an options menu.
• Dynamic audio levels: Gradually fading music and sound effects in or out during scene transitions, cutscenes, or when pausing the game.
• Special effects: Creating moments of sudden silence or loud bursts for dramatic effect.
• Accessibility: Providing options for players with hearing sensitivities.

When VM_SOUND_MASTERVOL is called, it directly controls the output level of the Game Boy’s audio amplifier. All sounds (music and sound effects) will be affected by this global volume setting.

Syntax:

VM_SOUND_MASTERVOL VOL

• VOL: The volume value (an integer). This value typically ranges from 0 (silent) to a maximum value (e.g., 7 or 15, depending on the specific Game Boy model and audio driver implementation), where higher values mean louder volume.

Usage Example: Implementing a Volume Slider in an Options Menu

Imagine your game has an options menu where the player can adjust the master volume using a slider or up/down buttons. You would use VM_SOUND_MASTERVOL to apply the player’s chosen volume setting.

; In your options menu script:

; Variable to store the current master volume setting
VAR_MASTER_VOLUME:
  .R_INT8 0 ; Initialize to a default volume (e.g., 7 for max)

; Max volume constant (example, adjust based on actual range)
MAX_VOLUME:
  .R_INT8 7

; ... code for displaying volume slider/buttons and handling input ...

HANDLE_VOLUME_UP:
  ; Increment volume, but don't exceed max
  VM_RPN
    .R_REF_MEM .R_INT8, VAR_MASTER_VOLUME
    .R_INT8 1
    .R_OPERATOR +
    .R_INT8
  VM_STOP
  VM_SET_INT8 VAR_MASTER_VOLUME, 0 ; Store incremented value

  VM_IF_CONST .GT, VAR_MASTER_VOLUME, MAX_VOLUME, SET_MAX_VOLUME, 0
  VM_JUMP APPLY_VOLUME

SET_MAX_VOLUME:
  VM_SET_CONST VAR_MASTER_VOLUME, MAX_VOLUME

APPLY_VOLUME:
  ; Apply the new master volume
  VM_SOUND_MASTERVOL VAR_MASTER_VOLUME

  ; Update volume display in UI
  VM_CALL UPDATE_VOLUME_DISPLAY

  VM_RET

HANDLE_VOLUME_DOWN:
  ; Decrement volume, but don't go below 0
  VM_RPN
    .R_REF_MEM .R_INT8, VAR_MASTER_VOLUME
    .R_INT8 1
    .R_OPERATOR -
    .R_INT8
  VM_STOP
  VM_SET_INT8 VAR_MASTER_VOLUME, 0 ; Store decremented value

  VM_IF_CONST .LT, VAR_MASTER_VOLUME, 0, SET_MIN_VOLUME, 0
  VM_JUMP APPLY_VOLUME

SET_MIN_VOLUME:
  VM_SET_CONST VAR_MASTER_VOLUME, 0
  VM_JUMP APPLY_VOLUME

UPDATE_VOLUME_DISPLAY:
  ; ... routine to update UI element showing current volume ...
  VM_RET

In this example, VM_SOUND_MASTERVOL VAR_MASTER_VOLUME is called whenever the player adjusts the volume. The VAR_MASTER_VOLUME variable is clamped between 0 and MAX_VOLUME to ensure valid input. This allows players to customize their audio experience, making the game more accessible and enjoyable.

Analogy to Game Boy Development: This is a direct interface with the Game Boy’s APU (Audio Processing Unit) registers, specifically controlling the master volume output. In modern game development, it’s analogous to setting the global volume level in an audio mixer or an audio manager:

• Unity: AudioListener.volume = newVolume;
• Godot: AudioServer.set_bus_volume_db(bus_idx, new_volume_db);

It provides a global control over the game’s sound output, essential for user settings and dynamic audio effects.