tws-zombies-scripts/t6/scripts/README.md

# TWS T6 Zombies scripts

Plutonium T6 versions of the T5 server scripts. Defaults live in the scripts,
just like T5. The telemetry token is embedded in the reporter script; no
separate token config or database setup is required.

| File | Role | Dependencies |
| --- | --- | --- |
| `tws_t6_common.gsc` | Shared HUD values, helpers, `.help`, connection and first-spawn dispatchers | Stock T6 |
| `tws_t6_hud.gsc` | Match/round timers, name, zombie count and health bar | Common |
| `tws_t6_afk.gsc` | `.afk` / `.back`, protection, movement and weapon blocking | Common |
| `tws_t6_lock.gsc` | Lock at round 20; clear password on game over | Common, HUD |
| `tws_t6_telemetry.gsc` | Async queued game reports (game_start/heartbeat/round_change/game_end) | tws-t6-gsc-utils |
| `tws_t6_join.gsc` | `.join` chat command lets a spectator newcomer enter mid-match once | Common |
| `tws_t6_leaderboard.gsc` | Private map high-round record and every tied holder on connection | Common, tws-t6-gsc-utils |

## Install

1. Copy all seven `tws_t6_*.gsc` files into
   `Plutonium/storage/t6/scripts/zm/`. Update common along with leaderboard.
2. For telemetry or leaderboard, install the [tws-t6-gsc-utils build](../plugins/README.md), based on upstream v3.1.1,
   in `Plutonium/plugins/` and restart the server process. The other five scripts
   do not require that plugin.
3. Ensure the API service's `EC_TELEMETRY_TOKEN` matches the token embedded in
   the reporter; see [authentication setup](../../README.md#telemetry-authentication-t5-and-t6).
4. Restart the map to load script updates.

If upgrading from the earlier leaderboard filename, **remove
`tws_leaderboard.gsc` from the T6 server script directory** before installing
`tws_t6_leaderboard.gsc`, so both copies do not load.

If updating an existing deployment, **remove `tws_t6_db.gsc` and
`tws_t6_bank.gsc` from the server script directory**. Copying the remaining files
will not remove those old scripts. Remove any `exec server.example.cfg` added for
the earlier version. Neither a database nor that config file is used anymore.

Source `.gsc` files load directly under Plutonium's
[documented T6 script layout](https://plutonium.pw/docs/modding/loading-mods/).
Keep the filenames and `scripts/zm` location so shared references resolve.
To omit telemetry, remove its script; disabling it at runtime does not remove
its plugin dependency during linking. The same rule applies to leaderboard.

## Map record announcements

`tws_t6_leaderboard.gsc` reads the public Electric Cherry API without credentials.
It works independently of telemetry and HUD, and privately announces records
once per connection, including newcomers waiting in spectator mode.

Map selection uses stock `level.scr_zm_ui_gametype` and
`level.scr_zm_map_start_location`, falling back to the corresponding
`ui_gametype` / `ui_zm_mapstartlocation` dvars when absent. For example,
`zstandard` + `town` selects `t6:zm_transit:town`, while `zclassic` + `transit`
selects TranZit. Survival, Grief and Turned variants follow Electric Cherry's
catalogue. An unknown mode/location is logged instead of guessing from the engine
map. Use `tws_leaderboard_map_key` for a custom registered selection if needed.

The plugin must expose `httpPost` (with the GET method override), `jsonParse`,
`typeof` and `formatString`. [Shared configuration, caching and validation](../../README.md#map-record-announcements)
apply to both versions. All T6 script filenames use the `tws_t6_` prefix.

## Chat commands

Type `.help` or `.commands` in chat to see the commands supplied by the loaded TWS modules and
a short description of each. The list is shown only to the requesting player,
including spectators who have not spawned. Commands are case-insensitive.
Help appears below the health bar for 12 seconds, clear of the timers, zombie
counter and health display. Typing either command again restarts that display time.

| Command | Description |
| --- | --- |
| `.help`, `.commands` | List available commands |
| `.afk` | Pause with protection |
| `.back` | Return from AFK |
| `.join` | Join mid-round (newcomers only) |
| `.leaders` | Show the map record again (leaderboard module required) |

AFK and Join register their commands during `init()` through
`tws_t6_common::register_help_command(command, description)`. If a module is
omitted, its commands are omitted from `.help`. Register new commands alongside
their module's initialization so the list stays current.
The enabled leaderboard module registers `.leaders`, which replays the latest
cached map record privately. Repeating it restarts the record from the first page;
help temporarily hides the record until its own display ends.

## Defaults, matching T5

- HUD values live in `tws_t6_common::common_config()`. That function and
  `ensure_config()` came from T5; they initialize in-script values and do not
  load a config file. The requested fullscreen corner alignment is retained.
- AFK uses T5's native `level waittill("say", message, player)` listener.
  `.back` restores movement and weapons immediately, then ends protection after
  two seconds. The T6 control/weapon fix remains in place.
- Lock uses T5's HUD round/game-over notifications. Default threshold is 20.
  As in T5, it clears `g_password` at startup and game over.
- Telemetry is enabled by default and posts to
  `https://ec.thewrightserver.net/api/telemetry`. Set `tws_server_id` to the exact,
  case-sensitive Electric Cherry registry name; missing or overlong names
  disable reporting with a console diagnostic. An embedded token matching the service's
  `EC_TELEMETRY_TOKEN` (at least 32 characters) and an HTTPS URL are required as well.

The dvars already present in T5 are still supported: `tws_lock_round`,
`tws_server_id`, `tws_telemetry_url`, and `tws_telemetry_enabled` (`0` disables
telemetry). Earlier settings still override defaults; remove any old HTTP URL
override when upgrading. The reporter token lives in `level.telemetry_token`.

## Round telemetry

Telemetry runs directly in GSC using tws-t6-gsc-utils. Configure the exact Electric
Cherry registry name and full endpoint in your existing server configuration:

```cfg
set tws_server_id "t6_zombie_town_1"
set tws_telemetry_url "https://ec.thewrightserver.net/api/telemetry"
```

The script embeds the reporter token in `level.telemetry_token`; it must match
the API service's `EC_TELEMETRY_TOKEN` environment variable. Follow the shared
[authentication setup](../../README.md#telemetry-authentication-t5-and-t6). Every
request includes `Authorization: Bearer <token>` and `Content-Type:
application/json`. Token rotation requires updating and redeploying both reporter
scripts. Token and endpoint changes require a map restart.

It sends four event types over the life of a match, mirroring the T5 script:

| Event | When | Round in payload |
| --- | --- | --- |
| `game_start` | First playable spawn | omitted |
| `heartbeat` | Every 30s while the match is in progress | current round |
| `round_change` | Every new positive round | new round |
| `game_end` | `end_game` / `game_ended` / `intermission` | final round |

Each event payload includes `event`, `server`, `map`, `match`, `seq`, `round` (except `game_start`)
and a `players` array with `name`, `guid`, `kills`, `headshots`, `downs`, `revives`
and `score` per player. `guid` reads Plutonium's `player.guid` engine property
(T5 uses the `player getGuid()` method — T6 has no such method, but the field is
equivalent for identity purposes). `kills`/`headshots`/`downs`/`revives` read
from T6's stock match counters in `player.pers[]`; missing or negative values
are reported as `0`. `score` is the player's current spendable `player.score`.

Delivery uses one in-flight request and a FIFO queue. Every match receives a
native-generated key; `seq` starts at 1 for `game_start` and increases at capture.
Start/end snapshots are saved to disk before sending and replayed before the next
start after map/process restarts. Transport failures, native timeouts, HTTP 429
and 5xx retain the head with 1–30 second backoff. Other 4xx are terminal. Round
and heartbeat failures remain best effort; waiting heartbeats collapse to the
newest snapshot. Acceptance requires 2xx plus the JSON boolean `ok: true`; logs
include `telemetry.timing.matchId` as `ec_match_id` when available.

The TWS plugin still enforces 5-second connection and 15-second transfer deadlines.
Increase `tws_telemetry_log_level` to `2` for capture/queue/response logging; set to
`0` for errors and recovery. **Deploy Electric Cherry #144 and the updated native
plugin before these scripts.** See the shared
[delivery and rollout notes](../../README.md#telemetry-delivery-and-rollout-t5-and-t6)
for outbox storage, error handling, limits and live validation.

## `.join` for newcomers

Late connectors who never got a spawn can type `.join` in chat to leave spectator
mode before the round ends, once per connection. `.join` is rejected if the player
has already played, if the game is not running, if no active player is alive, or
during intermission. The script hooks the stock `spectator_respawn` path via
`level.custom_spawnplayer`; it does not skip the map-authored spawn callback if
another mod installed one first.

## Validation

To compile all seven scripts for T6 PC with gsc-tool:

```powershell
.\tools\check.ps1 -CompilerPath C:\path\to\gsc-tool.exe
```

Compilation does not verify engine/plugin linking or gameplay. T6 differences,
research sources and live checks are in [NOTES.md](NOTES.md).