# OpenVT control bridge plan

## Objective

Take runtime outputs from this repo and make them actionable inside OpenVT.

Current runtime outputs already include:

- reply text
- avatar actions such as:
  - `talk:start`
  - `talk:stop`
  - `emotion:*`
  - `gesture:*`

## Verified useful OpenVT primitives

### 1. TCP listener pattern already exists in OpenVT

OpenVT includes a reusable TCP server pattern in:

- `vendor/open-vt/lib/tracking/net/tcp_tracker.gd`

This means a local control bridge can likely be implemented in the same style as tracker ingestion.

### 2. JSON decoding already exists in multiple trackers

Examples:

- `vendor/open-vt/lib/tracking/camera/vts/vts_tracker.gd`
- `vendor/open-vt/lib/tracking/camera/vts_blendshapes/vts_tracker.gd`

So a JSON-over-TCP control protocol is a natural fit.

### 3. Stage/model control entry points exist

Verified scene/controller anchors:

- `vendor/open-vt/studio/stage/stage.gd`
- `vendor/open-vt/lib/model/vt_model.gd`

OpenVT already exposes model lifecycle and tracking update paths; a bridge can target the active model and/or stage.

## Recommended control protocol

Use a simple local TCP JSON protocol.

### Why this path

- matches existing OpenVT tracker infrastructure
- avoids inventing an HTTP stack inside Godot
- easy to emit from Bun/Node
- good enough for localhost control from the runtime

## Suggested messages

```json
{ "type": "talk", "state": "start" }
{ "type": "talk", "state": "stop" }
{ "type": "emotion", "value": "happy" }
{ "type": "gesture", "value": "nod" }
{ "type": "text", "value": "Hello chat!" }
```

## Minimal OpenVT-side implementation plan

1. Add a new control node/script under OpenVT, for example:
   - `vendor/open-vt/lib/control/runtime_control.gd`
2. Reuse the TCP server pattern from `tcp_tracker.gd`
3. Parse JSON messages
4. Map actions to existing model/expression/animation hooks

## Minimal repo-side implementation plan

1. Add a Bun-side TCP client sender
2. On each runtime output action, emit one JSON message to localhost
3. Keep OBS separate from this bridge; OBS can continue to capture OpenVT visually

## Immediate next step

Implement the repo-side sender first:

- `src/openvt-control.ts`

That preserves the interface even before the OpenVT side is fully patched.

