Witcher 3 Devkit #

Native control, inspection, UI automation and evidence capture for a running Witcher 3 process. An external agent chooses each action after observing the result of the last one. This repository supplies tools, not a combat policy or a game simulator.

Qualified environment: Remastered 5.01 DX12, Steam/Proton on Linux, KDE KWin. The native bridge, input adapter and HUD asset are specific to that installation. Help and offline tests work in a source-only checkout; native control does not. There is no general first-time installer.

How it works #

flowchart TD
    A["Agent or human"] --> B["w3dev CLI or debugger.Client"]
    B --> C["Single persistent debugger owner"]
    C --> J["Durable operation journal"]
    C --> D["REDengine loopback debugging connection"]
    D --> E["Installed WitcherScript bridge"]
    E --> F["Game state and input handlers"]
    E --> G["Bounded native input adapter"]
    F --> C
    G --> C
    E --> H["Passive in-game HUD"]

The owner admits one operation at a time. Its operation ID supports result lookup after a client timeout; a timeout does not cancel native work. The bridge checks session and request identity; host operations also check generation and running build identity. Bounded input advances the real game, releases input, and returns to a checked pause boundary. Native delivery and intended gameplay effect are reported separately. Unknown delivery blocks further mutation rather than triggering a blind retry.

The architecture describes the components; the command contracts define current arguments and completion semantics.

Discover and operate #

From an existing, owned installation:

w3dev guide debugger
w3dev commands --json
w3dev help debug step --json
w3dev doctor
w3dev verify
w3dev debug status

These are read-only discovery and preflight commands; they do not launch the game. Check for an owner or pending operation before starting a session.

Stage	Command	Boundary
Launch	w3dev debug open	Starts asynchronously; does not select a save.
Load	w3dev debug load NAME --sha256 HASH	Hashes the chosen fixture and waits for a new world generation.
Observe	w3dev debug inspect --view world	Fresh state; debug status is cached.
Take control	w3dev debug control agent	Explicitly enables virtual input and devkit pause.
Act	w3dev debug step --ticks 10	Finite advance and verified boundary; input is optional.
Check	w3dev debug operation ID	Retrieves an existing operation; never replays it.
Return	w3dev debug control human	Clears agent input and devkit pause without clearing unrelated pauses.
Finish	w3dev debug close	Unsaved exit, save/mod audit, and restoration of owned personal settings.

Choose an existing, hash-verified fixture; NAME and HASH above are placeholders, not bundled saves. The game opens in human mode by default. Human controller reads pass through the original XInput function; physical latency has not been measured. Agent mode does not block physical keyboard or mouse input. No registered MCP server or debug-console typing is required.

The CLI emits JSON on stdout and diagnostics on stderr. w3dev help COMMAND --json supplies bounds, prerequisites, effects, completion and examples; w3dev explain CODE supplies recovery guidance. Python clients can import witcher_devkit.debugger.Client from a source checkout. Construction alone does not launch or attach.

Capabilities #

Area	Start here
Installation and source-only setup	SETUP.md
Control, observation and recovery	w3dev guide debugger; architecture
HUD annotations	w3dev help debug overlay --json; qualification
Native adapters	native/README.md
UI asset tooling	research/README.md
Presentation timing	presentation/README.md
Evidence contracts	schemas/README.md, Rust reader

Input delivery does not prove a hit, dodge or AI decision. Short transitions can escape host-stepped until conditions; event gaps are reported, not filled. Screenshots and telemetry are not guaranteed to describe the same render frame. Use debug inspect --view capabilities before relying on a hook. The qualification summary distinguishes tested paths from source-only assumptions.

Source checkout #

./w3dev commands --json
python3 -m unittest discover -s . -p 'test_*.py' -q

This test command does not start the game. The CLI and tests use standard-library Python; optional UI asset research and native builds require separate local toolchains. Keep configuration, downloaded dependencies, game assets, session receipts, saves and raw captures out of Git. The setup guide explains path discovery and qualified installation updates.

Python implementation is in witcher_devkit/, game script templates are in scripts/, and bounded source fixtures are in fixtures/. Offline tests and explicit live harnesses are separated under tests/. Native adapters are in native/, local UI asset tooling and indexes in research/, and optional presentation instrumentation in presentation/. plans/ contains bounded experiment examples, not a required fight controller.

Scope #

One installation has one owner. Worktrees share receipts, locks and the native game process; never start a second owner or change the owning source mid-session. debug recover preserves unresolved delivery and original evidence. Do not overwrite progress saves, deploy consumer-policy mods or assume native adapters work on another build. See SETUP.md before attempting installation on another host.

Original devkit code is MIT-licensed. Third-party notices are in licenses/; see SETUP.md for build dependencies. This repository does not redistribute game files or locally downloaded asset toolchains.