mvbg

VM_INPUT_WAIT

VM_INPUT_WAIT is a GBVM instruction used to pause the execution of the current script until a specified input (button press) is detected.

Purpose: This instruction is crucial for creating interactive sequences where the game needs to wait for player confirmation or action before proceeding. It is essential for:

• Dialogue progression: Waiting for the player to press a button to advance to the next line of dialogue or close a text box.
• Menu navigation: Pausing the game until the player selects an option or confirms a choice.
• Cutscenes: Halting the script until a specific button is pressed to skip or continue a cinematic sequence.
• Tutorials: Ensuring the player performs a required action before the tutorial proceeds.

When VM_INPUT_WAIT is called, the script will halt its execution and wait indefinitely until any of the buttons specified in the MASK are pressed. Once a matching input is detected, the script resumes from the instruction immediately following VM_INPUT_WAIT.

Syntax:

VM_INPUT_WAIT MASK

• MASK: An input mask (a constant) that represents the specific button or combination of buttons to wait for. The script will resume if any of the buttons specified in the mask are pressed. Common input masks include:
  • .INPUT_A: Wait for the A button.
  • .INPUT_B: Wait for the B button.
  • .INPUT_ANY: Wait for any button press.
  • Combinations (e.g., .INPUT_A | .INPUT_B to wait for either A or B).

Usage Example: Advancing Dialogue with A Button

Imagine a dialogue system where each line of text is displayed, and the player must press the A button to advance to the next line.

; In your dialogue display script:

; Input constants (these would be defined globally)
.INPUT_A:
  .R_INT8 16 ; Example value for A button

DIALOGUE_SEQUENCE:
  VM_LOAD_TEXT TEXT_LINE_1
  VM_DISPLAY_TEXT
  VM_INPUT_WAIT .INPUT_A ; Wait for A button press

  VM_LOAD_TEXT TEXT_LINE_2
  VM_DISPLAY_TEXT
  VM_INPUT_WAIT .INPUT_A ; Wait for A button press

  VM_LOAD_TEXT TEXT_LINE_3
  VM_DISPLAY_TEXT
  VM_INPUT_WAIT .INPUT_A ; Wait for A button press

  VM_LOAD_TEXT TEXT_DIALOGUE_END
  VM_DISPLAY_TEXT
  VM_IDLE 30 ; Display message for a short time

  VM_RET

TEXT_LINE_1:
  .TEXT "Welcome, traveler!"
  .TEXT_END

TEXT_LINE_2:
  .TEXT "The journey ahead is perilous."
  .TEXT_END

TEXT_LINE_3:
  .TEXT "Are you ready to face the challenge?"
  .TEXT_END

TEXT_DIALOGUE_END:
  .TEXT "Dialogue finished."
  .TEXT_END

In this example, VM_INPUT_WAIT .INPUT_A is used after each line of dialogue. The script will pause at this instruction until the player presses the A button. This allows the player to read the text at their own pace and control the flow of the conversation.

Analogy to other programming languages/game engines: This is analogous to a blocking input function or a yield statement that waits for a specific event:

• C/C++ (console): getchar() or _getch() waiting for a key press.
• Game engines: A coroutine that yield return new WaitForInput(KeyCode.A); or a state machine waiting for an InputEvent.

It provides a simple yet effective way to synchronize script execution with player interaction, making the game responsive and user-friendly.