mvbg

VM_ACTOR_SET_MOVE_SPEED

VM_ACTOR_SET_MOVE_SPEED is a GBVM instruction used to control the movement speed of a specified actor.

Purpose: An actor’s movement speed is a critical parameter that affects gameplay, character control, and overall game pacing. VM_ACTOR_SET_MOVE_SPEED is essential for:

• Character progression: Allowing players to gain speed upgrades or suffer from movement-impairing status effects.
• NPC behavior: Making enemies faster or slower, or adjusting the patrol speed of NPCs.
• Dynamic gameplay: Implementing speed boosts, slow traps, or varying movement speeds based on terrain (e.g., slower in water, faster on a road).
• Difficulty adjustment: Modifying enemy speeds to increase or decrease game challenge.

When VM_ACTOR_SET_MOVE_SPEED is called, the actor’s internal movement speed parameter is updated. Subsequent movement commands (like VM_ACTOR_MOVE_TO) for that actor will use this new speed.

Syntax:

VM_ACTOR_SET_MOVE_SPEED ACTOR, SPEED

• ACTOR: A variable that contains the actor number (ID) of the actor whose movement speed you want to adjust.
• SPEED: The new movement speed (an integer). Higher values typically mean faster movement, while lower values mean slower movement. The exact scale depends on the engine’s implementation (e.g., pixels per frame, or a multiplier).

Usage Example: Player Speed Boost from a Power-Up

Imagine your player character can pick up a “Speed Boost” power-up that temporarily increases their movement speed. After a duration, their speed should return to normal.

; In your script, when a speed boost power-up is collected:

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

; Define normal and boosted speeds
SPEED_NORMAL:
  .R_INT8 1 ; Example: Normal speed
SPEED_BOOSTED:
  .R_INT8 2 ; Example: Double speed

; Variable to track if speed boost is active
VAR_SPEED_BOOST_ACTIVE:
  .R_INT8 0 ; 0 = inactive, 1 = active

; ... code for power-up collection detection ...

COLLECT_SPEED_BOOST:
  ; Check if boost is already active to prevent stacking
  VM_IF_CONST .EQ, VAR_SPEED_BOOST_ACTIVE, 1, END_BOOST_COLLECT, 0

  ; Set speed boost active flag
  VM_SET_CONST VAR_SPEED_BOOST_ACTIVE, 1

  ; Increase player's movement speed
  VM_ACTOR_SET_MOVE_SPEED PLAYER_ACTOR_ID, SPEED_BOOSTED

  VM_LOAD_TEXT TEXT_SPEED_BOOST_ACTIVE
  VM_DISPLAY_TEXT

  VM_IDLE 180 ; Boost duration (e.g., 3 seconds at 60 FPS)

  ; Return player's movement speed to normal
  VM_ACTOR_SET_MOVE_SPEED PLAYER_ACTOR_ID, SPEED_NORMAL

  ; Reset speed boost active flag
  VM_SET_CONST VAR_SPEED_BOOST_ACTIVE, 0

  VM_LOAD_TEXT TEXT_SPEED_BOOST_EXPIRED
  VM_DISPLAY_TEXT

END_BOOST_COLLECT:
  ; ... continue script ...

TEXT_SPEED_BOOST_ACTIVE:
  .TEXT "Speed Boost!"
  .TEXT_END

TEXT_SPEED_BOOST_EXPIRED:
  .TEXT "Speed Boost expired."
  .TEXT_END

In this example, when the player collects a speed boost, VM_ACTOR_SET_MOVE_SPEED PLAYER_ACTOR_ID, SPEED_BOOSTED instantly increases their movement speed. After a set duration (controlled by VM_IDLE), their speed is returned to SPEED_NORMAL using another VM_ACTOR_SET_MOVE_SPEED call. This provides a clear and immediate gameplay effect.

Analogy to other programming languages/game engines: This is analogous to setting the speed or move_speed property of a character controller or agent in a game engine:

• Unity: navMeshAgent.speed = newSpeed; or characterController.moveSpeed = newSpeed;
• Godot: Setting a speed variable that is then used in move_and_slide().

It provides direct control over how quickly an actor traverses the game world, which is fundamental for character control and game pacing.