@s2script/sdk 0.9.0 → 0.10.0

package/clients.d.ts

@@ -36,6 +36,42 @@ export declare class Client {
    * reason in the server log), setting is an inert no-op and reads stay false.
    */
   voiceMuted: boolean;
+  /**
+   * Tell this client to run `cmd` in their own console, as if they had typed it
+   * (SourceMod `ClientCommand`).
+   *
+   * Requires a real client: a bot has no console, so this is a no-op on bots — use
+   * {@link Client.fakeCommand} for server-side execution. Returns `false` when the command was not
+   * dispatched (empty text, bad slot, or the engine interface is unavailable on this build), never
+   * a silent no-op.
+   *
+   * @example
+   * client.command("play sounds/ui/beep.vsnd");
+   */
+  command(cmd: string): boolean;
+  /**
+   * Have the SERVER process `cmd` as if this client had sent it (SourceMod `FakeClientCommand`).
+   *
+   * Unlike {@link Client.command} this works on bots, because nothing is sent to a client — the
+   * engine dispatches the command itself, attributed to this player's slot. Live-verified:
+   * `fakeCommand("say hi")` on slot 0 prints as that player, not as Console.
+   *
+   * Returns `false` — never a silent no-op — for a bad slot, empty text, an unavailable interface,
+   * or a name that is not a registered console **command** (a ConVar such as `mp_friendlyfire` is
+   * refused: use `Server.command` for those).
+   *
+   * KNOWN LIMITATION: engine commands (`say`, `kill`, …) execute. A command registered by an
+   * s2script plugin is dispatched by the engine, but its JS handler will NOT run — the core holds
+   * the isolate borrow across all JS, so re-entering the dispatcher hits the documented
+   * re-entrancy skip. (This is not a permissions issue: every s2script command is registered
+   * client-executable, which is why a player can type it in their own console.) To invoke another
+   * plugin's behaviour, use a cross-plugin interface rather than faking its command. See
+   * docs/superpowers/specs/2026-07-25-client-command-design.md §12.
+   *
+   * @example
+   * client.fakeCommand("say hello");   // as though the player typed it
+   */
+  fakeCommand(cmd: string): boolean;
 }
 /**
  * Look up connected clients by slot or enumerate them all.

package/contracts/README.md

@@ -0,0 +1,37 @@
+# Standard interface contracts
+
+These are **type-only contracts for inter-plugin interfaces** — not SDK capability modules.
+
+The framework deliberately ships **no implementation** for anything in here. Each contract describes
+a shape that a *community plugin* implements and publishes, so that consumers can depend on one
+agreed interface instead of a different ad-hoc shape per plugin:
+
+```ts
+// producer
+import type { EconService } from "@s2script/cs2/econ";
+const impl: EconService = { /* … */ };
+ctx.publish("econ", impl);          // manifest: s2script.publishes
+
+// consumer
+import type { EconService } from "@s2script/cs2/econ";
+const econ = ctx.tryUse<EconService>("econ");   // null while unpublished
+```
+
+**Why contracts and not features.** Skins and workshop integration are Valve-backend and
+game-content concerns, not engine touchpoints. Implementing them in the framework would drag the
+core toward a specific game's economy and Steam's services, against *the core is engine-generic* and
+*dependencies point one way: game → core*. Publishing the contract gets the ecosystem interop
+without the framework taking on that surface.
+
+**Rules that apply to every contract here** (they cross the plugin boundary, see
+`docs/ARCHITECTURE.md`):
+
+- Arguments and return values cross by **structured copy as JSON**. A `BigInt` throws and silently
+  drops the whole payload, so every 64-bit value (Steam IDs, workshop IDs, item IDs) is typed as a
+  **decimal string**, never `number` or `bigint`.
+- `EntityRef` is the one live-ish exception: it crosses tagged and is revived serial-gated on the
+  other side, so it stays `T | null`-safe.
+- A hard dependency (`ctx.use`) throws `InterfaceUnavailable` if the producer is absent; an optional
+  one (`ctx.tryUse`) returns `null`. For anything in here, prefer `tryUse` — these are third-party.
+- Contracts are semver-governed. Adding an optional member is a minor; changing or removing one is a
+  major.

package/contracts/workshop.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `@s2script/sdk/contracts/workshop` — the standard contract for a **workshop / UGC** plugin.
+ *
+ * TYPE-ONLY. The framework ships no implementation: subscribing to, downloading and mounting UGC is
+ * a Steam-services concern, not a Source 2 engine touchpoint. A community plugin implements this and
+ * publishes it; consumers depend on the one agreed shape. See `contracts/README.md`.
+ *
+ * Engine-generic on purpose — every Source 2 title has workshop content, so nothing here is
+ * CS2-specific. Game-specific economy lives in `@s2script/cs2/econ`.
+ *
+ * @example
+ * import type { WorkshopService } from "@s2script/sdk/contracts/workshop";
+ * const ws = ctx.tryUse<WorkshopService>("workshop");
+ * if (ws) {
+ *   const map = await ws.currentMap();
+ *   console.log(map ? `${map.title} (${map.id})` : "not a workshop map");
+ * }
+ */
+
+/**
+ * A workshop item. `id` is a **decimal string**, never a number: published-file IDs are 64-bit and a
+ * `BigInt` cannot cross the plugin boundary (it throws and drops the whole payload).
+ */
+export interface WorkshopItem {
+  /** Published-file ID as a decimal string, e.g. `"3070288894"`. */
+  readonly id: string;
+  /** Item title, or `""` when metadata has not been fetched yet. */
+  readonly title: string;
+  /** Owning author's SteamID64 as a decimal string, or `""` if unknown. */
+  readonly authorSteamId: string;
+  /** Bytes on disk once installed; `0` when not installed or unknown. */
+  readonly sizeBytes: number;
+  /** Last-updated Unix seconds; `0` if unknown. */
+  readonly updatedAt: number;
+}
+
+/** An installed workshop map, as reported by {@link WorkshopService.currentMap}. */
+export interface WorkshopMap extends WorkshopItem {
+  /** The BSP name the engine loads (what `Server.mapName` reports once live). */
+  readonly mapName: string;
+}
+
+/** Progress for an in-flight download. */
+export interface WorkshopDownloadProgress {
+  readonly id: string;
+  readonly bytesDownloaded: number;
+  readonly bytesTotal: number;
+}
+
+/**
+ * The contract a workshop plugin publishes.
+ *
+ * Everything that touches Steam is asynchronous — an implementation must not block the game frame.
+ * Methods resolve to `null`/`false` rather than throwing when an item is unknown or Steam is
+ * unreachable, so a consumer degrades instead of crashing (the framework's standing posture).
+ */
+export interface WorkshopService {
+  /** The currently-running workshop map, or `null` when the server is on a stock map. */
+  currentMap(): Promise<WorkshopMap | null>;
+
+  /** Metadata for `id`, or `null` if unknown/unreachable. */
+  info(id: string): Promise<WorkshopItem | null>;
+
+  /**
+   * Ensure `id` is installed and up to date, resolving `true` once usable.
+   * Implementations should be idempotent — calling it for an already-current item is a cheap `true`.
+   */
+  ensureInstalled(id: string): Promise<boolean>;
+
+  /** In-flight download progress, or `null` when nothing is downloading for `id`. */
+  progress(id: string): Promise<WorkshopDownloadProgress | null>;
+
+  /**
+   * Change level to a workshop map. Resolves `false` when the item is not a map, is not installed
+   * and could not be fetched, or the change was refused. On success the server changes level, so a
+   * caller should not assume any code after this runs on the same map.
+   */
+  changeMap(id: string): Promise<boolean>;
+
+  /** Every installed workshop item known to the implementation. */
+  installed(): Promise<readonly WorkshopItem[]>;
+}

package/dist/cli.js

@@ -1217,6 +1217,10 @@ function typecheckPlugin(pluginDir, opts) {
       // dirs are deleted). tsc picks the longest matching prefix, so `@s2script/sdk/*` wins for
       // sdk imports.
       "@s2script/sdk/*": ["sdk/*.d.ts"],
+      // Game-package SUBPATHS (e.g. @s2script/cs2/econ -> packages/cs2/econ.d.ts). Needed because
+      // the `@s2script/*` fallback below maps to `<pkg>/index.d.ts`, which cannot express a
+      // subpath. tsc picks the longest matching prefix, so this wins for cs2 subpath imports.
+      "@s2script/cs2/*": ["cs2/*.d.ts"],
       "@s2script/*": ["*/index.d.ts"],
       ...contractPaths
     }
@@ -4963,21 +4967,37 @@ var SUPPORTED_NAV_KINDS = /* @__PURE__ */ new Set([
   "vector",
   "qangle"
 ]);
+var WRITABLE_NAV_KINDS = /* @__PURE__ */ new Set(["f32", "bool", "i32"]);
 function buildNavModel(config, catalog) {
   const targetClasses = [...new Set(config.map((e) => e.target))];
   const schemaModel = buildModel(catalog, targetClasses);
   const sorted = [...config].sort((a2, b) => a2.wrapper < b.wrapper ? -1 : a2.wrapper > b.wrapper ? 1 : 0);
   const wrappers = sorted.map((entry) => {
     const all = flattenedFields(schemaModel, entry.target);
+    const wantWritable = new Set(entry.writable ?? []);
     const fields = [];
     const skippedKinds = [];
     for (const f of all) {
       if (SUPPORTED_NAV_KINDS.has(f.accessorKind)) {
-        fields.push(f);
+        fields.push({ ...f, navWritable: wantWritable.has(f.rawName) });
       } else {
         skippedKinds.push({ propName: f.propName, accessorKind: f.accessorKind });
       }
     }
+    for (const raw of wantWritable) {
+      const f = fields.find((x) => x.rawName === raw);
+      if (!f) {
+        const known = all.some((x) => x.rawName === raw);
+        throw new Error(
+          `nav-targets: ${entry.wrapper}.writable lists ${JSON.stringify(raw)}, which ` + (known ? `exists on ${entry.target} but has an unsupported accessor kind, so it has no nav accessor at all.` : `does not exist on ${entry.target} or any of its ancestors (renamed or removed?).`)
+        );
+      }
+      if (!WRITABLE_NAV_KINDS.has(f.accessorKind)) {
+        throw new Error(
+          `nav-targets: ${entry.wrapper}.writable lists ${JSON.stringify(raw)} (kind '${f.accessorKind}'), but there is no EntityRef.write*Via for that kind. Add the native and extend WRITABLE_NAV_KINDS, or drop the field from the allowlist.`
+        );
+      }
+    }
     return {
       wrapper: entry.wrapper,
       prop: entry.prop,
@@ -5004,6 +5024,11 @@ var READ_VIA = {
   u16: "readUInt16Via",
   u32: "readUInt32Via"
 };
+var WRITE_VIA = {
+  f32: "writeFloat32Via",
+  bool: "writeBoolVia",
+  i32: "writeInt32Via"
+};
 function emitNavJs(model) {
   const out = [HEADER4, "(function () {", "  var off = __s2_schema_offset;"];
   const vecClasses = /* @__PURE__ */ new Set();
@@ -5037,7 +5062,9 @@ function emitNavJs(model) {
         if (!method) continue;
         getter = `get: function () { return this.root.${method}(this.path, ${resolve13}); }`;
       }
-      out.push(`    ${S2(f.propName)}: { ${getter} },`);
+      const wmethod = f.navWritable ? WRITE_VIA[kind] : void 0;
+      const setter = wmethod ? `, set: function (v) { this.root.${wmethod}(this.path, ${resolve13}, v); }` : "";
+      out.push(`    ${S2(f.propName)}: { ${getter}${setter} },`);
     }
     out.push("  });");
   }
@@ -5092,9 +5119,20 @@ function emitNavDts(model) {
   if (needsEntityRef) out.push('import type { EntityRef } from "@s2script/sdk/entity";');
   out.push("");
   for (const w of model.wrappers) {
+    if (w.fields.some((f) => f.navWritable)) {
+      out.push(`/**`);
+      out.push(` * Fields NOT marked \`readonly\` are writable.`);
+      out.push(` *`);
+      out.push(` * A write takes effect immediately \u2014 the server reads these during movement \u2014 but it is **not**`);
+      out.push(` * flagged for replication, because this object is reached through a pointer chain and the`);
+      out.push(` * change-notifier addresses the root entity. A client predicting the old value may therefore`);
+      out.push(` * see brief mismatch until the next authoritative correction. SourceMod's \`SetEntPropFloat\``);
+      out.push(` * on the same fields behaves the same way.`);
+      out.push(` */`);
+    }
     out.push(`export interface ${w.wrapper} {`);
     for (const f of w.fields) {
-      out.push(`  readonly ${f.propName}: ${TSTYPE[f.accessorKind]};`);
+      out.push(`  ${f.navWritable ? "" : "readonly "}${f.propName}: ${TSTYPE[f.accessorKind]};`);
     }
     out.push("}", "");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.9.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": {
@@ -120,13 +121,19 @@
     "./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

@@ -14,6 +14,15 @@
  */
 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,

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;
+};