mvbg

VM_ACTOR_SET_COLL_ENABLED

VM_ACTOR_SET_COLL_ENABLED is a GBVM instruction used to enable or disable collision detection for a specified actor.

Purpose: Collision detection is a core component of game physics and interaction. However, there are many scenarios where you might want to temporarily or permanently disable an actor’s ability to collide with other objects or the environment. VM_ACTOR_SET_COLL_ENABLED is essential for:

• Ghosting/Phasing: Allowing a character to pass through walls or other actors (e.g., a ghost, a character using a special ability).
• Invincibility frames: Temporarily disabling collisions after a character takes damage to prevent immediate re-damage.
• Cutscenes/Transitions: Preventing actors from colliding during scripted sequences where their movement is predetermined.
• Non-interactive elements: For purely visual actors that should never interact physically with the game world.

When collision is disabled, the actor will typically ignore collision checks with other actors or the environment, allowing it to move freely through previously solid objects. When enabled, it will resume normal collision behavior.

Syntax:

VM_ACTOR_SET_COLL_ENABLED ACTOR, ENABLED

• ACTOR: A variable that contains the actor number (ID) of the actor whose collision properties you want to modify.
• ENABLED: A constant that specifies whether collisions should be enabled or disabled:
  • .ACTOR_COLLISION_DISABLED: Disables collision detection for the actor.
  • .ACTOR_COLLISION_ENABLED: Enables collision detection for the actor.

Usage Example: Implementing a Dash/Phase Through Walls Ability

Imagine a player character with a special ability to dash through walls for a short duration. You can achieve this by temporarily disabling their collisions.

; In your player ability script:

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

; Input for dash ability
INPUT_DASH:
  .R_INT8 32 ; Example input value for dash button

; Flag to track if player is currently dashing
VAR_IS_DASHING:
  .R_INT8 0 ; 0 = not dashing, 1 = dashing

; ... code for input detection ...

CHECK_DASH_INPUT:
  VM_INPUT_GET VAR_INPUT_STATE
  VM_IF_CONST .EQ, VAR_INPUT_STATE, INPUT_DASH, START_DASH, 0
  VM_JUMP END_DASH_CHECK

START_DASH:
  ; Check if already dashing to prevent re-triggering
  VM_IF_CONST .EQ, VAR_IS_DASHING, 1, END_DASH_CHECK, 0

  ; Set dashing flag
  VM_SET_CONST VAR_IS_DASHING, 1

  ; Disable player collisions
  VM_ACTOR_SET_COLL_ENABLED PLAYER_ACTOR_ID, .ACTOR_COLLISION_DISABLED

  VM_LOAD_TEXT TEXT_DASH_START
  VM_DISPLAY_TEXT

  ; Perform the dash movement (e.g., move quickly in current direction)
  VM_ACTOR_GET_DIR PLAYER_ACTOR_ID, VAR_PLAYER_DIR
  ; ... logic to move player quickly based on VAR_PLAYER_DIR ...
  VM_ACTOR_MOVE_TO PLAYER_ACTOR_ID, VAR_DASH_TARGET_X, VAR_DASH_TARGET_Y, 0 ; No collision check during dash

  VM_IDLE 30 ; Dash duration (e.g., 0.5 seconds)

  ; Re-enable player collisions
  VM_ACTOR_SET_COLL_ENABLED PLAYER_ACTOR_ID, .ACTOR_COLLISION_ENABLED

  ; Reset dashing flag
  VM_SET_CONST VAR_IS_DASHING, 0

  VM_LOAD_TEXT TEXT_DASH_END
  VM_DISPLAY_TEXT

END_DASH_CHECK:
  ; ... continue game loop ...

TEXT_DASH_START:
  .TEXT "Dashing!"
  .TEXT_END

TEXT_DASH_END:
  .TEXT "Dash ended."
  .TEXT_END

In this example, when the player activates the dash ability, VM_ACTOR_SET_COLL_ENABLED PLAYER_ACTOR_ID, .ACTOR_COLLISION_DISABLED temporarily turns off collision detection for the player. This allows them to move through obstacles. After a short duration, collisions are re-enabled with VM_ACTOR_SET_COLL_ENABLED PLAYER_ACTOR_ID, .ACTOR_COLLISION_ENABLED.

Analogy to other programming languages/game engines: This is analogous to enabling or disabling a Collider component in Unity, a CollisionShape2D in Godot, or setting a collidable property to false or true in a 2D game framework. It provides direct control over whether an actor participates in the game’s physics and interaction system.