@s2script/sdk 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.11.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",
@@ -20,7 +20,8 @@
   },
   "devDependencies": {
     "@clack/prompts": "^1.7.0",
-    "fflate": "^0.8.2"
+    "fflate": "^0.8.2",
+    "semver": "^7.8.5"
   },
   "publishConfig": {
     "access": "public"

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 {

package/sound.d.ts

@@ -18,8 +18,23 @@ export interface SoundEmitOptions {
  *  only: a stashed context used after the handler returns (or past an await) is a no-op `false`
  *  (the engine manifest is gone). */
 export interface PrecacheContext {
-  /** Add a resource path (e.g. "soundevents/mypack.vsndevts") to the session resource manifest.
-   *  True iff the engine accepted the add. */
+  /**
+   * Add a resource path to the game session manifest — a soundevents file, a model, a particle.
+   *
+   * @example
+   * pc.add("soundevents/mypack.vsndevts");
+   * pc.add("models/props/cs_office/microwave.vmdl");
+   *
+   * Returns true iff the engine ACCEPTED the string, which is not the same as the resource existing
+   * or being loadable: it returns true for a path with no file behind it too. A model that was never
+   * really there still spawns as the pink-and-black ERROR box, and the engine only says so later, at
+   * spawn time, with "requested but is not in the system (Missing from a manifest?)". Treat a `false`
+   * as fatal and a `true` as "not rejected".
+   *
+   * TIMING: the manifest is built once per map, before plugins that load later exist. A plugin loaded
+   * AFTER that point — including on the boot map of a fresh server start — misses that map's
+   * precache, and its resources stay unusable until the next map change.
+   */
   add(path: string): boolean;
 }