adventureland/docs/admin/api.md

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

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)

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)

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)

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.

# 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