mvbg

VM_ACTOR_SET_BOUNDS

VM_ACTOR_SET_BOUNDS is a GBVM instruction used to define or redefine the collision bounding box for a specified actor.

Purpose: In game development, a bounding box is an invisible rectangle (or other simple shape) that surrounds an actor and is used for collision detection. It’s typically simpler than the actor’s actual sprite, making collision calculations more efficient. VM_ACTOR_SET_BOUNDS is essential for:

Accurate collision detection: Ensuring that interactions between actors (e.g., player hitting an enemy, projectile hitting a wall) are detected correctly.
Dynamic collision areas: Adjusting an actor’s collision box based on its current animation frame (e.g., a character crouching might have a smaller bounding box).
Optimizing performance: Using simple bounding boxes instead of pixel-perfect collision for faster calculations.
Defining interactive areas: Marking regions around an actor that trigger events when another actor enters them.

When VM_ACTOR_SET_BOUNDS is called, the actor’s internal collision detection parameters are updated. Subsequent collision checks involving this actor will use the newly defined bounding box.

Syntax:

VM_ACTOR_SET_BOUNDS ACTOR, LEFT, RIGHT, TOP, BOTTOM

ACTOR: A variable that contains the actor number (ID) of the actor whose bounding box you want to set.
LEFT: The leftmost X-coordinate of the bounding box, relative to the actor’s origin (usually its top-left corner or center).
RIGHT: The rightmost X-coordinate of the bounding box, relative to the actor’s origin.
TOP: The topmost Y-coordinate of the bounding box, relative to the actor’s origin.
BOTTOM: The bottommost Y-coordinate of the bounding box, relative to the actor’s origin.

Usage Example: Adjusting Player Bounding Box for Crouching

Imagine a player character that can crouch. When crouching, their visual sprite changes, and their collision box should also become smaller to allow them to pass under low obstacles.

; In your player input handling script:

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

; Bounding box definitions (relative to actor's top-left corner)
; Normal standing bounds (e.g., 0, 15, 0, 15 for a 16x16 sprite)
BOUNDS_NORMAL_LEFT:
  .R_INT8 0
BOUNDS_NORMAL_RIGHT:
  .R_INT8 15
BOUNDS_NORMAL_TOP:
  .R_INT8 0
BOUNDS_NORMAL_BOTTOM:
  .R_INT8 15

; Crouching bounds (e.g., 0, 15, 8, 15 for a 16x8 collision area)
BOUNDS_CROUCH_LEFT:
  .R_INT8 0
BOUNDS_CROUCH_RIGHT:
  .R_INT8 15
BOUNDS_CROUCH_TOP:
  .R_INT8 8
BOUNDS_CROUCH_BOTTOM:
  .R_INT8 15

; Check for crouch input
VM_INPUT_GET VAR_INPUT_STATE
VM_IF_CONST .EQ, VAR_INPUT_STATE, INPUT_CROUCH, START_CROUCH, 0
  VM_JUMP END_CROUCH_CHECK

START_CROUCH:
  ; Set player animation to crouching
  VM_ACTOR_SET_ANIM PLAYER_ACTOR_ID, ANIM_PLAYER_CROUCH

  ; Set the actor's bounding box to the smaller crouching bounds
  VM_ACTOR_SET_BOUNDS PLAYER_ACTOR_ID, BOUNDS_CROUCH_LEFT, BOUNDS_CROUCH_RIGHT, BOUNDS_CROUCH_TOP, BOUNDS_CROUCH_BOTTOM

  VM_JUMP END_CROUCH_CHECK

END_CROUCH_CHECK:
  ; If crouch input is released, or not pressed, revert to normal bounds
  VM_IF_CONST .NE, VAR_INPUT_STATE, INPUT_CROUCH, END_CROUCH, 0
  VM_JUMP CONTINUE_GAME_LOOP

END_CROUCH:
  ; Set player animation to idle or walking
  VM_ACTOR_SET_ANIM PLAYER_ACTOR_ID, ANIM_PLAYER_IDLE

  ; Set the actor's bounding box back to normal standing bounds
  VM_ACTOR_SET_BOUNDS PLAYER_ACTOR_ID, BOUNDS_NORMAL_LEFT, BOUNDS_NORMAL_RIGHT, BOUNDS_NORMAL_TOP, BOUNDS_NORMAL_BOTTOM

CONTINUE_GAME_LOOP:
  ; ... rest of game loop ...

INPUT_CROUCH:
  .R_INT8 16 ; Example input value for crouch button
ANIM_PLAYER_CROUCH:
  .R_INT8 5 ; Example animation ID for crouching
ANIM_PLAYER_IDLE:
  .R_INT8 0 ; Example animation ID for idle

In this example, when the player presses the CROUCH button, VM_ACTOR_SET_BOUNDS is used to change the player actor’s collision box to a smaller rectangle. This allows the player to pass under obstacles that they couldn’t while standing. When the button is released, the bounds are reset to normal.

Analogy to other programming languages/game engines: This is analogous to adjusting the size or offset of a Collider component in Unity, a CollisionShape2D in Godot, or manually defining collision rectangles in a 2D game framework. It provides precise control over the physical interaction area of an actor, independent of its visual sprite.