mvbg

VM_MUSIC_SETPOS

VM_MUSIC_SETPOS is a GBVM instruction used to set the playback position of the currently playing music track to a specific pattern and row.

Purpose: Game Boy music is often composed in a tracker-like format, where songs are structured into patterns (sequences of notes/commands) and rows (individual steps within a pattern). VM_MUSIC_SETPOS allows for precise control over music playback, enabling:

• Jumping to specific song sections: Skipping intros, jumping to choruses, or moving to a bridge section.
• Dynamic music transitions: Seamlessly transitioning between different parts of a song based on gameplay events (e.g., entering combat, completing a puzzle).
• Looping specific sections: Creating custom loops within a song for extended gameplay segments.
• Debugging music: Quickly navigating to specific parts of a song during development.

When VM_MUSIC_SETPOS is called, the music driver immediately jumps to the specified PATTERN and ROW within the current music track, and playback continues from that point.

Syntax:

VM_MUSIC_SETPOS PATTERN, ROW

• PATTERN: The pattern number (an integer) within the current music track to which the playback position should be set. Patterns are typically indexed starting from 0.
• ROW: The row number (an integer) within the specified PATTERN to which the playback position should be set. Rows are typically indexed starting from 0.

Usage Example: Skipping Music Intro After Game Start

Imagine your game has a long music intro on the title screen. Once the player presses Start, you want to skip the intro and jump directly to the main loop of the music.

; In your title screen script:

; Assume MUSIC_TITLE_SCREEN is the current music track
; Assume the main loop of the music starts at PATTERN 2, ROW 0
MAIN_MUSIC_LOOP_PATTERN:
  .R_INT8 2
MAIN_MUSIC_LOOP_ROW:
  .R_INT8 0

; ... code for displaying title screen and waiting for input ...

PLAYER_PRESSES_START:
  ; Skip the music intro and jump to the main loop
  VM_MUSIC_SETPOS MAIN_MUSIC_LOOP_PATTERN, MAIN_MUSIC_LOOP_ROW

  VM_LOAD_TEXT TEXT_GAME_STARTED
  VM_DISPLAY_TEXT
  VM_IDLE 60

  VM_RAISE EXCEPTION_CHANGE_SCENE, SCENE_GAME_PLAY
  VM_RET

TEXT_GAME_STARTED:
  .TEXT "Game Started!"
  .TEXT_END

SCENE_GAME_PLAY:
  .R_INT8 1 ; Example scene ID

In this example, VM_MUSIC_SETPOS MAIN_MUSIC_LOOP_PATTERN, MAIN_MUSIC_LOOP_ROW is called when the player presses Start. This immediately changes the music playback position to the beginning of the main loop, bypassing the intro. This provides a more responsive and streamlined experience for the player.

Analogy to Game Boy Development: This is a direct interface with the Game Boy’s music driver, allowing for precise control over the playback of tracker-based music. In modern audio production, it’s analogous to seeking to a specific timestamp or marker within an audio file, or jumping to a particular section in a MIDI sequence. It provides fine-grained control over the musical flow of your game, allowing for dynamic and interactive audio experiences.