mvbg

VM_ACTOR_SET_FLAGS

VM_ACTOR_SET_FLAGS is a GBVM instruction used to modify various behavioral and visual flags for a specified actor.

Purpose: Actors in Game Boy games often have internal flags that control their properties, such as visibility, animation behavior, or collision detection. VM_ACTOR_SET_FLAGS provides a powerful way to dynamically change these properties at runtime. It is essential for:

• Dynamic visibility: Hiding or showing actors based on game events (e.g., a secret passage appearing, an enemy spawning).
• Animation control: Disabling animation looping for one-shot animations or specific poses.
• Collision toggling: Temporarily enabling or disabling an actor’s collision detection (e.g., for phasing through walls).
• Persistence: Marking an actor as persistent across scene changes.

This instruction works by applying a FLAGS value using a MASK. The MASK determines which flags are affected, and the FLAGS value determines whether those affected flags are set (to 1) or cleared (to 0).

Syntax:

VM_ACTOR_SET_FLAGS ACTOR, FLAGS, MASK

• ACTOR: A variable that contains the actor number (ID) of the actor whose flags you want to modify.
• FLAGS: A bitmask representing the desired state of the flags you want to change. For each bit in FLAGS that is set to 1, the corresponding flag will be set. For each bit set to 0, the corresponding flag will be cleared.
• MASK: A bitmask that specifies which flags are to be affected by the operation. Only the flags corresponding to the bits set to 1 in the MASK will be modified. Flags corresponding to bits set to 0 in the MASK will remain unchanged.

Common Flags:

• .ACTOR_FLAG_PINNED: Controls if the actor is pinned to the screen or moves with the camera.
• .ACTOR_FLAG_HIDDEN: Controls the actor’s visibility (1 for hidden, 0 for visible).
• .ACTOR_FLAG_ANIM_NOLOOP: Disables animation looping for the actor.
• .ACTOR_FLAG_COLLISION: Enables/disables collision detection for the actor.
• .ACTOR_FLAG_PERSISTENT: Marks the actor to persist across scene changes.

Usage Example: Hiding and Showing a Secret Item

Imagine a secret item that only appears after the player solves a puzzle. You can initially keep the item hidden and then reveal it using VM_ACTOR_SET_FLAGS.

; In your script:

; Assume SECRET_ITEM_ACTOR_ID is the actor ID for the secret item
SECRET_ITEM_ACTOR_ID:
  .R_INT8 50 ; Example Actor ID

; Assume VAR_PUZZLE_SOLVED is a flag (0 = unsolved, 1 = solved)
VAR_PUZZLE_SOLVED:
  .R_INT8 0

; Initially, hide the secret item (e.g., in scene initialization)
; To hide: FLAGS = .ACTOR_FLAG_HIDDEN, MASK = .ACTOR_FLAG_HIDDEN
VM_ACTOR_SET_FLAGS SECRET_ITEM_ACTOR_ID, .ACTOR_FLAG_HIDDEN, .ACTOR_FLAG_HIDDEN

; ... code for puzzle logic ...

; When the puzzle is solved:
PUZZLE_SOLVED_ROUTINE:
  VM_SET_CONST VAR_PUZZLE_SOLVED, 1

  ; Show the secret item
  ; To show: FLAGS = 0 (clear hidden flag), MASK = .ACTOR_FLAG_HIDDEN
  VM_ACTOR_SET_FLAGS SECRET_ITEM_ACTOR_ID, 0, .ACTOR_FLAG_HIDDEN

  VM_LOAD_TEXT TEXT_SECRET_ITEM_APPEARS
  VM_DISPLAY_TEXT
  VM_IDLE 60

  VM_RET

TEXT_SECRET_ITEM_APPEARS:
  .TEXT "A secret item appeared!"
  .TEXT_END

; Flag constants (these would be defined globally)
.ACTOR_FLAG_HIDDEN:
  .R_INT8 1 ; Example bit value for hidden flag

In this example:

1. Initially, VM_ACTOR_SET_FLAGS SECRET_ITEM_ACTOR_ID, .ACTOR_FLAG_HIDDEN, .ACTOR_FLAG_HIDDEN sets the _HIDDEN flag for the SECRET_ITEM_ACTOR_ID, making it invisible. Here, FLAGS has the _HIDDEN bit set, and MASK also has the _HIDDEN bit set, meaning only the _HIDDEN flag is targeted and set to 1.
2. When the puzzle is solved, VM_ACTOR_SET_FLAGS SECRET_ITEM_ACTOR_ID, 0, .ACTOR_FLAG_HIDDEN is called. Here, FLAGS is 0 (meaning the _HIDDEN bit is 0), and MASK is still .ACTOR_FLAG_HIDDEN. This clears the _HIDDEN flag, making the item visible.

This demonstrates how FLAGS and MASK work together: MASK selects which flags to modify, and FLAGS provides the new values for those selected flags.

Analogy to other programming languages/game engines: This is analogous to setting boolean properties or bit flags on a game object:

• Unity: gameObject.SetActive(true/false); or collider.enabled = true/false;
• Godot: node.visible = true/false; or collision_shape.disabled = true/false;
• C/C++: Bitwise operations on a status register or flag variable: actor->flags = (actor->flags & ~MASK) | (new_flags & MASK);

It provides a flexible way to control multiple binary properties of an actor with a single instruction.