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.

🛑 Sacred — never modify

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.

EndpointAuthPurpose
GET /health, GET /api/health—Liveness
POST /login, POST /register—Auth (register is owner/web only)
GET /character, POST /characterJWTSacred create/confirm on spawn
POST /character/position, /character/gear/equipJWTSacred position + equip
GET /api/items—Item rows (bag UI)
GET /api/enemies · /:id—Enemy templates
POST /api/character/save-progressJWTlevel, experience, gold, stat_*
GET /api/character/stats/:characterIdJWTCharacter stat block
GET /api/inventory/:characterIdJWTBag contents
POST /api/inventory/save ¡ /equipJWTPersist / equip slots
GET /api/professions/:characterId ¡ recipes/:characterIdJWTProfession skills / known recipes
GET /api/recipes?profession=—Recipe list
POST /api/craftJWTCraft/smelt (transactional, XP award)
POST /api/professions/award-xpJWTProfession XP
POST /api/combat/hitJWTValidate + sanity cap; logs only
POST /api/combat/killJWTAward XP+gold+loot atomically
POST /api/combat/death ¡ session/end ¡ GET stats/:characterIdJWTDeath log, session summary, combat stats
POST /api/loot/drop ¡ /rollJWTDB-backed drops
POST /api/gold/adjustJWTSigned gold delta
GET /api/mastery/:characterId ¡ POST /api/mastery/awardJWTHero mastery (used by HeroMasteryManager)
GET /api/leaderboard/{damage,healing,mastery,waves}—Leaderboards
GET/POST /api/talents/*JWTTalent tree, invest, respec
GET/POST /api/quests/*JWTAvailable, accept, complete, progress
POST /api/guilds/*JWTCreate, invite, leave, motd
GET /api/quests lore/*, feedback, broadcast/pending, maintenance/statusmixedMisc content + ops
/api/admin/*AdminAccounts, characters, give-item/gold, broadcast, logs, maintenance, stats
â„šī¸ Server-only surface

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:

GuardKeyRule
Hit gate (recentHits)charId:enemyTemplateIdKill 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}.

âš ī¸ Alpha caveats

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/drop or save-progress on kill — /api/combat/kill handles both.
â„šī¸ Where this runs

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