mvbg

VM_PROJECTILE_LAUNCH

VM_PROJECTILE_LAUNCH is a GBVM instruction used to create and launch an instance of a projectile that has been previously defined and loaded into a slot.

Purpose: Projectiles are common elements in many games, representing bullets, arrows, fireballs, or other objects that travel across the screen. VM_PROJECTILE_LAUNCH is essential for:

• Combat systems: Firing weapons, casting spells, or launching attacks.
• Environmental hazards: Creating moving obstacles or traps.
• Puzzles: Launching objects to hit targets or activate mechanisms.
• Visual effects: Generating particles or debris that move in a specific direction.

This instruction takes a TYPE (which refers to a pre-loaded projectile definition) and a pseudo-structure IDX that specifies the projectile’s initial position, angle/direction, and various flags that control its behavior.

Syntax:

VM_PROJECTILE_LAUNCH TYPE, IDX

• TYPE: The slot number (an integer) of the projectile definition to launch. This slot must have been previously loaded with a projectile type using VM_PROJECTILE_LOAD_TYPE.
• IDX: A pseudo-structure (or a variable pointing to one) that contains the launch parameters for the projectile. This typically includes:
  • pos.x: The X-coordinate (horizontal position) from where the projectile will be launched.
  • pos.y: The Y-coordinate (vertical position) from where the projectile will be launched.
  • angle: The angle or direction of the projectile’s initial movement. This can be a cardinal direction or a more granular angle value, depending on the engine’s implementation.
  • flags: Bit flags that control the projectile’s behavior:
    • .PROJECTILE_STRONG: If set, the projectile will not be destroyed upon collision with certain objects.
    • .PROJECTILE_ANIM_ONCE: If set, the projectile’s animation will play once and then stop, rather than looping.

Usage Example: Player Firing an Arrow

Imagine your player character can fire arrows. You would have an arrow projectile type loaded, and then use VM_PROJECTILE_LAUNCH to fire an arrow from the player’s position in their current facing direction.

; In your player attack script:

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

; Assume PROJECTILE_ARROW_SLOT is the slot where the arrow projectile type is loaded
PROJECTILE_ARROW_SLOT:
  .R_INT8 0 ; Example slot ID

; Variables for launch parameters
VAR_LAUNCH_X:
  .R_INT16 0
VAR_LAUNCH_Y:
  .R_INT16 0
VAR_LAUNCH_ANGLE:
  .R_INT8 0
VAR_LAUNCH_FLAGS:
  .R_INT8 0

; ... code for player pressing attack button ...

PLAYER_FIRES_ARROW:
  ; Get player's current position for launch point
  VM_ACTOR_GET_POS PLAYER_ACTOR_ID, VAR_LAUNCH_X, VAR_LAUNCH_Y

  ; Get player's current direction for launch angle
  VM_ACTOR_GET_DIR PLAYER_ACTOR_ID, VAR_LAUNCH_ANGLE

  ; Set projectile flags (e.g., no special flags for a basic arrow)
  VM_SET_CONST VAR_LAUNCH_FLAGS, 0

  ; Launch the arrow projectile
  VM_PROJECTILE_LAUNCH PROJECTILE_ARROW_SLOT, VAR_LAUNCH_X, VAR_LAUNCH_Y, VAR_LAUNCH_ANGLE, VAR_LAUNCH_FLAGS
  ; Note: The parameters for VM_PROJECTILE_LAUNCH are often passed as a contiguous block
  ; or directly as arguments, depending on the GBVM version. The pseudo-structure implies
  ; that the X, Y, angle, and flags are expected in a specific order after the TYPE.

  VM_SFX_PLAY SFX_ARROW_LAUNCH_BANK, SFX_ARROW_LAUNCH, 0b1111, .SFX_PRIORITY_NORMAL

  VM_RET

SFX_ARROW_LAUNCH_BANK:
  .R_INT8 BANK(SFX_ARROW_LAUNCH)
SFX_ARROW_LAUNCH:
  ; ... sound effect data ...

In this example, VM_PROJECTILE_LAUNCH is called to create an arrow projectile. The arrow is launched from the player’s current position (VAR_LAUNCH_X, VAR_LAUNCH_Y) and in the direction the player is facing (VAR_LAUNCH_ANGLE). This allows for dynamic and responsive projectile attacks in your game.

Analogy to Game Boy Development: This is analogous to instantiating a new game object (a bullet, a missile) from a prefab or template in a modern game engine, and then setting its initial position, rotation, and velocity:

• Unity: Instantiate(projectilePrefab, spawnPoint.position, spawnPoint.rotation);
• Godot: var projectile = ProjectileScene.instance(); add_child(projectile); projectile.position = spawn_pos; projectile.rotation = spawn_rot;

It provides the core functionality for adding dynamic, moving objects that interact with the game world, crucial for many action and adventure games.