doc: Dev journal entry about IIDX engine and syncbook

Due to recent development of tools and discussions, this
is something that came up and has probably been overdue
for ages.

Document key concepts of how the iidx engine works regaring
rendering, game loop and (song) sync.

Add a “syncbook” that provides context and guidelines how
to configure any (modern) system to work properly with iidx.
This commit is contained in:
icex2
2025-02-20 12:20:55 +01:00
parent ce1a004bf6
commit c337bdb7c0
11 changed files with 563 additions and 119 deletions
+220
View File
@@ -0,0 +1,220 @@
# IIDX "Syncbook": A guide to ensuring sync and performant gameplay
This is a guide applicable to all IIDX versions that are native Windows PC-based. The goal is to
enable proper configuration of those games to ensure the game engine "runs in-sync" with any of its
IO (visual GPU/display output, audio output, user input) resulting in high and stable performance
for smooth game-play.
This document won't go into the implementation details of the game engine. Please refer to the
[IIDX engine details journal](../dev/journal/2025-02-09-iidx-engine.md) for a more in-depth
information.
## Understanding the problems and options to address them
First, let's understand what the key problems are and how they contribute to different issues
that impact game-play.
### Song de-syncing
Symptom: Throughout playing a song, the audio is de-syncing even it was fine when the song started.
Cause: A mismatch of expected frame time by the game engine and actually delivered frame time by the
GPU driver. This can come either as a stable frame time that just mismatches in general or (highly)
fluctuating frame times.
Fluctuating frame times are likely to be caused by some configuration of the GPU driver
settings and display combination:
* G-sync on modern displays causes known fluctuations
* V-sync not correctly configured/enforced or even vsync-off override in driver
* Incorrect display timings causing refresh rate fluctuations
* Bugs/issues with display's firmware (possible though unlikely, check above items first)
Stable frame times but not having the correct ones that the game engine expects is a different
problem that can be addressed by:
* Knowing the refresh rates expected by the game engine of the different game versions
* Configuring your GPU driver's display timings to match the expected frame times
* Or, patch the game's chart data with your custom display timings so the game engine gets uses
*your* "correct" frame times
* Note: Offline patching the chart data doesn't work for several game versions as the monitor
check does override this data, but not as flexible as required
* Use the chart patch feature of bemanitools instead
### Micro-stuttering and non-smooth note scrolling
This is a trickier problem as it can be caused by a few different things.
* GPU/display related
* Fluctuating refresh rates result in fluctuating frame times in the main game loop
* GPU power configuration in non-performance mode (e.g. "power saving") causes processing latency
due to sleep states
* CPU related
* CPU power configuration on Windows in non-performance mode (e.g. "power saving") causes
processing latency due to sleep states
* Correct CPU C-states configuration in BIOS/UEFI
* These cannot be configured in Windows and are separate from Windows's power configuration
* Other stuff running in the background of the system causing fluctuations
* (Synchronous) Disk I/O heavy applications stealing CPU time
* Or any other process creating a considerable amount of CPU or GPU load
## Configuration guide for different game versions
### Measuring monitor refresh rate
Let's start with configuring the system to meet the game engine's expectation regarding the
target monitor refresh rate and requiring vsync.
First, use the [d3d9-monitor-check tool](../tools/d3d9-monitor-check.md) to measure the currently
configured refresh rate of your monitor. Note that your monitor might yield different timings on
different resolutions and different game versions run on
[different rendering resolutions](../dev/journal/2025-02-09-iidx-engine.md#rendering-resolutions).
For example, the game version is 31 with the rendering resolution of 1920x1080 in FHD mode that you
want to target:
```bat
d3d9-monitor-check.exe cmdline refresh-rate-test 1920 1080 60
```
The test shows the current monitor refresh rate and the average refresh rate over the course of
the test. Check that the avg. refresh rate is stable during the measuring phase (during warm-up,
it's ok if it fluctuates).
This test allows you to determine/check:
* Refresh rate/frame time fluctuations: if you see (high) fluctuations on the first or second
decimal place
* What's your current target refresh rate the GPU is driving your monitor at
* If vsync isn't overridden by some other driver setting as you want to see a refresh rate around
the 60 hz mark
### Measuring vsync issues
Some displays or the GPU configuration might lead to vsync issues which can be detected with the
`d3d9-monitor-check.exe` tool as well.
```bat
d3d9-monitor-check.exe cmdline vsync-test 1920 1080 60
```
This runs a test with a VSYNC text that alternates red and cyan colors. If the text appears grey
all the time, everything's fine. If you spot brief red or cyan text either occasionally or
periodically, your current configuration has vsync issues resulting in skipped frames or old
frames displaying longer.
### Configuration
The following are recommended configurations for the different game versions. If any of these
don't work as expected, you have to troubleshoot and tweak these potentially. Please refer to the
[guidelines above](#configuration-guide-for-different-game-versions) to understand how to use
the tooling and test your changes.
#### Recommended configuration with NVIDIA GPU and driver
We want to achieve the following configuration on the GPU driver:
* Turn-off g-sync if you have a monitor that supports it
* Disable power saving mode on GPU driver
* V-sync is not forced off
* Run the display on a target refresh rate of `59.950 hz` which has been determined to be
[the most compatible across all PC-based versions](../dev/journal/2025-02-09-iidx-engine.md#engine-step-time).
##### Turn-off g-sync
Create a new GPU profile for IIDX, if it doesn't exist yet:
```bat
nvgpu.exe profile create iidx
```
Add the application names when the profile needs to be applied:
```bat
:: For iidx versions 9 to 17
nvgpu.exe profile application-add iidx bm2dx.exe
:: For iidx versions 18+
nvgpu.exe profile application-add iidx launcher.exe
```
Disable G-SYNC for the profile:
```bat
nvgpu.exe profile gsync-disable iidx
```
##### Disable power saving mode
Set GPU power state to maximum for the profile (assumes you have a
[GPU profile called `iidx` already created](#turn-off-g-sync)):
```bat
nvgpu.exe profile gpu-power-state-max iidx
```
##### Configure and verify target refresh rate of 59.950 hz and vsync
Get display ID of your primary display:
```bat
nvgpu.exe display primary-display-id
```
Copy the hex-value of the display ID and use it in the following commands.
Test the custom display timing first, e.g. for versions that run in 1920x1080
(Replace `<DISPLAY_ID> ` with the primary display ID you got):
```bat
nvgpu.exe display custom-resolution-test <DISPLAY_ID> 1920 1080 59.95 10
```
This will test it for 10 seconds and then revert. If the result looked good, i.e. the screen didn't
go blank or the display output was garbage, apply it:
```bat
nvgpu.exe display custom-resolution-set <DISPLAY_ID> 1920 1080 59.95
```
Test and verify the configuration is applied and works correctly:
```bat
d3d9-monitor-check.exe cmdline refresh-rate-test 1920 1080 60
```
Test if the enforced refresh rate is compatible with your display and vsync is working correctly:
```bat
d3d9-monitor-check.exe cmdline vsync-test 1920 1080 60
```
##### Alternative refresh rate configuration
If for some reason your display doesn't support 59.950 hz properly, i.e. display artifacts or vsync
issues, you can use any other 60 hz compatible refresh rate, e.g. anything between 59.900 hz and
60.100 hz that your display supports properly.
Follow the same steps [as above](#configure-and-verify-target-refresh-rate-of-59950-hz-and-vsync)
but use a different refresh rate, e.g. 60.000 hz.
Verify using the `d3d9-monitor-check.exe` with the outlined steps if you need to play around to find
a refresh rate that works for your setup.
For the game versions 9 to 19, you have to use the chart patch feature of bemanitools to patch
the charts to your custom refresh rate. Otherwise, the game engine will run on your configured
refresh rate, but it will take the non-matching refresh rate from the chart data which causes
song de-syncing.
For example, to configure a refresh rate of 60.000 hz in the iidxhook config file:
```text
gfx.monitor_check=60.000
```
##### ATI/AMD
Currently, there is no tooling provided by bemanitools to configure the AMD GPU driver. The basic
concepts of what needs to be configured still applies as outlined in the NVIDIA sections above
though, e.g. through AMD's GPU control panel.
Further steps and instructions TBD
+4 -13
View File
@@ -146,16 +146,7 @@ This can be related to various issues:
start "" /relatime "gamestart.bat"
```
- Enforce v-sync enabled in your GPU settings.
- Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx) that is not
jumping around. Use the timebase feature of one of the newer games to check that or enable
iidxhook's timebase and check the log output for the determined value. Run this a few times and
check if the results differ.
- Use iidxhook's frame rate limiter feature (see further below) to software lock the refresh rate.
This might be necessary on Windows 7 and newer for D3D8 games, e.g. iidx 9 to 12, which seem to
ignore GPU side v-sync.
- Use iidxhook's auto timebase feature (see further below) or set a pre-determined value to cut down
start-up times.
Also refer to the [iidx-syncbook](iidx-syncbook.md).
### The game still stutters (randomly) and drifts off-sync
@@ -173,9 +164,7 @@ This can be caused by:
## My songs are offsync
- Make sure your machine's refresh rate is stable
- If you don't get a close to 59.94hz refresh rate, use the software monitor check/auto timebase
that's built into iidxhook (refer to help/config file)
Refer to the [iidx-syncbook](iidx-syncbook.md).
## The game crashes instantly (10th, RED, HAPPY SKY)
@@ -233,6 +222,8 @@ file) or use a CLVSD.ax codec which has the debugger checks removed.
## I used the auto timebase option and/or limited my refresh rate but the songs are still going offsync
Refer to the [iidx-syncbook](iidx-syncbook.md) if you haven't already.
There aren't many options left. The old games were developed for specific hardware and are not
guaranteed to work well on (especially) newer hardware. Multiple monitor setups can also have a bad
impact on a stable refresh rate. Try a setup with just a single monitor you want to use for gameplay
+4 -13
View File
@@ -115,16 +115,7 @@ This can be related to various issues:
start "" /relatime "gamestart.bat"
```
- Enforce v-sync enabled in your GPU settings.
- Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx) that is not
jumping around. Use the timebase feature of one of the newer games to check that or enable
iidxhook's timebase and check the log output for the determined value. Run this a few times and
check if the results differ.
- Use iidxhook's frame rate limiter feature (see further below) to software lock the refresh rate.
This might be necessary on Windows 7 and newer for D3D8 games, e.g. iidx 9 to 12, which seem to
ignore GPU side v-sync.
- Use iidxhook's auto timebase feature (see further below) or set a pre-determined value to cut down
start-up times.
Also refer to the [iidx-syncbook](iidx-syncbook.md).
### The game still stutters (randomly) and drifts off-sync
@@ -142,9 +133,7 @@ This can be caused by:
## My songs are offsync
- Make sure your machine's refresh rate is stable
- If you don't get a close to 59.94hz refresh rate, use the software monitor check/auto timebase
that's built into iidxhook (refer to help/config file)
Refer to the [iidx-syncbook](iidx-syncbook.md).
## The game crashes instantly
@@ -192,6 +181,8 @@ CLVSD.ax codec which has the debugger checks removed.
## I used the auto timebase option and/or limited my refresh rate but the songs are still going offsync
Refer to the [iidx-syncbook](iidx-syncbook.md) if you haven't already.
There aren't many options left. The old games were developed for specific hardware and are not
guaranteed to work well on (especially) newer hardware. Multiple monitor setups can also have a bad
impact on a stable refresh rate. Try a setup with just a single monitor you want to use for gameplay
+4 -19
View File
@@ -132,16 +132,7 @@ This can be related to various issues:
start "" /relatime "gamestart.bat"
```
- Enforce v-sync enabled in your GPU settings.
- Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx) that is not
jumping around. Use the timebase feature of one of the newer games to check that or enable
iidxhook's timebase and check the log output for the determined value. Run this a few times and
check if the results differ.
- Use iidxhook's frame rate limiter feature (see further below) to software lock the refresh rate.
This might be necessary on Windows 7 and newer for D3D8 games, e.g. iidx 9 to 12, which seem to
ignore GPU side v-sync.
- Use iidxhook's auto timebase feature (see further below) or set a pre-determined value to cut down
start-up times.
Also refer to the [iidx-syncbook](iidx-syncbook.md).
## "NETWORK WARNING" instead of "NETWORK OK"
@@ -154,15 +145,7 @@ This can be caused by:
## My songs are offsync
The built-in monitor check just determines if the game should sync to either 59.94 hz (S-Video
setting) or 60.04 hz (VGA setting). If you don't have a setup that runs on (as close as possible)
these values:
- Make sure your machine's refresh rate is stable, e.g. 60.00x hz.
- If you don't get a close to 59.94hz (S-Video setting) or 60.04 hz (VGA setting) refresh rate, go
an set the output mode in the operator menu to "VGA" to enforce the game to run chart syncing on
60.04 hz refresh rate (even if your setup does not have that value). Next, use the software
monitor check/auto timebase that's built into iidxhook (refer to cmd help/configfile).
Refer to the [iidx-syncbook](iidx-syncbook.md).
## My game runs too fast
@@ -205,6 +188,8 @@ CLVSD.ax codec which has the debugger checks removed.
## I used the auto timebase option and/or limited my refresh rate but the songs are still going offsync
Refer to the [iidx-syncbook](iidx-syncbook.md) if you haven't already.
There aren't many options left. The old games were developed for specific hardware and are not
guaranteed to work well on (especially) newer hardware. Multiple monitor setups can also have a bad
impact on a stable refresh rate. Try a setup with just a single monitor you want to use for gameplay
+4 -19
View File
@@ -143,16 +143,7 @@ This can be related to various issues:
start "" /relatime "gamestart.bat"
```
- Enforce v-sync enabled in your GPU settings.
- Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx) that is not
jumping around. Use the timebase feature of one of the newer games to check that or enable
iidxhook's timebase and check the log output for the determined value. Run this a few times and
check if the results differ.
- Use iidxhook's frame rate limiter feature (see further below) to software lock the refresh rate.
This might be necessary on Windows 7 and newer for D3D8 games, e.g. iidx 9 to 12, which seem to
ignore GPU side v-sync.
- Use iidxhook's auto timebase feature (see further below) or set a pre-determined value to cut down
start-up times.
Also refer to the [iidx-syncbook](iidx-syncbook.md).
## "NETWORK WARNING" instead of "NETWORK OK"
@@ -165,15 +156,7 @@ This can be caused by:
## My songs are offsync
The built-in monitor check just determines if the game should sync to either 59.94 hz (S-Video
setting) or 60.04 hz (VGA setting). If you don't have a setup that runs on (as close as possible)
these values:
- Make sure your machine's refresh rate is stable, e.g. 60.00x hz.
- If you don't get a close to 59.94hz (S-Video setting) or 60.04 hz (VGA setting) refresh rate, go
an set the output mode in the operator menu to "VGA" to enforce the game to run chart syncing on
60.04 hz refresh rate (even if your setup does not have that value). Next, use the software
monitor check/auto timebase that's built into iidxhook (refer to cmd help/configfile).
Refer to the [iidx-syncbook](iidx-syncbook.md).
## My game runs too fast
@@ -211,6 +194,8 @@ CLVSD.ax codec which has the debugger checks removed.
## I used the auto timebase option and/or limited my refresh rate but the songs are still going offsync
Refer to the [iidx-syncbook](iidx-syncbook.md) if you haven't already.
There aren't many options left. The old games were developed for specific hardware and are not
guaranteed to work well on (especially) newer hardware. Multiple monitor setups can also have a bad
impact on a stable refresh rate. Try a setup with just a single monitor you want to use for gameplay
+2 -15
View File
@@ -143,16 +143,7 @@ This can be related to various issues:
start "" /relatime "gamestart.bat"
```
- Enforce v-sync enabled in your GPU settings.
- Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx) that is not
jumping around. Use the timebase feature of one of the newer games to check that or enable
iidxhook's timebase and check the log output for the determined value. Run this a few times and
check if the results differ.
- Use iidxhook's frame rate limiter feature (see further below) to software lock the refresh rate.
This might be necessary on Windows 7 and newer for D3D8 games, e.g. iidx 9 to 12, which seem to
ignore GPU side v-sync.
- Use iidxhook's auto timebase feature (see further below) or set a pre-determined value to cut down
start-up times.
Also refer to the [iidx-syncbook](iidx-syncbook.md).
## "NETWORK WARNING" instead of "NETWORK OK"
@@ -165,11 +156,7 @@ This can be caused by:
## My songs are offsync
From this version onwards (if you use the very final data of Lincle), the game comes with a built-in
auto timebase option ("monitor check" on startup) which dynamically, detects the refresh rate of
your current setup. Thus, BT5's timebase option is not included from this hook version onwards,
anymore. Ensure that refresh rate displayed is very stable, e.g. 60.00x hz, and the game should be
able to provide you with a smooth and sync game experience.
Refer to the [iidx-syncbook](iidx-syncbook.md).
## My game runs too fast
+2 -10
View File
@@ -155,11 +155,7 @@ This can be related to various issues:
start "" /relatime "gamestart.bat"
```
- Enforce v-sync enabled in your GPU settings.
- Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx) that is not
jumping around. Use the timebase feature of one of the newer games to check that or enable
iidxhook's timebase and check the log output for the determined value. Run this a few times and
check if the results differ.
Also refer to the [iidx-syncbook](iidx-syncbook.md).
## "NETWORK WARNING" instead of "NETWORK OK"
@@ -172,11 +168,7 @@ This can be caused by:
## My songs are offsync
From this version onwards (or Lincle very final revision), the game comes with a built-in auto
timebase option ("monitor check" on startup) which dynamically, detects the refresh rate of your
current setup. Thus, BT5's timebase option is not included from this hook version onwards, anymore.
Ensure that refresh rate displayed is very stable, e.g. 60.00x hz, and the game should be able to
provide you with a smooth and sync game experience.
Refer to the [iidx-syncbook](iidx-syncbook.md).
## My game runs too fast
+2 -10
View File
@@ -159,11 +159,7 @@ This can be related to various issues:
start "" /relatime "gamestart.bat"
```
- Enforce v-sync enabled in your GPU settings.
- Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx) that is not
jumping around. Use the timebase feature of one of the newer games to check that or enable
iidxhook's timebase and check the log output for the determined value. Run this a few times and
check if the results differ.
Also refer to the [iidx-syncbook](iidx-syncbook.md).
## "NETWORK WARNING" instead of "NETWORK OK"
@@ -176,11 +172,7 @@ This can be caused by:
## My songs are offsync
From IIDX 20 (or Lincle very final revision) onwards, the game comes with a built-in auto timebase
option ("monitor check" on startup) which dynamically, detects the refresh rate of your current
setup. Thus, BT5's timebase option is not included from this hook version onwards, anymore. Ensure
that refresh rate displayed is very stable, e.g. 60.00x hz, and the game should be able to provide
you with a smooth and sync game experience.
Refer to the [iidx-syncbook](iidx-syncbook.md).
## My game runs too fast
+2 -10
View File
@@ -158,11 +158,7 @@ This can be related to various issues:
start "" /relatime "gamestart.bat"
```
- Enforce v-sync enabled in your GPU settings.
- Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx) that is not
jumping around. Use the timebase feature of one of the newer games to check that or enable
iidxhook's timebase and check the log output for the determined value. Run this a few times and
check if the results differ.
Also refer to the [iidx-syncbook](iidx-syncbook.md).
## "NETWORK WARNING" instead of "NETWORK OK"
@@ -175,11 +171,7 @@ This can be caused by:
## My songs are offsync
From IIDX 20 (or Lincle very final revision) onwards, the game comes with a built-in auto timebase
option ("monitor check" on startup) which dynamically, detects the refresh rate of your current
setup. Thus, BT5's timebase option is not included from this hook version onwards, anymore. Ensure
that refresh rate displayed is very stable, e.g. 60.00x hz, and the game should be able to provide
you with a smooth and sync game experience.
Refer to the [iidx-syncbook](iidx-syncbook.md).
## My game runs too fast
+2 -10
View File
@@ -205,11 +205,7 @@ This can be related to various issues:
start "" /relatime "gamestart.bat"
```
- Enforce v-sync enabled in your GPU settings.
- Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx) that is not
jumping around. Use the timebase feature of one of the newer games to check that or enable
iidxhook's timebase and check the log output for the determined value. Run this a few times and
check if the results differ.
Also refer to the [iidx-syncbook](iidx-syncbook.md).
## "NETWORK WARNING" instead of "NETWORK OK"
@@ -222,11 +218,7 @@ This can be caused by:
## My songs are offsync
From IIDX 20 (or Lincle very final revision) onwards, the game comes with a built-in auto timebase
option ("monitor check" on startup) which dynamically, detects the refresh rate of your current
setup. Thus, BT5's timebase option is not included from this hook version onwards, anymore. Ensure
that refresh rate displayed is very stable, e.g. 60.00x hz, and the game should be able to provide
you with a smooth and sync game experience.
Refer to the [iidx-syncbook](iidx-syncbook.md).
## My game runs too fast