mvbg

VM_COS_SCALE

VM_COS_SCALE is a GBVM instruction used to calculate the cosine of a given angle, scaled by a specified factor, and store the result in a variable.

Purpose: Trigonometric functions like cosine are essential for many game mechanics, especially those involving circular motion, waves, or angles. VM_COS_SCALE is particularly useful for:

Circular movement: Moving objects in circles or ellipses (e.g., orbiting planets, rotating platforms).
Wave-like motion: Creating oscillating movements (e.g., bobbing platforms, swaying objects).
Angle-based calculations: Determining horizontal components of movement or position based on an angle.
Visual effects: Implementing effects that involve radial patterns or smooth, oscillating changes.

This instruction takes an angle and a scale factor. The angle is typically represented in a Game Boy-specific format (0-255 for a full circle, where 64 units represent 90 degrees). The SCALE parameter affects the precision of the calculation.

Syntax:

VM_COS_SCALE IDX, IDX_ANGLE, SCALE

IDX: The target variable (a GBVM variable) that will receive the calculated cosine value. This variable also acts as the cosine scale, meaning the result of the cosine function will be multiplied by the value initially in IDX.
IDX_ANGLE: The variable that contains the angle to be passed into the cosine function. This angle is typically an 8-bit unsigned integer, where:
- 0 (or 255) represents 0 degrees (pointing up).
- 64 represents 90 degrees (pointing right).
- 128 represents 180 degrees (pointing down).
- 192 represents 270 degrees (pointing left).
SCALE: The accuracy of the calculation, an integer between 0 and 7. A higher value generally means more precision but might take slightly longer to compute.

Usage Example: Creating a Bobbing Platform

Imagine a platform that bobs up and down smoothly. You can use VM_COS_SCALE to calculate its vertical position based on a continuously increasing angle.

; In your platform's update script:

; Assume PLATFORM_ACTOR_ID is the actor ID for the platform
PLATFORM_ACTOR_ID:
  .R_INT8 60 ; Example Actor ID

; Variables for angle, amplitude, and base Y position
VAR_BOB_ANGLE:
  .R_INT8 0 ; Current angle for bobbing (0-255)
VAR_BOB_AMPLITUDE:
  .R_INT8 8 ; How much the platform moves up/down (e.g., 8 pixels)
VAR_BASE_PLATFORM_Y:
  .R_INT16 100 ; The center Y position of the platform
VAR_CURRENT_OFFSET_Y:
  .R_INT16 0 ; Calculated vertical offset
VAR_PLATFORM_X:
  .R_INT16 50 ; Platform's fixed X position
VAR_PLATFORM_Y:
  .R_INT16 0 ; Platform's current Y position

PLATFORM_BOB_LOOP:
  ; Increment the angle for continuous motion
  VM_RPN
    .R_REF_MEM .R_INT8, VAR_BOB_ANGLE
    .R_INT8 1 ; Increment by 1 each frame
    .R_OPERATOR +
    .R_INT8
  VM_STOP
  VM_SET_INT8 VAR_BOB_ANGLE, 0

  ; Calculate the vertical offset using cosine
  ; The result will be scaled by VAR_BOB_AMPLITUDE
  VM_SET_INT8 VAR_CURRENT_OFFSET_Y, VAR_BOB_AMPLITUDE ; Set IDX to amplitude
  VM_COS_SCALE VAR_CURRENT_OFFSET_Y, VAR_BOB_ANGLE, 4 ; Calculate cosine, scale by amplitude, accuracy 4

  ; Add the offset to the base Y position to get the new platform Y
  VM_RPN
    .R_REF_MEM .R_INT16, VAR_BASE_PLATFORM_Y
    .R_REF_MEM .R_INT16, VAR_CURRENT_OFFSET_Y
    .R_OPERATOR +
    .R_INT16
  VM_STOP
  VM_SET_INT16 VAR_PLATFORM_Y, 0

  ; Set the platform's new position
  VM_ACTOR_SET_POS PLATFORM_ACTOR_ID, VAR_PLATFORM_X, VAR_PLATFORM_Y

  VM_IDLE 1 ; Yield control for one frame
  VM_JUMP PLATFORM_BOB_LOOP

In this example, VM_COS_SCALE is used to calculate a vertical offset based on VAR_BOB_ANGLE and VAR_BOB_AMPLITUDE. As VAR_BOB_ANGLE continuously increments, the cosine value oscillates, causing VAR_CURRENT_OFFSET_Y to smoothly change between positive and negative values. This offset is then added to VAR_BASE_PLATFORM_Y to create the bobbing motion of the platform.

Analogy to other programming languages/game engines: This is analogous to using Math.cos() or cosf() in C/C++ or math.cos() in Python to calculate a value based on an angle, and then multiplying it by an amplitude to get a desired range. It’s a fundamental mathematical operation for simulating natural, oscillating movements in games.