# 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

```mermaid
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](docs/ARCHITECTURE.md) describes the components;
the [command contracts](#discover-and-operate) define current arguments and
completion semantics.

## Discover and operate

From an existing, owned installation:

```sh
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`](witcher_devkit/debugger.py) from a source
checkout. Construction alone does not launch or attach.

## Capabilities

| Area | Start here |
| --- | --- |
| Installation and source-only setup | [SETUP.md](SETUP.md) |
| Control, observation and recovery | `w3dev guide debugger`; [architecture](docs/ARCHITECTURE.md) |
| HUD annotations | `w3dev help debug overlay --json`; [qualification](docs/QUALIFICATION.md) |
| Native adapters | [native/README.md](native/README.md) |
| UI asset tooling | [research/README.md](research/README.md) |
| Presentation timing | [presentation/README.md](presentation/README.md) |
| Evidence contracts | [schemas/README.md](schemas/README.md), [Rust reader](readers/shadow-rust/README.md) |

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](docs/QUALIFICATION.md) distinguishes tested paths
from source-only assumptions.

## Source checkout

```sh
./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](SETUP.md) explains
path discovery and qualified installation updates.

Python implementation is in [`witcher_devkit/`](witcher_devkit/README.md), game
script templates are in [`scripts/`](scripts/README.md), and bounded source
fixtures are in [`fixtures/`](fixtures/README.md). Offline tests and explicit
live harnesses are separated under [`tests/`](tests/README.md).
Native adapters are in [`native/`](native/README.md), local UI asset tooling
and indexes in [`research/`](research/README.md), and optional presentation
instrumentation in [`presentation/`](presentation/README.md).
[`plans/`](plans/README.md) 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](SETUP.md) before attempting installation
on another host.

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