@s2script/sdk 0.5.0 → 0.6.0

package/sound.d.ts

@@ -1,6 +1,7 @@
 /** @s2script/sound — engine-generic sound: emit a named SoundEvent + register custom precache paths. */
 import type { EntityRef } from "./entity";
 
+/** Options for {@link Sound.emit} — the source entity, recipient slots, and volume. */
 export interface SoundEmitOptions {
   /** Source entity (serial-gated; a stale ref emits nothing and returns 0). Omitted -> worldspawn
    *  (a global/2D sound). */
@@ -22,6 +23,14 @@ export interface PrecacheContext {
   add(path: string): boolean;
 }
 
+/**
+ * Engine-generic sound entry point — play a named SoundEvent to some or all clients.
+ * @example
+ * import { Sound } from "@s2script/sdk/sound";
+ * // global 2D broadcast to every valid client (worldspawn source):
+ * const guid = Sound.emit("MyPack.Ping");
+ * if (guid === 0) console.log("emit failed (unresolved name / stale source)");
+ */
 export declare const Sound: {
   /** Play a named SoundEvent (the engine resolves name->hash; built-in soundevents need no
    *  precache). Returns the engine sound GUID (nonzero) or 0 on failure (unresolved engine

package/timers.d.ts

@@ -3,7 +3,13 @@
  * NO runtime code: the engine injects the implementation at load time.
  */
 
-/** Await a delay of `ms` milliseconds before continuing. */
+/**
+ * Await a delay of `ms` milliseconds before continuing. Tick-integrated (resumes on a game frame).
+ * @example
+ * import { delay } from "@s2script/sdk/timers";
+ * // plugins/funcommands/src/plugin.ts:77 — sm_freeze auto-unfreeze after `secs`
+ * delay(secs * 1000).then(() => { const q = Player.fromSlot(slot); if (q && q.pawn) q.pawn.moveType = WALK; });
+ */
 export declare function delay(ms: number): Promise<void>;
 /** Yield to the next microtick. */
 export declare function nextTick(): Promise<void>;

package/topmenu.d.ts

@@ -1,4 +1,6 @@
 /** @s2script/topmenu — the extensible admin/top menu registry. NO runtime code (injected at load). */
+
+/** A single registered top-menu entry (an admin command surfaced in the adminmenu). */
 export interface TopMenuItem {
   /** Plugin-namespaced unique id, e.g. "playercommands:slap". A duplicate id replaces. */
   id: string;
@@ -9,10 +11,23 @@ export interface TopMenuItem {
   /** Runs in THIS plugin's context when an admin selects the item; receives the admin's 0-based slot. */
   onSelect: (adminSlot: number) => void;
 }
+/** A handler-free copy of the whole registry — what a menu renderer reads to build the display. */
 export interface TopMenuSnapshot {
+  /** All category names, in registration order. */
   categories: string[];
+  /** Every registered item's metadata (no `onSelect`), tagged with its category. */
   items: { id: string; category: string; name: string; flags: number }[];
 }
+/**
+ * The shared admin/top-menu registry — renderers read {@link TopMenu.snapshot} and dispatch picks
+ * through {@link TopMenu.select}; items are contributed by plugins via their own ctx.topmenu.
+ * @example
+ * import { TopMenu } from "@s2script/sdk/topmenu";
+ * const snap = TopMenu.snapshot();
+ * for (const cat of snap.categories) renderCategory(cat);
+ * // when the admin picks an item id, dispatch it back to its owner plugin:
+ * m.onSelect(e => { TopMenu.select(e.info, slot); });
+ */
 export declare const TopMenu: {
   /** All categories + item metadata (no handlers) — the adminmenu renderer reads this. */
   snapshot(): TopMenuSnapshot;

package/trace.d.ts

@@ -57,6 +57,14 @@ export interface TraceOptions {
   ignoreEntity?: EntityRef;
 }
 
+/**
+ * Ray-tracing entry point — `line`/`ray`/`hull` traces over the Source 2 physics scene.
+ * @example
+ * import { Trace } from "@s2script/sdk/trace";
+ * import { Vector } from "@s2script/sdk/math";
+ * const down = Trace.line(new Vector(o.x, o.y, o.z + 500), new Vector(o.x, o.y, o.z - 100));
+ * if (down.didHit) console.log(down.fraction, down.endPos);
+ */
 export declare const Trace: {
   /** A line trace from `start` to `end`. */
   line(start: Vector, end: Vector, opts?: TraceOptions): TraceHit;

package/translations.d.ts

@@ -1,5 +1,15 @@
 /** @s2script/translations — SourceMod-style i18n (per-client language, phrase files, {1} formatting). */
+
+/** A phrase set: key → template string, where `{1}`/`{2}`/… are positional substitution slots. */
 export type Phrases = Record<string, string>;
+/**
+ * SourceMod-style translation registry: seed a default phrase set, override it per language from
+ * `translations/<code>/<name>.phrases.json`, then translate a key for a given client's language.
+ * @example
+ * import { Translations } from "@s2script/sdk/translations";
+ * Translations.load("trdemo", { Greeting: "Hello {1}", Bye: "Goodbye {1}" });
+ * console.log(Translations.translate(-1, "Greeting", "world")); // "Hello world"
+ */
 export declare const Translations: {
   /** Register a phrase set: `seed` is the built-in English default; translations/<code>/<name>.phrases.json overrides per language. */
   load(name: string, seed: Phrases): void;

package/transmit.d.ts

@@ -3,6 +3,7 @@
  *  engine-side hook enforces it every snapshot — zero JS runs in the per-client hot path. */
 import type { EntityRef } from "./entity";
 
+/** Hot-path measurement counters returned by {@link Transmit.stats}. */
 export interface TransmitStats {
   /** CheckTransmit invocations observed since load/reset. */
   snapshots: number;
@@ -16,6 +17,13 @@ export interface TransmitStats {
   nsMax: number;
 }
 
+/**
+ * Declarative per-client entity visibility: hide an entity from some viewers, enforced engine-side each snapshot.
+ * @example
+ * import { Transmit } from "@s2script/sdk/transmit";
+ * // examples/transmit-demo/src/plugin.ts:58 — show `prop` ONLY to one viewer slot
+ * const ok = Transmit.setVisibleTo(prop, [slot]);
+ */
 export declare const Transmit: {
   /** Replace this plugin's visibility rule for `entity`: it is transmitted ONLY to the given viewer
    *  slots (an empty array = hidden from everyone). Multiple plugins AND-merge — an entity reaches a

package/usercmd.d.ts

@@ -11,6 +11,12 @@ import type { QAngle } from "./math";
  * handler — a stashed `UserCmdView` used after the handler returns, or across an `await`,
  * reads/writes nothing). There is exactly ONE `UserCmdView` instance for the whole process; every
  * handler call operates on it.
+ * @example
+ * import type { UserCmdView } from "@s2script/sdk/usercmd";
+ * // examples/usercmd-demo/src/plugin.ts:21 — read this tick's input
+ * ctx.clients.onRunCmd((cmd: UserCmdView, info: { slot: number }) => {
+ *   console.log(`slot=${info.slot} fwd=${cmd.forwardMove} btn=${cmd.buttons}`);
+ * });
  */
 export interface UserCmdView {
   /** +forward / -back. Normalized to roughly [-1, 1] (not the legacy ±450 units). */

package/usermessages.d.ts

@@ -3,9 +3,13 @@ import type { HookResultValue } from "./events";
 /** A general protobuf user-message builder. Build then send in one synchronous burst. */
 export class UserMessage {
   constructor(name: string);
+  /** Set an integer field. Returns `this` for chaining. */
   setInt(field: string, value: number): this;
+  /** Set a float field. Returns `this` for chaining. */
   setFloat(field: string, value: number): this;
+  /** Set a string field. Returns `this` for chaining. */
   setString(field: string, value: string): this;
+  /** Set a boolean field. Returns `this` for chaining. */
   setBool(field: string, value: boolean): this;
   /** Infer the setter from the JS value type. */
   set(field: string, value: number | string | boolean): this;
@@ -28,15 +32,29 @@ export interface UserMessageView {
   readonly recipients: number[];
   /** protobuf TextFormat dump — the documented FALLBACK for unmapped messages only; prefer typed reads. */
   readonly debugString: string;
+  /** Whether `path` is present on the current message. Dotted nested paths supported ("origin.x"). */
   hasField(path: string): boolean;
   /** Scalar int read (int32/uint32/fixed32/enum; bool as 0/1). Dotted nested paths supported
    *  ("origin.x" walks sub-messages). null = no such field / repeated / no current message. */
   readInt(path: string): number | null;
+  /** Scalar float read (float/double). Dotted nested paths supported. null if absent/repeated/no message. */
   readFloat(path: string): number | null;
+  /** Scalar bool read. Dotted nested paths supported. null if absent/repeated/no message. */
   readBool(path: string): boolean | null;
+  /** Scalar string/bytes read. Dotted nested paths supported. null if absent/repeated/no message. */
   readString(path: string): string | null;
 }
 
+/**
+ * Intercept outbound user messages before delivery (read typed fields, optionally suppress the send).
+ * @example
+ * import { UserMessages } from "@s2script/sdk/usermessages";
+ * import { HookResult, type HookResultValue } from "@s2script/sdk/events";
+ * // examples/usermsg-demo/src/plugin.ts:15 — blanket-block radio text
+ * UserMessages.onPre("CCSUsrMsg_RadioText", (m): HookResultValue | void => {
+ *   if (blockRadio) return HookResult.Handled;
+ * });
+ */
 export declare const UserMessages: {
   /** Pre-hook an outbound user message by unscoped name (partial match, SayText2-style; the view
    *  carries the canonical name). Runs SYNCHRONOUSLY before delivery. Return >= HookResult.Handled

package/votes.d.ts

@@ -1,6 +1,17 @@
 /** @s2script/votes — chat-ballot voting with revote + an optional live center tally. NO runtime code (injected at load). */
-export interface VoteResult { readonly winner: number | null; readonly counts: number[]; readonly total: number; }
+
+/** The outcome delivered to {@link VoteConfig.onEnd} when a vote ends. */
+export interface VoteResult {
+  /** 0-based index of the winning option, or null on a tie or zero votes. */
+  readonly winner: number | null;
+  /** Per-option vote counts, parallel to {@link VoteConfig.options}. */
+  readonly counts: number[];
+  /** Total votes cast. */
+  readonly total: number;
+}
+/** Configuration for {@link Vote.start}. */
 export interface VoteConfig {
+  /** The question shown to voters. */
   question: string;
   /** 2..9 options (chat votes are single-digit). */
   options: string[];
@@ -8,13 +19,45 @@ export interface VoteConfig {
   duration: number;
   /** show a live center tally (default false — the SM chat-only way). */
   showLiveTally?: boolean;
+  /** Called once when the vote ends (or is exhausted), with the tallied {@link VoteResult}. It may start a new vote (the lock is released first). */
   onEnd: (result: VoteResult) => void;
 }
-export interface VoteTally { question: string; options: { label: string; count: number }[]; total: number; secondsLeft: number; }
-export interface VoteTallyRenderer { show(slot: number, tally: VoteTally): void; clear(slot: number): void; }
+/** A per-tick snapshot of an in-progress vote, handed to a {@link VoteTallyRenderer}. */
+export interface VoteTally {
+  /** The question being voted on. */
+  question: string;
+  /** Each option's label and current vote count. */
+  options: { label: string; count: number }[];
+  /** Total votes cast so far. */
+  total: number;
+  /** Seconds remaining before the vote ends. */
+  secondsLeft: number;
+}
+/** A live-tally display backend for votes — registered via {@link Vote.registerTallyRenderer}. */
+export interface VoteTallyRenderer {
+  /** Show/update the running tally for `slot`. */
+  show(slot: number, tally: VoteTally): void;
+  /** Remove the tally display for `slot` (the vote ended or the player left). */
+  clear(slot: number): void;
+}
+/**
+ * The voting entry point — one active chat-ballot vote at a time, tallied on close.
+ * @example
+ * import { Vote } from "@s2script/sdk/votes";
+ * Vote.start({
+ *   question: `Kick ${name}?`,
+ *   options: ["Yes", "No"],
+ *   duration: 20,
+ *   showLiveTally: true,
+ *   onEnd: (r) => {
+ *     if (r.winner === 0 && r.counts[0] > r.total / 2) kick(name);
+ *   },
+ * });
+ */
 export declare const Vote: {
   /** Start a vote (chat ballot to all connected players). Returns false if one is already active. */
   start(config: VoteConfig): boolean;
+  /** True while a vote is running (the single-vote lock is held). */
   isActive(): boolean;
   /** Abort the active vote (no onEnd). */
   cancel(): void;

package/ws.d.ts

@@ -1,12 +1,29 @@
 /** @s2script/ws — client WebSocket. NO runtime code (injected as __s2pkg_ws). */
+
+/** An open WebSocket connection — a per-plugin handle over a copied message stream (no live socket crosses to JS). */
 export interface WebSocket {
+  /** Register a handler invoked for each inbound text frame. */
   onMessage(handler: (data: string) => void): void;
+  /** Register a handler for connection close; `code`/`reason` come from the close frame. */
   onClose(handler: (code: number, reason: string) => void): void;
+  /** Register a handler for a transport error; `err` is the error text. */
   onError(handler: (err: string) => void): void;
+  /** Send a text frame. */
   send(data: string): void;
+  /** Close the connection. */
   close(): void;
 }
+/** Entry point for opening WebSocket connections. */
 export declare const WebSocket: {
-  /** Connect to a WebSocket server (wss:// for TLS). Resolves on the open handshake; rejects on connect failure. */
+  /**
+   * Connect to a WebSocket server (`wss://` for TLS) off the game thread.
+   * @returns Resolves on the open handshake with the live {@link WebSocket} handle.
+   * @throws Rejects on connect failure (bad URL, refused, TLS/handshake error).
+   * @example
+   * import { WebSocket } from "@s2script/sdk/ws";
+   * const ws = await WebSocket.connect("wss://ws.postman-echo.com/raw");
+   * ws.onMessage((data) => { console.log("echo:", data); ws.close(); });
+   * ws.send("hello-from-s2script");
+   */
   connect(url: string): Promise<WebSocket>;
 };