Skip to content

stubs.md

Latest commit

 

History

History
120 lines (79 loc) · 3.83 KB

stubs.md

File metadata and controls

120 lines (79 loc) · 3.83 KB
Raw

API Stubs

Some Windows games delay-load system DLLs that Wine/GPTK does not provide. Instead of crashing with a module-not-found exception at startup, the game can be given a minimal stub DLL that exports the expected symbols and returns a safe error code, allowing the game to fall back gracefully.

gptk-stubs automates building and installing these stubs.

Why This Is Needed

Windows PE executables can list DLLs in two ways:

  • Static imports (Data Directory entry 1): loaded at process start; a missing DLL is a hard failure.
  • Delay-load imports (Data Directory entry 13): loaded on first call; a missing DLL raises exception 0xc06d007e (module not found) at that call site.

Wine silently ignores delay-load entries it cannot satisfy until the game actually calls into them. At that point, if the DLL is absent, the exception propagates up and crashes the process — often before any window appears, making it look like the game refuses to start.

The fix is a stub DLL that:

  1. Exports the expected function at the expected ordinal.
  2. Returns HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) (0x80070032) so the caller detects the feature is unavailable and skips it rather than crashing.

Known Stubs

GameInput.dll

Affected games: God of War: Ragnarök, and any title using Microsoft's GameInput API.

Crash symptom: process exits immediately with exception 0xc06d007e; no window appears; Wine log shows DelayLoadFailureHook or nothing at all before the crash.

Exported symbol: GameInputCreate at ordinal 1.

Source: stubs/gameinput.c, stubs/gameinput.def

Using gptk-stubs

Prerequisites

None for normal use. A prebuilt GameInput.dll (this project's own binary) ships with the toolkit, so gptk-stubs installs it without a compiler.

Only rebuilding from source — gptk-stubs --force-build — needs the mingw-w64 cross-compiler:

brew install mingw-w64

Install into one prefix

gptk-stubs --prefix GOWR

Install into every existing prefix

gptk-stubs --all

Archived prefixes ending in .broken-*, .backup-*, .old-*, or .disabled-* are skipped.

Build and cache without installing

gptk-stubs --build-only

The compiled GameInput.dll is cached at $GPTK_HOME/stubs/GameInput.dll and reused on subsequent runs.

Force a rebuild

gptk-stubs --force-build --prefix GOWR

Override the cache directory

RIPPERMOON_STUBS_DIR=/path/to/cache gptk-stubs --prefix GOWR

Manual Installation

If you prefer to install the stub without the script:

# Build
x86_64-w64-mingw32-gcc -nostdlib -shared \
  -o GameInput.dll \
  stubs/gameinput.c stubs/gameinput.def \
  -lkernel32

# Install
cp GameInput.dll ~/WinePrefixes/GOWR/drive_c/windows/system32/GameInput.dll

Then add WINEDLLOVERRIDES='GameInput=n' to the launch command so Wine uses the native (your stub) version rather than looking for a builtin.

Launch Command

After installing the stub, include WINEDLLOVERRIDES='GameInput=n' in the launch environment:

cd "$GPTK_EXTERNAL_ROOT/Games/GoWR"
env GPTK_WINE_HOME="$GPTK_HOME/runners/gptk-dsound-nocap-20260513" \
    WINEDLLOVERRIDES='GameInput=n' \
  gptk-launch --prefix GOWR --set-winver win10 \
    --no-dxr --avx --metalfx \
    --log-file "$GPTK_HOME/logs/gowr-launch.log" \
    -- ./GoWR.exe \
      -dxSkipDriverVersionCheck -disableNvStreamline \
      -disablePSPCSteam -novalidation

See examples/gowr-launch.zsh.example for the full self-contained example.

Adding a New Stub

  1. Create stubs/NEWDLL.c with the stub implementation.
  2. Create stubs/NEWDLL.def listing the exports.
  3. Update bin/gptk-stubs to build and install it (follow the gameinput pattern).
  4. Document it in this file under Known Stubs.