@s2script/sdk 0.12.0 → 0.13.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.12.0",
+  "version": "0.13.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

@@ -91,6 +91,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 {