Nearcade v3.0.8 | The "System Doctor" Update

Nearcade v3.0.8 — The "System Doctor" Update

This release is a stability and diagnostics-first patch. It introduces the System Doctor preflight engine, fixes a critical Windows capture regression on hybrid GPU laptops that has been present since 3.0.1, ships the Open Remote Play sidecar daemon as a redistributable binary-as-an-SDK, and lays architectural groundwork for cross-platform modality decoupling.

---

🔧 Critical Fixes

Windows Screen Capture — Hybrid GPU Regression (fixes 3.0.1–3.0.7)

Affected hardware: Laptops with both an Intel iGPU and a discrete NVIDIA or AMD GPU where the display output is routed through the dGPU (the most common gaming laptop configuration).

Since 3.0.1, every capture path on these machines — window selection, DXGI full-screen, WinRT, and the legacy VM fallback — returned Could not start video source. The root cause was Nearcade unconditionally forcing Chromium onto a specific GPU adapter at startup, while Windows DXGI Desktop Duplication is an OS-level API that requires the capturing process to run on the same adapter that drives the display output. Forcing the wrong adapter returns DXGI_ERROR_UNSUPPORTED with no recoverable fallback.

NearsecTogether 3.0.0 (the working baseline) set no GPU adapter flags and capture succeeded. That behavior is now restored on Windows:

• Removed --force-high-performance-gpu on Windows (was incorrectly applied to all platforms)
• Removed --disable-gpu-driver-bug-workarounds on Windows (was absent in the working 3.0.0 build; suppresses workarounds hybrid GPU setups rely on)
• Added --use-angle=d3d11 for Windows only — this is safe (it selects the ANGLE rendering backend, not a GPU adapter) and consistent with what Chromium recommends for D3D11 contexts

The OS now selects whichever adapter owns the display output, which is what DXGI requires. No user action is needed — the fix is automatic.

Validation target: CornObjects (Nearcade Discord) — Intel UHD 0x468B + NVIDIA discrete, display on dGPU. NT 3.0.0 worked on this machine; 3.0.1–3.0.7 broke it. This build should restore capture.

---

🩺 System Doctor — Preflight Diagnostic Engine

A new host-side diagnostic tool that audits your system before streaming. Run it from the CLI, trigger it from the dashboard, or query it from the REST API.

What it checks:

Subsystem	Checks
Input	evdev permissions, uinput access, kernel module state
Display	Compositor detection (Wayland/X11/Gamescope), display server state
Audio	PulseAudio / PipeWire daemon, virtual sink presence
Encoder / GPU	DRM render node access, VA-API slice encoding, NVIDIA driver + UVM, Windows GPU adapter class
Network	LAN IP (excluding Docker/VPN virtual interfaces), STUN UDP reachability, port availability
System	open file descriptor limits, kernel version

How to use it:

# CLI
npm run doctor

# REST API (while Nearcade server is running)
GET  /api/system-doctor           # full cached report
POST /api/system-doctor/refresh   # force re-run all probes

The dashboard also surfaces a diagnostic modal with per-check status, colour-coded severity, and copy-pasteable remediation commands. The doctor states findings only — it never modifies your system.

---

🖥️ Windows GPU Adapter Classification

At startup on Windows, Nearcade now queries Electron's GPU info after the app is ready and classifies your GPU topology. This is used by the System Doctor and logged to the startup console for diagnostics.

GPU Class	Description	Capture	Encode
Discrete (dGPU)	NVIDIA or AMD dedicated GPU, no iGPU	✅ Optimal	✅ NVENC / AMF
Hybrid	iGPU + dGPU — OS now picks the display adapter automatically	✅ Fixed in this release	✅ dGPU encoder
Integrated (iGPU)	Single integrated GPU, no discrete partner	✅ Works	✅ QuickSync / VCE
APU	AMD/Intel CPU-integrated graphics, no discrete GPU	✅ Works	⚠️ Throughput limited
None active	All adapters report inactive (driver/config failure)	❌ DXGI fails	❌

APU note: If you're on an APU (e.g. Ryzen 5 5600G, Intel Core Ultra without a dGPU), capture works fine but the same silicon handles game rendering and video encoding at the same time. Under high load this can cause encoder frame drops. The System Doctor will flag this with a warning and suggest lowering resolution or bitrate. An external discrete GPU resolves this entirely.

---

📡 Open Remote Play (ORP) — Binary SDK & Modality Decoupling

Sidecar Daemon (bin/orp-daemon.mjs)

ORP can now run as a standalone binary that any client communicates with over a local JSON-lines socket. This means:

• Game engines (Godot, Unity) can integrate ORP without shipping a Node.js runtime
• Non-JavaScript clients can speak ORP via a simple line-delimited JSON protocol
• The binary self-updates as the ORP spec evolves — integrators just ship the binary and talk to it

Example clients are included for Python, Godot GDScript, and Unity C#.

Modality Decoupling

The host and viewer now negotiate which features are actually present rather than assuming a fixed capability set. Modalities are declared per-session and respected throughout the pipeline:

• video — screen/window capture stream
• audio — host audio loopback
• input — keyboard, mouse, gamepad relay
• voice — bidirectional voice chat

If a client or host is missing a modality (no mic, no gamepad, etc.), the session continues gracefully for the modalities that are present. Neither side enforces features the other doesn't support.

Tolerant Reader Standard

ORP implementations are required to ignore unknown fields rather than reject messages. This means older clients remain compatible when new fields are added to the spec, and newer clients can communicate with older hosts. Conformance tests enforce this.

---

🛠 Architecture

• src/scripts/core/ — System Doctor and supporting engine modules now live here, separated from the extended feature scripts
• Sanitized LAN IP detection — Virtual interfaces (Docker bridges, Tailscale, WireGuard, VPN tunnels, vEthernet) are excluded from the displayed host IP so users don't accidentally share an unreachable virtual address
• Display sleep blocker — The host OS display sleep timer is now suppressed while Nearcade is running, preventing capture interruption mid-session
• ORP JSON schemas + conformance suite — tools/open-remote-play/ ships with a full schema registry and 52 conformance tests covering announce, offer, answer, candidate, input, and modality negotiation message types
• Config v4 Migration & Recovery — Automatically resets legacy 3.0.7 Windows configs that had forced "gpuPreference": "integrated", "zeroCopy": true, "fpsUnlock": true, and "vsyncOff": true back to safe defaults (auto for GPU preference, false for zeroCopy/optimizations).
• GPU Preference Control in Settings — Dashboard settings now includes a dedicated GPU selector with live hardware controller polling (↻) and an in-app restart prompt.
• Handheld Layout Synchronization Fix — Resolved an issue where selecting default layout mode could still launch into handheld mode on Steam Deck / Gamescope environments due to lingering session state.
• Host Session Chat Layering Fix — Adjusted the controller prompt bar positioning and z-indexing in src/pages/host.html so input prompts never obscure the Session Chat.
• UI Hover Outlines Normalized — Eliminated double outlines across all buttons, cards, settings, and modal controls caused by synthetic spatial-hover classes executing during physical mouse events and outline-offset stacking.
• zrok v2 Share Lifecycle & Reaper Fix — Fixed share deletion command (zrok2 delete share <token>) and reaper epoch timestamp parsing, resolving account share quota saturation ([401] shareUnauthorized).

---

Known Limitations / Testing Needed

• The hybrid GPU capture fix has been validated by log analysis against the 3.0.0/3.0.7 regression but requires confirmation on affected hardware (CornObjects' machine is the primary test target)
• APU streaming performance under high-resolution game load is not yet benchmarked — default settings are conservative
• WinRT screen capture (WinrtScreenCapture feature flag) remains enabled as a fallback path and may behave differently across Windows versions

---

Nearcade v3.0.8 Release