Merge pull request 'feat(bridge): protocol 13 with RunicNPC, edge → main (runicnpc 9e step 3, merge 2 of 3)' (#29) from edge into main

Reviewed-on: #29

.gitea/workflows/release.yml

@@ -29,8 +29,9 @@
 #    exact commit being released.
 #
 # 2. A FRAMEWORK-NEUTRAL LAYOUT. The tarball holds one directory,
-#    `runicgateway-rust-plugin/`, with `RunicGateway.cs` and `manifest.json` at
-#    its top. It does NOT mirror `oxide/plugins/`: the same file goes to
+#    `runicgateway-rust-plugin/`, with `RunicGateway.cs`, its helpers
+#    (`RunicGatewayZones.cs`, `RunicGatewayDomes.cs`) and `manifest.json` at its top. Every `.cs` in it is listed in the
+#    manifest's `files`, and the installer and the egg place every one of them. It does NOT mirror `oxide/plugins/`: the same file goes to
 #    `oxide/plugins/` or `carbon/plugins/`, and the installer and the egg each
 #    decide which (§34.2.1). The fixed, unversioned prefix is so a reader never
 #    has to parse the version out of a path to find the manifest that states it.
@@ -38,6 +39,11 @@
 # 3. THE VERSION IS STAMPED into the shipped copy's `[Info(…)]` attribute, so
 #    `oxide.plugins` / `c.plugins` on a server names the release it runs. The
 #    committed file keeps its placeholder; the manifest records the commit.
+#    Only the bridge is stamped. A helper (docs/modules/rust/PLAN_FIXES.md D168,
+#    D182 — today `RunicGatewayZones.cs` for ZoneManager and `RunicGatewayDomes.cs`
+#    for ZoneDomes, PLAN_REDESIGNS D194) keeps its own
+#    version: it does one job, changes rarely, and the bridge reads its version at
+#    hello to know which job it does.
 #
 # The version is never the protocol. The protocol lives in overlay.toml and
 # moves only when a message shape does; the version moves on every releasable
@@ -73,6 +79,9 @@ env:
   REPO: RunicGateway/Rust-Plugins
   ARTIFACT: runicgateway-rust-plugin
   PLUGIN: overlay/oxide/plugins/RunicGateway.cs
+  # The helpers shipped beside the bridge (D168, D182). Optional at runtime —
+  # the bridge loads without them — and installed by default.
+  HELPERS: overlay/oxide/plugins/RunicGatewayZones.cs overlay/oxide/plugins/RunicGatewayDomes.cs
   SEED_VERSION: "0.1.0"
   INSTALLER_REPO: RunicGateway/installer
 
@@ -279,6 +288,9 @@ jobs:
         run: |
           set -euo pipefail
           [ -f "$PLUGIN" ] || { echo "::error::${PLUGIN} is missing"; exit 1; }
+          for helper in $HELPERS; do
+            [ -f "$helper" ] || { echo "::error::${helper} is missing"; exit 1; }
+          done
           [ -f overlay.toml ] || { echo "::error::overlay.toml is missing (protocol + framework declarations)"; exit 1; }
           node scripts/checkPlugin.js
           # The stamp below rewrites exactly one [Info(...)] line; zero or two
@@ -304,6 +316,19 @@ jobs:
           grep -qF "[Info(\"Runic Gateway\", \"RunicGateway\", \"${VERSION}\")]" "${STAGE}/RunicGateway.cs" \
             || { echo "::error::stamping the version into [Info(...)] did not take"; exit 1; }
 
+          # The helpers go in as committed, each keeping its own [Info] version.
+          for helper in $HELPERS; do
+            cp "$helper" "${STAGE}/$(basename "$helper")"
+          done
+
+          # `files` names every .cs staged, with its sha256 — the installer places
+          # exactly this set, and checks each file against it.
+          PAIRS=()
+          for f in "${STAGE}"/*.cs; do
+            PAIRS+=("$(basename "$f")" "$(sha256sum "$f" | cut -d' ' -f1)")
+          done
+          FILES="$(jq -n '[$ARGS.positional | _nwise(2) | {(.[0]): .[1]}] | add' --args "${PAIRS[@]}")"
+
           # Declarations from overlay.toml. Read, don't hardcode — the point of
           # that file is that the protocol number lives in one place.
           toml_str() { grep -m1 -E "^$1[[:space:]]*=" overlay.toml | sed -E 's/.*"([^"]+)".*/\1/'; }
@@ -313,6 +338,10 @@ jobs:
           # requires_plugins = ["Kits", "ZoneManager"] is already a JSON array.
           # One line, quoted strings only; anything else fails the check below.
           REQUIRES="$(grep -m1 -E '^requires_plugins[[:space:]]*=' overlay.toml | sed -E 's/^[^=]*=[[:space:]]*//')"
+          # The RunicNPC API the bridge's npc.* commands need (runicnpc stage 4). 0 when
+          # absent, which a bundle reads as "carries no RunicNPC".
+          RUNICNPC_API="$(grep -m1 -E '^runicnpc_api[[:space:]]*=' overlay.toml | sed -E 's/[^0-9]//g')"
+          RUNICNPC_API="${RUNICNPC_API:-0}"
           [ -n "$PROTOCOL" ]   || { echo "::error::could not read protocol from overlay.toml"; exit 1; }
           [ -n "$MIN_OXIDE" ]  || { echo "::error::could not read min_oxide_version from overlay.toml"; exit 1; }
           [ -n "$MIN_CARBON" ] || { echo "::error::could not read min_carbon_version from overlay.toml"; exit 1; }
@@ -329,7 +358,8 @@ jobs:
             --arg     min_oxide  "${MIN_OXIDE}" \
             --arg     min_carbon "${MIN_CARBON}" \
             --argjson requires   "${REQUIRES}" \
-            --arg     sha        "$(sha256sum "${STAGE}/RunicGateway.cs" | cut -d' ' -f1)" \
+            --argjson runicnpc   "${RUNICNPC_API}" \
+            --argjson files      "${FILES}" \
             '{
                component:          $component,
                version:            $version,
@@ -339,7 +369,8 @@ jobs:
                min_oxide_version:  $min_oxide,
                min_carbon_version: $min_carbon,
                requires_plugins:   $requires,
-               files: { "RunicGateway.cs": $sha }
+               runicnpc_api:       $runicnpc,
+               files:              $files
              }' > "${STAGE}/manifest.json"
           echo "----- manifest.json -----"
           cat "${STAGE}/manifest.json"

README.md

@@ -34,9 +34,24 @@ unauthenticated command channel on the network.
 ## Installing it
 
 ```
-overlay/oxide/plugins/RunicGateway.cs  →  <server>/oxide/plugins/RunicGateway.cs
+overlay/oxide/plugins/RunicGateway.cs       →  <server>/oxide/plugins/RunicGateway.cs
+overlay/oxide/plugins/RunicGatewayZones.cs  →  <server>/oxide/plugins/RunicGatewayZones.cs
+overlay/oxide/plugins/RunicGatewayDomes.cs  →  <server>/oxide/plugins/RunicGatewayDomes.cs
 ```
 
+`RunicGatewayZones.cs` is the **ZoneManager helper** (docs/modules/rust/PLAN_FIXES.md D181, D182). ZoneManager
+counts a player in a zone only when its trigger fires on entry, so a zone created, updated or re-created around
+somebody already standing there holds nobody. The helper patches that with Harmony. It is optional: without it the
+bridge still loads, scores its own zones by position, and reports the helper missing at hello. `rgz.status` in the
+server console says whether it patched.
+
+`RunicGatewayDomes.cs` is the **ZoneDomes helper** (docs/modules/rust/PLAN_REDESIGNS.md §3.2, D194). ZoneDomes'
+API ends by telling the player who asked how it went, and throws when a plugin calls it with no player; and at its
+own start it drops the dome of every zone that does not exist yet, which is every zone the bridge re-creates. The
+helper patches the first with Harmony and tells the bridge when ZoneDomes has started, so the bridge can put its
+domes back without drawing any twice. It is optional: without it the site offers no dome, and says which piece is
+missing. `rgd.status` in the server console says whether it patched.
+
 Oxide compiles and loads it on the write, and writes `oxide/config/RunicGateway.json` on first load:
 
 ```json
@@ -69,7 +84,8 @@ egg, both of which deploy a **released** plugin and install the sidecar beside i
 Every merge to `main` that carries a `feat`, `fix` or `perf` commit cuts a release
 (`.gitea/workflows/release.yml`): `runicgateway-rust-plugin-<version>.tar.gz` and `SHA256SUMS`. The
 tarball holds one directory, `runicgateway-rust-plugin/`, with `RunicGateway.cs` (its `[Info]`
-version stamped to the release) and a `manifest.json` folding in `overlay.toml`: the protocol, the
+version stamped to the release), the helpers beside it (each keeping its own version; every `.cs` is listed with
+its sha256 in the manifest's `files`, and the installer and the egg place them all) and a `manifest.json` folding in `overlay.toml`: the protocol, the
 Oxide and Carbon floors, and `requires_plugins`. The layout names no framework; the installer and
 the egg decide where the file goes. A release then asks the installer repo to recompose its Rust
 bundle.

overlay.toml

@@ -26,19 +26,24 @@
 # the same change that alters the emitters, exactly as the sidecar bumps
 # PROTOCOL_VERSION and the module bumps its own constant.
 #
-# Current: 12 — the transport, the read path, identity, the permission mirror,
+# Current: 13 — the transport, the read path, identity, the permission mirror,
 # configuration from the site, first-party clans, a raid frame that names who
 # lives there, the event leases, the world verbs events place and give back, and
 # the rewards: a run's participation tally, kit credits and chat (PROTOCOL.md §16),
 # the map: its picture and everything that moves on it (PROTOCOL.md §17), and the
-# optional mods: BetterChat titles and group styles, and popups (PROTOCOL.md §18).
-protocol = 12
+# optional mods: BetterChat titles and group styles, and popups (PROTOCOL.md §18),
+# and the first player walk's fixes (PROTOCOL.md §19) — opened by a configuration
+# save that answers at once and reports its reload as a `config.outcome` frame.
+protocol = 13
 
 # ── Oxide compatibility ──────────────────────────────────────────────────────
 #
-# The overlay only ADDS a file — one plugin into `oxide/plugins/` — and patches
-# nothing, so it is expected to work on any reasonably current Oxide. This is the
-# oldest build it is known good on.
+# The overlay only ADDS files — the bridge, and beside it the ZoneManager helper
+# (`RunicGatewayZones.cs`, docs/modules/rust/PLAN_FIXES.md D181, D182), both into
+# `oxide/plugins/` — and patches nothing on disk, so it is expected to work on any
+# reasonably current Oxide. The helper patches ZoneManager in memory with Harmony,
+# which both frameworks load; without it the bridge still loads and falls back.
+# This is the oldest build it is known good on.
 #
 # There is no `patches_verified_against` key, and there is no `patches/` tier:
 # Rust's server is a binary and Oxide's hook API is the supported way in, so
@@ -72,3 +77,16 @@ min_carbon_version = "2.0.259"
 # asked of a server without it is refused with a reason, and chat is the default.
 # BetterChat is optional in the same way — titles and group styles wait for it.
 requires_plugins = ["Kits", "ZoneManager"]
+
+# ── The RunicNPC API the bridge needs ───────────────────────────────────────
+#
+# RunicNPC (docs/runicnpc/PLAN.md stages 4 to 7): the bridge's npc.* commands call
+# RunicNPC's API and need at least this version of it. It MUST equal
+# `RunicNpcApiNeeded` in RunicGateway.cs; `node scripts/checkPlugin.js` holds the
+# two equal. The release copies it into manifest.json, and the installer's
+# bundle carries the latest RunicNPC release that answers at least it (D224).
+#
+# RunicNPC is required since its stage 9 (D310): without it, or with one older
+# than this, every npc.* command and every NPC an event places, Rust's own
+# scientists included, is refused as `runicnpc-missing` or `runicnpc-old`.
+runicnpc_api = 6

overlay/oxide/plugins/RunicGatewayDomes.cs

@@ -0,0 +1,261 @@
+// Runic Gateway Domes — a helper for ZoneDomes, shipped beside the Runic Gateway bridge.
+// Copyright (C) Runic Gateway contributors. GPL-3.0-or-later.
+//
+// ONE JOB (docs/modules/rust/PLAN_REDESIGNS.md §3.2, D168, D194):
+//
+// ZoneDomes draws a dome over a ZoneManager zone, and the bridge asks it to for an event zone
+// whose step wants one. Its API was written for a person at a keyboard: `AddNewDome` and
+// `RemoveExistingDome` both end by telling the player who asked how it went, with no check that
+// there was one. Called by a plugin with no player, the dome is made and saved, and THEN the call
+// throws — so the caller cannot tell a made dome from a failed one (plan §0.5, found on the rig).
+//
+// So this helper patches ZoneDomes with Harmony, the same way the zone helper patches ZoneManager
+// (D181):
+//
+//   * **A message with no player is not sent.** A prefix on ZoneDomes' `TranslateMessage(BasePlayer,
+//     string, string)` skips it when the player is null. Nothing else about the call changes, so
+//     `AddNewDome` returns its true or false normally.
+//   * **It says when ZoneDomes has finished starting.** ZoneDomes' own start (`InitializeDomes`)
+//     drops every dome whose zone does not exist yet and draws every one that does. A dome added
+//     BEFORE that is drawn a second time, and the first set of spheres stays in the world with
+//     nothing holding it. A postfix there raises `OnRgDomesReady`, and the bridge puts its domes
+//     back only after it.
+//
+// It is optional. Without it the bridge offers no dome and says why; the zones themselves are
+// unaffected. `rgd.status` in the server console prints its state.
+
+using System;
+using System.Reflection;
+using HarmonyLib;
+using Oxide.Core;
+using Oxide.Core.Plugins;
+
+namespace Oxide.Plugins
+{
+    [Info("Runic Gateway Domes", "Runic Gateway", "0.1.0")]
+    [Description("Helper for Runic Gateway: ZoneDomes can be called without a player, and says when it has started.")]
+    public class RunicGatewayDomes : RustPlugin
+    {
+        private const string HarmonyId = "runicgateway.domes";
+
+        /// <summary>The instance the static patches report to. Null while unloaded.</summary>
+        private static RunicGatewayDomes _instance;
+
+        private Harmony _harmony;
+        private MethodInfo _message;
+        private MethodInfo _initialize;
+
+        /// <summary><c>patched</c>, <c>unsupported</c> (ZoneDomes is here but not the shape patched), or <c>no-zonedomes</c>.</summary>
+        private string _state = "no-zonedomes";
+        private string _reason;
+
+        /// <summary>Whether ZoneDomes has finished its own start since it was patched. Main thread.</summary>
+        private bool _ready;
+
+        /// <summary>Set once the server is up, at this plugin's own <c>OnServerInitialized</c>.</summary>
+        private bool _serverUp;
+
+        // Patched as EARLY as possible — at load, or the moment ZoneDomes loads — so that at a real
+        // server start the patch is in before ZoneDomes' `OnServerInitialized` runs its start.
+
+        private void Loaded()
+        {
+            _instance = this;
+            Patch();
+        }
+
+        private void OnServerInitialized(bool initial)
+        {
+            _serverUp = true;
+
+            // Loaded into a running server: ZoneDomes, if it is here, started long ago.
+            if (!initial)
+                MarkReadyNextTick();
+        }
+
+        private void Unload()
+        {
+            Unpatch();
+            _instance = null;
+        }
+
+        private void OnPluginLoaded(Plugin plugin)
+        {
+            if (plugin == null || plugin.Name != "ZoneDomes")
+                return;
+
+            Unpatch();
+            Patch();
+
+            // A ZoneDomes loaded into a running server has run its start by now: the framework
+            // calls a hot-loaded plugin's `OnServerInitialized` before it tells anybody else it
+            // loaded. The tick is margin, and costs nothing.
+            if (_serverUp)
+                MarkReadyNextTick();
+        }
+
+        private void OnPluginUnloaded(Plugin plugin)
+        {
+            if (plugin != null && plugin.Name == "ZoneDomes")
+            {
+                Unpatch();
+                _state = "no-zonedomes";
+                _reason = null;
+            }
+        }
+
+        // ── The API the bridge calls ─────────────────────────────────────────────
+
+        /// <summary><c>patched</c>, <c>unsupported</c> or <c>no-zonedomes</c>.</summary>
+        private string State() => _state;
+
+        /// <summary>Why the state is not <c>patched</c>, or null.</summary>
+        private string StateReason() => _reason;
+
+        /// <summary>Whether ZoneDomes is patched and past its own start, so a dome may be added.</summary>
+        private bool Ready() => _state == "patched" && _ready;
+
+        /// <summary>The helper's own version, for hello.</summary>
+        private string HelperVersion() => Version.ToString();
+
+        // ── Patching ─────────────────────────────────────────────────────────────
+
+        private void Patch()
+        {
+            _ready = false;
+            Plugin zoneDomes = plugins.Find("ZoneDomes");
+
+            if (zoneDomes == null)
+            {
+                _state = "no-zonedomes";
+                _reason = null;
+                return;
+            }
+
+            const BindingFlags any = BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic;
+            Type type = zoneDomes.GetType();
+
+            _message = type.GetMethod("TranslateMessage", any, null, new[] { typeof(BasePlayer), typeof(string), typeof(string) }, null);
+            _initialize = type.GetMethod("InitializeDomes", any, null, Type.EmptyTypes, null);
+
+            string missing =
+                _message == null ? "TranslateMessage(BasePlayer, string, string)" :
+                _initialize == null ? "InitializeDomes()" :
+                type.GetMethod("AddNewDome", any) == null ? "AddNewDome" :
+                type.GetMethod("RemoveExistingDome", any) == null ? "RemoveExistingDome" :
+                null;
+
+            if (missing != null)
+            {
+                Fail($"this ZoneDomes ({zoneDomes.Version}) has no {missing}");
+                return;
+            }
+
+            try
+            {
+                _harmony = new Harmony(HarmonyId);
+                _harmony.Patch(_message, prefix: new HarmonyMethod(
+                    typeof(RunicGatewayDomes).GetMethod(nameof(BeforeMessage), BindingFlags.Static | BindingFlags.NonPublic)));
+                _harmony.Patch(_initialize, postfix: new HarmonyMethod(
+                    typeof(RunicGatewayDomes).GetMethod(nameof(AfterInitialize), BindingFlags.Static | BindingFlags.NonPublic)));
+            }
+            catch (Exception ex)
+            {
+                Fail($"Harmony could not patch ZoneDomes: {ex.Message}");
+                return;
+            }
+
+            _state = "patched";
+            _reason = null;
+            Puts($"patched ZoneDomes {zoneDomes.Version}: its API can be called without a player");
+        }
+
+        private void Unpatch()
+        {
+            if (_harmony != null)
+            {
+                try
+                {
+                    if (_message != null)
+                        _harmony.Unpatch(_message, HarmonyPatchType.Prefix, HarmonyId);
+
+                    if (_initialize != null)
+                        _harmony.Unpatch(_initialize, HarmonyPatchType.Postfix, HarmonyId);
+                }
+                catch (Exception ex)
+                {
+                    PrintWarning($"could not remove the ZoneDomes patches: {ex.Message}");
+                }
+            }
+
+            _harmony = null;
+            _message = null;
+            _initialize = null;
+            _ready = false;
+        }
+
+        private void Fail(string reason)
+        {
+            Unpatch();
+            _state = "unsupported";
+            _reason = reason;
+            PrintWarning($"{reason}. Runic Gateway will not offer a dome over its zones on this server.");
+        }
+
+        private void MarkReadyNextTick()
+        {
+            NextTick(() =>
+            {
+                if (_state != "patched" || _ready)
+                    return;
+
+                _ready = true;
+                Interface.CallHook("OnRgDomesReady");
+            });
+        }
+
+        // ── The patches ──────────────────────────────────────────────────────────
+
+        /// <summary>
+        ///     Harmony prefix on <c>ZoneDomes.TranslateMessage(BasePlayer, string, string)</c>.
+        ///     Returning false skips the message; a real player still gets it.
+        /// </summary>
+        private static bool BeforeMessage(BasePlayer player)
+        {
+            return player != null;
+        }
+
+        /// <summary>
+        ///     Harmony postfix on <c>ZoneDomes.InitializeDomes</c>. Anything thrown here would surface
+        ///     inside ZoneDomes, so nothing is allowed to.
+        /// </summary>
+        private static void AfterInitialize()
+        {
+            try
+            {
+                RunicGatewayDomes self = _instance;
+
+                if (self == null || self._state != "patched")
+                    return;
+
+                self._ready = true;
+                Interface.CallHook("OnRgDomesReady");
+            }
+            catch (Exception)
+            {
+                // Never ZoneDomes' problem.
+            }
+        }
+
+        // ── Console ──────────────────────────────────────────────────────────────
+
+        [ConsoleCommand("rgd.status")]
+        private void StatusCommand(ConsoleSystem.Arg arg)
+        {
+            if (arg.Connection != null && !arg.IsAdmin)
+                return;
+
+            arg.ReplyWith($"Runic Gateway Domes {Version}: {_state}{(_state == "patched" ? (_ready ? ", ready" : ", waiting for ZoneDomes to start") : "")}{(_reason != null ? $" ({_reason})" : "")}");
+        }
+    }
+}

overlay/oxide/plugins/RunicGatewayZones.cs

@@ -0,0 +1,376 @@
+// Runic Gateway Zones — a helper for ZoneManager, shipped beside the Runic Gateway bridge.
+// Copyright (C) Runic Gateway contributors. GPL-3.0-or-later.
+//
+// ITS FIRST JOB (docs/modules/rust/PLAN_FIXES.md F12, D168, D181, D182):
+//
+// ZoneManager counts a player as inside a zone only when the zone's trigger fires on ENTRY. A
+// zone created, updated or loaded around somebody who is already standing there never fires it,
+// so ZoneManager says nobody is inside — and its flags, its enter message and `OnEnterZone` never
+// happen for them. The first player walk found it twice: after a restart the org lead woke up
+// eighteen metres inside an event zone the bridge had just re-created, and ZoneManager's
+// `IsPlayerInZone` said no; and a zone opened around a player did the same. Every participant of
+// an event that survives a restart scores nothing until they walk out and back in.
+//
+// ZoneManager has no public way to ask it to look again: the routine that does (`UpdatePlayerZones`)
+// is private and runs only for a player who is connecting. So this helper patches ZoneManager with
+// Harmony, which is the org lead's decision (D181):
+//
+//   * **The patch point is `Zone.InitializeZone`**, the one method a zone passes through when it is
+//     created (`CreateOrUpdateZone`), updated (`Zone.Reset`) or loaded from ZoneManager's own data
+//     file at startup. A postfix there sees every one of them.
+//   * **It does not decide who is inside.** One tick later — when ZoneManager has finished
+//     registering the zone — it asks ZoneManager's own public `IsPositionInZone` for each connected
+//     player, and enters those it names through ZoneManager's own `OnPlayerEnterZone`. So ZoneManager's
+//     flags, eject and kill rules, enter message and `OnEnterZone` all apply exactly as if the
+//     player had walked in. A player ZoneManager already counts is skipped, and ZoneManager refuses
+//     a second entry anyway, so a trigger that does fire after all changes nothing.
+//   * **It fixes every zone on the server**, not only the bridge's. That is deliberate: the fault is
+//     ZoneManager's, and it is the same fault for an arena another plugin made.
+//
+// A SECOND JOB (RunicNPC stage 9d walk, the org lead's call, 2026-10-07):
+//
+// ZoneManager subscribes the hooks that enforce its flags (`OnEntityTakeDamage` for PvpGod and the
+// other damage flags, `OnEntityBuilt` for NoBuild, and so on) only for the flags some zone had when
+// ZoneManager loaded, or when a flag is toggled by command. A zone made later through its API —
+// which is every zone an event opens — never re-subscribes them, so on a server with no such zone
+// already, an event's PvpGod or NoBuild zone enforces nothing: the 9d walk shot a player dead and
+// built a foundation inside one. The same postfix that sees every zone made therefore also has
+// ZoneManager run its own `UpdateHookSubscriptions` on the next tick. ZoneManager decides what to
+// subscribe; this only asks it to look.
+//
+// It is optional. The bridge never depends on it to load: without it — deleted, or loaded but
+// unable to find what it patches after a ZoneManager update — the bridge scores the zones it made
+// by `IsPositionInZone` instead (D182), and reports this helper's state at hello so the site can
+// say what is missing. `rgz.status` in the server console prints the same state.
+
+using System;
+using System.Collections.Generic;
+using System.Reflection;
+using HarmonyLib;
+using Oxide.Core.Plugins;
+using UnityEngine;
+
+namespace Oxide.Plugins
+{
+    [Info("Runic Gateway Zones", "Runic Gateway", "0.2.0")]
+    [Description("Helper for Runic Gateway: ZoneManager counts players already inside a zone when it is created, updated or loaded, and enforces a new zone's flags.")]
+    public class RunicGatewayZones : RustPlugin
+    {
+        private const string HarmonyId = "runicgateway.zones";
+
+        /// <summary>The instance the static postfix reports to. Null while unloaded.</summary>
+        private static RunicGatewayZones _instance;
+
+        private Harmony _harmony;
+        private MethodInfo _patched;
+
+        // Reflected once per ZoneManager load. A ZoneManager reload is a new assembly, so all of it
+        // is looked up again then.
+        private Plugin _zoneManager;
+        private MethodInfo _enter;
+        private MethodInfo _getZone;
+        private FieldInfo _definition;
+        private PropertyInfo _id;
+
+        /// <summary>ZoneManager's private <c>UpdateHookSubscriptions</c>, or null when this ZoneManager has none (the second job is then off).</summary>
+        private MethodInfo _updateHooks;
+
+        /// <summary>
+        ///     What the bridge reads through <see cref="State"/>: <c>patched</c>, <c>unsupported</c>
+        ///     (ZoneManager is here but not the shape this helper patches), or <c>no-zonemanager</c>.
+        /// </summary>
+        private string _state = "no-zonemanager";
+        private string _reason;
+
+        /// <summary>Zones initialised this tick, swept once on the next. Main thread.</summary>
+        private readonly Dictionary<string, object> _pending = new Dictionary<string, object>();
+        private bool _sweepQueued;
+
+        private void OnServerInitialized()
+        {
+            _instance = this;
+            Patch();
+        }
+
+        private void Unload()
+        {
+            Unpatch();
+            _instance = null;
+        }
+
+        private void OnPluginLoaded(Plugin plugin)
+        {
+            if (plugin != null && plugin.Name == "ZoneManager")
+            {
+                Unpatch();
+                Patch();
+            }
+        }
+
+        private void OnPluginUnloaded(Plugin plugin)
+        {
+            if (plugin != null && plugin.Name == "ZoneManager")
+            {
+                Unpatch();
+                _state = "no-zonemanager";
+                _reason = null;
+            }
+        }
+
+        // ── The API the bridge calls ─────────────────────────────────────────────
+
+        /// <summary><c>patched</c>, <c>unsupported</c> or <c>no-zonemanager</c>.</summary>
+        private string State() => _state;
+
+        /// <summary>Why the state is not <c>patched</c>, or null.</summary>
+        private string StateReason() => _reason;
+
+        /// <summary>The helper's own version, for hello.</summary>
+        private string HelperVersion() => Version.ToString();
+
+        // ── Patching ─────────────────────────────────────────────────────────────
+
+        private void Patch()
+        {
+            _zoneManager = plugins.Find("ZoneManager");
+
+            if (_zoneManager == null)
+            {
+                _state = "no-zonemanager";
+                _reason = null;
+                return;
+            }
+
+            const BindingFlags any = BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic;
+
+            Type zmType = _zoneManager.GetType();
+            Type zoneType = zmType.GetNestedType("Zone", BindingFlags.Public | BindingFlags.NonPublic);
+            MethodInfo initialize = zoneType?.GetMethod("InitializeZone", any);
+
+            _getZone = zmType.GetMethod("GetZoneByID", any, null, new[] { typeof(string) }, null);
+            _updateHooks = zmType.GetMethod("UpdateHookSubscriptions", any, null, Type.EmptyTypes, null);
+            _definition = zoneType?.GetField("definition", any);
+            _id = _definition?.FieldType.GetProperty("Id", any);
+            _enter = zoneType == null
+                ? null
+                : zmType.GetMethod("OnPlayerEnterZone", any, null, new[] { typeof(BasePlayer), zoneType }, null);
+
+            string missing =
+                zoneType == null ? "ZoneManager.Zone" :
+                initialize == null ? "Zone.InitializeZone" :
+                _definition == null || _id == null ? "Zone.definition.Id" :
+                _enter == null ? "ZoneManager.OnPlayerEnterZone(BasePlayer, Zone)" :
+                _getZone == null ? "ZoneManager.GetZoneByID(string)" :
+                null;
+
+            if (missing != null)
+            {
+                Fail($"this ZoneManager ({_zoneManager.Version}) has no {missing}");
+                return;
+            }
+
+            try
+            {
+                _harmony = new Harmony(HarmonyId);
+                _harmony.Patch(initialize, postfix: new HarmonyMethod(
+                    typeof(RunicGatewayZones).GetMethod(nameof(AfterInitialize), BindingFlags.Static | BindingFlags.NonPublic)));
+                _patched = initialize;
+            }
+            catch (Exception ex)
+            {
+                Fail($"Harmony could not patch Zone.InitializeZone: {ex.Message}");
+                return;
+            }
+
+            _state = "patched";
+            _reason = null;
+            Puts($"patched ZoneManager {_zoneManager.Version}: a zone takes in the players already inside it" +
+                 (_updateHooks != null ? ", and a new zone's flags are enforced" : ""));
+            if (_updateHooks == null)
+                PrintWarning($"this ZoneManager ({_zoneManager.Version}) has no UpdateHookSubscriptions: a zone made after it loaded may not enforce its flags until ZoneManager reloads");
+
+            // The zones ZoneManager loaded before this helper did were initialised unwatched —
+            // which, at a server start, is all of them. Sweep them once now.
+            RefreshHooks();
+            SweepAll();
+        }
+
+        private void Unpatch()
+        {
+            if (_harmony != null && _patched != null)
+            {
+                try
+                {
+                    _harmony.Unpatch(_patched, HarmonyPatchType.Postfix, HarmonyId);
+                }
+                catch (Exception ex)
+                {
+                    PrintWarning($"could not remove the ZoneManager patch: {ex.Message}");
+                }
+            }
+
+            _harmony = null;
+            _patched = null;
+            _pending.Clear();
+        }
+
+        private void Fail(string reason)
+        {
+            Unpatch();
+            _state = "unsupported";
+            _reason = reason;
+            PrintWarning($"{reason}. Runic Gateway scores its zones by position instead; ZoneManager's own flags will not apply to somebody already inside a new zone.");
+        }
+
+        // ── The patch ────────────────────────────────────────────────────────────
+
+        /// <summary>
+        ///     Harmony postfix on <c>ZoneManager.Zone.InitializeZone</c>. Static, as Harmony needs;
+        ///     it only records the zone. Anything thrown here would surface inside ZoneManager, so
+        ///     nothing is allowed to.
+        /// </summary>
+        private static void AfterInitialize(object __instance)
+        {
+            try
+            {
+                _instance?.Queue(__instance);
+            }
+            catch (Exception)
+            {
+                // Never ZoneManager's problem.
+            }
+        }
+
+        private void Queue(object zone)
+        {
+            object definition = _definition.GetValue(zone);
+            string id = definition == null ? null : _id.GetValue(definition) as string;
+
+            if (string.IsNullOrEmpty(id))
+                return;
+
+            // The newest instance wins: a zone re-created in the same tick is one sweep.
+            _pending[id] = zone;
+
+            if (_sweepQueued)
+                return;
+
+            _sweepQueued = true;
+
+            // A tick later, not now. `CreateOrUpdateZone` initialises a zone once with an empty
+            // definition and again after the arguments are applied, and ZoneManager's startup load
+            // registers the zone in its table only AFTER initialising it — so `IsPositionInZone`
+            // answers correctly on the next tick and not before.
+            NextTick(SweepPending);
+        }
+
+        private void SweepPending()
+        {
+            _sweepQueued = false;
+
+            if (_state != "patched" || _pending.Count == 0)
+            {
+                _pending.Clear();
+                return;
+            }
+
+            var batch = new List<KeyValuePair<string, object>>(_pending);
+            _pending.Clear();
+
+            // The second job first: the hooks that enforce the new zones' flags, then the players.
+            RefreshHooks();
+
+            foreach (KeyValuePair<string, object> entry in batch)
+                Sweep(entry.Key, entry.Value);
+        }
+
+        /// <summary>
+        ///     Main thread. Has ZoneManager subscribe the hooks its zones' flags now need. ZoneManager
+        ///     only adds subscriptions here, and subscribing a hook twice is a no-op.
+        /// </summary>
+        private void RefreshHooks()
+        {
+            if (_updateHooks == null || _zoneManager == null)
+                return;
+
+            try
+            {
+                _updateHooks.Invoke(_zoneManager, null);
+            }
+            catch (Exception ex)
+            {
+                PrintWarning($"could not have ZoneManager refresh its hooks: {(ex.InnerException ?? ex).Message}");
+            }
+        }
+
+        private void SweepAll()
+        {
+            var ids = _zoneManager.Call("GetZoneIDs") as string[];
+
+            if (ids == null)
+                return;
+
+            foreach (string id in ids)
+                Sweep(id, null);
+        }
+
+        /// <summary>
+        ///     Main thread. Enters every connected player ZoneManager says is inside the zone and
+        ///     does not yet count. <paramref name="zone"/> is the instance to enter them into, or null
+        ///     to look it up (the startup sweep).
+        /// </summary>
+        private void Sweep(string id, object zone)
+        {
+            Plugin zm = _zoneManager;
+
+            if (zm == null || zm.Call("CheckZoneID", id) == null)
+                return;
+
+            zone = zone ?? _getZone.Invoke(zm, new object[] { id });
+
+            if (zone == null || (zone is UnityEngine.Object unity && unity == null))
+                return;
+
+            int entered = 0;
+
+            // A copy: entering a player can eject or kill them, which changes the live list.
+            // `activePlayerList` is Facepunch's ListHashSet, which has no ToArray.
+            foreach (BasePlayer player in new List<BasePlayer>(BasePlayer.activePlayerList))
+            {
+                if (player == null || player.IsNpc || player.transform == null)
+                    continue;
+
+                if (zm.Call("IsPlayerInZone", id, player) is bool already && already)
+                    continue;
+
+                if (!(zm.Call("IsPositionInZone", id, player.transform.position) is bool inside) || !inside)
+                    continue;
+
+                try
+                {
+                    _enter.Invoke(zm, new[] { (object)player, zone });
+                    entered++;
+                }
+                catch (Exception ex)
+                {
+                    PrintWarning($"could not enter {player.displayName} into zone {id}: {(ex.InnerException ?? ex).Message}");
+                }
+            }
+
+            if (entered > 0)
+                Puts($"zone {id}: {entered} player(s) already inside were counted in");
+        }
+
+        // ── Console ──────────────────────────────────────────────────────────────
+
+        [ConsoleCommand("rgz.status")]
+        private void StatusCommand(ConsoleSystem.Arg arg)
+        {
+            if (arg.Connection != null && !arg.IsAdmin)
+                return;
+
+            arg.ReplyWith($"Runic Gateway Zones {Version}: {_state}{(_reason != null ? $" ({_reason})" : "")}" +
+                          $"; new zones' flags {(_updateHooks != null ? "enforced" : "NOT refreshed (no UpdateHookSubscriptions)")}");
+        }
+    }
+}

scripts/checkPlugin.js

@@ -198,6 +198,14 @@ function check(source, toml) {
 
   // 5. The two declaration sites this repository owns must agree.
   const inCode = /ProtocolVersion\s*=\s*(\d+)\s*;/.exec(source)
+  // runicnpc stage 4: the RunicNPC API the bridge needs, declared twice like the protocol.
+  const npcToml = /^\s*runicnpc_api\s*=\s*(\d+)\s*$/m.exec(toml)
+  const npcCode = /const\s+int\s+RunicNpcApiNeeded\s*=\s*(\d+)\s*;/.exec(source)
+  if (npcCode && !npcToml) problems.push('the plugin needs a RunicNPC API (RunicNpcApiNeeded) and overlay.toml declares no runicnpc_api')
+  if (npcCode && npcToml && npcCode[1] !== npcToml[1]) {
+    problems.push(`the plugin needs RunicNPC API ${npcCode[1]} and overlay.toml declares runicnpc_api = ${npcToml[1]}. The bundle picks a RunicNPC by the second, so they must agree.`)
+  }
+
   const inToml = /^\s*protocol\s*=\s*(\d+)\s*$/m.exec(toml)
 
   if (!inCode) problems.push('could not read ProtocolVersion from the plugin source')