# @vgai/p2p-colyseus

Colyseus-compatible runtime pieces for running the same multiplayer room/client source in real Colyseus, loopback tests, universal Node WebSocket mode, browser-hosted P2P over WebRTC, and Cloudflare relay fallback.

The core contract is strict: gameplay code should be authored like normal Colyseus code. Runtime selection belongs in config, build aliases, launch URLs, or test harnesses.

## Authoring Contract

Game code may use ordinary Colyseus-style imports:

```ts
import { Client, Callbacks } from '@colyseus/sdk';
import { Schema, MapSchema, type } from '@colyseus/schema';
import { Room } from 'colyseus';
```

Game code should not import WebRTC, Cloudflare signaling, relay fallback, `@vgai/p2p-colyseus`, or engine transport selection APIs. If the source has to branch for real Colyseus vs P2P, the compatibility package or launch layer is incomplete.

## Runtime Modes

- Real Colyseus: normal Colyseus packages and a real Colyseus server.
- Loopback: `loopback://` client plus registered room classes for tests.
- Universal Node WebSocket: no Colyseus server dependency, but WebSocket transport.
- P2P host: browser creates the authoritative room and accepts clients.
- P2P join: browser joins a host-created room by `roomId`.
- Relay fallback: Cloudflare signaling/relay carries packets when direct WebRTC is unavailable or forced.

## Browser Client Configuration

Configure P2P outside gameplay code:

```ts
import { configureP2PColyseusClient } from '@vgai/p2p-colyseus/browser';
import { TankRoom } from './server/rooms/tank-room';

configureP2PColyseusClient({
  mode: {
    kind: 'p2p-host',
    signalingUrl: 'https://vgai-p2p-colyseus.example.workers.dev',
    iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
  },
  rooms: {
    tank_room: TankRoom,
  },
});
```

Joining an existing host:

```ts
configureP2PColyseusClient({
  mode: {
    kind: 'p2p-join',
    signalingUrl: 'https://vgai-p2p-colyseus.example.workers.dev',
    roomId,
    iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
  },
});
```

For proofing relay mode:

```ts
configureP2PColyseusClient({
  mode: {
    kind: 'p2p-join',
    signalingUrl,
    roomId,
    iceServers: [],
    forceRelay: true,
  },
});
```

## Cloudflare Worker

The Worker entrypoint is exported at:

```ts
@vgai/p2p-colyseus/cloudflare/worker
```

Local commands:

```bash
npm --workspace @vgai/p2p-colyseus run typecheck
npm --workspace @vgai/p2p-colyseus run test
npm --workspace @vgai/p2p-colyseus run wrangler:dry-run
npm --workspace @vgai/p2p-colyseus run wrangler:dev
npm --workspace @vgai/p2p-colyseus run wrangler:deploy
```

Deployment config lives in `wrangler.toml`.

## Cloudflare Env Vars

- `P2P_COLYSEUS_RELAY_DISABLED`: set to `true` to reject relay service traffic.
- `P2P_COLYSEUS_RELAY_DAILY_BUDGET_USD`: budget input used to derive the global relay byte cap.
- `P2P_COLYSEUS_RELAY_ESTIMATED_USD_PER_GIB`: egress estimate used with the budget.
- `P2P_COLYSEUS_RELAY_MAX_GLOBAL_BYTES_PER_DAY`: explicit byte cap override.
- `P2P_COLYSEUS_MAX_REQUEST_BODY_BYTES`: maximum HTTP POST body size.
- `P2P_COLYSEUS_MAX_GLOBAL_REQUESTS_PER_DAY`: global daily Worker request cap.
- `P2P_COLYSEUS_MAX_GLOBAL_WEBSOCKET_MESSAGES_PER_DAY`: global daily WebSocket relay message cap.
- `P2P_COLYSEUS_MAX_ACTIVE_RELAY_SOCKETS`: active relay WebSocket cap.
- `P2P_COLYSEUS_ALLOWED_ORIGINS`: optional comma-separated CORS/origin allowlist. Unset means all origins are allowed.

## Proof Command

From the repo root:

```bash
npm run typecheck && npm run test:p2p-colyseus-proof
```

The proof deploys the Worker, runs package tests, executes live relay checks, records browser gameplay videos, summarizes artifacts, and validates all required proof rows. Artifact details are documented in `docs/P2P-COLYSEUS-PROOF-ARTIFACTS.md`.

## Known Scope Boundaries

- The workspace package is ESM-only (`"type": "module"`). CJS package output is not currently produced.
- This is not a full Colyseus Cloud replacement.
- Redis-backed presence/driver behavior is represented by local compatibility shims unless a proof explicitly covers distributed behavior.
- Host migration is not implemented.
- Direct WebRTC is proven in Chromium proof contexts; wider browser/NAT coverage is tracked in `docs/P2P-COLYSEUS-REMAINING-CHECKLIST.md`.

Current product/security decisions are tracked in `docs/P2P-COLYSEUS-DECISIONS.md`.