@s2script/sdk 0.12.0 → 0.14.0

package/commands.d.ts

@@ -1,5 +1,7 @@
 /** @s2script/commands — register server commands. NO runtime code (injected at load). */
 
+import type { HookResultValue } from "./events";
+
 /**
  * Where a command was invoked from — SourceMod's *reply source*. Set by the dispatch path and
  * exposed as {@link CommandInvocation.replySource}; it is what {@link CommandInvocation.reply}
@@ -112,6 +114,23 @@ export declare const Commands: {
   handleChatTrigger(slot: number, message: string): { silent: boolean; ran: boolean } | null;
   /** The trigger characters — SM PublicChatTrigger (`"!"`) / SilentChatTrigger (`"/"`). Mutate to reconfigure. */
   readonly triggers: { public: string; silent: string };
+  /**
+   * Observe a CLIENT command by name — SourceMod's `AddCommandListener`.
+   *
+   * Unlike {@link register}, which CREATES a command, this hooks one that already exists — including
+   * commands the engine itself owns (`player_ping`, `jointeam`, `drop`, `buy`). Registering a
+   * ConCommand of an engine-owned name fails outright ("unable to link multiple ConCommands named
+   * X"), so this is the only way to see those.
+   *
+   * OBSERVE-BY-DEFAULT: the engine still handles the command as normal. Return
+   * `>= HookResult.Handled` to suppress its engine-side handling — but note that for a command with
+   * a visible effect (a ping marker, a team change) suppressing is usually NOT what you want.
+   *
+   * @example
+   * // Middle-mouse ping opens the shop, and still places the ping.
+   * ctx.commands.onClientCommand("player_ping", (slot) => { openShop(slot); });
+   */
+  onClientCommand(name: string, handler: (slot: number, argString: string) => HookResultValue | void): void;
   /** Every globally-registered command with its required admin `flags`: `0` = anyone, `-1` = console/server-only,
    * else the `ADMFLAG` bit mask (map bits→names in your plugin). The `sm_help` backend. */
   list(): { name: string; flags: number }[];

package/events.d.ts

@@ -55,5 +55,24 @@ export declare const Events: {
   /** Fire a game event. Returns the engine FireEvent result. */
   fire(name: string, fields?: Record<string, number | string | boolean | bigint>, dontBroadcast?: boolean): boolean;
   /** Fire a game event to ONE client (SourceMod FireToClient). Same field type-inference as `fire`. Returns false on miss. */
+  /**
+   * Restrict the event currently being pre-dispatched to `slots`, instead of hiding it from everyone.
+   *
+   * Only meaningful from inside an `onPre` handler that ALSO returns `HookResult.Handled`. The pair
+   * means "do not broadcast this normally — deliver it to exactly these viewers". An empty array hides
+   * it from every client.
+   *
+   * This exists because CS2 fans a game event out to clients as one message PER CLIENT, so plain
+   * suppression is all-or-nothing. Naming recipients keeps every field the engine populated, which
+   * re-firing a rebuilt copy per viewer does not.
+   *
+   * @example
+   * ctx.events.onPre("player_death", () => {
+   *   Events.setRecipients(traitorSlots);   // only Traitors see the kill
+   *   return HookResult.Handled;
+   * });
+   */
+  setRecipients(slots: readonly number[]): void;
+
   fireToClient(slot: number, name: string, fields?: Record<string, string | number | boolean | bigint>): boolean;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "license": "MIT OR Apache-2.0",
   "description": "s2script SDK — the builtin capability types (imported as @s2script/sdk/entity, …) plus the `s2s` CLI for building Source 2 / CS2 plugins.",
   "type": "module",

package/plugin.d.ts

@@ -77,7 +77,18 @@ export interface CtxEntities {
 /** Per-frame + map/precache hooks on this plugin's load-scope ({@link PluginContext.server}). */
 export interface CtxServer {
   /** Run `fn` every game frame. @param opts - `priority` orders it within the frame (`monitor` runs last, read-only). */
-  onGameFrame(fn: () => void, opts?: { priority?: "high" | "normal" | "low" | "monitor" }): void;
+  /**
+   * Run `fn` every game frame.
+   *
+   * `phase` picks WHERE in the frame it runs and defaults to `"pre"` (before simulation). Use
+   * `"post"` when the work must land after the engine's own per-frame writes — re-asserting a netvar
+   * the engine re-derives during simulation is overwritten if written in `"pre"`, because the
+   * derivation happens after and the outgoing snapshot carries the engine's value.
+   */
+  onGameFrame(
+    fn: () => void,
+    opts?: { priority?: "high" | "normal" | "low" | "monitor"; phase?: "pre" | "post" },
+  ): void;
   /** A new map became live; `mapName` is the BSP name. */
   onMapStart(handler: (mapName: string) => void): void;
   /** Precache window — register models/sounds to precache for the current map. */
@@ -91,6 +102,17 @@ export interface CtxCommands {
   registerServer(name: string, handler: (cmd: CommandInvocation) => void): void;
   /** Register an admin command gated by `flags` (an `ADMFLAG` bitmask; fail-safe default-deny). */
   registerAdmin(name: string, flags: number, handler: (cmd: CommandInvocation) => void): void;
+  /**
+   * Observe an existing CLIENT command by name — SourceMod's `AddCommandListener`.
+   *
+   * For engine-owned commands (`player_ping`, `jointeam`, `drop`), which {@link register} cannot
+   * claim. Observe-by-default: the engine still handles it unless the handler returns
+   * `>= HookResult.Handled`. Unsubscribed automatically when the plugin unloads.
+   */
+  onClientCommand(
+    name: string,
+    handler: (slot: number, argString: string) => HookResultValue | void,
+  ): void;
 }
 /** Config live-reload subscription on this plugin's load-scope ({@link PluginContext.config}). */
 export interface CtxConfig {