# tws-t5-aio notes

Reference for the `tws_*.gsc` files in this repo. Platform quirks and
load-bearing decisions that show up as invariants in the code.

## Install

Copy all `tws_*.gsc` to `storage/t5/scripts/sp/` on the Plutonium T5 server
(v2 Plutainer: `app/runtime/plutonium/storage/t5/scripts/sp/`).

- `sudo chown -R 1000:1000 <app>` — Plutainer runs as UID 1000
- `docker exec <container> rcon-cli map_restart` — reloads scripts in place

## Platform quirks (T5 SP engine, Plutonium)

- **One `level waittill("connected")` only.** `tws_common` owns it. A
  second listener breaks the T5 SP connect handshake. Per-player work goes
  through `tws_common::register_spawn_handler` and gets dispatched after
  `spawned_player`.
- **Chat uses `level waittill("say", ...)`**, not `callbackPlayerSay`. T5 SP
  dedicated disables the sound subsystem, cascading through the say-callback
  dispatch — `callbackPlayerSay` never fires.
- **`SetTimerUp(N)` only ticks when `N == 0`** on T5 SP. Non-zero seeds
  render "0:00" but don't advance. Late joiners see 0, not real elapsed;
  authoritative elapsed lives in `level.match_start_time`.
- **Dynamic text: use `SetValue`, not `SetText`.** `SetText` allocates a
  config string per call; per-tick rebuilds overflow and take the server
  down. Composite strings like `"87/160"` are three elements.
- **`NewClientHudElem(player)`, not `NewHudElem()`.** `NewHudElem` is
  globally owned; in co-op every player's HUD draws on top of every other
  player's. Fall back to `NewHudElem` only if elements don't render at all
  (diagnostic).
- **Zombies namespace is WaW-derived** (`maps\_zombiemode_*`), not BO2's
  `maps\mp\zombies\_zm_*`.
- **Check `t5-gsc-utils` source as well as its README.** Current source
  includes `http::request` and `jsonSerialize` / `jsonParse`, in addition
  to file IO, console commands and MySQL. Telemetry requires a DLL built
  with these HTTP/JSON components; older builds may lack them.
  See [HTTP source](https://github.com/alicealys/t5-gsc-utils/blob/main/src/component/http.cpp)
  and [JSON source](https://github.com/alicealys/t5-gsc-utils/blob/main/src/component/json.cpp).

## Load-bearing decisions

- **Match / round timers anchor to first spawn / first observed round
  transition — never level init.** Anchoring at init included the map-load
  + connect + intro window, producing "displayed 4:00 → frozen 7:00" drift.
  Many BO1 maps pre-set `round_number = 1` at init, so the round watcher
  fires on transitions only and the timer row seeds on first spawn as a
  fallback.
- **Game-over trigger is level-scope, raced across three candidate
  notifies** (`end_game` / `game_ended` / `intermission`) since BO1 maps
  are inconsistent. Per-player triggers do not work — `self waittill("death")`
  is intercepted by the zombiemode scripts before it reaches our scope, and
  polling `self.health` misses the zero-crossing (health is rewritten during
  the game-over sequence).
- **Bank writes DB-first, memory-second.** Every mutation writes to the DB
  and only updates `self.bank` / `self.score` after the write confirms. A
  dead DB can never create phantom money. Deposits use `INSERT ... ON
  DUPLICATE KEY UPDATE`; withdrawals gate on `WHERE balance >= ?` so the DB
  itself blocks overdrafts under concurrent commands.
- **Bank command surface is `command::add_sv` (server console), not chat.**
  SP-engine chat is unreliable and `chat::register_command` isn't available
  in `t5-gsc-utils`.

## Current state / caveats

- `bank_load` in `tws_bank.gsc` is a **diagnostic stub**: bare minimum to
  isolate what specifically kills the connect handshake. Do not restore the
  stripped `getGuid` / MySQL body until the stub passes join cleanly.
- DB credentials in `tws_db.gsc` are hardcoded for the initial fleet test.
  Move to dvars (`tws_db_host` / `tws_db_user` / `tws_db_password` /
  `tws_db_name`) before this repo goes public — otherwise the fleet's DB
  password lives in source.

## Module map

| File | Role | Fires notifies | Reads notifies |
|---|---|---|---|
| `tws_common` | Shared config, HUD helpers, `.help` registry, spawn-handler registry, single connect listener + dispatcher | — | `say` |
| `tws_db`     | MariaDB pool config + reachability probe | `db_probe_done` | — |
| `tws_hud`    | Timer row, zombie count, health bar | `hud_round_changed`, `hud_match_started`, `hud_game_over` | (internal) |
| `tws_bank`   | Persistent bank + `bank` / `deposit` / `withdraw` commands | — | `db_probe_done` |
| `tws_afk`    | `.afk` / `.back` chat toggle, owns its [AFK] indicator | — | — |
| `tws_join`   | `.join` for spectators who have not played on this connection | — | `say`, `end_game`, `game_ended`, `intermission` |
| `tws_lock`   | Lobby `g_password` lock at milestone round (`tws_lock_round`, default 20) | — | `hud_round_changed`, `hud_game_over` |
| `tws_telemetry` | Ordered JSON game start, round, 30-second heartbeat, and game end reports with full player snapshots | `telemetry_queued`, `telemetry_finished` (internal) | `end_game`, `game_ended`, `intermission` |