YGS Yupi Game Services Docs

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:

platformplatformGroup
webWEB
android, iosMOBILE
windows, macos, linuxPC
switchCONSOLE

3. Game REST API v1

Method & PathAuthDescription
GET /api/v1/healthPublicService status, uptime, global CCU, 24h match count, loaded drivers.
POST /api/v1/auth/guestTenantCreate guest account. Body: { platform, displayName? } → returns { authToken, player }.
POST /api/v1/auth/recovery-codeBearerGenerate 12-char unambiguous cross-device recovery code (XXXX-XXXX-XXXX).
POST /api/v1/auth/recoverTenantRestore account on a new device. Body: { recoveryCode, platform }.
GET /api/v1/profileBearerGet player profile, Elo, division, and per-mode modeStats.
PATCH /api/v1/profileBearerUpdate sanitized display name (3–20 chars, profanity filtered).
GET /api/v1/leaderboardTenant (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