mvbg

VM_INPUT_ATTACH

VM_INPUT_ATTACH is a GBVM instruction used to associate a prepared script (from a VM_CONTEXT_PREPARE slot) with a specific input event, so that the script executes when that input is detected.

Purpose: This instruction is fundamental for handling player input and triggering game events in response to button presses. It allows you to:

• Define button actions: Specify what happens when the player presses the A button, B button, D-pad directions, Start, or Select.
• Contextual input: Change the behavior of input buttons based on the current game state (e.g., A button attacks in combat, but confirms dialogue in a menu).
• Modular input handling: Keep input-response logic separate from the main game loop, making it easier to manage and modify.

When VM_INPUT_ATTACH is called, the GBVM creates a link between the specified MASK (representing an input button or combination) and the script located in the SLOT. Whenever the input corresponding to the MASK is detected, the script in the SLOT will be executed.

Syntax:

VM_INPUT_ATTACH MASK, SLOT

• MASK: An input mask (a constant) that represents the specific button or combination of buttons to which the script should be attached. Common input masks include:
  • .INPUT_A: A button
  • .INPUT_B: B button
  • .INPUT_UP: Up D-pad
  • .INPUT_DOWN: Down D-pad
  • .INPUT_LEFT: Left D-pad
  • .INPUT_RIGHT: Right D-pad
  • .INPUT_START: Start button
  • .INPUT_SELECT: Select button
  • Combinations (e.g., .INPUT_A | .INPUT_B)
• SLOT: The slot number (an integer) that contains the script to be executed when the input MASK is detected. This slot must have been previously prepared using VM_CONTEXT_PREPARE.

Usage Example: Attaching Dialogue to the A Button

Imagine you want the player to initiate dialogue with an NPC by pressing the A button when near them. You would prepare a dialogue script and then attach it to the A button input.

; In your game initialization or scene setup:

; Define the dialogue script
NPC_DIALOGUE_SCRIPT:
  VM_LOAD_TEXT TEXT_NPC_GREETING
  VM_DISPLAY_TEXT
  VM_INPUT_WAIT
  VM_RET

TEXT_NPC_GREETING:
  .TEXT "Hello, adventurer!"
  .TEXT_END

; Prepare the dialogue script in slot 1
VM_CONTEXT_PREPARE 1, BANK(NPC_DIALOGUE_SCRIPT), NPC_DIALOGUE_SCRIPT

; Attach slot 1 to the A button input
VM_INPUT_ATTACH .INPUT_A, 1

; ... rest of game logic ...

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

In this example:

1. NPC_DIALOGUE_SCRIPT is defined, which handles displaying text and waiting for input.
2. VM_CONTEXT_PREPARE 1, BANK(NPC_DIALOGUE_SCRIPT), NPC_DIALOGUE_SCRIPT registers NPC_DIALOGUE_SCRIPT with slot 1.
3. VM_INPUT_ATTACH .INPUT_A, 1 then links the A button input to slot 1. Now, whenever the A button is pressed, the NPC_DIALOGUE_SCRIPT will be executed.

This allows for a clean separation of input detection and the actions that result from that input. You can easily change what the A button does by attaching a different script to its input mask.

Analogy to other programming languages/game engines: This is analogous to registering an event listener or a callback function for a specific input event:

• JavaScript: document.addEventListener('keydown', handleKeyPress);
• Unity: Input.GetButtonDown("Fire1") triggering a method, or using Unity’s new Input System to bind actions to events.
• Godot: Connecting a signal from an InputEvent to a function.

It provides a flexible and event-driven way to respond to player input, making your game interactive and responsive.