@s2script/sdk 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.8.0",
+  "version": "0.10.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",
@@ -30,7 +30,8 @@
     "*.d.ts",
     "README.md",
     "LICENSE-MIT",
-    "LICENSE-APACHE"
+    "LICENSE-APACHE",
+    "contracts"
   ],
   "exports": {
     "./admin": {
@@ -111,19 +112,28 @@
     "./transmit": {
       "types": "./transmit.d.ts"
     },
+    "./unsafe": {
+      "types": "./unsafe.d.ts"
+    },
     "./usercmd": {
       "types": "./usercmd.d.ts"
     },
     "./usermessages": {
       "types": "./usermessages.d.ts"
     },
+    "./voice": {
+      "types": "./voice.d.ts"
+    },
     "./votes": {
       "types": "./votes.d.ts"
     },
     "./ws": {
       "types": "./ws.d.ts"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./contracts/workshop": {
+      "types": "./contracts/workshop.d.ts"
+    }
   },
   "repository": {
     "type": "git",

package/server.d.ts

@@ -35,6 +35,28 @@ export declare const Server: {
     min?: number;
     max?: number;
   }): boolean;
+  /**
+   * Watch a cvar for changes (SourceMod `HookConVarChange`, ModSharp's cvar change hook).
+   *
+   * `name` is a cvar name, or `"*"` for every cvar. The handler receives the cvar's name and its
+   * new and old values as strings — for `"*"` the name tells you which one moved.
+   *
+   * NOTIFY-only: the engine's global change callback runs **after** the value has been applied, so
+   * a handler cannot veto a change; returning anything is ignored. A handler that throws is logged
+   * and contained, and the remaining handlers still run.
+   *
+   * Subscriptions are ledgered — unload removes them whether or not `dispose()` is called.
+   *
+   * @example
+   * import { Server } from "@s2script/sdk/server";
+   * Server.onCvarChange("mp_friendlyfire", (name, next, prev) => {
+   *   console.log(`${name}: ${prev} -> ${next}`);
+   * });
+   */
+  onCvarChange(
+    name: string,
+    handler: (name: string, newValue: string, oldValue: string) => void,
+  ): { dispose(): void };
   /** The server's configured max client count (`GetMaxClients()`). `0` if unavailable. */
   readonly maxPlayers: number;
   /** The current map name (`GetMapName()`, the BSP). `""` if unavailable. */

package/timers.d.ts

@@ -20,3 +20,42 @@ export declare function nextFrame(): Promise<void>;
  * Only valid inside a threadSleep-capable fiber context.
  */
 export declare function threadSleep(ms: number): void;
+
+/**
+ * A live callback timer, returned by {@link after} and {@link every}. Ledgered against the creating
+ * plugin: unload kills it whether or not `kill()` was called, so a repeating timer can never outlive
+ * its plugin and fire into a dead context.
+ */
+export interface Timer {
+  /** False once the timer has fired (one-shot), been killed, or had its plugin unloaded. */
+  readonly alive: boolean;
+  /** Cancel it. Idempotent — returns false if it was already dead. Safe to call from inside the callback. */
+  kill(): boolean;
+}
+
+/**
+ * Run `fn` once after `ms` milliseconds (SourceMod `CreateTimer` without `TIMER_REPEAT`).
+ *
+ * Prefer {@link delay} when you can `await`; use this when you need something cancellable.
+ * A throwing callback is reported and contained — it never kills the frame or the timer system.
+ *
+ * @example
+ * import { after } from "@s2script/sdk/timers";
+ * const t = after(5000, () => console.log("5s later"));
+ * t.kill();   // ...unless cancelled first
+ */
+export declare function after(ms: number, fn: () => void): Timer;
+
+/**
+ * Run `fn` every `ms` milliseconds until killed (SourceMod `CreateTimer` with `TIMER_REPEAT`).
+ *
+ * The next firing is scheduled *after* the callback returns, so a slow callback cannot pile up.
+ * `ms` must be greater than 0 — a zero-interval repeat would re-arm every drain and starve the
+ * frame, so it throws rather than degrading.
+ *
+ * @example
+ * import { every } from "@s2script/sdk/timers";
+ * const tick = every(1000, () => console.log("tick"));
+ * // later: tick.kill();
+ */
+export declare function every(ms: number, fn: () => void): Timer;

package/unsafe.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @s2script/sdk/unsafe — plugin-declared engine calls. NO runtime code: the engine injects the
+ * implementation at load (`__s2pkg_unsafe`).
+ *
+ * UNSAFE by design. A declared call reaches a real engine function. The framework validates every
+ * descriptor at load and degrades a failure to `null`, but it cannot prove your signature or vtable
+ * index names the function you meant. Requires manifest `permissions: ["engine:calls"]` AND an
+ * operator allow-list entry (see docs/superpowers/specs/2026-07-24-plugin-gamedata-design.md §6).
+ */
+
+/**
+ * The calls this plugin declares. The base interface is EMPTY — `s2s build` generates
+ * `.s2script/gamedata.d.ts`, which augments this from your gamedata's `calls` section.
+ */
+export interface EngineCalls {}
+
+/**
+ * Plugin-declared engine calls, resolved from this plugin's own gamedata.
+ *
+ * @example
+ * import { Engine } from "@s2script/sdk/unsafe";
+ * // Resolve ONCE at load — null means the descriptor failed a load-time gate.
+ * const ignite = Engine.call("ignite");
+ * if (!ignite) console.log(`unavailable: ${Engine.status("ignite")}`);
+ */
+export declare const Engine: {
+  /**
+   * The declared call, or `null` when its descriptor failed a load-time gate (signature miss,
+   * validator rejection, slot outside `.text`, missing platform entry, or the plugin is not
+   * operator-allow-listed). Guard once at load; the returned function is a plain callable.
+   */
+  call<K extends keyof EngineCalls>(name: K): EngineCalls[K] | null;
+  /** Why a descriptor is unavailable; `"available"` when it resolved. For diagnostics/operator reports. */
+  status(name: string): string;
+};

package/voice.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @s2script/sdk/voice — who can hear whom. NO runtime code: the engine injects the implementation
+ * at load (`__s2pkg_voice`).
+ *
+ * Layered UNDER `Client.voiceMuted`: a muted sender is inaudible to everyone regardless of any rule
+ * here, so admin moderation always beats a gameplay rule.
+ *
+ * Rules are declarative state, not a callback. The engine's listen matrix is re-asserted
+ * continuously and the underlying hook fires per (receiver, sender) pair, so a per-pair JS callback
+ * would run up to 64x64 times per refresh. Set a rule; the shim enforces it.
+ */
+
+/** Hot-path measurement counters returned by {@link Voice.stats}. */
+export interface VoiceStats {
+  /** Listen-matrix decisions the engine has asked about. */
+  calls: number;
+  /** Senders currently carrying a merged rule. */
+  entries: number;
+  /** Times a rule actually silenced a pair. THE effect counter — a rule that never rewrites is not working. */
+  rewrites: number;
+}
+
+/**
+ * Per-(receiver, sender) voice hearability.
+ *
+ * @example
+ * import { Voice } from "@s2script/sdk/voice";
+ * // A dead player is heard only by other dead players.
+ * Voice.setAudibleTo(deadSlot, otherDeadSlots);
+ * // ...and on respawn, hand the slot back to the engine.
+ * Voice.reset(deadSlot);
+ */
+export declare const Voice: {
+  /**
+   * This sender is audible ONLY to `receivers` (0-based slots). An empty array means audible to
+   * nobody — distinct from {@link Voice.reset}, which removes the rule and lets the engine decide.
+   * Rules from multiple plugins AND-merge, so another plugin can only ever narrow yours, never widen it.
+   *
+   * A rule is dropped automatically when the sender disconnects: slots are recycled, and a rule is
+   * about the player who occupied one, not the seat.
+   *
+   * Returns `false` — never throws — when the rule was NOT applied: voice control is degraded or its
+   * engine hook never installed on this build, `sender` is outside `[0, 64)`, or any element of
+   * `receivers` is. Note this differs from {@link import("./transmit").Transmit.setVisibleTo}, which
+   * throws `RangeError` on a bad slot; check the return value here rather than relying on a throw.
+   *
+   * @throws `TypeError` if `receivers` is not an array.
+   */
+  setAudibleTo(sender: number, receivers: readonly number[]): boolean;
+  /**
+   * Drop THIS plugin's rule for `sender`; other plugins' rules survive and are re-merged.
+   * `false` when you had no rule for that sender.
+   */
+  reset(sender: number): boolean;
+  /** Drop every rule this plugin owns. Unload does this automatically. */
+  resetAll(): void;
+  /** Hot-path counters, or null when the running shim predates this capability. */
+  stats(): VoiceStats | null;
+};