Add persistent cross-game player bank (Refs #3)

README.md

@@ -40,7 +40,7 @@ Versions use `MAJOR.MINOR.PATCH`: increase the patch for fixes and internal
 changes, the minor for compatible features, and the major for breaking changes
 to commands, configuration, native APIs, or data contracts. Reset lower fields
 when increasing the minor or major. Bump once per logical change; documentation-only
-and test-only changes are exempt. All 14 scripts and both plugins advance independently.
+and test-only changes are exempt. All 16 scripts and both plugins advance independently.
 
 The initial `1.0.0` versions document the existing source baseline. These TWS
 versions are separate from upstream revisions in each plugin's `upstream.json`
@@ -170,8 +170,64 @@ Modules currently in each tree:
 | lock       | `t5/scripts/tws_t5_lock.gsc`             | `t6/scripts/tws_t6_lock.gsc`            |
 | telemetry  | `t5/scripts/tws_t5_telemetry.gsc`        | `t6/scripts/tws_t6_telemetry.gsc` — queued `game_start` / `heartbeat` / `round_change` / `game_end` matching T5 |
 | join       | `t5/scripts/tws_t5_join.gsc`             | `t6/scripts/tws_t6_join.gsc`            |
+| bank | `tws_t5_bank.gsc` | `tws_t6_bank.gsc` — persistent shared GUID bank |
 | leaderboard | `t5/scripts/tws_t5_leaderboard.gsc`    | `t6/scripts/tws_t6_leaderboard.gsc`        |
 
+## Player bank (T5 and T6)
+
+Install `tws_t5_bank.gsc` or `tws_t6_bank.gsc` alongside the game's common and
+telemetry scripts (`1.0.0` or later). Players can use `.b` to read their balance,
+`.d <amount|all>` to deposit spendable points, and `.w <amount|all>` to withdraw.
+Configured bank modules register all three commands in `.help`. Balances are
+shared by GUID across games and survive map/server restarts. Transfers do not
+change `score_total`; bank-assisted matches still count on existing leaderboards.
+
+Deploy [Electric Cherry #146](https://gitea.thewrightserver.net/josh/electric-cherry/issues/146)
+first, then build/install both native plugins `1.1.0` and **restart the server
+processes**. The plugins provide `bankLoad`, `bankStore`, `bankRemove` and
+`bankResponse`. Removing the bank script is necessary to omit these linking
+requirements; disabling it by dvar does not avoid linking.
+
+Electric Cherry generates a unique bank token when it prepares a native server
+instance and injects it through that instance's private
+`electric_cherry_bank.cfg`. It sets `tws_server_id`, `tws_bank_token` and
+`tws_bank_url` automatically. Rebuilds and host moves keep the instance token;
+destroying the instance revokes it. Reusing a server name gets a new token.
+There is no `EC_BANK_TOKENS` map or per-server secret to maintain. Keep secrets
+outside shared scripts and promoted configs. The URL must use HTTPS.
+Set `tws_bank_enabled 0` to disable the module; restart maps after script/config changes.
+Electric Cherry's `EC_BANK_MAX_BALANCE` defaults to 250000 (range 1–1000000).
+Each transfer and bank-funded spendable balance is capped at 1000000 points.
+
+Transfers require a living player recorded in the server's current telemetry
+match. Newcomers may wait until the next 30-second heartbeat. The game validates
+points and player state again after a prepare reply; failed or uncertain
+prepares leave game points unchanged and cancel the reservation. After points
+move, a durable commit decision retries settlement without applying them again.
+A transfer in progress blocks new bank requests on that server. A GUID can
+have only one prepared transfer across the fleet.
+
+Preserve `tws-bank/t5/` and `tws-bank/t6/`, relative to the game process working
+directory, across process/container restarts, with one process per server/endpoint
+directory. EC host agents **1.9.0+** settle
+pending journals before deleting runtime storage on removal, rebuild, migration
+or launch cancellation. Update the agents before enabling the bank. An outage
+or invalid journal blocks cleanup and preserves the files. Decisions are scoped
+to server name and URL and contain no token. Recoveries run before new bank requests;
+failed cleanup/replies retry with the original identity. Corrupt storage
+blocks the bank; failed writes prevent points changes. Restore storage or
+credentials to finish pending work, rather than deleting the journal. Holds
+have no automatic expiry. Already-applied withdrawals are match points and
+are not refunded when a match ends or its process crashes. As with any live
+score, the journal cannot make game memory and the remote database atomic
+across a machine/storage failure.
+
+Run `node tools/check_bank.mjs` and `python3 tools/test_plugin_bank.py`.
+Before rollout, build/link Windows DLLs, compile GSC, and verify both games:
+help, balance and `all` commands, score HUD/persistence, max/overdraw errors,
+death/respawn/disconnect during HTTP, late telemetry, lost prepare/commit
+responses, disk failures and map/process restart with pending decisions.
+
 ## Map record announcements
 
 Install `tws_t5_leaderboard.gsc` for T5 or `tws_t6_leaderboard.gsc` for T6,