Gameplay synchronization - Revision history

Aoineko: /* Alternatives */

2025-10-17T22:17:19Z

‎Alternatives

Aoineko: /* Using MSXgl ISR */

2025-10-17T22:09:22Z

‎Using MSXgl ISR

Aoineko: /* Using BIOS */

2025-10-17T22:08:42Z

‎Using BIOS

Aoineko: /* Using BIOS */

2025-10-17T22:08:15Z

‎Using BIOS

Aoineko: /* Interrupt handler */

2025-10-17T22:06:44Z

‎Interrupt handler

Aoineko: /* How do I synchronize? */

2025-10-17T22:05:31Z

‎How do I synchronize?

Aoineko: /* Why should I synchronize? */

2025-10-17T22:03:05Z

‎Why should I synchronize?

Aoineko: /* Why should I synchronize? */

2025-10-17T22:02:32Z

‎Why should I synchronize?

Aoineko at 22:00, 17 October 2025

2025-10-17T22:00:40Z

Aoineko: /* Why should I synchronize? */

2025-10-17T21:55:00Z

‎Why should I synchronize?

@@ Line 202: / Line 202: @@
 Other solutions for managing the 50 Hz/60 Hz difference:
 * Do the opposite: design your game for 60 Hz and, on 50 Hz machines, run the gameplay loop twice every 5 frames. The big problem with this method is that the execution time of 2 frames can greatly exceed the time allowed between two v-blank signals.
-* Use two sets of movement values: one for 50 Hz and one for 60 Hz. This is feasible with fixed-point arithmetic (movement values must be 1.2x greater for 50 Hz to compensate for the frequency difference). You'll also need two sets of music and sound effects, or a format that can adapt (such as VGM).<sup>[[#Notes|#3]]</sup>
+* Use two sets of movement values: one for 50 Hz and one for 60 Hz. This is feasible with [[Fixed-point number|fixed-point arithmetic]] (movement values must be 1.2x greater for 50 Hz to compensate for the frequency difference). You'll also need two sets of music and sound effects, or a format that can adapt (such as VGM).<sup>[[#Notes|#3]]</sup>
 == Notes ==

@@ Line 122: / Line 122: @@
 ==== Using MSXgl ISR ====
-When using <tt>"ROM_48K_ISR"</tt>, <tt>"ROM_64K_ISR"</tt>, NEO mapper targets, or any ROM with <tt>InstallRAMISR</tt> set to <tt>"RAM0_ISR"</tt> or <tt>"RAM0_SEGMENT"</tt>, MSXgl's boot program switches memory page 0 to point to a ROM segment or RAM containing a custom interrupt handler (ISR).
+When using <tt>"ROM_48K_ISR"</tt>, <tt>"ROM_64K_ISR"</tt>, NEO mapper targets, or any ROM with <tt>InstallRAMISR</tt> set to <tt>"RAM0_ISR"</tt> or <tt>"RAM0_SEGMENT"</tt>, MSXgl's boot program switches memory page #0 to point to a ROM segment or RAM containing a custom interrupt handler (ISR).
 This custom ISR is optimized for games and works similarly to the BIOS's ISR for synchronization.

@@ Line 78: / Line 78: @@
 When the BIOS is active (main-ROM selected in memory page #0), an interrupt handler is called whenever an interrupt occurs.
 This handler checks the signal's origin and, if it's from the VDP's v-blank, calls a specific RAM address (called <tt>H.TIMI</tt>).
 Your program can "hook" this address to execute its own function.
 The 'hooked' function call is thus synchronized with the v-blank.

@@ Line 77: / Line 77: @@
 ==== Using BIOS ====
 When the BIOS is active (main-ROM selected in memory page #0), an interrupt handler is called whenever an interrupt occurs.
-This handler checks the signal's origin and, if it's from the VDP's v-blank, calls a specific RAM address.
+This handler checks the signal's origin and, if it's from the VDP's v-blank, calls a specific RAM address (called <tt>H.TIMI</tt>).
 Your program can "hook" this address to execute its own function.

@@ Line 71: / Line 71: @@
 === Interrupt handler ===
 The problem with Halt is that it will resume execution for any interrupt signal, not just v-blank.
-This can happen if you use the h-blank feature of the MSX2 (which notifies you when a specific screen line finishes rendering) or if a connected device triggers an interrupt.
+This can happen if you use the h-blank feature of the MSX2 (which notifies you when a specific screen line finishes rendering) or if any connected device triggers an interrupt.
 To address this, you must check whether the interrupt was caused by the VDP's v-blank signal.

@@ Line 47: / Line 47: @@
 === Halt ===
-The Z80 (MSX's CPU) has a special instruction, Halt, that pauses program execution until an interrupt signal occurs.
+The Z80 (MSX's CPU) has a special instruction, Halt, that pauses program execution until an [[Interrupt handler|interrupt signal]] occurs.
 As in most contexts, the only interrupt signal the CPU receives is the v-blank signal (triggered by the VDP), you can use the Halt instruction in your gameplay loop to synchronize with v-blank.

@@ Line 22: / Line 22: @@
 Let's continue the example: Now you add some code to handle player movement (input reading, basic physics, and collision detection).
 When you run your program again, the first thing you notice is that the monster moves more slowly than before.
-And when you start moving your character, it gets even worse: not only does the monster move even more slowly, but its speed is no longer constant.
+And when you start moving your player character, it gets even worse: not only does the monster move even more slowly, but its speed is no longer constant.
 Why?

@@ Line 2: / Line 2: @@
 == Why should I synchronize? ==
-Let’s say you want a monster to move from left to right across the screen. You create a loop where you increment an X coordinate and update the sprite’s position accordingly. If you test your program, the monster moves at a constant speed...
+Let's say you want a monster to move from left to right across the screen.
+You create a loop where you increment an X coordinate and update the sprite's position accordingly.
 So why bother with synchronization?
 ‎‎<syntaxhighlight lang="c">
@@ Line 19: / Line 20: @@
 </syntaxhighlight>
-Let’s continue the example: Now you add some code to handle player movement (including input reading, basic physics, and collision detection). When you run your program again, the first thing you notice is that the monster moves more slowly than before. And when you start moving your character, it gets even worse: not only does the monster move even more slowly, but its speed is no longer constant.
+Let's continue the example: Now you add some code to handle player movement (including input reading, basic physics, and collision detection).
 Why?
-Speed is defined as the amount of movement over time. For a constant amount of movement (e.g., +1 pixel to the right), the longer the time taken, the slower the speed.
+Speed is defined as the amount of movement over time.
-If your gameplay loop is not synchronized, the time the CPU needs to execute it will vary, affecting movement speed. Code branching (such as ‘if’ statements) makes this worse, as execution time becomes not constant (for example, some code may only run if a collision is detected).
+If your gameplay loop is not synchronized, the time the CPU needs to execute it will vary, affecting movement speed.
 Synchronizing your code ensures that your gameplay loop always executes at the same given speed.<sup>[[#Notes|#1]]</sup>
 == How do I synchronize? ==
-Synchronization simply involves waiting for a signal sent at a constant frequency before executing the next iteration of the gameplay loop. The MSX has a system ([[Interrupt handler|interrupts]]) that allows peripheral devices to send signals to the CPU, which the program can then handle.
+Synchronization simply involves waiting for a signal sent at a constant frequency before executing the next iteration of the gameplay loop.
-The most commonly used signal for gameplay synchronization is the one sent by the graphics processor (VDP) at the end of screen rendering: the "v-blank" (start of the vertical blanking interval). This signal is sent every 1/60th of a second on NTSC machines (60 Hz) or every 1/50th of a second on PAL/SECAM machines (50 Hz).
+The most commonly used signal for gameplay synchronization is the one sent by the graphics processor (VDP) at the end of screen rendering: the "v-blank" (start of the vertical blanking interval).
-If your gameplay loop waits for the v-blank signal, your code will always execute at the same time interval, regardless of its actual duration. This ensures that all movements occur at a constant speed.
+If your gameplay loop waits for the v-blank signal, your code will always execute at the same time interval, regardless of its actual duration.
 There are several ways to synchronize your gameplay.
 === Halt ===
-The Z80 (MSX’s CPU) has a special instruction, Halt, that pauses program execution until an interrupt signal occurs. As in most contexts, the only interrupt signal the CPU receives is the v-blank signal (triggered by the VDP), you can use the Halt instruction in your gameplay loop to synchronize with v-blank.
+The Z80 (MSX's CPU) has a special instruction, Halt, that pauses program execution until an interrupt signal occurs.
-With MSXgl, simply call the <tt>Halt()</tt> function in your gameplay loop (it’s good practice to call it first):
+With MSXgl, simply call the <tt>Halt()</tt> function in your gameplay loop (it's good practice to call it first):
 ‎‎<syntaxhighlight lang="c">
 void main()
@@ Line 61: / Line 70: @@
 === Interrupt handler ===
-The problem with Halt is that it will resume execution for any interrupt signal, not just v-blank. This can happen if you use the h-blank feature of the MSX2 (which notifies you when a specific screen line finishes rendering) or if a connected device triggers an interrupt.
+The problem with Halt is that it will resume execution for any interrupt signal, not just v-blank.
-To address this, you must check whether the interrupt was caused by the VDP’s v-blank signal.
+To address this, you must check whether the interrupt was caused by the VDP's v-blank signal.
 ==== Using BIOS ====
-When the BIOS is active (main-ROM selected in memory page #0), an interrupt handler is called whenever an interrupt occurs. This handler checks the signal’s origin and, if it’s from the VDP’s v-blank, calls a specific RAM address. Your program can "hook" this address to execute its own function.
+When the BIOS is active (main-ROM selected in memory page #0), an interrupt handler is called whenever an interrupt occurs.
-The ‘hooked’ function call is thus synchronized with the v-blank.
+The 'hooked' function call is thus synchronized with the v-blank.
 You have two options:
@@ Line 110: / Line 122: @@
 ==== Using MSXgl ISR ====
-When using <tt>"ROM_48K_ISR"</tt>, <tt>"ROM_64K_ISR"</tt>, NEO mapper targets, or any ROM with <tt>InstallRAMISR</tt> set to <tt>"RAM0_ISR"</tt> or <tt>"RAM0_SEGMENT"</tt>, MSXgl’s boot program switches memory page 0 to point to a ROM segment or RAM containing a custom interrupt handler (ISR).
+When using <tt>"ROM_48K_ISR"</tt>, <tt>"ROM_64K_ISR"</tt>, NEO mapper targets, or any ROM with <tt>InstallRAMISR</tt> set to <tt>"RAM0_ISR"</tt> or <tt>"RAM0_SEGMENT"</tt>, MSXgl's boot program switches memory page 0 to point to a ROM segment or RAM containing a custom interrupt handler (ISR).
-This custom ISR is optimized for games and works similarly to the BIOS’s ISR for synchronization. With MSXgl ISR, there’s no need to "hook" a function: the system expects your program to provide a function named <tt>VDP_InterruptHandler()</tt>, which is called every time the v-blank signal is detected.
+This custom ISR is optimized for games and works similarly to the BIOS's ISR for synchronization.
 The blocking function can now be written as follows:
@@ Line 148: / Line 161: @@
 == How to handle 60 and 50 Hz? ==
-The v-blank signal is ideal for synchronization, but its frequency differs between NTSC (60 Hz) and PAL/SECAM (50 Hz) regions. If you synchronize with v-blank, your game will run at different speeds on machines from these regions. This is a well known issue for European kids back in the days, who played slow Japanese (NTSC) games on their home (PAL/SECAM) MSX.
+The v-blank signal is ideal for synchronization, but its frequency differs between NTSC (60 Hz) and PAL/SECAM (50 Hz) regions.
 Since the program can detect whether the MSX is 50 Hz or 60 Hz, it can adapt to ensure the game runs at the same speed on all machines.
@@ Line 155: / Line 170: @@
 === Simple is best ===
-The easiest way to handle the frequency difference is to design your game for 50 Hz and, on 60 Hz machines, skip 1 frame every 6 frames. This ensures the same number of gameplay frames per second on all MSX systems. On 60 Hz machines, 1 frame out of 5 will last slightly longer (which is barely noticeable).<sup>[[#Notes|#2]]</sup>
+The easiest way to handle the frequency difference is to design your game for 50 Hz and, on 60 Hz machines, skip 1 frame every 6 frames.
 This can be implemented by modifying the WaitVBlank() function:
@@ Line 185: / Line 202: @@
 Other solutions for managing the 50 Hz/60 Hz difference:
 * Do the opposite: design your game for 60 Hz and, on 50 Hz machines, run the gameplay loop twice every 5 frames. The big problem with this method is that the execution time of 2 frames can greatly exceed the time allowed between two v-blank signals.
-* Use two sets of movement values: one for 50 Hz and one for 60 Hz. This is feasible with fixed-point arithmetic (movement values must be 1.2x greater for 50 Hz to compensate for the frequency difference). You’ll also need two sets of music and sound effects, or a format that can adapt (such as VGM).<sup>[[#Notes|#3]]</sup>
+* Use two sets of movement values: one for 50 Hz and one for 60 Hz. This is feasible with fixed-point arithmetic (movement values must be 1.2x greater for 50 Hz to compensate for the frequency difference). You'll also need two sets of music and sound effects, or a format that can adapt (such as VGM).<sup>[[#Notes|#3]]</sup>
 == Notes ==
-* <sup>#1</sup> If a gameplay loop’s execution time exceeds the synchronization interval, the game will not synchronize correctly.
+* <sup>#1</sup> If a gameplay loop's execution time exceeds the synchronization interval, the game will not synchronize correctly.
 * <sup>#2</sup> To support both 50 Hz and 60 Hz, a gameplay loop must not exceed the worst-case interval: 16.7 ms (60 Hz).
-* <sup>#3</sup> Some formats, like Arkos Tracker, let you set a tempo for your music (the wait time between beats). If you create music with a tempo that’s a multiple of 6, it can play at the same speed on a 50 Hz machine by using the corresponding multiple of 5.
+* <sup>#3</sup> Some formats, like Arkos Tracker, let you set a tempo for your music (the wait time between beats). If you create music with a tempo that's a multiple of 6, it can play at the same speed on a 50 Hz machine by using the corresponding multiple of 5.