@s2script/sdk 0.8.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[]>;
+}