From 5b6b6ca74d890fc413de4a359a0fc4c13a04e04a Mon Sep 17 00:00:00 2001
From: adtpdn <adtpdn@gmail.com>
Date: Sun, 5 Jul 2026 12:51:53 +0800
Subject: [PATCH] docs: add comprehensive Nakama server API reference

---
 Nakama-Server-API.md | 1639 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 1639 insertions(+)
 create mode 100644 Nakama-Server-API.md

diff --git a/Nakama-Server-API.md b/Nakama-Server-API.md
new file mode 100644
index 0000000..560b569
--- /dev/null
+++ b/Nakama-Server-API.md
@@ -0,0 +1,1639 @@
+# Tekton Nakama Lua Server API Reference
+
+> Auto-generated from source code. For AI agents — call these RPCs without reading Lua.
+
+## Table of Contents
+
+1. [Authentication & Core (core.lua)](#1-authentication--core-coreluau)
+2. [Utilities (utils.lua)](#2-utilities-utilsluau)
+3. [User Module (user.lua)](#3-user-module-userluau)
+4. [Economy Module (economy.lua)](#4-economy-module-economyluau)
+5. [Gacha Module (gacha.lua)](#5-gacha-module-gachaluau)
+6. [Leaderboard Module (leaderboard.lua)](#6-leaderboard-module-leaderboardluau)
+7. [Inbox/Mail Module (inbox.lua)](#7-inboxmail-module-inboxluau)
+8. [Daily Rewards Module (daily_rewards.lua)](#8-daily-rewards-module-daily_rewardsluau)
+9. [Admin Module (admin.lua)](#9-admin-module-adminluau)
+10. [Storage Collections Reference](#10-storage-collections-reference)
+11. [Leaderboard Config](#11-leaderboard-config)
+12. [Error Strings Reference](#12-error-strings-reference)
+13. [Permission Levels](#13-permission-levels)
+
+---
+
+## 1. Authentication & Core (`core.lua`)
+
+### After-Hook: `after_authenticate_steam`
+
+| Field | Value |
+|---|---|
+| **Trigger** | `AuthenticateSteam` |
+| **Purpose** | On first Steam login: sets display_name from Steam username, default role to `"player"` |
+| **Auth** | None (internal hook) |
+
+**Behavior:**
+- If user has no `display_name`, sets it from `input.username` (fallback: `"SteamPlayer"`)
+- If user metadata has no `role`, sets `metadata.role = "player"`
+
+### Startup (not an RPC)
+
+```
+nk.leaderboard_create("global_high_score", true, "desc", "best", nil, {})
+```
+
+Creates native leaderboard `"global_high_score"` on module load (also created in `leaderboard.lua` — pcall wraps both so duplicate is safe).
+
+---
+
+## 2. Utilities (`utils.lua`)
+
+Shared helpers used by other modules.
+
+### Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `ADMIN_ROLES` | `{admin=true, moderator=true, owner=true}` | Roles with admin privileges |
+| `SYSTEM_USER_ID` | `"00000000-0000-0000-0000-000000000000"` | System/nil user for global storage |
+| `CHANNEL_TYPE_ROOM` | `1` | Nakama channel type for rooms |
+| `CHANNEL_TYPE_DIRECT` | `2` | Nakama channel type for DMs |
+| `CHANNEL_TYPE_GROUP` | `3` | Nakama channel type for groups |
+
+### `utils.is_admin(context)`
+
+Checks if caller has admin/moderator/owner role.
+
+| Param | Type | Description |
+|---|---|---|
+| `context` | table | Nakama RPC context |
+
+**Returns:** `boolean`
+
+### `utils.is_match_host(context, match_id)`
+
+Checks if caller is the host of a match.
+
+| Param | Type | Description |
+|---|---|---|
+| `context` | table | Nakama RPC context |
+| `match_id` | string | Match ID to check |
+
+**Returns:** `boolean`
+**Note:** Reads `match.state` and checks `state.hostUserId` against `context.user_id`.
+
+### `utils.require_admin(context)`
+
+Errors with `"Admin privileges required"` if caller is not admin/moderator/owner.
+
+### `utils.require_admin_or_host(context, match_id)`
+
+Errors with `"Admin or host privileges required"` if caller is neither admin nor match host.
+
+### `utils.resolve_channel_id(channel_id)`
+
+Resolves a friendly room name (e.g. `"social_global"`) to a hashed Nakama channel ID.
+
+| Param | Type | Description |
+|---|---|---|
+| `channel_id` | string | Raw channel ID or friendly room name |
+
+**Returns:** `string` — resolved channel ID (passes through if already hashed, i.e. contains `"."`)
+**Logic:** If no `"."` in value, calls `nk.channel_id_build("", name, CHANNEL_TYPE_ROOM)`.
+
+---
+
+## 3. User Module (`user.lua`)
+
+### RPC: `get_user_profile`
+
+| Field | Value |
+|---|---|
+| **Function** | `user.rpc_get_user_profile` |
+| **Auth** | None required (can view any profile) |
+| **Purpose** | Get a user's public profile |
+
+**Params (JSON):**
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `user_id` | string | No | `context.user_id` | Target user ID |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `user_id` | string | User ID |
+| `username` | string | Username |
+| `display_name` | string | Display name |
+| `avatar_url` | string | Avatar URL |
+| `create_time` | string | Account creation time |
+| `role` | string | Role from metadata (`"player"` default) |
+
+**Errors:**
+- `"Account not found"` — user doesn't exist
+- `"Account banned until <time>. Reason: <reason>"` — temporary ban still active
+- `"Account permanently banned. Reason: <reason>"` — permanent ban
+
+**Ban logic:** Reads `metadata.banned`, `metadata.ban_expires` (Unix timestamp), `metadata.ban_reason`. If `ban_expires <= os.time()`, auto-clears the ban on read.
+
+### RPC: `update_user_profile`
+
+| Field | Value |
+|---|---|
+| **Function** | `user.rpc_update_user_profile` |
+| **Auth** | Required |
+| **Purpose** | Update own display name and/or avatar |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `display_name` | string | No | New display name |
+| `avatar_url` | string | No | New avatar URL |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | Always true |
+
+**Errors:**
+- `"Not authenticated"`
+- `"Failed to update profile"`
+
+### RPC: `search_users`
+
+| Field | Value |
+|---|---|
+| **Function** | `user.rpc_search_users` |
+| **Auth** | Required |
+| **Purpose** | Search users by username or display name |
+
+**Params (JSON):**
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `query` | string | No | `""` | Search term (ILike match on username/display_name). Empty = list all (limit 100). |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `users` | array | Array of user objects |
+
+**User object:**
+
+| Field | Type | Description |
+|---|---|---|
+| `user_id` | string | User ID |
+| `username` | string | Username |
+| `display_name` | string | Display name |
+| `avatar_url` | string | Avatar URL from metadata |
+
+**SQL:** Queries `users` table with `ILIKE`. Excludes system user `00000000-0000-0000-0000-000000000000`. Limit 100.
+
+### RPC: `change_credentials`
+
+| Field | Value |
+|---|---|
+| **Function** | `user.rpc_change_credentials` |
+| **Auth** | Required |
+| **Purpose** | Change email + password credentials |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `new_email` | string | No | New email |
+| `new_password` | string | No | New password |
+| `current_password` | string | If email set | Current password (required to unlink old email) |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | Always true |
+
+**Errors:**
+- `"Not authenticated"`
+- `"Current password required"` — account has email but no `current_password` provided
+- `"Incorrect current password."` — email auth re-verify failed
+- `"Failed to set new credentials: <err>"` — link_email failed (rolls back old link)
+
+**Logic:** Verifies current password via `nk.authenticate_email`, unlinks old email, links new email+password. On failure, re-links old credentials.
+
+### RPC: `send_lobby_invite`
+
+| Field | Value |
+|---|---|
+| **Function** | `user.rpc_send_lobby_invite` |
+| **Auth** | Required |
+| **Purpose** | Send a lobby invitation notification |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `to_user_id` | string | Yes | Recipient user ID |
+| `match_id` | string | Yes | Match/lobby ID to invite to |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | Always true |
+
+**Errors:**
+- `"Not authenticated"`
+- `"Missing to_user_id or match_id"`
+
+**Notification:** Code `1001`, persistent (`true`). Content: `{match_id, from_name}`.
+
+### RPC: `send_friend_request`
+
+| Field | Value |
+|---|---|
+| **Function** | `user.rpc_send_friend_request` |
+| **Auth** | Required |
+| **Purpose** | Send a friend request notification |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `user_id` | string | Yes | Target user ID |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | Always true |
+
+**Errors:**
+- `"Not authenticated"`
+- `"user_id is required"`
+- `"Cannot add yourself"`
+
+**Notification:** Code `1002`, persistent (`true`). Content: `{from_user_id, from_name}`.
+
+### RPC: `admin_get_user_history`
+
+| Field | Value |
+|---|---|
+| **Function** | `user.rpc_admin_get_user_history` |
+| **Auth** | Admin required |
+| **Purpose** | Get wallet ledger, login history, and match history for a user |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `user_id` | string | Yes | Target user ID |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `history.wallet_ledger` | array | Last 50 wallet ledger entries |
+| `history.logins` | array | Login history (up to 20) |
+| `history.matches` | array | Match history from storage collection `"matches"` |
+
+**Errors:**
+- `"Admin privileges required"` (via `utils.require_admin`)
+- `"user_id is required"`
+
+### After-Hook: `after_authenticate`
+
+| Field | Value |
+|---|---|
+| **Trigger** | `AuthenticateDevice`, `AuthenticateEmail`, `AuthenticateCustom` |
+| **Purpose** | Record login timestamp + IP to user storage |
+
+**Storage write:** Collection `"history"`, key `"logins"`, permission_read=`0`, permission_write=`0`. Keeps last 20 entries. Each entry: `{time, ip}`.
+
+---
+
+## 4. Economy Module (`economy.lua`)
+
+### Shop Catalog
+
+Hardcoded items available for purchase:
+
+| ID | Name | Category | Gold | Star | Rarity | Character |
+|---|---|---|---|---|---|---|
+| `oldpop-blue-hat` | Oldpop Blue Hat | head | 100 | 0 | Common | Oldpop |
+| `oldpop-green-hat` | Oldpop Green Hat | head | 100 | 0 | Common | Oldpop |
+| `oldpop-red-hat` | Oldpop Red Hat | head | 100 | 0 | Common | Oldpop |
+| `oldpop-yellow-hat` | Oldpop Yellow Hat | head | 100 | 0 | Common | Oldpop |
+| `oldpop-og-pant` | Copper OG Pant | costume | 0 | 0 | Common | Oldpop |
+| `oldpop-grey-pant` | Copper Grey Pant | costume | 150 | 0 | Common | Oldpop |
+| `oldpop-red-pant` | Copper Red Pant | costume | 150 | 0 | Common | Oldpop |
+| `oldpop-yellow-pant` | Copper Yellow Pant | costume | 150 | 0 | Common | Oldpop |
+| `oldpop-blue-gloves` | Oldpop Blue Gloves | glove | 75 | 0 | Common | Oldpop |
+| `oldpop-green-gloves` | Oldpop Green Gloves | glove | 75 | 0 | Common | Oldpop |
+| `oldpop-red-gloves` | Oldpop Red Gloves | glove | 75 | 0 | Common | Oldpop |
+| `oldpop-yellow-gloves` | Oldpop Yellow Gloves | glove | 75 | 0 | Common | Oldpop |
+
+### RPC: `get_shop_catalog`
+
+| Field | Value |
+|---|---|
+| **Function** | `economy.rpc_get_shop_catalog` |
+| **Auth** | Required |
+| **Purpose** | Get the shop catalog grouped by category, plus featured banners |
+
+**Params:** None (ignore payload)
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `catalog` | object | Grouped by category (`head`, `costume`, `glove`). Each entry: `{id, name, gold, star, rarity, character}` |
+| `featured_banners` | array | Banners from `shop_config`/`featured_banners` (max 3 items, each: `{item_id, ...}`) |
+
+**Errors:** `"Not authenticated"`
+
+### RPC: `buy_currency`
+
+| Field | Value |
+|---|---|
+| **Function** | `economy.rpc_buy_currency` |
+| **Auth** | Required |
+| **Purpose** | Purchase a currency package (IAP) |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `package_id` | string | Yes | One of: `gold_100`, `gold_500`, `gold_1000`, `gold_2000`, `gold_5000`, `gold_10000`, `star_100`, `star_250`, `star_600` |
+| `receipt` | string | For gold packages | Store receipt for validation |
+| `idempotency_key` | string | Yes | Idempotency key (prevents double-claim) |
+| `store_type` | string | No | `"google"`, `"apple"`, or `"test"` (default: `"test"`) |
+
+**Package table:**
+
+| Package ID | Gold Change | Star Change | Requires Verification |
+|---|---|---|---|
+| `gold_100` | +100 | 0 | Yes |
+| `gold_500` | +550 | 0 | Yes |
+| `gold_1000` | +1150 | 0 | Yes |
+| `gold_2000` | +2400 | 0 | Yes |
+| `gold_5000` | +6250 | 0 | Yes |
+| `gold_10000` | +13000 | 0 | Yes |
+| `star_100` | -500 | +100 | No |
+| `star_250` | -1100 | +250 | No |
+| `star_600` | -2500 | +600 | No |
+
+**Returns (JSON) — success:**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | `true` |
+| `status` | string | `"verified"` (receipt validated) or `"pending"` (no receipt, awaiting verification) |
+| `package_id` | string | Package ID |
+| `duplicate` | bool | (optional) `true` if idempotency key already used |
+
+**Errors:**
+- `"Not authenticated"`
+- `"Package ID required"`
+- `"Idempotency key required"`
+- `"Invalid package ID"`
+- `"InvalidReceipt"` — IAP validation failed
+- `"NotEnoughFunds"` — wallet update failed (e.g. insufficient gold for star packages)
+
+**Idempotency:** Checks `receipts` collection with idempotency_key. Returns existing result on duplicate.
+
+**Receipt validation:** For `store_type="test"`, accepts `receipt == "mock_receipt_for_now"`.
+
+### RPC: `purchase_item`
+
+| Field | Value |
+|---|---|
+| **Function** | `economy.rpc_purchase_item` |
+| **Auth** | Required |
+| **Purpose** | Purchase an item from the shop catalog |
+
+**Params (JSON):**
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `item_id` | string | Yes | — | Item ID from catalog |
+| `quantity` | number | No | 1 | Quantity (min 1) |
+| `idempotency_key` | string | Yes | — | Idempotency key |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | `true` |
+| `item` | string | Item ID purchased |
+| `duplicate` | bool | (optional) `true` if idempotency key already used |
+
+**Errors:**
+- `"Not authenticated"`
+- `"Item ID required"`
+- `"Invalid quantity"`
+- `"Idempotency key required"`
+- `"ItemNotFound"`
+- `"NotEnoughFunds"` — insufficient gold/star balance
+- `"PurchaseFailed"` — storage write failed
+
+**Storage writes:**
+- Collection `"inventory"`, key `item_id`: `{category, purchased_at, quantity}`
+- Collection `"receipts"`, key `idempotencyKey`: `{type="item", item_id, quantity, cost, processed_at}`
+
+### RPC: `admin_set_featured_banners`
+
+| Field | Value |
+|---|---|
+| **Function** | `economy.rpc_admin_set_featured_banners` |
+| **Auth** | Admin required |
+| **Purpose** | Set up to 3 featured banner items for the shop |
+
+**Params (JSON):**
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `banners` | array | No | `[]` | Array of banner objects, each with `{item_id, ...}` (max 3) |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | `true` |
+| `banners` | array | Final banners array (max 3) |
+
+**Errors:**
+- `"Admin privileges required"`
+- `"Item not found in catalog: <itemId>"` — banner references a non-catalog item
+
+**Storage:** Collection `"shop_config"`, key `"featured_banners"`, user `SYSTEM_USER_ID`, permission_read=`2`, permission_write=`0`.
+
+### RPC: `admin_get_featured_banners`
+
+| Field | Value |
+|---|---|
+| **Function** | `economy.rpc_admin_get_featured_banners` |
+| **Auth** | Admin required |
+| **Purpose** | Get current featured banners config |
+
+**Params:** None (ignore payload)
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `banners` | array | Current banners (may be empty) |
+
+---
+
+## 5. Gacha Module (`gacha.lua`)
+
+### Gacha Banners
+
+| Banner ID | Name | Currency | Pull 1 Cost | Pull 10 Cost | Pity At |
+|---|---|---|---|---|---|
+| `star` | Star Banner | star | 160 | 1440 | 90 |
+| `gold` | Gold Banner | gold | 50 | 450 | 90 |
+
+### Drop Rates
+
+| Rarity | Probability | Pool Items |
+|---|---|---|
+| `real_prize` | 1.0% | `skin_gacha_rainbow_suit`, `skin_gacha_dragon_hat`, `skin_gacha_phantom_gloves`, `skin_gacha_neon_acc` |
+| `rare` | 14.0% | `frag_rare` |
+| `uncommon` | 25.0% | `frag_uncommon` |
+| `common` | 60.0% | `frag_common` |
+
+### Real Prize Catalog
+
+| Item ID | Name | Category |
+|---|---|---|
+| `skin_gacha_rainbow_suit` | Rainbow Suit | costume |
+| `skin_gacha_dragon_hat` | Dragon Hat | head |
+| `skin_gacha_phantom_gloves` | Phantom Gloves | glove |
+| `skin_gacha_neon_acc` | Neon Accessory | accessory |
+
+### Fragment Items
+
+| ID | Name | Rarity |
+|---|---|---|
+| `frag_common` | Common Fragment | common |
+| `frag_uncommon` | Uncommon Fragment | uncommon |
+| `frag_rare` | Rare Fragment | rare |
+
+### RPC: `perform_gacha_pull`
+
+| Field | Value |
+|---|---|
+| **Function** | `gacha.rpc_perform_gacha_pull` |
+| **Auth** | Required |
+| **Purpose** | Perform 1 or 10 gacha pulls on a banner |
+
+**Params (JSON):**
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `banner_id` | string | Yes | — | `"star"` or `"gold"` |
+| `count` | number | No | 1 | Number of pulls (1 or 10) |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | Always true |
+| `results` | array | Array of pull results: `{id, rarity, name}` |
+| `new_pity` | number | Updated pity counter for this banner |
+
+**Errors:**
+- `"Not authenticated"`
+- `"Banner ID required"`
+- `"Invalid count"`
+- `"Unknown banner: <banner_id>"`
+- `"Could not read account"`
+- `"Insufficient currency"`
+- `"Failed to update wallet"`
+- `"Failed to write storage: <err>"`
+
+**Pity system:** After `pity_at` (90) pulls without a `real_prize`, the next pull is guaranteed `real_prize`. Pity counter resets on `real_prize` drop. Pity counter persists per banner in storage.
+
+**Storage reads/writes:**
+- Collection `"profiles"`, key `"pity_counters"`: per-banner pity counts
+- Collection `"profiles"`, key `"fragments"`: fragment inventory
+- Collection `"inventory"`, key = item_id: real prize items
+
+**Wallet:** Deducts currency cost. For `count=10`, uses `pull_10_cost` if available, otherwise `pull_1_cost * count`.
+
+---
+
+## 6. Leaderboard Module (`leaderboard.lua`)
+
+### Leaderboard Config
+
+| Property | Value |
+|---|---|
+| **ID** | `"global_high_score"` |
+| **Authoritative** | `true` |
+| **Sort Order** | `"desc"` (highest first) |
+| **Operator** | `"best"` (best score kept) |
+| **Reset Schedule** | `nil` (never resets) |
+
+### RPC: `get_leaderboard_stats`
+
+| Field | Value |
+|---|---|
+| **Function** | `leaderboard.rpc_get_leaderboard_stats` |
+| **Auth** | None |
+| **Purpose** | Get top 50 leaderboard entries |
+
+**Params:** None (ignore payload)
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `leaderboard` | array | Top 50 leaderboard entries |
+
+**Leaderboard entry object:**
+
+| Field | Type | Description |
+|---|---|---|
+| `user_id` | string | Owner user ID |
+| `username` | string | Username |
+| `display_name` | string | Username (fallback — actually `record.username`) |
+| `avatar_url` | string | Avatar URL from metadata |
+| `loadout_character` | string | Character from metadata (default `"Copper"`) |
+| `high_score` | number | Score |
+| `games_played` | number | From metadata |
+| `games_won` | number | From metadata |
+
+### RPC: `submit_score`
+
+| Field | Value |
+|---|---|
+| **Function** | `leaderboard.rpc_submit_score` |
+| **Auth** | Required |
+| **Purpose** | Submit/update own score on the leaderboard |
+
+**Params (JSON):**
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `score` | number | No | 0 | Score to submit |
+| `games_played` | number | No | 0 | Games played count |
+| `games_won` | number | No | 0 | Games won count |
+| `avatar_url` | string | No | From account | Avatar URL |
+| `loadout_character` | string | No | `"Copper"` | Character selection |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | `true` |
+
+**Errors:**
+- `"Not authenticated"`
+- `"Failed to submit score"`
+
+### RPC: `sync_leaderboard`
+
+| Field | Value |
+|---|---|
+| **Function** | `leaderboard.rpc_sync_leaderboard` |
+| **Auth** | Required |
+| **Purpose** | Bulk-sync all users' stats from `"stats"` and `"profiles"` collections to the native leaderboard |
+
+**Params:** None (ignore payload)
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | Always true |
+| `synced` | number | Number of records written |
+| `objects_found` | number | Stats objects found |
+| `debug` | array | Error messages per user |
+
+**Errors:**
+- `"Not authenticated"`
+- `"Sync failed: <err>"`
+
+**Storage reads:** Collection `"stats"` (all users, limit 100), Collection `"profiles"` (all users, limit 100), key `"profile"`.
+
+### RPC: `reset_stats`
+
+| Field | Value |
+|---|---|
+| **Function** | `leaderboard.rpc_reset_stats` |
+| **Auth** | Required |
+| **Purpose** | Delete own leaderboard record and reset stats to zero |
+
+**Params:** None (ignore payload)
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | `true` |
+
+**Storage write:** Collection `"stats"`, key `"game_stats"` — zeros out `games_played`, `games_won`, `high_score`, `total_kills`, `total_deaths`. permission_read=`2`, permission_write=`1`.
+
+### RPC: `admin_update_stats`
+
+| Field | Value |
+|---|---|
+| **Function** | `leaderboard.rpc_admin_update_stats` |
+| **Auth** | Admin required |
+| **Purpose** | Force-overwrite a user's stats and leaderboard record |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `user_id` | string | Yes | Target user ID |
+| `stats` | object | Yes | Stats object: `{high_score, games_played, games_won, loadout_character, ...}` |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | `true` |
+
+**Errors:**
+- `"Admin privileges required"`
+- `"User ID and stats are required"`
+
+**Storage write:** Collection `"stats"`, key `"game_stats"`, permission_read=`1`, permission_write=`0`.
+
+### RPC: `admin_delete_stats`
+
+| Field | Value |
+|---|---|
+| **Function** | `leaderboard.rpc_admin_delete_stats` |
+| **Auth** | Admin required |
+| **Purpose** | Delete a user's stats storage and leaderboard record |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `user_id` | string | Yes | Target user ID |
+
+**Storage deletes:** `{collection="stats", key="stats"}`, `{collection="stats", key="game_stats"}`, plus leaderboard record.
+
+### RPC: `admin_sync_leaderboard`
+
+| Field | Value |
+|---|---|
+| **Function** | `leaderboard.rpc_admin_sync_leaderboard` |
+| **Auth** | Admin required |
+| **Purpose** | Same as `sync_leaderboard` but requires admin |
+
+**Delegates to:** `leaderboard.rpc_sync_leaderboard` (same params, same returns).
+
+---
+
+## 7. Inbox/Mail Module (`inbox.lua`)
+
+### RPC: `admin_send_mail`
+
+| Field | Value |
+|---|---|
+| **Function** | `inbox.rpc_admin_send_mail` |
+| **Auth** | Admin required |
+| **Purpose** | Send a personal (targeted) or global mail |
+
+**Params (JSON):**
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `title` | string | No | `"Announcement"` | Mail title |
+| `content` | string | No | `""` | Mail body |
+| `start_date` | string | No | Current UTC | ISO8601 start date |
+| `end_date` | string | No | `""` | ISO8601 end date (global only) |
+| `rewards` | array/object | No | `{}` | Attached rewards (see claim_mail_reward for format) |
+| `target_user_id` | string | No | `""` | If set → personal mail to this user. Omit → global mail |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | `true` |
+| `mail` | object | The created mail object |
+
+**Mail object fields:** `id` (UUIDv4), `title`, `content`, `sender` (`"TEKTON DEV TEAM"`), `date`, `start_date`, `end_date`, `expiry_date` (30 days from now), `rewards`, `type` (`"personal"` or `"global"`).
+
+**Personal storage:** Collection `"inbox"`, key `"personal"`, permission_read=`1`, permission_write=`0`.
+**Global storage:** Collection `"config"`, key `"global_mail"`, user `SYSTEM_USER_ID`, permission_read=`2`, permission_write=`0`.
+
+### RPC: `get_mail`
+
+| Field | Value |
+|---|---|
+| **Function** | `inbox.rpc_get_mail` |
+| **Auth** | Required |
+| **Purpose** | Get all non-deleted, non-expired personal + global mail for the user |
+
+**Params:** None (ignore payload)
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `mails` | array | Filtered mail objects (excludes deleted, expired, not-yet-started, ended global) |
+| `state` | object | `{claimed_ids, deleted_ids, read_ids}` |
+
+**Filtering logic:** Excludes mail where:
+- ID is in `state.deleted_ids`
+- `expiry_date` is in the past
+- `start_date` is in the future
+- Global mail with `end_date` in the past
+
+**Storage reads:**
+- Collection `"inbox"`, key `"personal"`, user = caller
+- Collection `"config"`, key `"global_mail"`, user = `SYSTEM_USER_ID`
+- Collection `"inbox"`, key `"state"`, user = caller
+
+### RPC: `claim_mail_reward`
+
+| Field | Value |
+|---|---|
+| **Function** | `inbox.rpc_claim_mail_reward` |
+| **Auth** | Required |
+| **Purpose** | Claim rewards attached to a mail |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `mail_id` | string | Yes | Mail ID to claim rewards from |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | `true` |
+| `claimed_ids` | array | Updated list of claimed mail IDs |
+
+**Reward format (in the mail object):**
+
+Legacy dict format: `{star=100, gold=50}`
+Array format: `[{type="star", amount=100}, {type="gold", amount=50}, {type="frag_rare", id="frag_rare", amount=1}, {type="skin", id="skin_gacha_rainbow_suit"}]`
+
+| Reward `type` | Behavior |
+|---|---|
+| `"star"` | Added to wallet |
+| `"gold"` | Added to wallet |
+| `"frag_"` prefix | Added to inventory fragments (key: `"fragments"`) |
+| `"item"` | Added to inventory fragments |
+| `"skin"` | Added to inventory (key = skin item ID) |
+
+**Errors:**
+- `"Not authenticated"`
+- `"mail_id required"`
+- `"Reward already claimed"`
+- `"Mail not found"`
+
+**Storage writes:** Wallet update, then collection `"inventory"` (fragments or skins), then `"inbox"`/`"state"`.
+
+### RPC: `delete_mail`
+
+| Field | Value |
+|---|---|
+| **Function** | `inbox.rpc_delete_mail` |
+| **Auth** | Required |
+| **Purpose** | Soft-delete a mail (adds ID to state.deleted_ids) |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `mail_id` | string | Yes | Mail ID to delete |
+
+### RPC: `save_mail_state`
+
+| Field | Value |
+|---|---|
+| **Function** | `inbox.rpc_save_mail_state` |
+| **Auth** | Required |
+| **Purpose** | Mark mails as read |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `read_ids` | array | No | Array of mail IDs to mark as read |
+
+### RPC: `admin_list_mail`
+
+| Field | Value |
+|---|---|
+| **Function** | `inbox.rpc_admin_list_mail` |
+| **Auth** | Admin required |
+| **Purpose** | List all mail (global + personal) across all users |
+
+**Params:** None (ignore payload)
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `mails` | array | All mails sorted by date descending. Personal mails have extra fields: `type="personal"`, `target_user_id` |
+
+### RPC: `admin_update_mail`
+
+| Field | Value |
+|---|---|
+| **Function** | `inbox.rpc_admin_update_mail` |
+| **Auth** | Admin required |
+| **Purpose** | Edit or move a mail between users |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `mail_id` | string | Yes | Mail ID to update |
+| `type` | string | No | `"global"` or `"personal"` |
+| `target_user_id` | string | If personal | Current owner (for lookup) |
+| `new_target_user_id` | string | No | Transfer to a different user |
+| `title` | string | No | New title |
+| `content` | string | No | New content |
+| `end_date` | string | No | New end date |
+| `expiry_date` | string | No | New expiry date |
+
+### RPC: `admin_delete_mail_server`
+
+| Field | Value |
+|---|---|
+| **Function** | `inbox.rpc_admin_delete_mail_server` |
+| **Auth** | Admin required |
+| **Purpose** | Permanently delete mail from server storage |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `mail_id` | string | Yes | Mail ID to delete |
+| `type` | string | No | `"global"` or `"personal"` |
+| `target_user_id` | string | If personal | Owner user ID |
+
+---
+
+## 8. Daily Rewards Module (`daily_rewards.lua`)
+
+### Default Reward Schedule
+
+Days 1–31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`.
+
+| Day | Reward |
+|---|---|
+| 1 | 10 star |
+| 2 | 15 star |
+| ... | ... |
+| 19 | 100 star (capped) |
+| 20–31 | 100 star each |
+
+### RPC: `claim_daily_reward`
+
+| Field | Value |
+|---|---|
+| **Function** | `daily_rewards.rpc_claim_daily_reward` |
+| **Auth** | Required |
+| **Purpose** | Claim today's daily reward |
+
+**Params:** None (ignore payload)
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | bool | `true` |
+| `reward_type` | string | `"star"`, `"gold"`, or a fragment ID (starts with `"frag_"`) |
+| `reward_amount` | number | Amount rewarded |
+| `day` | number | Day number (1-indexed) |
+
+**Errors:**
+- `"Not authenticated"`
+- `"Already claimed today"` — `last_claim_date == today`
+- `"Already claimed all rewards for this month"` — day index >= rewards array length
+- `"Already claimed today's reward"` — day index already in `claimed_days`
+
+**Storage reads/writes:**
+- Read: Collection `"daily_rewards"`, key `"state"` (per-user)
+- Read: Collection `"config"`, key `"daily_rewards"`, user `SYSTEM_USER_ID` (config)
+- Write: Collection `"daily_rewards"`, key `"state"` (updates claimed days)
+- Write (if fragment): Collection `"inventory"`, key `"fragments"`
+- Wallet update for star/gold rewards
+
+**Reward types:** `"star"` or `"gold"` → wallet update. `"frag_"` prefix → inventory fragments.
+
+### RPC: `get_daily_reward_state`
+
+| Field | Value |
+|---|---|
+| **Function** | `daily_rewards.rpc_get_daily_reward_state` |
+| **Auth** | Required |
+| **Purpose** | Get current daily reward state and month config |
+
+**Params:** None (ignore payload)
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `state` | object | `{claimed_days, last_claim_date, month}` |
+| `month_rewards` | array | Reward config for current month (array of `{type, amount}`) |
+| `can_claim_today` | bool | Whether user can claim today |
+| `today_date` | string | Today's UTC date (YYYY-MM-DD) |
+| `today_index` | number | Today's 0-based index |
+| `server_month` | number | Current month number |
+
+### RPC: `set_daily_reward_config` [Admin]
+
+| Field | Value |
+|---|---|
+| **Function** | `daily_rewards.rpc_set_daily_reward_config` |
+| **Auth** | Admin required |
+| **Purpose** | Set monthly daily reward configuration |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `config` | object | Yes | Map of month → array of `{type, amount}` rewards. E.g. `{"01": [{type="star", amount=50}, ...]}` |
+
+### RPC: `get_daily_reward_config_admin` [Admin]
+
+| Field | Value |
+|---|---|
+| **Function** | `daily_rewards.rpc_get_daily_reward_config_admin` |
+| **Auth** | Admin required |
+| **Purpose** | Get the current daily reward config |
+
+---
+
+## 9. Admin Module (`admin.lua`)
+
+### RPC: `admin_kick_player`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_kick_player` |
+| **Auth** | Admin **or** match host |
+| **Purpose** | Kick a player from a match |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `match_id` | string | Yes | Match ID |
+| `user_id` | string | Yes | Player to kick |
+| `reason` | string | No | `"Kicked by admin"` |
+
+**Errors:**
+- `"Admin or host privileges required"`
+- `"Cannot kick yourself"`
+- `"Failed to kick player"`
+
+**Mechanism:** Sends `nk.match_signal` with `{action="kick", user_id, reason}`.
+
+### RPC: `admin_ban_player`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_ban_player` |
+| **Auth** | Admin required |
+| **Purpose** | Ban a player (sets metadata.banned, kicks from match) |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `user_id` | string | Yes | User to ban |
+| `reason` | string | No | `"Banned by admin"` |
+| `duration_hours` | number | No | Hours until ban expires (omitted = permanent) |
+| `match_id` | string | No | Also kick from this match |
+
+**Errors:**
+- `"Admin privileges required"`
+- `"Cannot ban yourself"`
+- `"Target account not found"`
+- `"Cannot ban an admin"`
+
+**Storage:** Writes ban record to collection `"bans"`, key = `user_id`, user = `SYSTEM_USER_ID`, permission_read=`2`, permission_write=`0`.
+
+### RPC: `admin_unban_player`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_unban_player` |
+| **Auth** | Admin required |
+| **Purpose** | Remove ban from a player |
+
+**Params (JSON):**
+
+| Field | Type | Required |
+|---|---|---|
+| `user_id` | string | Yes |
+
+### RPC: `admin_get_ban_list`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_get_ban_list` |
+| **Auth** | Admin required |
+| **Purpose** | List all ban records |
+
+### RPC: `admin_get_server_stats`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_get_server_stats` |
+| **Auth** | Admin (or host if `match_id` provided) |
+| **Purpose** | Get server stats (active matches, players) |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `match_id` | string | No | If set, includes match-specific stats |
+
+**Returns (JSON):**
+
+| Field | Type | Description |
+|---|---|---|
+| `active_matches` | number | Count of active matches |
+| `total_players` | number | Total players in matches |
+| `server_time` | number | `os.time()` |
+| `match` | object | (optional) `{id, size, tick_rate, authoritative}` |
+
+### RPC: `admin_end_match`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_end_match` |
+| **Auth** | Admin **or** match host |
+| **Purpose** | Signal a match to end |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `match_id` | string | Yes | Match ID |
+| `reason` | string | No | `"Ended by admin"` |
+
+### RPC: `admin_set_user_role`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_set_user_role` |
+| **Auth** | **Owner only** (role must be `"owner"`) |
+| **Purpose** | Set a user's role |
+
+**Params (JSON):**
+
+| Field | Type | Required | Valid Values |
+|---|---|---|---|
+| `user_id` | string | Yes | Target user |
+| `role` | string | Yes | `"player"`, `"moderator"`, `"admin"` |
+
+**Errors:**
+- `"Only owners can modify user roles"`
+- `"Invalid role"`
+
+### RPC: `admin_topup_gold`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_topup_gold` |
+| **Auth** | Admin required |
+| **Purpose** | Add 999,999 gold to own wallet (dev quick-fill) |
+
+**Wallet update:** `{gold = 999999}`
+
+### RPC: `admin_clear_global_chat`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_clear_global_chat` |
+| **Auth** | Admin required |
+| **Purpose** | Delete all messages from a chat channel |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `channel_id` | string | Yes | Channel ID or room name |
+
+**Returns (JSON):** `{success, deleted}`
+
+### RPC: `admin_list_users`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_list_users` |
+| **Auth** | Admin required |
+| **Purpose** | List all users (limit 500) with role and ban info |
+
+**Returns (JSON):** `{users: [{user_id, username, display_name, create_time, role, banned, ban_reason}], count}`
+
+### RPC: `admin_delete_users`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_delete_users` |
+| **Auth** | Admin required |
+| **Purpose** | Permanently delete user accounts |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `user_ids` | array | Yes | Array of user IDs to delete |
+
+**Errors:**
+- `"Cannot delete your own account"`
+- `"Cannot delete admin account"` (prevents deleting admin/moderator/owner)
+
+**Returns (JSON):** `{success, deleted: [user_ids], failed: [{user_id, reason}]}`
+
+### RPC: `admin_get_user_detail`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_get_user_detail` |
+| **Auth** | Admin required |
+| **Purpose** | Get comprehensive user details (profile, friends, purchases, storage, wallet ledger) |
+
+**Params (JSON):**
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `user_id` | string | Yes | — | Target user ID |
+| `collections` | array | No | `["profiles","stats","inventory","receipts","history","matches","inbox"]` | Storage collections to include |
+
+**Returns (JSON):** Rich object with `{user, friends, purchases, wallet_ledger, storage, subscription}`.
+
+### RPC: `admin_update_user_identity`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_update_user_identity` |
+| **Auth** | Admin required |
+| **Purpose** | Update a user's identity fields (username, display_name, timezone, location, lang_tag, avatar_url, metadata) |
+
+**Params (JSON):**
+
+| Field | Type | Required |
+|---|---|---|
+| `user_id` | string | Yes |
+| `username` | string | No |
+| `display_name` | string | No |
+| `timezone` | string | No |
+| `location` | string | No |
+| `lang_tag` | string | No |
+| `avatar_url` | string | No |
+| `metadata` | object | No (merged into existing metadata) |
+
+### RPC: `admin_set_user_password`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_set_user_password` |
+| **Auth** | Admin required |
+| **Purpose** | Force-set a user's password (user must have email credential) |
+
+**Params (JSON):**
+
+| Field | Type | Required |
+|---|---|---|
+| `user_id` | string | Yes |
+| `password` | string | Yes |
+
+**Errors:**
+- `"User has no email credential"`
+- `"user_id and password are required"`
+
+### RPC: `admin_get_player_list`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_get_player_list` |
+| **Auth** | Admin **or** match host |
+| **Purpose** | Get player list for a match (stub — returns empty) |
+
+### RPC: `admin_get_chat_config`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_get_chat_config` |
+| **Auth** | Admin required |
+| **Purpose** | Get lobby chat configuration |
+
+**Returns (JSON):** `{config: {prefix, max_messages, max_age_days}}`
+
+### RPC: `admin_set_chat_config`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_set_chat_config` |
+| **Auth** | Admin required |
+| **Purpose** | Set lobby chat configuration |
+
+**Params (JSON):**
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `prefix` | string | No | `""` | Chat prefix |
+| `max_messages` | number | No | 50 | Max messages |
+| `max_age_days` | number | No | 0 | Max message age |
+
+**Storage:** Collection `"config"`, key `"lobby_chat"`, user `SYSTEM_USER_ID`.
+
+### RPC: `admin_purge_old_messages`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_purge_old_messages` |
+| **Auth** | Admin required |
+| **Purpose** | Delete chat messages older than specified days |
+
+**Params (JSON):**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `channel_id` | string | Yes | Channel ID or room name |
+| `max_age_days` | number | Yes | Delete messages older than this |
+
+### RPC: `admin_list_channel_messages`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_list_channel_messages` |
+| **Auth** | Admin required |
+| **Purpose** | List messages in a chat channel |
+
+**Params (JSON):**
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `channel_id` | string | Yes | — | Channel ID or room name |
+| `limit` | number | No | 50 | Messages per page |
+| `cursor` | string | No | `""` | Pagination cursor |
+| `forward` | bool | No | `true` | Direction |
+
+### RPC: `admin_delete_channel_message`
+
+| Field | Value |
+|---|---|
+| **Function** | `admin.rpc_admin_delete_channel_message` |
+| **Auth** | Admin required |
+| **Purpose** | Delete a specific chat message |
+
+**Params (JSON):**
+
+| Field | Type | Required |
+|---|---|---|
+| `channel_id` | string | Yes |
+| `message_id` | string | Yes |
+
+---
+
+## 10. Storage Collections Reference
+
+### Collection: `"shop_config"`
+
+| Key | User | Permission Read | Permission Write | Schema |
+|---|---|---|---|---|
+| `featured_banners` | SYSTEM | 2 (public) | 0 (owner) | `{banners: [{item_id, ...}]}` |
+
+### Collection: `"receipts"`
+
+| Key | User | Permission Read | Permission Write | Schema |
+|---|---|---|---|---|
+| `<idempotency_key>` | Owner | 1 (owner-read) | 0 (owner) | `{type, package_id/ item_id, status, changeset, receipt, processed_at, ...}` |
+
+### Collection: `"inventory"`
+
+| Key | User | Permission Read | Permission Write | Schema |
+|---|---|---|---|---|
+| `<item_id>` | Owner | 1 (owner-read) | 0 (owner) | `{category, purchased_at, quantity}` (or `{acquired_via, purchased_at}` for skins) |
+| `"fragments"` | Owner | 1 (owner-read) | 0 (owner) | `{frag_common: N, frag_uncommon: N, frag_rare: N, ...}` |
+
+### Collection: `"profiles"`
+
+| Key | User | Permission Read | Permission Write | Schema |
+|---|---|---|---|---|
+| `"pity_counters"` | Owner | 1 (owner-read) | 0 (owner) | `{star: N, gold: N}` (per-banner pity) |
+| `"fragments"` | Owner | 1 (owner-read) | 0 (owner) | Fragment counts (same as inventory fragments) |
+| `"profile"` | Owner | 2 (public) | 0 (owner) | Profile data (avatar_url, loadout_character, etc.) |
+
+### Collection: `"history"`
+
+| Key | User | Permission Read | Permission Write | Schema |
+|---|---|---|---|---|
+| `"logins"` | Owner | 0 (no-read) | 0 (owner) | `{logins: [{time, ip}, ...]}` (max 20) |
+
+### Collection: `"stats"`
+
+| Key | User | Permission Read | Permission Write | Schema |
+|---|---|---|---|---|
+| `"game_stats"` | Owner | 1 (owner-read) or 2 (public) | 1 (owner-write) or 0 (owner) | `{games_played, games_won, high_score, total_kills, total_deaths, avatar_url, loadout_character}` |
+| `"stats"` | Owner | Varies | 0 (owner) | Legacy/user-level stats |
+
+### Collection: `"inbox"`
+
+| Key | User | Permission Read | Permission Write | Schema |
+|---|---|---|---|---|
+| `"personal"` | Owner | 1 (owner-read) | 0 (owner) | `{mails: [{id, title, content, sender, date, start_date, end_date, expiry_date, rewards, type}]}` |
+| `"state"` | Owner | 1 (owner-read) | 0 (owner) | `{claimed_ids: [string], deleted_ids: [string], read_ids: [string]}` |
+
+### Collection: `"daily_rewards"`
+
+| Key | User | Permission Read | Permission Write | Schema |
+|---|---|---|---|---|
+| `"state"` | Owner | 1 (owner-read) | 0 (owner) | `{claimed_days: [number], last_claim_date: "YYYY-MM-DD", month: "MM"}` |
+
+### Collection: `"config"` (system-level)
+
+| Key | User | Permission Read | Permission Write | Schema |
+|---|---|---|---|---|
+| `"daily_rewards"` | SYSTEM | 2 (public) | 0 (owner) | `{"MM": [{type, amount}, ...]}` (month→rewards map) |
+| `"global_mail"` | SYSTEM | 2 (public) | 0 (owner) | `{mails: [{id, title, content, ...}]}` |
+| `"lobby_chat"` | SYSTEM | 2 (public) | 0 (owner) | `{prefix, max_messages, max_age_days}` |
+
+### Collection: `"bans"`
+
+| Key | User | Permission Read | Permission Write | Schema |
+|---|---|---|---|---|
+| `<user_id>` | SYSTEM | 2 (public) | 0 (owner) | `{user_id, username, banned_by, banned_at, reason, expires}` |
+
+### Collection: `"matches"` (per-user)
+
+| Key | User | Permission | Schema |
+|---|---|---|---|
+| `<match_id>` | Owner | 0 (owner) | Match result data (keyed by match ID, varies) |
+
+---
+
+## 11. Leaderboard Config
+
+| Property | Value |
+|---|---|
+| **ID** | `"global_high_score"` |
+| **Authoritative** | `true` (can only be written server-side) |
+| **Sort Order** | `"desc"` (highest → lowest) |
+| **Operator** | `"best"` (keep best score per user) |
+| **Reset** | `nil` (never auto-resets) |
+| **Created By** | Both `core.lua` and `leaderboard.lua` on module load |
+
+---
+
+## 12. Error Strings Reference
+
+### Auth errors (raised by utils)
+
+| Error String | Trigger |
+|---|---|
+| `"Admin privileges required"` | Non-admin calls admin RPC |
+| `"Admin or host privileges required"` | Non-admin, non-host calls admin/host RPC |
+| `"Not authenticated"` | `context.user_id` is nil |
+
+### Economy errors
+
+| Error String | Trigger |
+|---|---|
+| `"Package ID required"` | `buy_currency` called without `package_id` |
+| `"Idempotency key required"` | Missing `idempotency_key` |
+| `"Invalid package ID"` | Unknown `package_id` |
+| `"InvalidReceipt"` | IAP receipt validation failed |
+| `"NotEnoughFunds"` | Insufficient wallet balance for purchase |
+| `"ItemNotFound"` | Item ID not in shop catalog |
+| `"Invalid quantity"` | Quantity < 1 |
+| `"PurchaseFailed"` | Storage write failed during item purchase |
+| `"Item not found in catalog: <id>"` | Admin tried to banner a non-catalog item |
+
+### User errors
+
+| Error String | Trigger |
+|---|---|
+| `"Account not found"` | User ID doesn't exist |
+| `"Account banned until <time>. Reason: <reason>"` | Temporary ban |
+| `"Account permanently banned. Reason: <reason>"` | Permanent ban |
+| `"Failed to update profile"` | `nk.account_update_id` failed |
+| `"Current password required"` | Email change without current password |
+| `"Incorrect current password."` | Email re-auth failed |
+| `"Failed to set new credentials: <err>"` | Link email failed |
+| `"Missing to_user_id or match_id"` | Lobby invite missing fields |
+| `"Cannot add yourself"` | Friend request to self |
+| `"user_id is required"` | Missing target in friend request |
+
+### Gacha errors
+
+| Error String | Trigger |
+|---|---|
+| `"Banner ID required"` | Missing `banner_id` |
+| `"Invalid count"` | Count < 1 |
+| `"Unknown banner: <id>"` | Invalid banner |
+| `"Could not read account"` | Account lookup failed |
+| `"Insufficient currency"` | Not enough star/gold |
+| `"Failed to update wallet"` | Wallet update failed |
+| `"Failed to write storage: <err>"` | Storage write failed |
+
+### Leaderboard errors
+
+| Error String | Trigger |
+|---|---|
+| `"Failed to submit score"` | Leaderboard write failed |
+| `"Sync failed: <err>"` | Storage list failed |
+| `"User ID and stats are required"` | Missing params in admin_update_stats |
+
+### Inbox errors
+
+| Error String | Trigger |
+|---|---|
+| `"mail_id required"` | Missing mail ID |
+| `"Reward already claimed"` | Mail already in claimed_ids |
+| `"Mail not found"` | Mail ID not in any mailbox |
+| `"Mail not found in global"` | Update/delete: mail not in global |
+| `"Mail not found in personal inbox"` | Update/delete: mail not in personal |
+| `"target_user_id required for personal mail"` | Missing owner for personal mail operations |
+
+### Daily reward errors
+
+| Error String | Trigger |
+|---|---|
+| `"Already claimed today"` | `last_claim_date == today` |
+| `"Already claimed all rewards for this month"` | Day index >= reward array length |
+| `"Already claimed today's reward"` | Day index already in `claimed_days` |
+
+### Admin errors
+
+| Error String | Trigger |
+|---|---|
+| `"Cannot kick yourself"` | Self-kick attempt |
+| `"Failed to kick player"` | Match signal failed |
+| `"Cannot ban yourself"` | Self-ban attempt |
+| `"Target account not found"` | Account lookup failed |
+| `"Cannot ban an admin"` | Target is admin/moderator/owner |
+| `"Only owners can modify user roles"` | Non-owner tries role change |
+| `"Invalid role"` | Role not in `{player, moderator, admin}` |
+| `"channel_id is required"` | Missing channel ID for chat operations |
+| `"channel_id and message_id are required"` | Missing chat message params |
+| `"Failed to delete message: <err>"` | Channel message remove failed |
+| `"Failed to list messages: <err>"` | Channel list failed |
+| `"max_age_days must be > 0"` | Invalid purge param |
+| `"Match not found"` | Match lookup failed |
+| `"User has no email credential"` | Cannot set password for non-email user |
+| `"Cannot delete your own account"` | Self-deletion attempt |
+| `"Cannot delete admin account"` | Deleting admin/moderator/owner |
+| `"No user IDs provided"` | Empty `user_ids` array |
+
+---
+
+## 13. Permission Levels
+
+### Role Hierarchy
+
+| Role | Can Call Admin RPCs | Can Modify Roles | Notes |
+|---|---|---|---|
+| `"player"` | No | No | Default role |
+| `"moderator"` | Yes | No | Same as admin for auth checks |
+| `"admin"` | Yes | No | Standard admin |
+| `"owner"` | Yes | Yes (only owner) | Can set `player`, `moderator`, `admin` roles |
+
+### Auth Check Functions Summary
+
+| Check | What It Allows |
+|---|---|
+| `utils.require_admin` | Any RPC gated by this. Roles: admin, moderator, owner |
+| `utils.require_admin_or_host` | Admin/moderator/owner, OR match host (state.hostUserId) |
+| `metadata.role == "owner"` | Only `admin_set_user_role` |
+
+### Storage Permission Bits
+
+| Value | Meaning |
+|---|---|
+| `0` | Owner only (no one can read/write except server) |
+| `1` | Owner read, server write |
+| `2` | Public read, server write |
+
+### System User ID
+
+```
+00000000-0000-0000-0000-000000000000
+```
+
+Used for global/shared storage collections (bans, config, global_mail, shop_config).
+
+---
+
+## RPC Summary Table
+
+| RPC Name | Module | Auth | Admin? |
+|---|---|---|---|
+| `get_user_profile` | user | None | No |
+| `update_user_profile` | user | Required | No |
+| `search_users` | user | Required | No |
+| `change_credentials` | user | Required | No |
+| `send_lobby_invite` | user | Required | No |
+| `send_friend_request` | user | Required | No |
+| `admin_get_user_history` | user | Required | Yes |
+| `get_shop_catalog` | economy | Required | No |
+| `buy_currency` | economy | Required | No |
+| `purchase_item` | economy | Required | No |
+| `admin_set_featured_banners` | economy | Required | Yes |
+| `admin_get_featured_banners` | economy | Required | Yes |
+| `perform_gacha_pull` | gacha | Required | No |
+| `get_leaderboard_stats` | leaderboard | None | No |
+| `submit_score` | leaderboard | Required | No |
+| `sync_leaderboard` | leaderboard | Required | No |
+| `reset_stats` | leaderboard | Required | No |
+| `admin_update_stats` | leaderboard | Required | Yes |
+| `admin_delete_stats` | leaderboard | Required | Yes |
+| `admin_sync_leaderboard` | leaderboard | Required | Yes |
+| `admin_send_mail` | inbox | Required | Yes |
+| `get_mail` | inbox | Required | No |
+| `claim_mail_reward` | inbox | Required | No |
+| `delete_mail` | inbox | Required | No |
+| `save_mail_state` | inbox | Required | No |
+| `admin_list_mail` | inbox | Required | Yes |
+| `admin_update_mail` | inbox | Required | Yes |
+| `admin_delete_mail_server` | inbox | Required | Yes |
+| `claim_daily_reward` | daily_rewards | Required | No |
+| `get_daily_reward_state` | daily_rewards | Required | No |
+| `set_daily_reward_config` | daily_rewards | Required | Yes |
+| `get_daily_reward_config_admin` | daily_rewards | Required | Yes |
+| `admin_kick_player` | admin | Required | Admin or host |
+| `admin_ban_player` | admin | Required | Yes |
+| `admin_unban_player` | admin | Required | Yes |
+| `admin_get_ban_list` | admin | Required | Yes |
+| `admin_get_server_stats` | admin | Required | Admin or host |
+| `admin_end_match` | admin | Required | Admin or host |
+| `admin_set_user_role` | admin | Required | Owner only |
+| `admin_topup_gold` | admin | Required | Yes |
+| `admin_clear_global_chat` | admin | Required | Yes |
+| `admin_list_users` | admin | Required | Yes |
+| `admin_delete_users` | admin | Required | Yes |
+| `admin_get_user_detail` | admin | Required | Yes |
+| `admin_update_user_identity` | admin | Required | Yes |
+| `admin_set_user_password` | admin | Required | Yes |
+| `admin_get_player_list` | admin | Required | Admin or host |
+| `admin_get_chat_config` | admin | Required | Yes |
+| `admin_set_chat_config` | admin | Required | Yes |
+| `admin_purge_old_messages` | admin | Required | Yes |
+| `admin_list_channel_messages` | admin | Required | Yes |
+| `admin_delete_channel_message` | admin | Required | Yes |
+
+## Wallet Update Summary
+
+| Operation | Changeset | Context |
+|---|---|---|
+| IAP: gold packages (verified) | `{gold: +N}` | `buy_currency` |
+| IAP: star packages | `{star: +N, gold: -N}` | `buy_currency` (costs gold) |
+| Purchase item | `{gold: -N}` or `{star: -N}` | `purchase_item` |
+| Gacha pull | `{<currency>: -cost}` | `perform_gacha_pull` |
+| Claim mail rewards | `{star: +N}` and/or `{gold: +N}` | `claim_mail_reward` |
+| Daily reward | `{star: +N}` or `{gold: +N}` | `claim_daily_reward` |
+| Admin gold top-up | `{gold: 999999}` | `admin_topup_gold` |
+
+All wallet updates use `nk.wallet_update(user_id, changeset, {}, true)` (third arg `true` = update only, no metadata).