Standalone setup #

This repository is a Witcher 3 development tool, independent of any combat-model project. The qualified native installation is Remastered 5.01, DX12, on Linux with Steam/Proton and KDE KWin. Python help and evidence tooling work without a running game. Native control requires the matching installed bridge and receipts.

Existing host #

The original checkout is ~/witcher3-devkit; ~/.local/bin/w3dev points to its launcher. Upgraded worktrees can share its installation after the explicit state migration below. Migration does not reinstall or deploy game files:

w3dev guide setup
w3dev doctor
w3dev verify
w3dev guide debugger
w3dev commands --json

These commands do not launch or contact the game. Use debug open when ready to launch with automatic lab settings; debug close performs the normal restoration. Read the debugger guide before recovery or resuming a previous session.

Source-only checkout #

git clone https://tangled.org/io-streamer.bsky.social/witcher3-devkit
cd witcher3-devkit
./w3dev commands --json
./w3dev guide debugger
python3 -m unittest discover -s . -p 'test_*.py' -q

Python CLI/help/tests use the standard library. On a new host, place a symlink to this checkout's w3dev in a directory on PATH if desired. Direct ./w3dev and python3 /absolute/path/to/cli.py require no registration or package installation. User-supplied relative input/output paths resolve against the caller's directory; paths in examples such as plans/hag-pilot.json assume this repository as CWD.

Configure a game installation using local-config.example.json as the format. The default shared config is ${XDG_CONFIG_HOME:-~/.config}/witcher3-devkit/local-config.json. A checkout-local ignored local-config.json remains a fallback when no shared config exists. Schema version 1 permits only schema_version, game_directory and documents_directory. Relative paths are resolved against the config file, independent of the caller's working directory.

W3DEV_CONFIG takes precedence over shared and checkout-local configuration; an explicitly selected missing file is an error. W3DEV_GAME and W3DEV_DOCUMENTS override their respective config values. Without config, defaults describe a conventional Linux Steam library and app 292030's Proton documents. Defaults are discovery hints, not proof of installation. doctor shows the effective paths. Never change config during an active session.

Changing paths does not install, transfer ownership of, or qualify another build. install-native and install-ui update an already-owned installation; there is no general first-time installer. A new installation requires reviewed matching native adapters, bridge/UI assets, dependency hashes and deployment receipts. Do not copy another machine's receipts or invent hashes to bypass verification.

For an automatic Steam update, use w3dev reconcile-game-update to inspect the exact supported build and dependency checks. It does not modify the executable. After building the reviewed adapters, --apply performs a backed-up, checked reconciliation; unknown builds remain blocked. See Steam update compatibility for qualification and hash-guarded rollback. install-native is not an executable-update bypass.

Dependencies and data #

The current host has Steam/Proton, xdotool, Spectacle, KDE KWin and Python GI/DBus support. The native protocol uses the existing loopback bridge. Research/UI tools have their own environment under research/python-env; native build scripts use the pinned compiler/SDK under research/. These local dependencies are retained on this host and intentionally absent from a source clone. See native/README.md, research/README.md and research/findings.json for build inputs and provenance.

Optional Rust evidence reader:

cargo build --locked --manifest-path readers/shadow-rust/Cargo.toml

--offline is supported when dependencies are already cached. Python verification does not require Rust. Local config, receipts, sessions, backups, raw traces and extracted/downloaded assets are ignored by Git. Worktrees share installation state but retain their own source and build outputs. Worktrees share installation ownership; do not copy receipts or create a second runtime.

For Python consumers, add the canonical checkout to sys.path and import debugger.Client. The existing support.manage helper name is retained for compatibility, but now aliases this repository's game_paths module; it no longer imports the combat lab's manage.py or any balance code.