mvbg

VM_POLL

VM_POLL is a GBVM instruction used to wait for and detect specific events, such as player input or music routine completion, without blocking the entire game loop indefinitely.

Purpose: In game development, you often need to react to various asynchronous events. While VM_INPUT_WAIT blocks until a specific input, VM_POLL offers a more flexible way to wait for one of several event types. It is essential for:

• Event-driven game loops: Allowing your game to respond to input, music cues, or other events as they happen, rather than constantly checking for them.
• Non-blocking waits: Unlike some blocking wait functions, VM_POLL can be used in a loop to check for events, allowing other game logic to run if no event is detected.
• Synchronizing with music: Triggering game events or visual effects precisely when a music routine finishes or reaches a certain point.
• Complex input handling: Detecting input events while also monitoring other game systems.

When VM_POLL is called, it waits until an event specified in the MASK occurs. Once an event is detected, it stores information about the event (its type and value) into designated variables and then allows the script to continue execution.

Syntax:

VM_POLL IDX_EVENT, IDX_VALUE, MASK

• IDX_EVENT: The target variable (a GBVM variable) that will receive a flag indicating the type of event that occurred:
  • 1: An input event was detected.
  • 2: A music routine event was detected.
• IDX_VALUE: The target variable (a GBVM variable) that will receive the value associated with the event:
  • For input events: The input mask of the button(s) pressed.
  • For music routine events: The specific music event value (e.g., end of song).
• MASK: A bitmask that specifies which types of events VM_POLL should wait for:
  • .POLL_EVENT_INPUT: Wait for any input event.
  • .POLL_EVENT_MUSIC: Wait for a music routine event.
  • You can combine these (e.g., .POLL_EVENT_INPUT | .POLL_EVENT_MUSIC) to wait for either type of event.

Usage Example: Waiting for Input or Music End

Imagine a title screen where the game waits for either a button press to start the game or for the title screen music to finish playing before transitioning to a demo mode.

; In your title screen script:

; Variables to store event information
VAR_EVENT_TYPE:
  .R_INT8 0
VAR_EVENT_VALUE:
  .R_INT8 0

; Event masks
.POLL_EVENT_INPUT:
  .R_INT8 1 ; Example value for input event
.POLL_EVENT_MUSIC:
  .R_INT8 2 ; Example value for music event

; Input mask for any button press
.INPUT_ANY:
  .R_INT8 255 ; Example value for any button (all bits set)

TITLE_SCREEN_LOOP:
  ; Play title screen music (if not already playing)
  VM_MUSIC_PLAY MUSIC_TITLE_SCREEN, 0, 0

  ; Wait for either input or music event
  VM_POLL VAR_EVENT_TYPE, VAR_EVENT_VALUE, .POLL_EVENT_INPUT | .POLL_EVENT_MUSIC

  ; Check what type of event occurred
  VM_IF_CONST .EQ, VAR_EVENT_TYPE, .POLL_EVENT_INPUT, HANDLE_INPUT_EVENT, 0
  VM_IF_CONST .EQ, VAR_EVENT_TYPE, .POLL_EVENT_MUSIC, HANDLE_MUSIC_EVENT, 0

  VM_JUMP TITLE_SCREEN_LOOP ; Continue looping if no relevant event or unhandled event

HANDLE_INPUT_EVENT:
  ; Player pressed a button, start the game
  VM_MUSIC_STOP
  VM_LOAD_TEXT TEXT_GAME_START
  VM_DISPLAY_TEXT
  VM_IDLE 60
  VM_RAISE EXCEPTION_CHANGE_SCENE, SCENE_GAME_START
  VM_RET

HANDLE_MUSIC_EVENT:
  ; Music finished, transition to demo mode
  VM_LOAD_TEXT TEXT_DEMO_START
  VM_DISPLAY_TEXT
  VM_IDLE 60
  VM_RAISE EXCEPTION_CHANGE_SCENE, SCENE_DEMO_MODE
  VM_RET

TEXT_GAME_START:
  .TEXT "Starting Game!"
  .TEXT_END

TEXT_DEMO_START:
  .TEXT "Starting Demo!"
  .TEXT_END

MUSIC_TITLE_SCREEN:
  ; ... music data ...

SCENE_GAME_START:
  .R_INT8 1 ; Example scene ID
SCENE_DEMO_MODE:
  .R_INT8 2 ; Example scene ID

In this example, VM_POLL waits for either player input or the completion of the title screen music. If input is detected, the game starts. If the music finishes, it transitions to a demo mode. This allows for flexible event handling on a single screen, reacting to multiple potential triggers.

Analogy to other programming languages/game engines: This is analogous to an event loop or a select/poll system call in operating systems, where a program waits for activity on multiple input sources. In game engines, it’s similar to having an event dispatcher that can listen for various types of events (input, audio, timers) and trigger corresponding callbacks. It provides a way to create responsive and dynamic game states that react to multiple conditions.