mvbg

VM_RTC_SET

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

Purpose: While the RTC typically runs continuously, there are scenarios where you might need to manually set its values. VM_RTC_SET allows your game to adjust the RTC. This is essential for:

• Setting initial time: If your game has a specific starting time or date, you can initialize the RTC to that value.
• Time synchronization: Allowing players to manually adjust the in-game time if it drifts or if they want to align it with real-world time.
• Debugging/Testing: Quickly setting the RTC to a future or past time to test time-based events.
• Cheats/Developer tools: Providing a way for developers to manipulate the game’s internal clock.

This instruction takes a value from a specified variable and writes it to a single time component of the RTC. Care should be taken when using this instruction, as incorrect values can lead to unexpected behavior or desynchronization of the RTC.

Syntax:

VM_RTC_SET IDX, WHAT

• IDX: The source variable (a GBVM variable) whose value will be written to the RTC component.
• WHAT: A constant that specifies which RTC component to write to:
  • .RTC_SECONDS: Writes to the seconds component (0-59).
  • .RTC_MINUTES: Writes to the minutes component (0-59).
  • .RTC_HOURS: Writes to the hours component (0-23).
  • .RTC_DAYS: Writes to the days component (0-365+).

Usage Example: Setting the Game’s Starting Time

Imagine your game always starts at 8:00 AM on Day 0. You can use VM_RTC_SET to initialize the RTC to this specific time when a new game begins.

; In your new game initialization script:

; Variables to hold the desired starting time
VAR_START_SECONDS:
  .R_INT8 0
VAR_START_MINUTES:
  .R_INT8 0
VAR_START_HOURS:
  .R_INT8 8 ; 8 AM
VAR_START_DAYS:
  .R_INT16 0 ; Day 0

; RTC component constants
.RTC_SECONDS:
  .R_INT8 0
.RTC_MINUTES:
  .R_INT8 1
.RTC_HOURS:
  .R_INT8 2
.RTC_DAYS:
  .R_INT8 3

NEW_GAME_START:
  ; Set the RTC to the desired starting time
  VM_RTC_SET VAR_START_SECONDS, .RTC_SECONDS
  VM_RTC_SET VAR_START_MINUTES, .RTC_MINUTES
  VM_RTC_SET VAR_START_HOURS, .RTC_HOURS
  VM_RTC_SET VAR_START_DAYS, .RTC_DAYS

  ; After setting, you might want to start the RTC if it was stopped
  VM_RTC_START

  VM_LOAD_TEXT TEXT_GAME_STARTED_AT
  VM_DISPLAY_TEXT
  VM_IDLE 60

  ; ... continue game setup ...
  VM_RET

TEXT_GAME_STARTED_AT:
  .TEXT "Game started at 8:00 AM!"
  .TEXT_END

In this example, VM_RTC_SET is used multiple times to set the seconds, minutes, hours, and days components of the RTC to specific starting values. This ensures that the game’s internal clock begins from a consistent and desired point, which can be important for time-based events or narrative elements.

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 manually setting the system clock or synchronizing it with a network time server. It allows games to establish a specific starting point for their internal timekeeping, which is crucial for time-sensitive gameplay mechanics.