Yupi Game Services (YGS) Documentation
Cross-platform multiplayer backend over https:// + wss:// for HTML5/Web, Android, iOS, Windows, macOS, Linux, and Nintendo Switch.
Base Endpoints
- HTTP API:
https://gameservices.yupistudios.com/api/v1 - WebSocket Gateway:
wss://gameservices.yupistudios.com/ws - Admin Console:
https://gameservices.yupistudios.com/admin/ - Defold SDK Archive:
/downloads/ygs-defold-latest.zip
2. Multi-Tenant Authentication & Headers
Every game tenant is strictly isolated by game_id. Pass these headers on all Game REST API requests:
X-YGS-Game-Id: pongzera X-YGS-Api-Key: ygs_pub_your_publishable_key Authorization: Bearer ygs_tok_... # required on authenticated routes
Supported platform tags map automatically to console-compliant leaderboard groups:
platform | platformGroup |
|---|---|
web | WEB |
android, ios | MOBILE |
windows, macos, linux | PC |
switch | CONSOLE |
3. Game REST API v1
| Method & Path | Auth | Description |
|---|---|---|
GET /api/v1/health | Public | Service status, uptime, global CCU, 24h match count, loaded drivers. |
POST /api/v1/auth/guest | Tenant | Create guest account. Body: { platform, displayName? } → returns { authToken, player }. |
POST /api/v1/auth/recovery-code | Bearer | Generate 12-char unambiguous cross-device recovery code (XXXX-XXXX-XXXX). |
POST /api/v1/auth/recover | Tenant | Restore account on a new device. Body: { recoveryCode, platform }. |
GET /api/v1/profile | Bearer | Get player profile, Elo, division, and per-mode modeStats. |
PATCH /api/v1/profile | Bearer | Update sanitized display name (3–20 chars, profanity filtered). |
GET /api/v1/leaderboard | Tenant (Bearer opt.) | Global Elo Top-N (?limit=100&offset=0&ladder=global) + me + onlineCount. |
4. WebSocket Protocol v1
Connect with TCP_NODELAY enabled on server side:
wss://gameservices.yupistudios.com/ws?game=pongzera&key=<apiKey>&token=<authToken>&v=1&platform=web
Client → Server Messages
{ "t": "ping", "ts": 1700000000000, "rtt": 24 }{ "t": "q_join", "mode": "classic_pong", "localPlayers": 1, "maxRemotePlayers": 1, "ladder": "global" }{ "t": "q_leave" }{ "t": "st_start" }— Vote "Start Now" in 4-player staging room{ "t": "rm_create", "mode": "mode_four_way", "winScore": 7, "teamFormat": "2v2", "fillBots": true }{ "t": "rm_join", "code": "AB3K9M", "localPlayers": 1 }{ "t": "rm_update", ... }/rm_ready/rm_start/rm_leave/rm_rematch{ "t": "in", "s": 1, "d": -1, "q": 42 }— Continuous directional input{ "t": "act", "s": 1, "k": "shoot", "q": 43, "payload": {} }— Discrete action{ "t": "forfeit" }/{ "t": "rejoin", "matchId": "..." }
Server → Client Messages
welcome, pong, err, q_state, st_state, rm_state, m_start, cd, sn, ev, sc, over.
5. Official Defold SDK Installation
Add both dependencies in your project's game.project and run Project → Fetch Libraries:
[project] dependencies#0 = https://github.com/defold/extension-websocket/archive/refs/tags/4.1.0.zip dependencies#1 = https://gameservices.yupistudios.com/downloads/ygs-defold-latest.zip [online] ygs_http_url = https://gameservices.yupistudios.com ygs_ws_url = wss://gameservices.yupistudios.com/ws ygs_game_id = pongzera ygs_api_key = <your-publishable-key>
Then require local ygs = require "ygs.ygs", call ygs.init(), and call ygs.update(dt) in your main loop.
6. Authoritative & Relay Drivers (IGameRoomDriver)
YGS includes two built-in drivers:
pongzera-v1— 60 Hz deterministic server physics simulation for Classic, Old West, 4-Way, and Hockey.relay-v1— Generic state/event relay + consensus completion so any 3rd-party game can ship online rooms, Elo, and leaderboards on Day 1.
To add a new custom authoritative driver, implement IGameRoomDriver in src/drivers/ and register it in src/drivers/driverRegistry.ts.
7. Self-Hosting & Cloud Deployment
Fly.io (ashburn / iad + /data SQLite WAL volume)
./scripts/deploy_fly.sh
Docker Compose + Automatic HTTPS (Caddy)
docker compose --profile https up -d --build