add admin docs

2026-11-08 02:16:03 +01:00
parent 793797dacb
commit b70127a57b
3 changed files with 635 additions and 0 deletions
@@ -0,0 +1,130 @@
+# Game-Server-API (`/server.api/...`)
+
+Der Game-Server läuft separat vom Backend und lauscht lokal auf Port `7192`.
+Seine Admin-Endpunkte liegen unter `/server.api/` und sind **nicht** die
+öffentliche JSON-API des Backends (`/api`).
+
+## Endpunkte
+
+| Methode | Endpunkt | Zweck |
+|---|---|---|
+| `POST` | `/server.api/eval` | JavaScript im Game-Server ausführen |
+| `POST` | `/server.api/cupdate` | Shells eines online Characters setzen |
+| `POST` | `/server.api/shutdown` | Game-Server herunterfahren |
+| `POST` | `/server.api/new_friend` | intern: Freund hinzufügen |
+| `POST` | `/server.api/lost_friend` | intern: Freund entfernen |
+
+Alle diese Endpunkte verlangen `spass` = `keys.ACCESS_MASTER`. Der Key erlaubt
+beliebige Codeausführung im Game-Server und darf niemals öffentlich werden.
+
+## `ACCESS_MASTER` lesen
+
+```sh
+cd /data/ai/gaming/adventureland
+
+ACCESS_MASTER="$(docker compose exec -T al-game node -e \
+  'process.stdout.write(require("/app/secretsandconfig/keys").ACCESS_MASTER)')"
+```
+
+Den Wert nicht in Chat, Logs oder Commits schreiben.
+
+## `/server.api/eval`
+
+Felder:
+
+- `spass` – `ACCESS_MASTER`
+- `code` – JavaScript, wird im Game-Server ausgeführt
+- `data` – JSON-String, im Code als `data` verfügbar
+
+Der Code läuft im Modul-Scope des Game-Servers. Verfügbar sind unter anderem
+`players`, `name_to_id`, `get_player(name)`, `add_item`, `resend`,
+`calculate_player_stats` und `output`.
+
+### Gold geben (live)
+
+```sh
+curl -sS -X POST http://127.0.0.1:7192/server.api/eval \
+  --data-urlencode "spass=$ACCESS_MASTER" \
+  --data-urlencode 'code=var p=get_player("CharName"); if(p){ p.gold += 100000; resend(p,"reopen+u+cid"); output={ok:true,gold:p.gold}; } else { output={ok:false,reason:"offline"}; }' \
+  --data-urlencode 'data={}'
+```
+
+### Item geben (live)
+
+```sh
+curl -sS -X POST http://127.0.0.1:7192/server.api/eval \
+  --data-urlencode "spass=$ACCESS_MASTER" \
+  --data-urlencode 'code=var p=get_player("CharName"); if(p){ var n=add_item(p,{name:"hpot0",q:100},{announce:false}); resend(p,"reopen+u+cid"); output={ok:true,slot:n}; } else { output={ok:false,reason:"offline"}; }' \
+  --data-urlencode 'data={}'
+```
+
+`add_item` prüft Inventarplatz und stapelt stackbare Items. `announce:false`
+verhindert eine globale Fundmeldung.
+
+### XP geben (live)
+
+```sh
+curl -sS -X POST http://127.0.0.1:7192/server.api/eval \
+  --data-urlencode "spass=$ACCESS_MASTER" \
+  --data-urlencode 'code=var p=get_player("CharName"); if(p){ p.xp += 100000; resend(p,"reopen"); output={ok:true,level:p.level,xp:p.xp}; } else { output={ok:false,reason:"offline"}; }' \
+  --data-urlencode 'data={}'
+```
+
+`resend(p,"reopen")` ruft `calculate_player_stats` auf und führt Level-Ups aus.
+
+## `/server.api/cupdate`
+
+Felder:
+
+- `spass` – `ACCESS_MASTER`
+- `id` – Character-Name (`player.id` ist der Name, nicht `CH_...`)
+- `cash` – neuer Gesamtstand der Shells
+- `ncash` – Betrag für die „received shells“-Meldung; wird **nicht** addiert
+
+`cupdate` setzt `player.cash` auf `cash`. Es ist kein Inkrement. Deshalb zuerst
+den neuen Gesamtstand in MongoDB schreiben und dann `cupdate` aufrufen.
+
+```sh
+# 1. Account-Cash erhöhen
+docker compose exec al-mongo mongosh adventureland --eval \
+  'db.user.updateOne({"info.email":"du@example.com"}, { $inc: { cash: 1000 } })'
+
+# 2. Neuen Gesamtstand lesen
+NEW_TOTAL="$(docker compose exec -T al-mongo mongosh adventureland --quiet --eval \
+  'db.user.findOne({"info.email":"du@example.com"},{cash:1}).cash')"
+
+# 3. Online-Character aktualisieren
+curl -sS -X POST http://127.0.0.1:7192/server.api/cupdate \
+  --data-urlencode "spass=$ACCESS_MASTER" \
+  --data-urlencode 'id=CharName' \
+  --data-urlencode "cash=$NEW_TOTAL" \
+  --data-urlencode 'ncash=1000'
+```
+
+Ohne online Character reicht der MongoDB-Wert; beim nächsten Login wird
+`user.cash` geladen.
+
+## Wichtige Hinweise
+
+- **Shells** sind accountweit (`user.cash`). Ein `/cupdate` ändert nur die
+  laufende Kopie im Game-Server; die DB muss separat aktualisiert werden.
+- **Gold** ist pro Character (`character.info.gold` / `player.gold`) oder
+  accountweit in der Bank (`user.info.gold`).
+- `eval` ist mächtig und ungefiltert. Nur lokal oder hinter einer
+  vertrauenswürdigen Admin-Schicht betreiben.
+- `aadd_item` nicht verwenden: Es ruft `reopen()` auf, das im Node-Port nicht
+  definiert ist. Stattdessen `add_item` + `resend`.
+- Der Game-Server speichert live geänderte Character-Daten regelmäßig. Für
+  dauerhafte Änderungen an Offline-Characters die MongoDB-Variante verwenden;
+  für laufende Characters `eval`.
+- `ACCESS_MASTER` rotieren, bevor der Port öffentlich erreichbar ist. Der
+  Default steht in `files/config/keys.js`.
+
+## Quellen
+
+- `source-repos/adventureland_mongodb/node/server.js` – `server_api`-Router,
+  `/eval`, `/cupdate`, `/shutdown`; `add_item`, `resend`
+- `source-repos/adventureland_mongodb/adventure_functions.js` –
+  `server_url`, `server_eval`, `server_eval_safe`, `character_eval`
+- `files/config/options.js` – `api_path: "/server.api/"`, `local_port: 7192`
+- `source-repos/adventureland_mongodb/README.md` – Admin-/Executor-Hinweise