# Debugging Linux Games

> Use when a Steam, Proton, Wine, Lutris, or Heroic game misbehaves on Linux — crashes at launch, black screen, missing DLSS / Ray Tracing / Path Tracing / DLSS-RR / Frame Generation, anti-cheat failures, shader stutter, controller or HDR or Wayland-fullscreen problems, intro-video failures ("Failed to create SourceReader", MF_E_UNEXPECTED), NVAPI "Unknown function ID" log spam, gamescope dedup black-screens, vkd3d swapchain crashes. Especially before patching or forking DXVK, vkd3d-proton, dxvk-nvapi, gamescope, Wine, or Proton; before reading RE Engine, Unreal, Unity, Source 2, id Tech, or Decima logs; or when a game is mentioned with NVIDIA Blackwell, NixOS, niri, gamescope, proton-cachyos, GE-Proton, or proton-tkg. Triggers on phrases like "won't launch", "RT/PT grayed out", "Proton fix for", "/WineDetectionEnabled", "ProtonDB", "VKD3D_CONFIG", "PROTON_USE_WAYLAND", or any moment the impulse is "let me read the Proton/Wine/vkd3d source" before checking community fixes.

- Skill: `joshsymonds/debugging-linux-games` (Agent Skill)
- Install (CLI): `npx skillmds@latest add joshsymonds/debugging-linux-games`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joshsymonds/debugging-linux-games/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: joshsymonds (https://skillmd.com/u/joshsymonds)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/joshsymonds/debugging-linux-games

---


# Debugging Linux Games (Research-First)

## Overview

Steam-on-Linux problems almost always have a documented community fix. The
documented fix is usually a game launch option, an env var, a config tweak,
or a known proton-ge / proton-cachyos release with a workaround baked in —
NOT a patch to dxvk-nvapi or vkd3d-proton. Diving into shim code without
checking first is how 10 hours get spent producing patches that the actual
fix renders unnecessary.

**Core principle:** Community research first. Code second. Always.

**Iron Law:** NO patches, forks, overlays, postFixup drops, or any code
changes to the Wine/Proton/DXVK/vkd3d/gamescope stack until the six-source
research checklist below has been completed within a 30-minute time-box.
If a launch option, env var, config flag, or proton-ge build already
solves the problem, that's the answer — even if reading the source feels
more satisfying. No exceptions.

**Announce at start:** "I'm using debugging-linux-games to research before
touching code."

## Rigidity Level

LOW FREEDOM — The research phase is mandatory. The 30-minute time-box is
mandatory. The "no shims until research is done" gate is mandatory.

## The Six-Source Checklist

Time-box: 30 minutes. Stop earlier if a documented fix matches the symptom.

| # | Source | What you're looking for |
|---|--------|-------------------------|
| 1 | **ProtonDB** (`protondb.com/app/<id>`) | Working launch options, known issues, Proton version that works |
| 2 | **Steam Community discussions** for the app, Linux/Wine/Proton tags | Fix threads from devs or users — this is where `/WineDetectionEnabled:False` for PRAGMATA was found |
| 3 | **Game-specific subreddits + r/linux_gaming** | Recent threads naming the title |
| 4 | **GitHub issues** across `ValveSoftware/Proton`, `HansKristian-Work/vkd3d-proton`, `doitsujin/dxvk`, `jp7677/dxvk-nvapi`, `ValveSoftware/gamescope` | Engine-specific bugs and merged workarounds; check both open AND closed |
| 5 | **GE-Proton + proton-cachyos release notes** | Per-release "added fix for X" entries with env vars |
| 6 | **PCGamingWiki Linux section** for the title | Engine-level fixes, "Wayland-broken" / "needs DXVK_CONFIG" notes |

For RE Engine / Capcom titles specifically: check whether
`/WineDetectionEnabled:False` is documented as a launch option — Capcom's
RE Engine games (MH Wilds, PRAGMATA, RE4R, DD2) gate RT/PT/DLSS-RR behind
an internal Wine detection check.

## The Process

### Phase 1: Identify Game + Engine + Stack

Before searching, gather:
- **Game title + Steam app ID** (the app ID makes ProtonDB / Steam community search precise)
- **Engine** (RE Engine, Unreal 4/5, Unity, Source 2, etc.) — engines tend to share fixes
- **Stack** (proton version, GPU vendor + arch, compositor, gamescope yes/no, kernel)
- **Exact symptom** (full error text or screenshot, not paraphrased)
- **What the user already tried**

For NixOS + proton-cachyos + Blackwell + niri specifically: most "X is
broken in gamescope" reports translate to "use `PROTON_USE_WAYLAND=1` and
skip gamescope, then check the title-specific fix."

### Phase 2: Six-Source Research (30 min, time-boxed)

Dispatch parallel research:

```
Agent (general-purpose, parallel × 2)
  description: "ProtonDB + Steam community search for <title>"
  prompt: |
    Find the working Linux/Proton configuration for <title> (Steam app
    ID <id>). Check:
    - protondb.com/app/<id> — top reports, recommended proton version,
      launch options listed
    - steamcommunity.com/app/<id>/discussions — filter for Linux/Wine/Proton
    - r/linux_gaming and the game's subreddit
    Report: (a) launch options that consistently work, (b) known issues
    list with workarounds, (c) any "do not use gamescope" or "use proton-ge
    X.Y" notes. Under 300 words.

Agent (general-purpose, parallel × 2)
  description: "GitHub issues + PCGamingWiki for <title>/<engine>"
  prompt: |
    Search:
    - github.com/ValveSoftware/Proton issues (open + closed) for "<title>"
      and "<engine>"
    - HansKristian-Work/vkd3d-proton, doitsujin/dxvk, jp7677/dxvk-nvapi
      issues for the same
    - ValveSoftware/gamescope for engine-specific compat issues
    - GE-Proton release notes for added fixes naming the game
    - PCGamingWiki <title> page, Linux section
    Report: (a) issue numbers + status, (b) any env var or
    VKD3D_CONFIG/DXVK_HUD workaround, (c) which proton version landed
    a fix. Under 300 words.
```

While agents run, optionally inspect the local proton log
(`PROTON_LOG=1` writes to `~/steam-<id>.log`) for OBVIOUS errors. **Don't
form a theory yet** — the research output reframes log lines.

### Phase 3: Apply the Documented Fix

If research found a fix:

1. Apply it (launch option in Steam, env var in launch options, etc.)
2. Test it
3. If it works: DONE. Stop. Do not also "fix" the underlying shim.
4. If the fix is wired through nix-config (e.g., add it to
   `pkgs/proton-gamescope/run.sh` as a default), make the minimal change
   and commit with a comment citing the source thread / issue.

### Phase 4: Only If Research Is Empty — Then Diagnose

Only after all six sources have been checked AND no documented fix
exists, escalate to code-level diagnosis:

1. Reproduce with `PROTON_LOG=1`
2. Bisect the stack: try `PROTON_USE_WAYLAND=0/1`, `gamescope on/off`,
   different proton builds (proton-cachyos vs GE-Proton vs experimental)
3. Form a hypothesis WITH EVIDENCE from logs
4. Verify the hypothesis in the source before patching

If you reach this phase, hand off to `gambit:brainstorming` with the bug
report and research notes attached. Its research step dispatches the scout for
the reproduction command and root cause.

## Critical Rules

### Rules That Have No Exceptions

1. **No shim patches before research** — Research takes 30 minutes; patches take days.
2. **The user wanting "the technical answer" is not permission to skip research** — Confident technical briefs about NVAPI IDs / vkd3d swapchain races / NGX queries are exactly the trap this skill exists to prevent.
3. **If the fix is `/some-cli-flag` or `PROTON_FOO=1`, that's the fix** — Don't also patch the underlying behavior. Game ships with a launch option for a reason.
4. **A "confident technical brief" is evidence of a trap, not evidence of correctness** — When training data confidently names internal function IDs, structure fields, or closed-source behavior, treat that as a flag to check community sources HARDER, not as a green light to start patching.
5. **30-minute research time-box is a floor, not a ceiling** — If 30 minutes turns up nothing, that's signal this might genuinely be a new bug; document and proceed to Phase 4. But don't shortcut research because "I bet it's the swapchain."

### Common Excuses

All mean: **STOP. Do the research first.**

| Excuse | Reality |
|--------|---------|
| "I can see from the log it's a vkd3d swapchain race" | Logs after research land differently than logs before research |
| "ProtonDB users don't have this specific Blackwell setup" | Issues from any GPU often share a fix; check anyway |
| "The fix is obvious — let me just patch the shim" | "Obvious" is exactly the bias this skill exists to counter |
| "We already have a fork — just bump it" | If the fork was unnecessary in the first place, bumping it perpetuates the mistake |
| "Community research is slow for niche games" | 30 minutes upper bound. If it's truly niche, you'll know fast |
| "The user is technical and wants the deep answer" | The deep answer is often "the game ships with a CLI flag for this" |

## Reference: PRAGMATA Anti-Pattern

This skill exists because PRAGMATA (Steam app 3357650) was debugged for
~10 hours and produced 4 fork patches:

- `dxvk-nvapi-josh`: 5 Blackwell/Streamline NVAPI ID stubs + CUDA SM fix
- `vkd3d-proton-josh`: 0×0 ResizeBuffers refusal + maxImageExtent bail-out
- `gamescope-patches/win-is-useless-respect-content-override`
- `gamescope-patches/scale-by-buffer-when-x11-geom-smaller`

Every patch addressed a real bug — but none of them gated the user's goal
(RT/PT/DLSS-RR enablement). The actual fix was:

- `PROTON_USE_WAYLAND=1` (skip the X11 path that motivated the gamescope patches)
- `PROTON_DLSS_UPGRADE=1` + don't hide NVIDIA GPU
- `/WineDetectionEnabled:False` as a game launch option

All three were findable in 15 minutes via this skill's checklist. None
were inventable from first principles.

The forks were removed in `nix-config` commit 6251c4c. The branches are
preserved on GitHub for historical reference. Do not repeat this pattern.

## Verification Checklist

Before reporting a "fix" or making any code change to the Wine/Proton stack:

- [ ] Game title + Steam app ID identified
- [ ] Engine identified
- [ ] All six sources checked (or time-box elapsed)
- [ ] Documented fix from community: APPLIED + VERIFIED, or NONE FOUND
- [ ] If applying a documented fix: minimal change, commit references the source
- [ ] If no documented fix: handed off to `gambit:brainstorming` with the bug report and research notes attached, for its research step to dispatch the scout for the reproduction command and root cause

**Can't check all boxes?** Return to Phase 2.

## Integration

**This skill calls:**
- Two parallel `general-purpose` research agents (Phase 2)
- `gambit:brainstorming` (Phase 4, only if research is empty; pass the bug report and research notes so its research step can dispatch the scout for the reproduction command and root cause)

**Called by:**
- User reports a Steam game on Linux broken
- Before any commit that touches a Wine/Proton stack package
- Before opening a fork of any Wine/Proton/DXVK/vkd3d/gamescope project