tws-zombies-scripts/CHANGELOG.md

# Changelog

Changes are listed newest first, with an independent version for every individual
T5/T6 script and each native plugin. Current versions are recorded in
[versions.json](versions.json); see the [version policy](README.md#versioning).

## 2026-10-12

### Public game-bank endpoint — TWS #13

| Component | Version | Affected source |
| --- | --- | --- |
| `tws_t5_bank.gsc` | `2.0.0` | `t5/scripts/tws_t5_bank.gsc` |
| `tws_t6_bank.gsc` | `2.0.0` | `t6/scripts/tws_t6_bank.gsc` |

- Use `https://ec.thewrightserver.net/api/bank` for all balance, transfer and
  settlement requests on both engines. Remove the `tws_bank_url` override;
  stale settings are ignored. This configuration removal requires a major bump.
  Keep EC's `tws_server_id` and private per-instance `tws_bank_token` authentication.
- Both T5 and T6 receive the same behavior with their existing namespaces and
  startup guards. Native plugins and other scripts need no source changes.
- Compatibility: requires companion EC agent `1.9.1+` to recognize public and
  legacy controller-derived journals during authenticated teardown settlement.
  Existing plugin `1.1.0`, common `1.0.0+` and telemetry `1.0.0+` remain sufficient;
  no new native API or third-party dependency requirement.
- Deployment: update agents first. When changing endpoints, **rebuild through
  EC** so the old process stops and its pending decisions settle before a new
  process starts. Do not switch scripts with just a map restart in that case;
  journals are endpoint-scoped. If the old URL already matches exactly, copy the
  scripts and restart the map; no full server-process restart is required.
  See [endpoint upgrade and recovery](README.md#upgrading-the-bank-endpoint).
  No deployment was performed; agent release signing, Windows/GSC compilation
  and live T5/T6 validation remain required.
- Checks: portable script fixtures exercise real initialization with stale
  overrides, every request type, authentication, empty balances and retries.
  Native fixtures cover zero-balance and insufficient-balance replies alongside
  existing durable storage and process-restart checks.

### Persistent cross-game player bank — TWS #3 / Electric Cherry #146

| Component | Version | Affected source |
| --- | --- | --- |
| `tws_t5_bank.gsc` | `1.0.0` | New `t5/scripts/tws_t5_bank.gsc` |
| `tws_t6_bank.gsc` | `1.0.0` | New `t6/scripts/tws_t6_bank.gsc` |
| `t5-plugin` | `1.1.0` | `t5/plugins/tws-t5-gsc-utils/src/component/bank.cpp`, `src/utils/bank.cpp`, `src/utils/bank.hpp` |
| `t6-plugin` | `1.1.0` | `t6/plugins/tws-t6-gsc-utils/src/component/bank.cpp`, `src/utils/bank.cpp`, `src/utils/bank.hpp` |

- Add `.b`, `.d <amount|all>` and `.w <amount|all>` plus help registration on
  both engines. Store shared GUID balances and ledger history through Electric
  Cherry's authenticated bank API. EC generates and injects a private token per
  immutable server instance, preserving it on rebuild/move and revoking it on
  retirement. No manual token map is required;
  the shared telemetry token does not authorize bank operations.
- Add native `bankLoad`, `bankStore`, `bankRemove` and `bankResponse` helpers.
  Save cancellation before preparing a transfer, replace it with a commit
  decision before applying points without yielding, and replay settlement
  after map/process restarts. Invalid replies, insufficient funds, changed
  player state, and failed journal writes leave spendable points unchanged.
  Preserve earned `score_total`; applied withdrawals belong to the current match.
- T5 and T6 receive equivalent behavior with their own namespaces, last-stand
  APIs, entry points and journal directories. Other scripts are unchanged;
  existing common help registration and telemetry match keys already suffice.
- Compatibility: deploy Electric Cherry #146 first, then each game's plugin
  `1.1.0` and bank script `1.0.0`, with common and telemetry `1.0.0` or newer.
  EC host agents `1.9.0+` settle pending journals before destructive teardown.
  No new third-party dependency, upstream pin, or loader version requirement.
  Keep `tws-bank/<game>/` on persistent writable storage; preserve pending
  journals when rotating credentials or restarting servers.
- Deployment: build/install both Windows x86 DLLs and **restart the full server
  processes**, then install the new bank scripts and create/rebuild through EC
  to inject private credentials. Restart maps after script changes. See
  [bank setup and recovery](README.md#player-bank-t5-and-t6).
  No deployment was performed. Windows DLL linking, GSC compilation and live
  Plutonium checks remain required.
- Checks: `node tools/check_bank.mjs` exercises the actual transfer functions;
  `python3 tools/test_plugin_bank.py` checks native journals, response validation,
  failed writes and process recovery with sanitizers. The T6 compiler check
  now includes all eight modules.

### T6 newcomer join eligibility — `tws_t6_join.gsc` `1.0.1`

- Fix `t6/scripts/tws_t6_join.gsc` treating the initial T6 setup spawn as
  gameplay, which rejected a new spectator's `.join` on Farm Survival round 3.
  Wait for the stock delayed spectator transition, then record actual play.
  Continue observing later spawns so waiting for the next round cannot grant
  an extra life after death. Reject requests while a spawn is settling; a real
  death during that window also permanently closes eligibility.
- T5 is unchanged: its separate SP spawn flow and `self.initialized` guard
  do not use T6's delayed game-mode spectator transition.
- Compatibility: existing T6 common `1.0.0` or later; no new dependency
  requirement. Deploy the updated join script to `storage/t6/scripts/zm/`
  and restart the map. No full server-process restart is required.
- Portable regression fixtures: `node tools/check_join.mjs`. Compilation and
  live Plutonium validation remain required; no deployment was performed.

### Persistent top-left Discord URL

| Script | Version | Affected source |
| --- | --- | --- |
| `tws_t5_hud.gsc` | `1.1.0` | `t5/scripts/tws_t5_hud.gsc` |
| `tws_t5_common.gsc` | `1.1.0` | `t5/scripts/tws_t5_common.gsc` |
| `tws_t6_hud.gsc` | `1.1.0` | `t6/scripts/tws_t6_hud.gsc` |
| `tws_t6_common.gsc` | `1.1.0` | `t6/scripts/tws_t6_common.gsc` |

- Add `https://discord.thewrightserver.net` as a small, light-gray top-left
  HUD label, created once per connection, including spectator newcomers.
  It has no expiry or death/respawn reset and is cleaned up on disconnect.
  Move the gameplay stack down 20 HUD units to leave room above the timers;
  help and record positioning follow the shared layout automatically.
- Both engines receive the feature using their existing HUD anchors: T5
  left/top safe-area alignment and T6 fullscreen alignment.
- Compatibility: deploy each game's HUD and common `1.1.0` together for the
  reserved top line. No new native plugin or external dependency requirement.
  Other scripts and both plugins retain their existing versions.
- Deployment: copy the updated HUD and common scripts to `storage/t5/scripts/sp/`
  or `storage/t6/scripts/zm/`, respectively, and restart the map. No full
  server-process restart is required. No deployment has been performed here.
- Live validation remains required on both Plutonium games: check placement
  and readability, join as a spectator, die/respawn, reconnect, and open help
  and records to verify spacing and that only one URL label appears.

### Initial versioning baseline

Established independent version `1.0.0` entries for each of the 14 scripts and
both plugins from source commit
`b508b6739b185d5048e8a8f96ccb16e429f1d37a`. This records the existing source state;
earlier changes remain in Git history without retroactively assigned versions.
The baseline introduces `versions.json`, this changelog, the README links and
version policy, and the maintenance rules in `AGENTS.md`. It changes no game
script or plugin behavior and requires no deployment by itself.

The component entries below summarize the existing functionality and deployment
requirements for servers adopting this baseline. Version assignment does not
indicate that a Windows build, live-game validation, or deployment was performed.

### T5 script baselines

Each row is a separately versioned script under `t5/scripts/`.

| Script | Version | Existing functionality |
| --- | --- | --- |
| `tws_t5_afk.gsc` | `1.0.0` | AFK toggle, protection, and indicator |
| `tws_t5_common.gsc` | `1.0.0` | Shared configuration, helpers, commands, and player dispatchers |
| `tws_t5_hud.gsc` | `1.0.0` | Timers, zombie count, and health display |
| `tws_t5_join.gsc` | `1.0.0` | Immediate join for newcomers |
| `tws_t5_leaderboard.gsc` | `1.0.0` | Map record announcements and `.leaders` command |
| `tws_t5_lock.gsc` | `1.0.0` | Lobby lock at the configured round milestone |
| `tws_t5_telemetry.gsc` | `1.0.0` | Game reports, durable boundary retries, balance and cumulative score |

- Compatibility: these initial script versions use `tws_t5_common.gsc` `1.0.0`;
  lobby lock also needs `tws_t5_hud.gsc` `1.0.0`. Telemetry and leaderboard use
  TWS T5 plugin `1.0.0`. Telemetry additionally requires
  Electric Cherry's match/sequence deduplication and `score_total` support;
  follow the [receiver and plugin rollout order](README.md#telemetry-delivery-and-rollout-t5-and-t6).
  Disabling telemetry by dvar does not remove its native linking requirements.
- Deployment: follow the [T5 installation/upgrade instructions](t5/scripts/README.md#install--upgrade),
  copy the desired scripts and their required dependencies to
  `storage/t5/scripts/sp/`, and restart the map.
  Installing or updating the required plugin needs a full server-process restart.

### T6 script baselines

Each row is a separately versioned script under `t6/scripts/`, adapted to T6 APIs
and map variants.

| Script | Version | Existing functionality |
| --- | --- | --- |
| `tws_t6_afk.gsc` | `1.0.0` | AFK toggle, protection, and indicator |
| `tws_t6_common.gsc` | `1.0.0` | Shared configuration, helpers, commands, and player dispatchers |
| `tws_t6_hud.gsc` | `1.0.0` | Timers, zombie count, and health display |
| `tws_t6_join.gsc` | `1.0.0` | Immediate join for newcomers |
| `tws_t6_leaderboard.gsc` | `1.0.0` | Map record announcements and `.leaders` command |
| `tws_t6_lock.gsc` | `1.0.0` | Lobby lock at the configured round milestone |
| `tws_t6_telemetry.gsc` | `1.0.0` | Game reports, durable boundary retries, balance and cumulative score |

- Compatibility: these initial script versions use `tws_t6_common.gsc` `1.0.0`;
  lobby lock also needs `tws_t6_hud.gsc` `1.0.0`. Telemetry and leaderboard use
  TWS T6 plugin `1.0.0`. Telemetry additionally requires
  Electric Cherry's match/sequence deduplication and `score_total` support;
  follow the [receiver and plugin rollout order](README.md#telemetry-delivery-and-rollout-t5-and-t6).
  Disabling telemetry by dvar does not remove its native linking requirements.
- Deployment: follow the [T6 installation instructions](t6/scripts/README.md#install),
  copy the desired scripts and their required dependencies to
  `storage/t6/scripts/zm/`, and restart the map.
  Installing or updating the required plugin needs a full server-process restart.

### T5 plugin — 1.0.0

- Baseline: the TWS-maintained plugin, including configurable HTTP deadlines,
  status/timing diagnostics, and durable telemetry storage and response helpers.
- Source covered: `t5/plugins/tws-t5-gsc-utils/` and the existing shared plugin
  build/dependency tooling under `tools/`.
- Compatibility: provides the native functions used by `tws_t5_telemetry.gsc`
  `1.0.0` and `tws_t5_leaderboard.gsc` `1.0.0`.
  Upstream source and dependency pins remain in the plugin's `upstream.json`.
  Upstream binary downloads do not include these TWS changes.
- Deployment: [build the x86 DLL on Windows](README.md#building-plugins), install
  `tws-t5-gsc-utils.dll` in `Plutonium/plugins/`, remove the old upstream DLL if
  present, and restart the full server process before loading dependent scripts.

### T6 plugin — 1.0.0

- Baseline: the matching TWS T6 plugin with configurable HTTP deadlines,
  status/timing diagnostics, and durable telemetry storage and response helpers.
- Source covered: `t6/plugins/tws-t6-gsc-utils/` and the existing shared plugin
  build/dependency tooling under `tools/`.
- Compatibility: provides the native functions used by `tws_t6_telemetry.gsc`
  `1.0.0` and `tws_t6_leaderboard.gsc` `1.0.0`.
  Upstream source and dependency pins remain in the plugin's `upstream.json`.
  Upstream binary downloads do not include these TWS changes.
- Deployment: [build the x86 DLL on Windows](README.md#building-plugins), install
  `tws-t6-gsc-utils.dll` in `Plutonium/plugins/`, remove the old upstream DLL if
  present, and restart the full server process before loading dependent scripts.