Add modular chat help for T5 and T6

t5/NOTES.md

@@ -76,7 +76,7 @@ Copy all `tws_*.gsc` to `storage/t5/scripts/sp/` on the Plutonium T5 server
 
 | File | Role | Fires notifies | Reads notifies |
 |---|---|---|---|
-| `tws_common` | Shared config, HUD helpers, spawn-handler registry, single connect listener + dispatcher | — | — |
+| `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` |

t5/README.md

@@ -11,7 +11,7 @@ Platform quirks and deploy commands: [NOTES.md](NOTES.md).
 
 | File | Role |
 |---|---|
-| [tws_common.gsc](tws_common.gsc) | Shared config, HUD helpers, spawn-handler registry, single `connected` listener + dispatcher |
+| [tws_common.gsc](tws_common.gsc) | Shared config, HUD helpers, `.help`, spawn-handler registry, single `connected` listener + dispatcher |
 | [tws_db.gsc](tws_db.gsc)         | MariaDB pool config + reachability probe |
 | [tws_hud.gsc](tws_hud.gsc)       | Bottom-left HUD stack: timers, zombie count, health bar |
 | [tws_bank.gsc](tws_bank.gsc)     | Persistent per-player bank + console commands |
@@ -20,6 +20,25 @@ Platform quirks and deploy commands: [NOTES.md](NOTES.md).
 | [tws_lock.gsc](tws_lock.gsc)     | Lobby `g_password` lock at a milestone round |
 | [tws_telemetry.gsc](tws_telemetry.gsc) | Direct HTTP game start, round, heartbeat, and game end reports |
 
+## Player commands
+
+Type `.help` in chat to see available player commands and a short description.
+The response is visible only to the requesting player and works while spectating,
+before the first spawn. Commands are case-insensitive.
+Help appears below the health bar for 12 seconds, clear of the timers, zombie
+counter and health display. Typing `.help` again restarts that display time.
+
+| Command | Effect |
+|---|---|
+| `.help` | List available commands |
+| `.afk` | Pause with protection |
+| `.back` | Return from AFK |
+| `.join` | Join mid-round (newcomers only) |
+
+Each module registers its own help entries; removing AFK or join also removes
+those entries from `.help` after a map restart. The bank's `bank`, `deposit`, and
+`withdraw` commands are server-console commands and are not listed in chat help.
+
 ## Dependency graph
 
 Arrows read "depends on" — solid means the source names the target with
@@ -80,6 +99,7 @@ connect listener anywhere else crashes the T5 SP handshake.
 - Shared HUD constants: `level.hud_x`, `hud_y`, `hud_row_*`, `hud_col_*`,
   `hud_font_*`, `hud_bar_*`, `hud_c_*`, `hud_rate`, `hud_health_threshold`
 - Spawn-handler registry
+- `.help` listener and help registry populated by installed command modules
 - Connect listener + per-player dispatch: iterates
   `level.tws_spawn_handlers` after `spawned_player` and threads each on
   the player
@@ -90,6 +110,7 @@ connect listener anywhere else crashes the T5 SP handshake.
 | `common_config()`                  | Populate every `level.hud_*` (idempotent) |
 | `ensure_config()`                  | No-op if config already set; called by every module's `init` |
 | `register_spawn_handler(fn)`       | Appends `::fn` to `level.tws_spawn_handlers` |
+| `register_help_command(command, description)` | Adds a player command to `.help`; call from the owning module's `init()` |
 | `make_text_elem(p, x, y, ax, s, c)`| `NewClientHudElem` text element with black-glow outline |
 | `make_shader_elem(p, x, y)`        | `NewClientHudElem` shader element |
 | `destroy_on_disconnect(elems)`     | Waits on `disconnect`, destroys the array |
@@ -98,6 +119,18 @@ connect listener anywhere else crashes the T5 SP handshake.
 
 **Depends on**: nothing (leaf module).
 
+**Live validation (requires a T5 server)**
+
+1. Type `.help` and `.HELP` while playing and while spectating before the first
+   spawn. Verify all four descriptions appear below the health bar, only for the
+   requesting player. Take damage so health numbers are visible and check that
+   they do not cover the help text.
+2. Remove AFK or join, restart the map, and verify its entries disappear while
+   `.help` and the remaining commands still work. Restore the scripts afterward.
+3. Repeat `.help` before 12 seconds elapse; verify one list stays visible for
+   12 seconds after the latest request, then hides. Reopen it after expiry,
+   die/respawn and reconnect; verify no duplicate text or leftover help elements.
+
 ---
 
 ## tws_db.gsc
@@ -219,7 +252,7 @@ module has zero knowledge of AFK.
 
 **Depends on**
 - `scripts\sp\tws_common::` — `ensure_config`, `make_text_elem`,
-  `destroy_on_disconnect`, `register_spawn_handler`
+  `destroy_on_disconnect`, `register_spawn_handler`, `register_help_command`
 - Shared config: `level.hud_x`, `level.hud_row_match`,
   `level.hud_font_small`, `level.hud_c_afk`
 - Stock BO1: `enableInvulnerability`, `disableInvulnerability`,

t5/tws_afk.gsc

@@ -13,6 +13,8 @@ init()
         return;
 
     scripts\sp\tws_common::ensure_config();
+    scripts\sp\tws_common::register_help_command(".afk", "Pause with protection");
+    scripts\sp\tws_common::register_help_command(".back", "Return from AFK");
 
     afk_init();
 

t5/tws_common.gsc

@@ -1,4 +1,4 @@
-/* tws_common.gsc — shared config, HUD helpers, spawn-handler registry, connect dispatcher. */
+/* tws_common.gsc — shared config, HUD helpers, spawn/help registries, connect dispatcher. */
 
 #include maps\_utility;
 #include common_scripts\utility;
@@ -10,6 +10,8 @@ init()
 
     common_config();
 
+    register_help_command(".help", "List available commands");
+    level thread help_chat_listener();
     level thread on_player_connect_dispatch();
 }
 
@@ -72,6 +74,84 @@ register_spawn_handler(fn)
     level.tws_spawn_handlers[level.tws_spawn_handlers.size] = fn;
 }
 
+// Modules register their own entries so help only lists installed commands.
+register_help_command(command, description)
+{
+    if (!isDefined(level.tws_help_commands))
+        level.tws_help_commands = [];
+
+    entry = spawnStruct();
+    entry.command = command;
+    entry.description = description;
+    level.tws_help_commands[level.tws_help_commands.size] = entry;
+}
+
+// Listen at level scope so newcomers can ask for help before their first spawn.
+help_chat_listener()
+{
+    for (;;)
+    {
+        level waittill("say", message, player);
+
+        if (!isDefined(player) || !isDefined(message))
+            continue;
+
+        if (toLower(message) == ".help")
+            player show_help();
+    }
+}
+
+show_help()
+{
+    // Cache the text per connection; repeated SetText calls consume config strings.
+    if (!isDefined(self.tws_help_elems))
+    {
+        elems = [];
+        // Use the same anchors as the HUD, with room below the health numbers.
+        y = level.hud_row_bar + level.hud_bar_height + 20;
+        title = make_text_elem(self, level.hud_x, y,
+            "left", level.hud_font_mid, level.hud_c_afk);
+        title SetText("Commands");
+        elems[elems.size] = title;
+
+        for (i = 0; i < level.tws_help_commands.size; i++)
+        {
+            entry = level.tws_help_commands[i];
+            elem = make_text_elem(self, level.hud_x, y + 22 + i * 18,
+                "left", level.hud_font_small, level.hud_c_count);
+            elem SetText("^3" + entry.command + "^7 - " + entry.description);
+            elems[elems.size] = elem;
+        }
+
+        self.tws_help_elems = elems;
+        self thread destroy_on_disconnect(elems);
+    }
+
+    for (i = 0; i < self.tws_help_elems.size; i++)
+    {
+        elem = self.tws_help_elems[i];
+        elem.alpha = 1;
+    }
+
+    // Only the expiry timer is replaced; the say listener and cleanup stay alive.
+    self notify("tws_help_refresh");
+    self thread hide_help_after_delay();
+}
+
+hide_help_after_delay()
+{
+    self endon("disconnect");
+    self endon("tws_help_refresh");
+
+    wait 12;
+
+    for (i = 0; i < self.tws_help_elems.size; i++)
+    {
+        elem = self.tws_help_elems[i];
+        elem.alpha = 0;
+    }
+}
+
 // only connect listener in the fleet; a second one crashes the T5 SP handshake
 on_player_connect_dispatch()
 {

t5/tws_join.gsc

@@ -9,6 +9,7 @@ init()
         return;
 
     scripts\sp\tws_common::ensure_config();
+    scripts\sp\tws_common::register_help_command(".join", "Join mid-round (newcomers only)");
     scripts\sp\tws_common::register_spawn_handler(::join_spawn);
 
     level thread join_chat_listener();