mvbg

VM_INPUT_GET

VM_INPUT_GET is a GBVM instruction used to read the current state of the Game Boy’s joypad buttons and store the result into a specified variable.

Purpose: This instruction is fundamental for any interactive game, as it allows your script to detect player input. It is essential for:

• Player control: Moving characters, performing actions (attacking, jumping), or navigating menus.
• Event triggers: Initiating events based on specific button presses (e.g., opening a door with the A button).
• Conditional logic: Changing game behavior based on whether a button is currently held down or was just pressed.
• Multiplayer (SGB): When using the Super Game Boy (SGB), it can read input from up to four connected joypads.

When VM_INPUT_GET is called, it captures the state of the specified joypad’s buttons at that exact moment. The result is typically a bitmask, where each bit corresponds to a specific button (e.g., A, B, Start, Select, D-pad directions).

Syntax:

VM_INPUT_GET IDX, JOYID

• IDX: The target variable (a GBVM variable) that will receive the joypad input state. This variable will contain a bitmask representing which buttons are currently pressed.
• JOYID: The joypad identifier from which to get input. For single-player Game Boy games, this is typically .JOY0. For Super Game Boy (SGB) games, you can specify .JOY0, .JOY1, .JOY2, or .JOY3 for different controllers.
  • .JOY0: Joypad 0 (Player 1)
  • .JOY1: Joypad 1 (Player 2)
  • .JOY2: Joypad 2 (Player 3)
  • .JOY3: Joypad 3 (Player 4)

Usage Example: Player Character Movement Based on D-Pad Input

Imagine your player character moves based on D-pad input. You would use VM_INPUT_GET to read the joypad state and then use conditional logic to move the player.

; In your main game loop or player input handling routine:

; Variable to store the current joypad input state
VAR_JOYPAD_STATE:
  .R_INT8 0

; Assume PLAYER_ACTOR_ID is the actor ID for the player
PLAYER_ACTOR_ID:
  .R_INT8 0

; Input constants (these would be defined globally, often as bitmasks)
.INPUT_UP:
  .R_INT8 1
.INPUT_DOWN:
  .R_INT8 2
.INPUT_LEFT:
  .R_INT8 4
.INPUT_RIGHT:
  .R_INT8 8
.INPUT_A:
  .R_INT8 16
.INPUT_B:
  .R_INT8 32

GAME_LOOP:
  ; Get the current state of Joypad 0
  VM_INPUT_GET VAR_JOYPAD_STATE, .JOY0

  ; Check for Up input
  VM_RPN
    .R_REF_MEM .R_INT8, VAR_JOYPAD_STATE
    .R_REF_MEM .R_INT8, .INPUT_UP
    .R_OPERATOR &
    .R_REF_MEM .R_INT8, .INPUT_UP
    .R_OPERATOR ==
    .R_INT8
  VM_STOP
  VM_IF_CONST .NE, 0, 0, MOVE_PLAYER_UP, 0 ; If result is true (not 0), jump

  ; Check for Down input
  VM_RPN
    .R_REF_MEM .R_INT8, VAR_JOYPAD_STATE
    .R_REF_MEM .R_INT8, .INPUT_DOWN
    .R_OPERATOR &
    .R_REF_MEM .R_INT8, .INPUT_DOWN
    .R_OPERATOR ==
    .R_INT8
  VM_STOP
  VM_IF_CONST .NE, 0, 0, MOVE_PLAYER_DOWN, 0

  ; ... similar checks for LEFT, RIGHT, A, B buttons ...

  VM_JUMP GAME_LOOP ; Continue game loop

MOVE_PLAYER_UP:
  VM_ACTOR_SET_DIR PLAYER_ACTOR_ID, .DIR_UP
  VM_ACTOR_MOVE_TO PLAYER_ACTOR_ID, VAR_PLAYER_X, VAR_PLAYER_Y - 8, 0 ; Move up 8 pixels
  VM_JUMP GAME_LOOP

MOVE_PLAYER_DOWN:
  VM_ACTOR_SET_DIR PLAYER_ACTOR_ID, .DIR_DOWN
  VM_ACTOR_MOVE_TO PLAYER_ACTOR_ID, VAR_PLAYER_X, VAR_PLAYER_Y + 8, 0 ; Move down 8 pixels
  VM_JUMP GAME_LOOP

; ... other movement/action routines ...

In this example, VM_INPUT_GET VAR_JOYPAD_STATE, .JOY0 reads the current state of the first joypad. The subsequent RPN blocks use bitwise AND (&) to check if specific buttons (like .INPUT_UP) are pressed. If a button is pressed, the player’s actor is moved accordingly. This forms the core of player control in many Game Boy games.

Analogy to other programming languages/game engines: This is analogous to polling input devices or checking the state of specific keys/buttons:

• Unity: Input.GetKey(KeyCode.UpArrow) or Input.GetButton("Jump").
• Godot: Input.is_action_pressed("ui_up").
• C/C++ (with a game library): IsKeyDown(KEY_UP).

It provides the direct means to read player input, which is fundamental for making your game interactive and responsive to player commands.