Auth & Game API
One Node/Express service (crossworlds-auth, port 3000, /opt/crossworlds-auth/server.js) holds auth plus all game endpoints. New responses use a {success, data} / {success, error} envelope; old gear endpoints are frozen.
The old gear endpoints â GET /character, POST /character, PATCH /character/position, POST /character/gear/equip, GET /items â and their tables (item_template, item_instance, character_gear) are called by Unity on every spawn. Do not rename, remove, or alter them.
Endpoints on the live server (verified)
All /api/* return {success, data} or {success, error}. Error strings are player-readable â Unity shows them verbatim. Bold rows have a client consumer in this repo; the rest are server-only today.
| Endpoint | Auth | Purpose |
|---|---|---|
GET /health, GET /api/health | â | Liveness |
POST /login, POST /register | â | Auth (register is owner/web only) |
GET /character, POST /character | JWT | Sacred create/confirm on spawn |
POST /character/position, /character/gear/equip | JWT | Sacred position + equip |
GET /api/items | â | Item rows (bag UI) |
GET /api/enemies ¡ /:id | â | Enemy templates |
POST /api/character/save-progress | JWT | level, experience, gold, stat_* |
GET /api/character/stats/:characterId | JWT | Character stat block |
GET /api/inventory/:characterId | JWT | Bag contents |
POST /api/inventory/save ¡ /equip | JWT | Persist / equip slots |
GET /api/professions/:characterId ¡ recipes/:characterId | JWT | Profession skills / known recipes |
GET /api/recipes?profession= | â | Recipe list |
POST /api/craft | JWT | Craft/smelt (transactional, XP award) |
POST /api/professions/award-xp | JWT | Profession XP |
POST /api/combat/hit | JWT | Validate + sanity cap; logs only |
POST /api/combat/kill | JWT | Award XP+gold+loot atomically |
POST /api/combat/death ¡ session/end ¡ GET stats/:characterId | JWT | Death log, session summary, combat stats |
POST /api/loot/drop ¡ /roll | JWT | DB-backed drops |
POST /api/gold/adjust | JWT | Signed gold delta |
GET /api/mastery/:characterId ¡ POST /api/mastery/award | JWT | Hero mastery (used by HeroMasteryManager) |
GET /api/leaderboard/{damage,healing,mastery,waves} | â | Leaderboards |
GET/POST /api/talents/* | JWT | Talent tree, invest, respec |
GET/POST /api/quests/* | JWT | Available, accept, complete, progress |
POST /api/guilds/* | JWT | Create, invite, leave, motd |
GET /api/quests lore/*, feedback, broadcast/pending, maintenance/status | mixed | Misc content + ops |
/api/admin/* | Admin | Accounts, characters, give-item/gold, broadcast, logs, maintenance, stats |
Talents, quests, guilds, leaderboards, combat/death, and combat/session are implemented on the server but have no caller in the current Unity client (no PartyManager, GuildPanelUI, QuestLogUI, or TalentTreeUI in the repo). See Implementation Status.
Combat anti-exploit (in-process, alpha)
Two in-memory Maps guard /api/combat/kill:
| Guard | Key | Rule |
|---|---|---|
Hit gate (recentHits) | charId:enemyTemplateId | Kill must find a hit < HIT_WINDOW_MS (30s); entry consumed on kill |
Kill rate limiter (lastKillTime) | charId | âĨ KILL_COOLDOWN_MS (2s) between any two kills |
Execution order: JWT + ownership â enemy lookup â rate limiter (429) â hit gate (400) â consume + record â transaction (XP+gold+rollDbLoot) â return {xpGained, goldGained, itemDropped}.
Both Maps are cleared on restart, there is no server-side player HP (a hacked client can ignore damage), and there is no per-run enemy dedup or arena session token. See Known Issues & Tech Debt.
Conventions
- Auth on every player-data endpoint via
requireJWT+ownedCharacter(). - Transactions wrap every multi-table write. Parameterized queries only.
- Do not call
/api/loot/droporsave-progresson kill â/api/combat/killhandles both.
Server work happens on the VPS (/opt/crossworlds-auth/server.js), not in this repo. This repo is the Unity client + dedicated server only. See Build & Deploy.
Related: Database Schema ¡ Login & Authentication Flow ¡ Combat Core & Loop ¡ Loot, Inventory & Crafting