# Connect a game to Ravensight Playtester

Run the CLI on the machine that can access your build. Sign in, link the project with `ravensight-playtest init --game <gameId>`, and complete its expectations brief. `run` quotes the existing persona price before registration. Adapters share the same prepaid job, action limits, model budget, cancellation, reports and uploads.

| Adapter | Target | Validation |
| --- | --- | --- |
| `playwright_web` | Browser URL, including canvas/WebGL exports | Automated tests and live Jump Bunny gameplay |
| `godot_driver` | Godot project with the playtest addon | Existing addon protocol and runner tests |
| `desktop_driver` | Local W3C/Appium session configuration | Protocol tested; experimental on physical builds |
| `unity_driver`, `unreal_driver` | Desktop exports through that same W3C interface | Engine-neutral screen controls, not editor plugins; experimental |
| `android_driver`, `ios_driver` | Appium device/emulator/simulator configuration | Protocol tested; hardware/build validation still required |
| `cli_stdio` | Developer-owned JSON-RPC bridge | Real child-process protocol test |

No adapter promises every game is autonomously solvable. Fast action games, unusual controls, anti-cheat, hardware access and protected platforms may require a game-specific bridge. Console tooling and authorization remain the developer's responsibility. The runner cannot bypass platform access restrictions.

## Browser and Godot

```sh
ravensight-playtest run --driver playwright_web --build-url https://your-game.example/ --headed
ravensight-playtest run --driver godot_driver --godot-project ./your-game
```

`--controller jev` enables structured action selection when the server supports it. Screen interpretation proposes controls and the selector chooses a supplied action. Uncertain decisions stop for review. Provider credentials stay on Ravensight. A completed playtest report is evidence for human review, not proof that a game is bug-free.

## Desktop and mobile

Install and configure an Appium-compatible driver for your platform. Start its server locally. Supply `ravensight-driver.json` with a loopback endpoint and capabilities appropriate to the installed driver:

```json
{
  "endpoint": "http://127.0.0.1:4723",
  "capabilities": {
    "platformName": "Android",
    "appium:automationName": "UiAutomator2",
    "appium:deviceName": "YOUR_LOCAL_DEVICE",
    "appium:app": "/absolute/path/to/game.apk"
  }
}
```

```sh
ravensight-playtest run --driver android_driver --driver-config ./ravensight-driver.json
```

For iOS, use `ios_driver`, `platformName: iOS`, your XCUITest driver and a provisioned device or simulator. For desktop, use the capabilities required by your installed desktop driver. Unity/Unreal exports use `unity_driver`/`unreal_driver`; no engine source is uploaded by this configuration. Configuration files are local and should not contain provider credentials. Do not expose the automation server publicly.

The runner creates a W3C session, reads page source plus PNG screenshots, and executes bounded coordinate clicks, keys, text and single-pointer swipes. It releases input after each action and closes the session when done. One persona uses the device at a time. Native adapters currently capture screenshots, not video or engine logs. Browser navigation is unavailable on these adapters. Model-visible text is limited to 12,000 characters; responses are bounded to 8 MB and commands time out after 30 seconds.

## Custom bridge

Use this for text games or your own engine/hardware integration. `--driver-config` points to:

```json
{
  "command": "/absolute/path/to/bridge-executable",
  "args": ["--game", "/absolute/path/to/build"],
  "cwd": "/absolute/path/to/project"
}
```

The configured executable is trusted local code chosen by the developer. The model cannot change it. It runs without a shell. Standard output must contain newline-delimited JSON-RPC 2.0 responses. Put diagnostics on stderr. Respond with the request ID and `result`, or an `error`:

```json
{"jsonrpc":"2.0","id":1,"method":"launch","params":{"protocolVersion":1}}
{"jsonrpc":"2.0","id":1,"result":{"ok":true}}
```

Required methods:

- `launch`: initialize/reset the game; return `{ "ok": true }`.
- `observe`: return `{ "text": "visible state" }`, optionally `screenshotBase64` containing PNG data.
- `act`: accept a `kind` of `key`, `type`, `click` or `wait`; return `{ "ok": true }` after execution. Apply your own game-specific legality checks. Never interpret model text as shell code.
- `screenshot`: return `{ "pngBase64": "..." }`, or a JSON-RPC error if unavailable. Text-only games can still produce text reports without screenshots.

Requests expire after 30 seconds. Oversized or malformed responses stop the bridge. The runner terminates its child when the session ends; the bridge must clean up any game processes it owns on termination. No custom protocol can establish compatibility with untested hardware by itself.

Protocol references: [W3C WebDriver](https://www.w3.org/TR/webdriver/), [Appium capabilities](https://appium.io/docs/en/3.2/guides/caps/).