tws-zombies-scripts/t5/scripts/NOTES.md

TWS T5 script notes

Reference for the tws_t5_*.gsc files in this repo. Platform quirks and load-bearing decisions that show up as invariants in the code.

Install

Copy all tws_t5_*.gsc to storage/t5/scripts/sp/ on the Plutonium T5 server (v2 Plutainer: app/runtime/plutonium/storage/t5/scripts/sp/).

• sudo chown -R 1000:1000 <app> — Plutainer runs as UID 1000
• docker exec <container> rcon-cli map_restart — reloads scripts in place

For existing installations, follow the upgrade cleanup before copying the renamed scripts.

Platform quirks (T5 SP engine, Plutonium)

• Initialize locals before loops when reading them afterwards. T5 rejected leaderboard's chosen variable at load time when its only assignment was inside the map-search loop, even though its later use was guarded by the match count. It now starts as undefined before that loop in both versions. The JavaScript fixture harness and T6 compiler did not catch this T5 error.
• One level waittill("connected") only. tws_t5_common owns it. A second listener breaks the T5 SP connect handshake. Per-player work goes through tws_t5_common::register_spawn_handler after spawned_player, or register_connect_handler for spectator-safe work after the dispatcher yields. Leaderboard uses the latter; its level worker owns all HTTP work.
• Chat uses level waittill("say", ...), not callbackPlayerSay. T5 SP dedicated disables the sound subsystem, cascading through the say-callback dispatch — callbackPlayerSay never fires.
• SetTimerUp(N) only ticks when N == 0 on T5 SP. Non-zero seeds render "0:00" but don't advance. Late joiners see 0, not real elapsed; authoritative elapsed lives in level.match_start_time.
• Dynamic counter text uses SetTextUnlimited; HP uses SetValue. Repeatedly generating unique strings through SetText risks exhausting the text config-string pool; identical strings can be reused by the engine's string lookup. The centered N ZOMBIES element uses Plutonium r5334+'s SetTextUnlimited only when the count changes. Composite HP retains numeric elements around a static slash and HP suffix; the group appears only while injured. Help reuses up to nine explicitly positioned command/description pairs, and record rows skip unchanged text.
• NewClientHudElem(player), not NewHudElem(). NewHudElem is globally owned; in co-op every player's HUD draws on top of every other player's. Fall back to NewHudElem only if elements don't render at all (diagnostic).
• Zombies namespace is WaW-derived (maps\_zombiemode_*), not BO2's maps\mp\zombies\_zm_*.
• Check t5-gsc-utils source as well as its README. Current source includes http::request and jsonSerialize / jsonParse. Telemetry and leaderboard require a DLL built with these HTTP/JSON components; older builds may lack them. See HTTP source and JSON source.

Load-bearing decisions

• Match / round timers anchor to first spawn / first observed round transition — never level init. Anchoring at init included the map-load
  • connect + intro window, producing "displayed 4:00 → frozen 7:00" drift. Many BO1 maps pre-set round_number = 1 at init, so the round watcher fires on transitions only and the timer row seeds on first spawn as a fallback.
• Connection-time HUD creation must not seed clocks. The unboxed core is available to waiting spectators with placeholders: timers upper left, branding top center and zombies/health bottom center. Timer updates retain their existing spawn/round lifecycle, independently of element creation.
• Visibility is separate from updates. HUD owns the exact, case-insensitive .hud chat command and its help entry. Common's core wrappers register each element and preserve its intended alpha behind a per-player visibility mask; health and AFK changes use set_core_alpha(). Hidden data/timers keep updating until game over freezes them. Help, records and stock elements remain separate. Visibility defaults on, survives death/respawn during the connection/map, and resets on reconnect or map restart. AFK protection is unaffected.
• One service view per player. Common owns the unboxed upper-right service area, ordered help rows, record display state and cleanup. Help shows all nine installed commands; extra registrations use nine rows per page. Help pauses record page time; .leaders during help replaces the pending replay from page one. Keep both services independent of the HUD module. Services never reposition the core, and AFK remains centered above the zombie count.
• Bound HUD element counts, including hidden elements. Core + AFK use 10 + 1 archived elements. Common allocates only the active service view: 19 nonarchived elements for nine-command help (20 with a multi-page counter), or four for records (five with a multi-page counter), and none while idle. Switching help/record views destroys the previous view first; pages reuse its elements. Keep the controller and pending requests separate from element lifetime so paused records resume normally. Both engines use explicit help rows; BO1 can concatenate newline-separated HUD text. Hiding an element does not free its slot. The previous 24-element persistent service allocation was consistent with the reported core corruption after records first appeared. The exact live T5 SP capacity remains unverified. The BO1 HUD update comes from an MP-based reconstruction and is not proof of T5 SP limits or current Plutonium stock usage. Validate automatic records, help, view switches and dismissal alongside stock notifications and other installed HUD mods; the core must remain intact throughout and after every service closes.
• Game-over trigger is level-scope, raced across three candidate notifies (end_game / game_ended / intermission) since BO1 maps are inconsistent. Per-player triggers do not work — self waittill("death") is intercepted by the zombiemode scripts before it reaches our scope, and polling self.health misses the zero-crossing (health is rewritten during the game-over sequence).

HUD 1.4.2 requires matching common 1.4.0+ and Plutonium r5334+ for SetTextUnlimited. On r5334+, update the HUD script and restart the map; older Plutonium clients and servers need updates and full restarts first. AFK 1.2.0 and leaderboard 1.1.0 remain compatible; AFK still requires common 1.4.0+. The full help order is .help, .hud, .afk, .back, .join, .leaders, .b, .d, .w: one page of nine commands, with full <amount|all> bank syntax. .hud is absent when HUD is omitted. Records use right-aligned Map record | Round N and up to three bounded holder lines, with no footer and no single-page counter. Both views retain 12-second page timing. Fullscreen X/Y overlay anchors use direct normalized 640 × 480 coordinates. Dynamic health fills use make_overlay_width() like their tracks. Apply int() after max() in that helper: native max() returns a float, but SetShader requires an integer width. Legacy panel helpers and their 0.75 horizontal conversion remain available for existing consumers. Font scale is at least 1.0. Numeric HP appears only while injured; the core and services have no panel backgrounds. The counter is one N ZOMBIES element centered at the health track's midpoint with uniform scale 1.25, starting as -- ZOMBIES. There is no new native-plugin/backend dependency or full server-process restart requirement when already using Plutonium r5334+. Run the shared HUD checks; portable fixtures do not replace T5 live loading, layout and lifecycle validation. Check the counter's centering at 0, 6, 9, 10, 99 and 100, after .hud hides/shows it, and after game over freezes the count.

Module map

File	Role	Fires notifies	Reads notifies
tws_t5_common	Shared config, HUD helpers, paginated .help, service window, spawn-handler registry, single connect listener + dispatcher	—	say, game-end notifications
tws_t5_hud	Unboxed core overlays and private .hud visibility toggle	hud_round_changed, hud_match_started, hud_game_over	say, internal notifications
tws_t5_afk	.afk / .back chat toggle, owns its [AFK] indicator	—	—
tws_t5_join	.join for spectators who have not played on this connection	—	say, end_game, game_ended, intermission
tws_t5_lock	Automatic g_password lock (tws_lock_round, default 20) plus majority .lock / .unlock votes	tws_lock_game_over (internal)	say, hud_round_changed, hud_game_over, end_game, game_ended, intermission
tws_t5_telemetry	Ordered JSON game start, round, 30-second heartbeat, and game end reports with full player snapshots	telemetry_queued, telemetry_finished (internal)	end_game, game_ended, intermission
tws_t5_leaderboard	Cached completed-match map record and all tied holders, privately on join	—	end_game, game_ended, intermission