@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:

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:

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:

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:

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

Cloudflare Worker

The Worker entrypoint is exported at:

@vgai/p2p-colyseus/cloudflare/worker

Local commands:

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:

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.