Gameplay synchronization

Synchronization is the process that ensures a code loop runs at a constant intended speed.

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... So why bother with synchronization?

‎‎

void main()
{
	/* Screen and sprites initialization... */

	u8 mPosX = 100; // Monster's position X coordinate
	while (1) // Gameplay loop
	{
		mPosX++;
		VDP_SetSpritePositionX(0, mPosX);
	}
}

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.

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.

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).

Synchronizing your code ensures that your gameplay loop always executes at the same given speed.^#1

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 (interrupts) that allows peripheral devices to send signals to the CPU, which the program can then handle.

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).

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.

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.

With MSXgl, simply call the Halt() function in your gameplay loop (it’s good practice to call it first):

‎‎

void main()
{
	/* Screen and sprites initialization... */

	u8 mPosX = 100; // Monster's position X coordinate
	while (1) // Gameplay loop
	{
		Halt(); // Wait for an interrupt signal to occur (hopefully, the v-blank one)

		mPosX++;
		VDP_SetSpritePositionX(0, mPosX);

		/* Player handling… */
	}
}

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.

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.

The ‘hooked’ function call is thus synchronized with the v-blank.

You have two options:

• Place your entire gameplay loop in this function! This is simple but not very handy for an actual game.
• Use this function to create a blocking function similar to Halt that only waits for the v-blank signal. This is the recommended method.

Example of a blocking function:

‎‎

// H_TIMI interrupt hook. Called when v-blank interrupt occured
void VBlankHook()
{
	g_VBlank = TRUE; // Set signal flag
}

// Wait for v-blank period
void WaitVBlank()
{
	while (g_VBlank == FALSE) {} // g_VBlank become TRUE when v-blank signal 
	g_VBlank = FALSE; // Reset signal flag
}

// Program entry
void main()
{
	/* Screen and sprites initialization... */

	Bios_SetHookCallback(H_TIMI, VBlankHook); // Register our function

	u8 mPosX = 100; // Monster's position X coordinate
	while (1) // Gameplay loop
	{
		WaitVBlank(); // Wait for an v-blank signal

		mPosX++;
		VDP_SetSpritePositionX(0, mPosX);

		/* Player handling… */
	}
}

Using MSXgl ISR

When using "ROM_48K_ISR", "ROM_64K_ISR", NEO mapper targets, or any ROM with InstallRAMISR set to "RAM0_ISR" or "RAM0_SEGMENT", 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 VDP_InterruptHandler(), which is called every time the v-blank signal is detected.

The blocking function can now be written as follows:

‎‎

// MSXgl ISR callback. Called when v-blank interrupt occured
void VDP_InterruptHandler()
{
	g_VBlank = TRUE; // Set signal flag
}

// Wait for v-blank period
void WaitVBlank()
{
	while (g_VBlank == FALSE) {} // g_VBlank become TRUE when v-blank signal 
	g_VBlank = FALSE; // Reset signal flag
}

// Program entry
void main()
{
	/* Screen and sprites initialization... */

	u8 mPosX = 100; // Monster's position X coordinate
	while (1) // Gameplay loop
	{
		WaitVBlank(); // Wait for an v-blank signal

		mPosX++;
		VDP_SetSpritePositionX(0, mPosX);

		/* Player handling… */
	}
}

How to handle 60 and 50 Hz?

V-blank signal is great to synchronize gameplay but this signal is not triggered at the same time interval on NTSC and PAL/SECAM regions (60 vs 50 Hz). So, if you synchronize with v-blank, your game will not run at the same speed on machines from both regions. This is a well known issue for European kids back in the days, who played slow Japanese games (NTSC) on their home MSX (PAL/SECAM).

As the program can detect if the MSX is a 50 or 60 Hz machine, it can adapt so the same game runs at the same speed on all machines.

There are several ways to do that.

Simple is best

The far simplest way to handle display frequency difference is to tune your game for 50 Hz and, when a 60 Hz machine is detected, just drop 1 frame out of 6. That way, you have the same number of gameplay frames per second on any MSX, and on 60 Hz, you just have 1 frame out of 5 that lasts a little longer (which is not noticeable).^#2

This can be achieved by changing only the WaitVBlank() function.

‎‎

// H_TIMI interrupt hook. Called when v-blank interrupt occured
void VDP_InterruptHandler()
{
	g_VBlank = TRUE; // Set signal flag
	g_VBlankCount++;
}

// Wait for v-blank period
void WaitVBlank()
{
	while (g_VBlank == FALSE) {} // g_VBlank become TRUE when v-blank signal 
	g_VBlank = FALSE; // Reset signal flag
	if (g_IsNTSC && (g_VBlankCount == 4)) // 5th frame on NTSC machine
	{
		while (g_VBlank == FALSE) {} // wait another frame
		g_VBlank = FALSE;
		g_VBlankCount = 0;
	}	
}

Note this method works well also for music playback so the same music (made for 50 Hz) can be replayed at the same speed on 50 and 60 Hz machines.

Alternatives

Other solutions for managing the difference between 50 Hz and 60 Hz machines:

• Do the opposite of the previous solution: tune your game for 60 Hz and, on a 50 Hz machine, run the gameplay loop twice every 5 frames. The big problem with this method is that the execution time of 2 frames may greatly exceed the time allocated between two v-blank signals.
• Have 2 sets of movement quantities, one for 50 Hz and one for 60 Hz. This is possible with fixed-point numbers (the movement quantities must be 1.2 times greater in 50 Hz to compensate for the frequency difference). You also need to provide two sets of music and sound effects, or have a format that can adapt (like VGM format).^#3

Notes

• ^#1 If the execution time of a gameplay loop is longer than the synchronization time, the game will not be synchronized correctly.
• ^#2 Note that to support both 50 and 60 Hz, a gameplay loop must not exceed the time interval of the worst case: the 60 Hz where a frame lasts 16.7 ms.
• ^#3 Some formats, such as Arkos Tracker, allow you to set a tempo for your music, which represents the wait between two beats. If you create your music with a tempo that is a multiple of 6, you can play it back at the same speed on a 50 Hz machine with a tempo of 5.