Add modular chat help for T5 and T6

t6/NOTES.md

@@ -23,6 +23,16 @@ HUD again owns the `hud_game_over` notification fan-out. Lock again waits on HUD
 notifications, applies T5's random password, and clears it on startup/game over.
 The added password-preservation dvars and independent lock watcher are gone.
 
+Common also listens for `.help` through the native `say` notification, independent
+of first-spawn initialization so newcomers can view commands while spectating.
+Each loaded command module registers its command and description with
+`register_help_command()` during `init()`. Lazy registry initialization preserves
+registrations regardless of module initialization order. Help uses client HUD
+elements below the health bar, sharing the HUD's anchors to avoid overlap with
+timers, zombie count and health numbers. Text is created once per connection and
+reused; each request restarts a 12-second visibility timer. Disconnect cleanup
+is independent of that timer. The command handlers retain their existing listeners.
+
 AFK again listens to the native `say` notification, so it no longer needs plugin
 chat registration. The additional T6 controls are only held while AFK; `.back`
 releases them before the protection grace period. Restoration is deferred during
@@ -82,9 +92,10 @@ at link time. The other four TWS modules can run without telemetry.
 
 ## Checks
 
-Local: all five files pass gsc-tool 1.4.10 T6 PC compilation; shared references and
-entry points are checked by `tools/check.ps1`. No live server was run for this
-baseline simplification. Compiler success does not certify runtime linking.
+Local: `tools/check.ps1` compiles all six files for T6 PC and checks shared
+references and entry points. It requires PowerShell and gsc-tool. The `.help`
+change passed the static entry-point/reference checks, but compilation and live
+gameplay were not run. Compiler success does not certify runtime linking.
 
 Live checks after deploying:
 
@@ -97,3 +108,12 @@ Live checks after deploying:
 4. Telemetry sends the initial occupied round and each new round to the existing
    endpoint. Check server ID/player count, same-round joins and an unreachable API.
 5. Repeat on the actual server maps, especially afterlife and special-enemy rounds.
+6. Type `.help` and `.HELP` before first spawn, during play and while AFK: see
+   `.help`, `.afk`, `.back` and `.join` with descriptions, only on the requesting
+   player's screen below the health bar. Take damage so health numbers appear
+   and verify they do not overlap help. Repeat the command before 12 seconds
+   elapse: one list should remain visible until 12 seconds after the latest
+   request. Reopen after expiry and reconnect; verify no duplicates or leftovers.
+   Remove the AFK or Join module, restart the map and confirm its commands are
+   absent. Restore the modules and confirm `.afk`, `.back` and `.join` still
+   behave as before.

t6/README.md

@@ -5,7 +5,7 @@ just like T5. There is no separate TWS config file or database setup.
 
 | File | Role | Dependencies |
 | --- | --- | --- |
-| `tws_t6_common.gsc` | Shared HUD values, helpers and first-spawn dispatcher | Stock T6 |
+| `tws_t6_common.gsc` | Shared HUD values, helpers, `.help` and first-spawn dispatcher | 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 |
@@ -31,6 +31,26 @@ 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.
 
+## Chat commands
+
+Type `.help` 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 `.help` again restarts that display time.
+
+| Command | Description |
+| --- | --- |
+| `.help` | List available commands |
+| `.afk` | Pause with protection |
+| `.back` | Return from AFK |
+| `.join` | Join mid-round (newcomers only) |
+
+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.
+
 ## Defaults, matching T5
 
 - HUD values live in `tws_t6_common::common_config()`. That function and
@@ -95,7 +115,7 @@ another mod installed one first.
 
 ## Validation
 
-All six scripts compile for T6 PC with gsc-tool 1.4.10. To repeat:
+To compile all six scripts for T6 PC with gsc-tool 1.4.10:
 
 ```powershell
 .\tools\check.ps1 -CompilerPath C:\path\to\gsc-tool.exe

t6/tws_t6_afk.gsc

@@ -10,6 +10,8 @@ main()
 init()
 {
     scripts\zm\tws_t6_common::ensure_config();
+    scripts\zm\tws_t6_common::register_help_command(".afk", "Pause with protection");
+    scripts\zm\tws_t6_common::register_help_command(".back", "Return from AFK");
     afk_init();
     scripts\zm\tws_t6_common::register_spawn_handler(::afk_spawn);
 }

t6/tws_t6_common.gsc

@@ -1,4 +1,4 @@
-/* tws_t6_common.gsc — shared config, HUD helpers, spawn-handler registry, connect dispatcher. */
+/* tws_t6_common.gsc — shared config, HUD helpers, help and spawn-handler registries. */
 
 #include maps\mp\_utility;
 #include common_scripts\utility;
@@ -11,7 +11,9 @@ main()
 init()
 {
     common_config();
+    register_help_command(".help", "List available commands");
 
+    level thread help_chat_listener();
     level thread on_player_connect_dispatch();
 }
 
@@ -74,6 +76,83 @@ register_spawn_handler(fn)
     level.tws_spawn_handlers[level.tws_spawn_handlers.size] = fn;
 }
 
+// Modules register their own commands, regardless of init order.
+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;
+}
+
+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;
+    }
+}
+
 // Shared dispatcher: one HUD instance and account load per connection.
 on_player_connect_dispatch()
 {

t6/tws_t6_join.gsc

@@ -14,6 +14,7 @@ init()
     println("[tws_t6_join] init reached");
 
     scripts\zm\tws_t6_common::ensure_config();
+    scripts\zm\tws_t6_common::register_help_command(".join", "Join mid-round (newcomers only)");
     scripts\zm\tws_t6_common::register_spawn_handler(::join_spawn);
 
     level thread join_chat_listener();