md-show/plan.md

---
name: Plugin Server Data Plan
overview: Stay on retail TeamSpeak + Client Plugin SDK (API 26). Improve what we send through TeamSpeak (and optionally a small authority) so less is ad-hoc client-only — without building a custom ServerLib app.
todos:
  - id: inventory-wire
    content: Inventory current CEPOS fields + hub_parser keys (what already goes via TS)
    status: pending
  - id: protocol-design
    content: Design versioned plugin-command + hub schema for extra server-side policy/data
    status: pending
  - id: implement-one
    content: Implement one additive send path (one message type or hub keys) — Golden Rule
    status: pending
  - id: optional-hybrid
    content: "Only if chosen: sketch hybrid authority audible-set API (still client PCM)"
    status: pending
  - id: no-serverlib
    content: Do not revive ClientLib/ServerLib custom app
    status: pending
isProject: false
---

# Better “send to server” on Plugin SDK (API 26)

**Discarded:** Option B (own ClientLib/ServerLib app). Deleted old plan file.

**Stay on:** retail TeamSpeak + plugin (`PLUGIN_API_VERSION 26`), branch `tsmain` / current V8 path.

## What “server” can mean here

| Meaning | Reality with Plugin SDK |
|---|---|
| **A. Retail TeamSpeak server** | Relay only. Plugin commands (`sendPluginCommand`) go client→server→clients. Channel description holds hub config. **No game proximity engine on TS.** |
| **B. Optional game voice authority** | Your own small process (or Conan dedicated server). Clients upload state; it returns audible sets. Plugin still applies PCM/3D. Not TeamSpeak ServerLib. |

This plan focuses on **A first** (more/better data over TeamSpeak), then optional **B** if you want central decisions.

## What V8 already sends today

- **CEPOS** via `sendPluginCommand("CEPOS:…")` — position, facing, voice distance (~56 B base64), throttled + keepalive ([`ts3_cepos.c`](src/ts/proximity/ts3_cepos.c))
- **CEDRAIN** — wakeup tick only
- **Hub settings** — read from **root channel description** (server admin writes config; plugin parses)

Proximity math and mute/gain stay **on each client**.

## What Plugin API 26 cannot do

- Run proximity inside retail `ts3server`
- True packet drop like ServerLib `ts3server_setClientWhisperList`
- Replace client PCM as the hearing mechanism without leaving Plugin SDK

## Improvements worth planning (ranked)

### 1. Richer / cleaner plugin-command protocol (TeamSpeak relay)

Keep CEPOS, add typed messages (compact binary/base64), e.g.:

- `CEPOS:` — position (as now; maybe version bump if fields added)
- `CEAUTH:` / identity bind hints (Steam/Conan id hash — still spoofable without B)
- `CEMODE:` — voice mode change events (less poll noise)
- `CEZONE:` — local zone enter/leave if useful for peers
- `CEPING:` — RTT / stale detection beyond keepalive

Rules: still `sendPluginCommand`; throttle; bounds-check; no secrets in cleartext.

### 2. Push more config to the TeamSpeak server (channel description / hub)

Today hub already carries ranges/zones. Expand systematically:

- Documented key schema (versioned)
- Radio defaults, fail-closed policy, feature flags
- Single writer (server admin / description) — clients only read

This is the cleanest “server owns policy” path **without** a custom backend.

### 3. Optional: client whisper lists (limited)

`requestClientSetWhisperList` exists in Plugin SDK. Possible for **overlays** (admin whisper), not as main proximity router (permissions + “whisper disables channel talk”). Plan as experiment only after protocol work.

### 4. Optional hybrid authority (if you want “server computes”)

```text
Conan / clients -> Voice Authority (your process)
Authority -> audible set per listener
Plugin applies mute/gain/3D (PCM) as today
TeamSpeak = voice transport + CEPOS or authority uplink
```

Fail closed if authority down. Positions still untrusted unless Conan dedicated server feeds the authority.

## Explicitly out of scope

- Custom TeamSpeak SDK 3.5 ClientLib/ServerLib product
- Branch `ts3-Testing` ServerLib bootstrap
- Expecting retail `ts3server` to run Conan proximity

## Suggested first milestone (if you approve later)

1. Inventory current CEPOS + hub keys (freeze wire format)
2. Design versioned plugin-command + hub schema (doc only)
3. Implement one additive message type or hub keys (one function)
4. Only then consider hybrid authority or whisper-list experiment

## Docs

- Keep [`vergleichs.md`](vergleichs.md) as historical Option B comparison, or add a short “discarded” banner when implementing
- New living doc under `doku/` when code starts (project rule)

## Decision needed from you (before any code)

Prefer **A-only** (better plugin commands + hub config on retail TS), or **A + optional hybrid authority** for central audible sets?