Updated Known issues (markdown)

Known-issues.md

@@ -6,7 +6,7 @@
 > [!CAUTION]
 > If you have Rivatuner (RTSS) or MSI Afterburner, **fully** shut both of them down before running spice, otherwise your game may crash or hang, sometimes without any trace in the log.
 
-## General
+# General
  * When you open a log.txt, you'll want to reopen it with `SHIFT-JIS` encoding to properly show Japanese text. How you do this depend on your text editor.
  * Some anti-virus software may (incorrectly) flag the binaries as malware. If you have concerns, you are free to inspect the included source files and compile on your own.
  * Windows XP is unfortunately no longer supported - see [here](https://github.com/spice2x/spice2x.github.io/wiki/Compiling-spice2x#compiling-for-winxp) for details.
@@ -15,12 +15,12 @@
  * If game crashes with `(AcLayers): (unknown): NotifyShims` on the stack - this is an internal Windows component crashing. Unsure what the exact cause is, but try unchecking `Disable fullscreen optimizations` and other compatibility options in `Properties` dialog for `spice.exe` / `spice64.exe`. Seems to be affecting small number of Windows 11 users.
  * No support will be provided for Linux users running with WINE / proton; you're on your own. That being said, we are not against other developers working on getting things to work better in Linux. If there are any small tweaks to the code base that can be made to make it easier to run on Linux, please feel free to submit a patch.
 
-## Configurator (spicecfg)
+# Configurator (spicecfg)
  * If `spicecfg.exe` fails to launch or crashes, try running `spice.exe -cfg` or `spice64.exe -cfg`  in the command line instead of spicecfg, which launches the configurator but with logging enabled. It's not *exactly* the same environment as spicecfg, but it's close enough.
  * `spicecfg.exe` may fail to launch or be super slow to open while OBS is running. This is due to a bug in OBS that locks the Windows HID APIs. Try turning off OBS temporarily.
  * `spicecfg.exe` may fail to launch when run from a network share (UNC path).
 
-## Input
+# Input
  * Spice will always process keyboard / mouse / gamepad / touch input even if the game does not have focus, as it uses Windows raw input API to directly communicate with input devices for lowest latency.
  * If your keyboard has trouble with NKRO in spice (i.e., if you press too many buttons, some keys do not respond):
     * Try binding keys using the `Naive` button (do it for all keys)
@@ -31,7 +31,7 @@
     * Some input remappers will not work, depending on what method they use (which Windows API they use). In order for injected input to be recognized by spice, it must flow through Raw Input API. Some applications are unable to do that.
  * Windows 11: if your controller is not detected for some reason, reboot your PC with your controller plugged in. Seems to be some bug with raw input APIs in newer versions of Windows 11.
 
-## Graphics
+# Graphics
 
  * Almost all of the supported games are meant to run in exclusive full screen. Running in windowed mode is a hack done on per-game basis. Things may not work as expected in windowed mode. Namely:
     * Some multi-monitor games will fail to display more than one window.
@@ -47,14 +47,14 @@
  * Third party DirectX-reimplementations (e.g., dxvk, ForceD3D9On12) may occasionally cause crashes in the weirdest ways; if you encounter random crashes, please try running the game without them. No support will be provided for these.
  * Having NVIDIA RTX Voice (or other NVIDIA applications) open sometimes causes games to randomly crash in fullscreen.
 
-## Game-specific
+# Game-specific
 
-### Gitadora
+## Gitadora
 
  * Gitadora may seem like it's stuttering, notes not moving at a steady framerate - if you see this, turn off full screen optimizations for spice64.exe.
  * To troubleshoot MIDI drums, see [MIDI input](https://github.com/spice2x/spice2x.github.io/wiki/MIDI-Input) page.
 
-#### XG2 / XG3
+### XG2 / XG3
 
  * Getting UI background videos to work can be finicky. Hopefully, wherever you obtain the data, they also provided the right codec DLLs and told you how to register them; spice won't do that for you.
  * If you get SECURITY ERROR during boot, make sure the game code is set correctly. Even if it's slightly off, the game will refuse to boot.
@@ -63,7 +63,7 @@
     * XG3 Drum: L32 J:A:A or J:B:A
     * XG3 Guitar: L33 J:A:A or J:B:A
 
-### DDR
+## DDR
 
  * DDR is known to crash when you change window decoration (borderless window) - option has been disabled in the UI.
  * Game may crash if running in windowed mode & focus is taken away while the game is booting.
@@ -78,16 +78,16 @@
     * You must do this again if you move or rename your game directory.
     * You may need to *unregister* the DLLs when you want to run older DDR versions, as incompatibility across versions may lead to a crash. (`regsvr32 /u ...`)
 
-### SDVX
+## SDVX
 
-#### Booth
+### Booth
  * sdvx1 (BOOTH) has some audio issues ([Issue #186](https://github.com/spice2x/spice2x.github.io/issues/186)) and very minor graphical glitches on Windows10/11. Try Win7, or try btools as some claim it runs this better.
 
-#### II
+### II
 
 * If you see `F:afpu-heap: malloc failed size=428088.` then try increasing heap size with `-h 201326592`.
 
-#### HH
+### HH
  * If your game crashes with something like this:
 ```
 W:signal: exception raised: EXCEPTION_BREAKPOINT
@@ -98,10 +98,10 @@ I:stackwalker: 74664880 (libavs-win32): (unknown): XCd229cc000099
  * If your game crashes when you switch regions (changing `<spec>J</spec>` to A or K), it means you have the Japanese region data and therefore missing the region graphic files.
     * You'll likely see this message: `W:BM2D: CreateLayer() 指定したレイヤーは存在しません shutter2`
 
-#### VW
+### VW
  * If your game freezes after carding in, make sure `dx9on12` / `9on12` options are OFF. VW causes 9on12 layer to crash or hang during certain screen transitions.
 
-#### EG
+### EG
  * On laptops - especially ones with hybrid iGPU+dGPU configuration - seem to have a **lot** of trouble correctly launching recent EG versions. This includes: window launching on the wrong monitor, failing to launch at correct resolution and/or refresh rate, or just failing to launch completely. The main issue seems to be that the game uses Windows and NVIDIA APIs to determine monitor state, but ends up with wrong information on hybrid GPU configurations. There is no fix or workaround at the moment, other than playing in windowed mode (YMMV), or just switching to a desktop PC. [Issue 117](https://github.com/spice2x/spice2x.github.io/issues/117)
  * EG may launch at wrong refresh rate when using the auto-rotate option. If that happens, try specifying `-graphics-force-refresh` - and if that still doesn't work, try setting `-dx9on12` to DX12on9. Note that, depending on your GPU, 9on12 may result in poor performance - or maybe better performance, it depends.
  * For EG, running on AMD GPUs (to be precise, non-NVIDIA GPUs) will need a few workarounds, due to the game taking dependency on NVIDIA SDK:
@@ -116,7 +116,7 @@ I:stackwalker: 74664880 (libavs-win32): (unknown): XCd229cc000099
   * Game crashes with `W:BM2D: CreateLayer() 指定したレイヤーは存在しません <name of missing texture>`, and then later with `EXCEPTION_ACCESS_VIOLATION`.
     * You have bad / incomplete data. Usually, it means a texture file is missing. In some cases, it may be caused by mismatched DLLs as well.
 
-#### Server-side graphics settings (SUBMONITOR_VSYNC_ENABLE and USE_CUDA_VIDEO_PRESENTER)
+### Server-side graphics settings (SUBMONITOR_VSYNC_ENABLE and USE_CUDA_VIDEO_PRESENTER)
 
 As of early 2024, game DLLs started to check for `SUBMONITOR_VSYNC_ENABLE` and `USE_CUDA_VIDEO_PRESENTER` **server-side** flags. They get loaded when you card into the game. Since they are sent by the server to your game, they must be toggled on the EA server; ask your server operator about how to change them.
 
@@ -132,7 +132,7 @@ When you would need to toggle flag(s) :
   * If videos show up as black (menu themes or subscreen background videos) - try turning `USE_CUDA_VIDEO_PRESENTER` **off**. This is only a problem on AMD/Intel GPU; no issue with NVIDIA.  
   * If fullscreen runs at expected FPS (60 or 120) but windowed mode doesn't (weird FPS like 40 or 90) then try changing `SUBMONITOR_VSYNC_ENABLE` to see if it improves it.
 
-#### VM mode specific
+### VM mode specific
 
  * VM mode doesn't play nice with `-monitor` option. As a workaround, change the primary monitor before launching.
  * VM mode may fail to launch if you have 3 or more monitors connected. Disconnect them so that you only have 1 or 2 connected, or try using `SDVX Subscreen Disable` option.
@@ -141,13 +141,13 @@ When you would need to toggle flag(s) :
  * AMD GPUs may see a crash after certain battle modes, such as Single Battle (crash on top of d3d9on12 module). Not enough data to determine exact configuration that causes this issue.
  * If you see `F:GraphicUtility: Timeout AddLoadBuff` during boot, then disk I/O is timing out in the game due to slow disk read speed. Add folder exception in anti-virus and move to an SSD.
 
-#### Physical touchscreen for subscreen
+### Physical touchscreen for subscreen
 
  * Note that a touch screen is **not** required to play VM mode. In full screen mode, you can press Page Up (`Toggle Sub Screen` button) and use your mouse to click. Or you can play in windowed mode which will launch two windows.
  * See [this page](https://github.com/spice2x/spice2x.github.io/wiki/Configuring-touch-screens-as-subscreen) for instructions on how to set up your touch screen.
  * If the secondary monitor doesn't refresh (if graphics seem "stuck"), enable `-sdvxsubredraw`. Don't enable it if there are no issues.
 
-### IIDX
+## IIDX
 
  * For camera hook (enabling webcams in-game) you have a few options: 
     * IIDX 25-26: leave `-iidxdisablecams` off and see if it works - YMMV, unless you're using official cams you will likely have poor experience.
@@ -162,7 +162,7 @@ When you would need to toggle flag(s) :
  * On some GPUs, DX9on12 may crash iidx31+. Turn off `DX9on12` / `9on12` options on these versions of iidx. Your log will be spammed with `afputils: CTexture::set_texture_image テクスチャの取得に失敗` or `W:CTexture: no such texture: id` and the game will eventually crash.
  * iidx25 and above: if the game suddenly stopped launching on Windows 11 around Feb/March 2025, you may be running into [Issue 260](https://github.com/spice2x/spice2x.github.io/issues/260) caused by Windows Update. Update to build `spice2x-25-03-03` or newer which contains a workaround. As a side effect, `REVERB EX` filter will sound different from what it's like on Windows 10.
 
-#### LDJ specific
+### LDJ specific
 
 This section only applies to LDJ mode, and not to TDJ mode.
 
@@ -173,7 +173,7 @@ This section only applies to LDJ mode, and not to TDJ mode.
     * (IIDX31+) If you are in song select, it cannot be changed. It can only be changed during the song.
  * LDJ is meant to be run at 60Hz. While you *can* patch the game to run at 120Hz you *will* see minor issues like default offset being "incorrect".
 
-#### TDJ specific
+### TDJ specific
 
 This section only applies to TDJ mode, and not to LDJ mode.
 
@@ -183,7 +183,7 @@ This section only applies to TDJ mode, and not to LDJ mode.
  * TDJ mode may fail to launch if you have 3 or more monitors connected. Disconnect them so that you only have 1 or 2 connected, or use `IIDX TDJ Subscreen Disable (-iidxnosub)` option. Subscreen overlay will continue to work.
  * iidx28-29 may mysteriously crash during boot when using `-iidxtdj` option on 003 DLL. As a fix, enable `Lightning Mode camera crash fix for spicetools` patch, or just use 010 DLL.
 
-##### The following can happen if you have the wrong DLL type and you're using `-iidxtdj`:
+#### The following can happen if you have the wrong DLL type and you're using `-iidxtdj`:
  * Game shuts down immediately with no obvious crashes in the log
  * USB I/O Error on boot
  * Subscreen overlay is blank/transparent
@@ -192,13 +192,13 @@ This section only applies to TDJ mode, and not to LDJ mode.
 
 ... to fix this, get the right DLL type for TDJ, or ensure your game is patched correctly to "force TDJ mode".
 
-### Beatstream
+## Beatstream
 
  * Beatstream uses native Windows Touch APIs, but makes a lot of assumption about how often touch events are sent. If your touch screen doesn't poll enough, it'll end up with holds not working in the game (instead it will be flickering on and off). You can try using `Force Touch Emulation (-touchemuforce)` option to work around it.
  * Game crashes if it loses window focus during boot. Keep the window at the front while the game is booting.
  * You may need to press Insert Card a few times for the card to be recognized ([Issue #219](https://github.com/spice2x/spice2x.github.io/issues/219)).
 
-### Nostalgia
+## Nostalgia
 
  * Same touch polling issue may be present in Nostalgia - see Beatstream section for a workaround. Fortunately, since you only need to navigate menus with the touch screen, you can just use a mouse instead.
  * Nostalgia is picky about audio. If you see the boot screen trying to initialize audio & eventually the window automatically closing, try a different audio device. Onboard Realtek device usually works.
@@ -207,7 +207,7 @@ This section only applies to TDJ mode, and not to LDJ mode.
  * Piano keys used for Nostalgia are velocity-sensitive. If you have velocity-sensitive MIDI piano, [read this section](https://github.com/spice2x/spice2x.github.io/wiki/MIDI-Input#nostalgia-key-binding). If you are using anything else, bind your buttons to `Key n Medium` so that every press registers as a medium press, which counts as both soft and hard press.
  * Game may crash if you touch a touch screen while it's booting up.
 
-### Reflec Beat
+## Reflec Beat
 
  * RB cabinets use high-frequency polling of IR sensor grid. Which means:
     * You may see phantom touches! If you use two fingers to touch [X1, Y1] and [X2, Y2], game will also register a touch at [X1, Y2] and [X2, Y1]. This is an issue on real cabs too, you just gotta live with it; it's a limitation of IR sensor grid technology.
@@ -218,7 +218,7 @@ This section only applies to TDJ mode, and not to LDJ mode.
  * When launched in windowed mode, the game must stay in borderless & fixed on top left corner of the primary monitor in order for touch emulation to work correctly. This is really only meant for debugging (with a mouse). For best experience, connect a touch screen and play in full screen mode.
  * Game crashes if it loses window focus during boot. Keep the window at the front while the game is booting.
 
-### Jubeat
+## Jubeat
 
  * Jubeat is unique in that it's the only OpenGL game.
     * Therefore, many of the graphics options simply do not work, including but not limited to: screenshots, window options, image scaling, streaming to Companion, etc.
@@ -229,21 +229,21 @@ This section only applies to TDJ mode, and not to LDJ mode.
         1. If playing on touch screen, move task bar to the top of screen
         1. Set task bar to auto-hide
 
-### Popn
+## Popn
  * pop'n 19 Tune Street; when HD mode is enabled, it may crash on title screen with `CommReadMyAddr` / `CommPolling` on the stack. This is caused by dirty / incomplete data that is widely distributed.
  * pop'n may appear to hang immediately after launching (either stuck on black screen, or "not responding" popup from Windows). This may be caused by slow disk I/O when the game tries to access NVRAM. Try waiting a few minutes and see if the game eventually boots. To speed this up, move to an SSD, and add an exception to any anti-virus scanners.
  * Some older popn games may boot into a cyan boot screen with white text (instead of black background with white text). Normally, this should only happen on boot screen, and should go back to normal colors when the game boots to the title screen. 
 
-### HELLO! pop'n music
+## HELLO! pop'n music
  * Game may crash if it loses focus during initialization. Let the game fully initialize and don't click away to another window.
  * Hello! pop'n music may boot into a cyan boot screen with white text (instead of black background with white text). Normally, this should only happen on boot screen, and should go back to normal colors when the game boots to the title screen. 
  * Hello! pop'n music may completely freeze during boot up sequence on AMD Ryzen processors. Root cause is unknown and it has not been debugged yet. [#87](https://github.com/spice2x/spice2x.github.io/issues/87)
 
-### Silent Scope: Bone Eater 
+## Silent Scope: Bone Eater 
 
  * Implementation is incomplete. It boots to test menu, but fails I/O check and does not boot to title screen. Serial I/O needs work. [Issue 114](https://github.com/spice2x/spice2x.github.io/issues/114)
 
-### Busou Shinki: Armored Princess Battle Conductor
+## Busou Shinki: Armored Princess Battle Conductor
 
  * Busou Shinki is based on Unity. See [section on Unity Games](#Unity-based-Games) for various limitations.
  * If you get a camera error, either plug in three compatible webcams, or get patched DLLs.
@@ -251,35 +251,35 @@ This section only applies to TDJ mode, and not to LDJ mode.
  * `Insert` key is a hardcoded debug key bound to Test button - bind a different key to insert coins.
  * WASD keys are hardcoded to be directional input.
 
-### Chase Chase Jokers
+## Chase Chase Jokers
 
  * Local EA server does not work for CCJ; it has been explicitly disabled.
  * CCJ is based on Unity. See [section on Unity Games](#Unity-based-Games) for various limitations.
  * Pressing Delete key occasionally breaks the game and causes I/O to stop working (seems to be a debug option). Recommended that you bind test button to some other key, or use a controller.
 
-### Otoca Doll
+## Otoca Doll
 
  * If you get a camera error, disable / unplug all webcams on your PC, including any VR headsets.
 
-### Scotto
+## Scotto
 
  * Bad data is commonly distributed that causes boot failure. Double check contents of eacoin.xml in `dev/nvram`.
  * Overlay doesn't work.
 
-### Museca
+## Museca
 
  * Do not run the game in windowed mode. It'll freeze / hang / lock up at random times. Run the game full screen in portrait orientation, 720x1280. If it persists, try disabling Full Screen Optimizations for it as well, so that you use Full Screen Exclusive.
 
-### FutureTomTom
+## FutureTomTom
 
  * You need to install Kinect v1.x SDK, Kinect Developer Tools, and DirectX SDK, otherwise the game will fail to launch with DLL load error.
  * Kinect v1 hardware (Xbox 360 Kinect or Kinect for Windows, not Xbox One Kinect, not Azure Kinect) is needed for the game to be fully playable with video feed and motion sensing; however, it is not required.
 
-### Winning Eleven 2012
+## Winning Eleven 2012
 
  * Path to the game must contain `KCK-001`; keep the folder name as-is (e.g., `KCK-001-2013040101`).
 
-## Unity-based Games
+# Unity-based Games
 
 Spicetools was never designed to provide support for games based on the Unity engine. While few games are supported, many basic functionalities may be missing compared to support for other games.
 
@@ -294,7 +294,7 @@ Spicetools was never designed to provide support for games based on the Unity en
  * These games will try to hide the cursor by default, but spice will override this to show the cursor if no touch screen is connected. If you want to forcibly show the cursor, use `Show Cursor (-s)` option.
  * Videos not playing (such as opening movie on attract screen) - see [Issue #250](https://github.com/spice2x/spice2x.github.io/issues/250).
 
-## SpiceCompanion
+# SpiceCompanion
 
 Note that SpiceCompanion apps are not part of the spice2x project (not forked). Unfortunately, they are also not being updated.
  
@@ -302,14 +302,14 @@ Note that SpiceCompanion apps are not part of the spice2x project (not forked).
  * On Windows and Android apps, multi-touch does not seem to work properly.
  * As of 2025, the iOS app has been delisted from the App Store.
 
-## Touch
+# Touch
 
  * `Always Show Cursor (-s)` option force enables WinTouch hooks. This is usually **not** what you want if you're using a touch screen, so leave it off.
  * In some rare cases, the overlay may interfere with touch input. Toggle it off, or use `Disable Spice Overlay (-overlaydisable)`.
 
-## Physical NFC Card Readers
+# Physical NFC Card Readers
 
-### HID SmartCard (ACR122U)
+## HID SmartCard (ACR122U)
 
 > [!WARNING]  
 > ACR112U card readers are no longer recommended to purchase. Official product was discontinued years ago, and many cheap Chinese clones on Amazon and Alibaba are unable to properly read FeliCa cards.
@@ -325,7 +325,7 @@ As mentioned above, many clones of ACR112U fail to properly read FeliCa cards. W
 
 Instead of trying to find a good ACR112U unit, you may instead want to look into DIY solutions based on cardIO HID protocol: https://rhythm-cons.wiki/other-hardware/card-readers/
 
-#### Card format conversion for ACR122U readers
+### Card format conversion for ACR122U readers
 
 There are two types of valid cards:
 
@@ -336,7 +336,7 @@ If you want to use invalid cards, such as MiFare cards, use `-scardfix fix` to c
 
 Really old games do not support FeliCa card numbers, instead they expect all card numbers to begin with E004. If you want to use your FeliCa cards with these old games, use `-scardfix all` to have spice automatically convert your new cards into the old format by prefixing with E004 (and chopping off a few digits at the end).
 
-## Other issues
+# Other issues
 
  * For more, please see the GitHub [issue tracker](https://github.com/spice2x/spice2x.github.io/issues).
  * Builds of spice2x `24-11-20` and older ship with ifs_layeredfs built in, but it's an old and slightly broken version. As of `24-12-06`, the built-in plugin is completely removed.