@s2script/sdk 0.5.0 → 0.5.1

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