Add persistent AFK reserves for both engines (Refs #12)

t5/scripts/README.md

@@ -12,7 +12,7 @@ Platform quirks and deploy commands: [NOTES.md](NOTES.md).
 |---|---|
 | [tws_t5_common.gsc](tws_t5_common.gsc) | Shared config, HUD helpers, paginated `.help`, service window, connect/spawn registries, single `connected` listener + dispatcher |
 | [tws_t5_hud.gsc](tws_t5_hud.gsc)       | Unboxed timers, branding, zombies/health and per-player `.hud` visibility toggle |
-| [tws_t5_afk.gsc](tws_t5_afk.gsc)       | `.afk` / `.back` chat toggle + `[AFK]` indicator |
+| [tws_t5_afk.gsc](tws_t5_afk.gsc)       | Persistent AFK reserve, contribution rewards, purchases and central countdown |
 | [tws_t5_join.gsc](tws_t5_join.gsc)     | `.join` lets newcomers spawn before the current round ends |
 | [tws_t5_lock.gsc](tws_t5_lock.gsc)     | Lobby `g_password` lock at a milestone round |
 | [tws_t5_telemetry.gsc](tws_t5_telemetry.gsc) | Direct HTTP game start, round, heartbeat, and game end reports |
@@ -65,8 +65,7 @@ slim health bar at the bottom center. `N ZOMBIES` is one centered element at
 the health track's midpoint, using uniform font scale `1.25` so the whole group
 stays centered as the digit count changes. Its initial placeholder is
 `-- ZOMBIES`. Current/maximum HP appears to the right of the bar only while
-injured; it disappears at full health. The AFK indicator sits above the zombie
-count. There are no panel backgrounds or timer labels.
+injured; it disappears at full health. The AFK reserve countdown is independently centered on screen. There are no panel backgrounds or timer labels.
 Fullscreen X/Y anchors use the normalized `640 × 480` viewport directly and
 bypass safe-area insets. Font scale is at least `1.0`; verify text fit, stock
 HUD overlap and Plutonium tag clearance at each aspect ratio in-game.
@@ -77,7 +76,7 @@ clock. It persists across death and respawn. Clocks, health and zombie-count
 displays freeze at game over. Health fallbacks only affect the display and
 never modify gameplay max health.
 
-The exact, case-insensitive `.hud` command toggles your core and AFK indicator.
+The exact, case-insensitive `.hud` command toggles your core. The AFK countdown stays visible.
 It defaults visible, keeps your choice across death/respawn on the current
 connection/map, and resets visible on reconnect or map restart. Timers and data
 continue updating while hidden; game-over values remain frozen. Help, records
@@ -86,22 +85,22 @@ and the stock HUD are unaffected. `.hud` requires the HUD module.
 Common provides one unboxed upper-right service area below the Plutonium tag.
 Records are right aligned, with `Map record | Round N` followed by up to three
 holder lines; there is no replay footer or single-page counter. Help displays
-the full nine-command list in aligned rows. Services remain private, leave the
+the installed command list in pages of nine rows in aligned rows. Services remain private, leave the
 core in place and work without the HUD module installed. See the
 [shared layout and validation guide](../../README.md#core-hud-and-service-window-t5-and-t6).
 Only the active service view holds HUD elements: 19 for nine-command help
-(20 with a multi-page counter), or four for records (five with a multi-page
+(20 with a multi-page counter; the standard AFK command set uses multiple pages), or four for records (five with a multi-page
 counter). Pages reuse elements; switching views or closing the service releases
 them. Idle services hold no HUD elements, while the controller retains pending
-requests and interruption/resume behavior. Core + AFK use 10 + 1 elements.
+requests and interruption/resume behavior. Core + AFK use 10 + 2 elements.
 
 HUD `1.4.2` requires common `1.4.0+` and
 [Plutonium r5334+](https://plutonium.pw/docs/changelog/#r5334) for its
 `SetTextUnlimited` counter, updated only when the count changes. Deploy the
 updated HUD script and restart the map on r5334+; no full server-process
 restart is required. Older Plutonium revisions need client/server updates and
-full restarts first. AFK `1.2.0` and leaderboard `1.1.0` remain compatible;
-AFK still requires common `1.4.0+`. No new native-plugin or backend requirement.
+full restarts first. Leaderboard `1.1.0` remains compatible. AFK `2.0.0` requires the matching
+plugin `1.4.0+` and EC reserve service; see the [AFK guide](../../docs/afk.md).
 
 ## Map record announcements
 
@@ -133,8 +132,8 @@ explicit row positions so T5 does not concatenate newline-separated text.
 | Command | Effect |
 |---|---|
 | `.help`, `.commands` | List available commands |
-| `.hud` | Hide or show your core HUD and AFK indicator (HUD module required) |
-| `.afk` | Pause with protection |
+| `.hud` | Hide or show your core HUD (AFK countdown stays visible) |
+| `.afk` | Enter protected AFK using your time reserve |
 | `.back` | Return from AFK |
 | `.join` | Join mid-round (newcomers only) |
 | `.leaders` | Show the map record again (leaderboard module required) |
@@ -282,9 +281,9 @@ gameplay updates start through the existing spawn lifecycle.
 
 **Features**
 - Upper-left match timer above round timer (round resets each round, both freeze on game over)
-- `.hud` toggles this player's core and AFK indicator; data updates continue while hidden
+- `.hud` toggles this player's core; the AFK countdown stays visible and data updates continue
 - Top-center `TWS ZOMBIES | discord.tws.lol` branding
-- One `N ZOMBIES` element centered above the health track, with the AFK indicator above it
+- One `N ZOMBIES` element centered above the health track, separate from the central AFK countdown
 - Slim health bar with green / amber / red ramp; current/maximum HP appears
   beside it only while injured
 - Spectator placeholders without starting the match clock on connection
@@ -319,32 +318,16 @@ without seeding clocks; `hud_start` calls it as a fallback if needed.
 
 ## tws_t5_afk.gsc
 
-Self-invoked pause mode. Owns the `[AFK]` indicator element, centered above the
-zombie count through common layout values. It does not require HUD.
+Persistent protected breaks using the shared GUID reserve. See the
+[AFK guide](../../docs/afk.md) for commands, policy, ownership, native APIs,
+crash recovery and live validation. Requires common `1.4.0+`, telemetry `1.0.0+`,
+matching plugin `1.4.0+`, Plutonium r5334+ and EC #151.
 
-**Features**
-- Chat commands `.afk` and `.back` (via `level waittill("say")` — not
-  `callbackPlayerSay`, which never fires on T5 SP dedicated)
-- On enter: `enableInvulnerability`, `freezeControls(true)`,
-  `self.ignoreme = true` (drops out of zombie targeting)
-- On exit: reverse, then a 2s grace tail keeps invuln + ignoreme through
-  the target-reacquisition window
-- `[AFK]` HUD element created per-player via spawn handler; alpha-toggled
-  by enter / exit through common's core visibility helpers, respecting `.hud`
-
-**Provides**
-- Per-player: `self.hud_afk_on` (bool), `self.hud_afk_elem` (HUD element),
-  writes `self.ignoreme` (stock BO1 targeting flag)
-- Level var: `level.afk_grace_seconds` (default 2)
-
-**Depends on**
-- `scripts\sp\tws_t5_common::` — `ensure_config`, `make_core_overlay_text`,
-  `set_core_alpha`, `destroy_on_disconnect`, `register_spawn_handler`, `register_help_command`
-- Shared config: overlay AFK position, `level.hud_font_afk`, `level.hud_c_afk`
-- Stock BO1: `enableInvulnerability`, `disableInvulnerability`,
-  `freezeControls`, `.ignoreme`, `level waittill("say", message, player)`
-
-Spawn handler registered: `::afk_spawn`.
+Chat uses `level waittill("say")`; the independent central countdown stays visible
+with `.hud` hidden. Activation rejects laststand before changing state. A stock
+damage callback owns only AFK protection; expiration immediately relinquishes it
+and AFK-owned controls/targeting, while manual `.back` keeps its separate two-second
+grace. Spawn handler `::afk_spawn` binds contribution and lifecycle watchers.
 
 ---
 
@@ -614,3 +597,10 @@ process. No database is required.
 Optional `tws_t5_moderation.gsc` 1.0.0 requires common 1.2.0 and the matching
 plugin 1.3.0. See the [moderation contract](../../docs/moderation.md) for private
 configuration, persistence, action results and deployment checks.
+
+## Persistent AFK reserve
+
+AFK `2.0.0` uses EC authorization and a local central countdown. See the
+[shared AFK guide](../../docs/afk.md) for exact commands, dependencies, recovery
+and live checks. Install plugin `1.4.0+` and fully restart the server process.
+The countdown remains visible with `.hud` hidden; expiration has no grace period.