mvbg

VM_INPUT_DETACH

VM_INPUT_DETACH is a GBVM instruction used to remove the association between a specific input event and any script that was previously attached to it.

Purpose: This instruction is the counterpart to VM_INPUT_ATTACH. While VM_INPUT_ATTACH sets up a script to run on input, VM_INPUT_DETACH removes that setup. This is crucial for:

• Contextual input handling: Disabling normal gameplay input when entering a menu, a dialogue sequence, a cutscene, or a puzzle mode, where different input actions are required.
• Preventing unintended actions: Ensuring that pressing a button doesn’t trigger an action that is inappropriate for the current game state.
• Dynamic control schemes: Allowing your game to change which inputs are active or what they do based on the player’s progress or current situation.

When VM_INPUT_DETACH is called, the GBVM breaks the link between the specified MASK (representing an input button or combination) and any script that was previously attached to it. After this, pressing the corresponding input will no longer trigger the detached script.

Syntax:

VM_INPUT_DETACH MASK

• MASK: An input mask (a constant) that represents the specific button or combination of buttons from which the script should be detached. This should match the MASK used in a previous VM_INPUT_ATTACH call.

Usage Example: Disabling Player Movement Input During Dialogue

Imagine your player character can move using the D-pad. When they initiate dialogue with an NPC, you want to temporarily disable their movement input so they don’t accidentally walk away during the conversation.

; In your script, when dialogue starts:

; Input masks for player movement
.INPUT_UP:
  .R_INT8 1
.INPUT_DOWN:
  .R_INT8 2
.INPUT_LEFT:
  .R_INT8 4
.INPUT_RIGHT:
  .R_INT8 8

; Assume PLAYER_MOVE_SCRIPT_SLOT is the slot number for player movement script
PLAYER_MOVE_SCRIPT_SLOT:
  .R_INT8 0 ; Example slot ID

; Assume DIALOGUE_SCRIPT_SLOT is the slot number for dialogue script
DIALOGUE_SCRIPT_SLOT:
  .R_INT8 1 ; Example slot ID

; In game initialization (or scene setup), movement scripts are attached:
; VM_CONTEXT_PREPARE PLAYER_MOVE_SCRIPT_SLOT, BANK(PLAYER_MOVE_ROUTINE), PLAYER_MOVE_ROUTINE
; VM_INPUT_ATTACH .INPUT_UP, PLAYER_MOVE_SCRIPT_SLOT
; VM_INPUT_ATTACH .INPUT_DOWN, PLAYER_MOVE_SCRIPT_SLOT
; VM_INPUT_ATTACH .INPUT_LEFT, PLAYER_MOVE_SCRIPT_SLOT
; VM_INPUT_ATTACH .INPUT_RIGHT, PLAYER_MOVE_SCRIPT_SLOT

; When player interacts with NPC and dialogue begins:
START_DIALOGUE_SEQUENCE:
  ; Detach all movement inputs
  VM_INPUT_DETACH .INPUT_UP
  VM_INPUT_DETACH .INPUT_DOWN
  VM_INPUT_DETACH .INPUT_LEFT
  VM_INPUT_DETACH .INPUT_RIGHT

  ; Now, attach the dialogue script to the A button (if not already)
  ; VM_INPUT_ATTACH .INPUT_A, DIALOGUE_SCRIPT_SLOT

  VM_LOAD_TEXT TEXT_DIALOGUE_START
  VM_DISPLAY_TEXT
  VM_INPUT_WAIT ; Wait for player to finish dialogue

  ; Re-attach movement inputs after dialogue ends
  VM_INPUT_ATTACH .INPUT_UP, PLAYER_MOVE_SCRIPT_SLOT
  VM_INPUT_ATTACH .INPUT_DOWN, PLAYER_MOVE_SCRIPT_SLOT
  VM_INPUT_ATTACH .INPUT_LEFT, PLAYER_MOVE_SCRIPT_SLOT
  VM_INPUT_ATTACH .INPUT_RIGHT, PLAYER_MOVE_SCRIPT_SLOT

  VM_LOAD_TEXT TEXT_DIALOGUE_END
  VM_DISPLAY_TEXT
  VM_IDLE 30

  VM_RET

TEXT_DIALOGUE_START:
  .TEXT "Dialogue started. Movement disabled."
  .TEXT_END

TEXT_DIALOGUE_END:
  .TEXT "Dialogue ended. Movement re-enabled."
  .TEXT_END

In this example, VM_INPUT_DETACH is used for each directional input (.INPUT_UP, .INPUT_DOWN, etc.) when the dialogue sequence begins. This prevents the player from moving their character while the dialogue is active. After the dialogue concludes, the inputs are re-attached using VM_INPUT_ATTACH, restoring normal movement control.

Analogy to other programming languages/game engines: This is analogous to removing an event listener or unbinding a callback function from an input event:

• JavaScript: document.removeEventListener('keydown', handleKeyPress);
• Unity: Unsubscribing from an input action event, or disabling an Input Action Map.
• Godot: Disconnecting a signal from an InputEvent.

It provides a way to dynamically control which inputs are active and what actions they trigger, allowing for flexible and context-sensitive control schemes in your game.