mvbg

VM_PROJECTILE_LOAD_TYPE

VM_PROJECTILE_LOAD_TYPE is a GBVM instruction used to load a projectile definition into a specific slot, making it available for launching with VM_PROJECTILE_LAUNCH.

Purpose: Before you can launch a projectile in your game, its properties (like its sprite, movement speed, collision behavior, and animation) need to be defined and loaded into the Game Boy’s memory. VM_PROJECTILE_LOAD_TYPE performs this setup. It is essential for:

Defining projectile types: Creating different kinds of projectiles (e.g., a fast arrow, a slow fireball, a bouncing bullet) with unique characteristics.
Memory management: Loading projectile data only when needed, rather than keeping all possible projectile types in memory at all times.
Dynamic projectile behavior: Allowing your game to switch between different projectile types based on player upgrades, enemy abilities, or game events.

When VM_PROJECTILE_LOAD_TYPE is called, it copies the projectile’s definition data from ROM (or another memory bank) into a designated TYPE slot in RAM. This slot then acts as a template for creating new instances of that projectile.

Syntax:

VM_PROJECTILE_LOAD_TYPE TYPE, BANK, ADDR

TYPE: The slot number (an integer) where the projectile definition will be loaded. This slot acts as an identifier for this specific projectile type.
BANK: The memory bank number where the projectile data (ADDR) is located. This is crucial for accessing projectile definitions that might be in a different ROM bank.
ADDR: The address (label) of the projectile data. This points to the raw data that defines the projectile’s properties (sprite, speed, etc.).

Usage Example: Loading Different Projectile Types for Player Weapons

Imagine your player character can switch between a bow (fires arrows) and a magic staff (fires fireballs). You would load the arrow projectile type and the fireball projectile type into different slots at the beginning of the game or when the player acquires the weapons.

; In your game initialization script:

; Define projectile data (these would be in your assets)
PROJECTILE_ARROW_DATA_BANK:
  .R_INT8 BANK(PROJECTILE_ARROW_DATA)
PROJECTILE_ARROW_DATA:
  ; ... raw data defining arrow projectile (sprite, speed, etc.) ...

PROJECTILE_FIREBALL_DATA_BANK:
  .R_INT8 BANK(PROJECTILE_FIREBALL_DATA)
PROJECTILE_FIREBALL_DATA:
  ; ... raw data defining fireball projectile (sprite, speed, etc.) ...

; Define slots for projectile types
PROJECTILE_SLOT_ARROW:
  .R_INT8 0 ; Slot 0 for arrows
PROJECTILE_SLOT_FIREBALL:
  .R_INT8 1 ; Slot 1 for fireballs

; Load the arrow projectile definition into slot 0
VM_PROJECTILE_LOAD_TYPE PROJECTILE_SLOT_ARROW, PROJECTILE_ARROW_DATA_BANK, PROJECTILE_ARROW_DATA

; Load the fireball projectile definition into slot 1
VM_PROJECTILE_LOAD_TYPE PROJECTILE_SLOT_FIREBALL, PROJECTILE_FIREBALL_DATA_BANK, PROJECTILE_FIREBALL_DATA

; ... rest of game initialization ...

; Later, in your player attack script, based on equipped weapon:
PLAYER_ATTACK_ROUTINE:
  ; Assume VAR_EQUIPPED_WEAPON holds the ID of the currently equipped weapon
  VM_IF_CONST .EQ, VAR_EQUIPPED_WEAPON, WEAPON_BOW, LAUNCH_ARROW, 0
  VM_IF_CONST .EQ, VAR_EQUIPPED_WEAPON, WEAPON_STAFF, LAUNCH_FIREBALL, 0
  VM_RET

LAUNCH_ARROW:
  ; Launch an arrow using the definition from PROJECTILE_SLOT_ARROW
  VM_PROJECTILE_LAUNCH PROJECTILE_SLOT_ARROW, VAR_PLAYER_X, VAR_PLAYER_Y, VAR_PLAYER_DIR, 0
  VM_RET

LAUNCH_FIREBALL:
  ; Launch a fireball using the definition from PROJECTILE_SLOT_FIREBALL
  VM_PROJECTILE_LAUNCH PROJECTILE_SLOT_FIREBALL, VAR_PLAYER_X, VAR_PLAYER_Y, VAR_PLAYER_DIR, 0
  VM_RET

WEAPON_BOW:
  .R_INT8 0
WEAPON_STAFF:
  .R_INT8 1

In this example, VM_PROJECTILE_LOAD_TYPE is used to pre-load the definitions for both arrow and fireball projectiles into distinct slots. Later, when the player attacks, the game checks the equipped weapon and uses VM_PROJECTILE_LAUNCH with the appropriate slot number to fire the correct type of projectile. This allows for flexible and extensible projectile systems in your game.

Analogy to Game Boy Development: This is analogous to defining a prefab or a template for a game object in a modern game engine. You define the properties of the object once, and then you can create multiple instances of it. On the Game Boy, this involves loading the raw data that describes the projectile into a dedicated memory area, ready to be instantiated when needed.