mvbg

VM_RTC_GET

VM_RTC_GET is a GBVM instruction used to read a specific time component (seconds, minutes, hours, or days) from the Game Boy Color’s (GBC) Real-Time Clock (RTC) and store it into a GBVM variable.

Purpose: The Game Boy Color introduced a Real-Time Clock (RTC) in some cartridges (like Pokémon Gold/Silver/Crystal) that continues to keep track of time even when the console is turned off. VM_RTC_GET allows your game to access this time information. This is essential for:

• Time-based events: Implementing in-game events that occur at specific times of day, on certain days, or after a certain duration (e.g., shops opening/closing, crops growing, daily bonuses).
• Day/Night cycles: Changing the game’s visuals or gameplay based on the time of day.
• Persistent world features: Allowing elements of the game world to evolve over real-world time.
• Unique gameplay mechanics: Creating games that interact with the player’s real-world schedule.

This instruction reads a single time component from the RTC and places it into a specified variable. Before reading, the RTC should typically be latched using VM_RTC_LATCH to ensure a consistent reading.

Syntax:

VM_RTC_GET IDX, WHAT

• IDX: The target variable (a GBVM variable) that will receive the retrieved RTC value.
• WHAT: A constant that specifies which RTC component to read:
  • .RTC_SECONDS: Reads the current seconds (0-59).
  • .RTC_MINUTES: Reads the current minutes (0-59).
  • .RTC_HOURS: Reads the current hours (0-23).
  • .RTC_DAYS: Reads the current days (0-365+).

Usage Example: Implementing a Simple Day/Night Cycle

Imagine your game has a simple day/night cycle that changes the screen’s palette based on the current hour of the day. You would read the current hour from the RTC.

; In your game loop or a dedicated time management script:

; Variable to store the current hour
VAR_CURRENT_HOUR:
  .R_INT8 0

; RTC component constants
.RTC_HOURS:
  .R_INT8 2 ; Example value for hours component

; Palette definitions (conceptual)
PALETTE_DAY_BANK:
  .R_INT8 BANK(PALETTE_DAY)
PALETTE_DAY:
  ; ... normal daytime palette ...

PALETTE_NIGHT_BANK:
  .R_INT8 BANK(PALETTE_NIGHT)
PALETTE_NIGHT:
  ; ... darker nighttime palette ...

GAME_TIME_UPDATE_LOOP:
  ; Latch the RTC to get a consistent reading
  VM_RTC_LATCH

  ; Get the current hour from the RTC
  VM_RTC_GET VAR_CURRENT_HOUR, .RTC_HOURS

  ; Check if it's daytime (e.g., 6 AM to 6 PM)
  VM_IF_CONST .GTE, VAR_CURRENT_HOUR, 6, CHECK_NIGHT, 0
  VM_JUMP SET_NIGHT_PALETTE

CHECK_NIGHT:
  VM_IF_CONST .LT, VAR_CURRENT_HOUR, 18, SET_DAY_PALETTE, 0
  VM_JUMP SET_NIGHT_PALETTE

SET_DAY_PALETTE:
  VM_LOAD_PALETTE .PALETTE_BACKGROUND_0, PALETTE_DAY_BANK, PALETTE_DAY
  VM_LOAD_PALETTE .PALETTE_SPRITE_0, PALETTE_DAY_BANK, PALETTE_DAY ; Also for sprites
  VM_JUMP END_TIME_UPDATE

SET_NIGHT_PALETTE:
  VM_LOAD_PALETTE .PALETTE_BACKGROUND_0, PALETTE_NIGHT_BANK, PALETTE_NIGHT
  VM_LOAD_PALETTE .PALETTE_SPRITE_0, PALETTE_NIGHT_BANK, PALETTE_NIGHT ; Also for sprites

END_TIME_UPDATE:
  VM_IDLE 60 ; Check time once per second
  VM_JUMP GAME_TIME_UPDATE_LOOP

In this example, VM_RTC_GET VAR_CURRENT_HOUR, .RTC_HOURS retrieves the current hour from the Game Boy Color’s RTC. Based on this hour, the script dynamically loads either a daytime or nighttime palette, creating a simple day/night cycle that reflects real-world time. This adds a layer of realism and dynamic change to the game world.

Analogy to Game Boy Development: This is a direct interface with the Game Boy Color’s Real-Time Clock hardware. In modern programming, it’s analogous to getting the current time from the system clock (DateTime.Now in C#, time.time() in Python, Date() in JavaScript). It allows games to interact with and respond to real-world time, enabling unique gameplay mechanics and persistent world features.