@s2script/sdk 0.5.0 → 0.5.1

package/events.d.ts

@@ -3,18 +3,27 @@
 /** A live game-event accessor. Valid ONLY during the synchronous handler — read fields before any `await`;
  *  a stashed GameEvent used later reads defaults. The raw engine event never crosses to JS. */
 export declare class GameEvent {
+  /** The event's name (e.g. `"player_death"`). */
   readonly name: string;
+  /** Read an integer field. `0` if absent or non-integer. */
   getInt(key: string): number;
+  /** Read a float field. `0` if absent or non-float. */
   getFloat(key: string): number;
+  /** Read a boolean field. `false` if absent. */
   getBool(key: string): boolean;
+  /** Read a string field. `""` if absent. */
   getString(key: string): string;
   /** A 64-bit field as a decimal string (SM-parity, wire-safe). */
   getUint64(key: string): string;
   /** A player field (e.g. "userid"/"attacker") as a 0-based slot, or -1 if absent. Resolve with Player.fromSlot. */
   getPlayerSlot(key: string): number;
+  /** Overwrite an integer field on the live event (valid only in the synchronous handler). */
   setInt(key: string, value: number): void;
+  /** Overwrite a float field on the live event (valid only in the synchronous handler). */
   setFloat(key: string, value: number): void;
+  /** Overwrite a boolean field on the live event (valid only in the synchronous handler). */
   setBool(key: string, value: boolean): void;
+  /** Overwrite a string field on the live event (valid only in the synchronous handler). */
   setString(key: string, value: string): void;
   /** Set a 64-bit field from a decimal string (SM-parity, wire-safe). */
   setUint64(key: string, value: string): void;
@@ -22,9 +31,26 @@ export declare class GameEvent {
 
 /** Collapsed pre-hook result. Return from an `onPre` handler; `Handled`/`Stop` suppress the client
  *  broadcast (server still processes). Returning nothing = `Continue`. */
-export declare const HookResult: { readonly Continue: 0; readonly Changed: 1; readonly Handled: 2; readonly Stop: 3 };
+export declare const HookResult: {
+  /** No change — proceed normally. Equivalent to returning nothing. */
+  readonly Continue: 0;
+  /** Fields were modified in place; proceed with the changes (the client broadcast still happens). */
+  readonly Changed: 1;
+  /** Suppress the client broadcast (the server still processes the event). */
+  readonly Handled: 2;
+  /** Suppress the client broadcast AND stop running lower-priority handlers. The collapse takes the MAX. */
+  readonly Stop: 3;
+};
+/** The numeric union an `onPre` handler may return — one of the {@link HookResult} values. */
 export type HookResultValue = 0 | 1 | 2 | 3;
 
+/**
+ * Fire and target game events from JS.
+ * @example
+ * import { Events } from "@s2script/sdk/events";
+ * // plugins/playercommands/src/plugin.ts:78 — announce a name change
+ * Events.fire("player_changename", { userid: p.userId, oldname, newname });
+ */
 export declare const Events: {
   /** Fire a game event. Returns the engine FireEvent result. */
   fire(name: string, fields?: Record<string, number | string | boolean | bigint>, dontBroadcast?: boolean): boolean;

package/globals.d.ts

@@ -3,7 +3,12 @@
 // typecheck gate as a root file so plugins that use these globals WITHOUT importing type-check against
 // the real sandbox — NOT lib.dom (the sandbox has no window/document/etc.).
 
-/** The engine-injected console (a subset of the browser/node console). */
+/**
+ * The engine-injected console (a subset of the browser/node console). Global — no import needed.
+ * @example
+ * // plugins/antiflood/src/plugin.ts:48 — write a line to the server console/log
+ * console.log("[antiflood] onLoad — chat flood protection active");
+ */
 declare const console: {
   log(...data: any[]): void;
   error(...data: any[]): void;

package/http.d.ts

@@ -1,11 +1,42 @@
 /** @s2script/http — async HTTP. NO runtime code (injected as __s2pkg_http). */
-export interface FetchOptions { method?: string; headers?: Record<string, string>; body?: string; timeoutMs?: number; }
+
+/** Options for {@link fetch}. */
+export interface FetchOptions {
+  /** HTTP method (e.g. `"GET"`, `"POST"`). @defaultValue `"GET"` */
+  method?: string;
+  /** Request headers as a name→value map. */
+  headers?: Record<string, string>;
+  /** Request body (already-serialized string; set your own `content-type`). */
+  body?: string;
+  /** Abort the request after this many milliseconds. @defaultValue no timeout */
+  timeoutMs?: number;
+}
+
+/** The response from a {@link fetch} call — a copied snapshot (no live socket). */
 export interface Response {
-  readonly status: number; readonly ok: boolean; readonly statusText: string;
+  /** HTTP status code (e.g. `200`, `404`). */
+  readonly status: number;
+  /** True iff {@link Response.status} is in the 2xx range. */
+  readonly ok: boolean;
+  /** HTTP status reason phrase (e.g. `"Not Found"`). */
+  readonly statusText: string;
+  /** Response headers as a lower-cased name→value map. */
   readonly headers: Record<string, string>;
+  /** The response body decoded as text. */
   text(): string;
+  /** Parse the response body as JSON into `T` (throws on invalid JSON). */
   json<T = unknown>(): T;
 }
-/** Perform an HTTP request off the game thread. Rejects on a network error / timeout; an HTTP
- *  status (incl. 4xx/5xx) RESOLVES with ok=false. */
+
+/**
+ * Perform an HTTP request off the game thread.
+ * @param url - Absolute `http(s)://` URL.
+ * @param options - Method, headers, body, and timeout (see {@link FetchOptions}).
+ * @returns Resolves for ANY HTTP response — a 4xx/5xx resolves with `ok=false`, it does not reject.
+ * @throws Rejects only on a network error or timeout.
+ * @example
+ * import { fetch } from "@s2script/sdk/http";
+ * const r = await fetch("https://httpbin.org/get", { timeoutMs: 15000 });
+ * if (r.ok) console.log(r.json<{ url: string }>().url);
+ */
 export declare function fetch(url: string, options?: FetchOptions): Promise<Response>;

package/interfaces.d.ts

@@ -8,6 +8,13 @@
  * events to every plugin subscribed to this interface via its `on(event, …)`.
  */
 export interface PublishHandle {
-  /** Emit a forwarded event to all consumers subscribed via `interface.on(event, …)`. */
+  /**
+   * Emit a forwarded event to all consumers subscribed via `interface.on(event, …)`. The payload is
+   * structured-copied across the context boundary (JSON, EntityRef-aware — never a live reference).
+   * @example
+   * import type { PublishHandle } from "@s2script/sdk/interfaces";
+   * // plugins/zones/src/plugin.ts:30 — notify consumers a zone was created
+   * iface.emit("created", { zone: z.name, min: z.min, max: z.max, tags: z.tags });
+   */
   emit(event: string, payload: unknown): void;
 }

package/math.d.ts

@@ -3,23 +3,37 @@
  * NO runtime code: the engine injects the implementation (core prelude) at load time.
  */
 
-/** A 3-component vector value (a copied snapshot; never a live pointer). */
+/**
+ * A 3-component vector value (a copied snapshot; never a live pointer).
+ * @example
+ * import { Vector } from "@s2script/sdk/math";
+ * const start = new Vector(0, 0, 100);
+ * console.log(start.length());
+ */
 export declare class Vector {
+  /** The X component. */
   x: number;
+  /** The Y component. */
   y: number;
+  /** The Z component. */
   z: number;
   constructor(x: number, y: number, z: number);
   /** Euclidean magnitude — e.g. speed from a velocity vector. */
   length(): number;
+  /** Format as `"Vector(x, y, z)"` (for logging). */
   toString(): string;
 }
 
 /** A Source 2 Euler angle value (x=pitch, y=yaw, z=roll), a copied snapshot. */
 export declare class QAngle {
+  /** Pitch, in degrees. */
   x: number;
+  /** Yaw, in degrees. */
   y: number;
+  /** Roll, in degrees. */
   z: number;
   constructor(x: number, y: number, z: number);
+  /** Format as `"QAngle(x, y, z)"` (for logging). */
   toString(): string;
 }
 

package/menu.d.ts

@@ -1,12 +1,62 @@
 /** @s2script/menu — interactive player menus (chat + center backends). NO runtime code (injected at load). */
-export declare const enum MenuStyle { Chat = "chat", Center = "center" }
-export declare const enum MenuCancelReason { Exit = 0, Timeout = 1, Disconnect = 2, NewMenu = 3 }
 
-export interface MenuSelectEvent { readonly slot: number; readonly item: number; readonly info: string; readonly display: string; }
-export interface MenuCancelEvent { readonly slot: number; readonly reason: MenuCancelReason; }
+/** The display backend a {@link Menu} renders through — the value of {@link Menu.style}. */
+export declare const enum MenuStyle {
+  /** Chat-log backend: numbered lines printed to chat, picked by typing the number. */
+  Chat = "chat",
+  /** CS2 center-screen HTML backend: W/S move the cursor, E selects; re-painted each tick. */
+  Center = "center",
+}
+/** Why a menu closed without a selection — the {@link MenuCancelEvent.reason}. */
+export declare const enum MenuCancelReason {
+  /** The player chose the Exit control (or `close`/`cancel` was called). */
+  Exit = 0,
+  /** The `display` seconds elapsed with no selection. */
+  Timeout = 1,
+  /** The player left the server. */
+  Disconnect = 2,
+  /** A newer menu was shown to the same slot, superseding this one. */
+  NewMenu = 3,
+}
+
+/** Payload for {@link Menu.onSelect} — the item a player picked. */
+export interface MenuSelectEvent {
+  /** 0-based player slot that made the selection. */
+  readonly slot: number;
+  /** 0-based index of the chosen item within the menu's item list. */
+  readonly item: number;
+  /** The `info` string the item was added with — the machine key, returned to your handler. */
+  readonly info: string;
+  /** The visible label the item was added with. */
+  readonly display: string;
+}
+/** Payload for {@link Menu.onCancel} — a menu that closed without a selection. */
+export interface MenuCancelEvent {
+  /** 0-based player slot whose menu closed. */
+  readonly slot: number;
+  /** Why it closed (see {@link MenuCancelReason}). */
+  readonly reason: MenuCancelReason;
+}
 
+/**
+ * A slot-based interactive menu. Add items, wire {@link Menu.onSelect}/{@link Menu.onCancel},
+ * then {@link Menu.display} to a player slot. The model paginates automatically (7 items per chat
+ * page) and picks a renderer by {@link Menu.style}, falling back to Chat when the style's renderer
+ * is unregistered. Only one menu is active per slot; displaying a new one supersedes the old
+ * ({@link MenuCancelReason.NewMenu}).
+ * @example
+ * import { Menu, MenuStyle } from "@s2script/sdk/menu";
+ * const m = new Menu("s2script Menu Demo");
+ * m.style = MenuStyle.Center;
+ * m.freezePlayer = true;                 // freeze movement while the WASD menu is open (nav still works)
+ * m.addItem("hp", "Heal to 100");
+ * m.addItem("noclip", "Toggle Noclip");
+ * m.onSelect(e => { console.log(`picked ${e.info} (slot ${e.slot})`); });
+ * m.display(slot, 30);
+ */
 export declare class Menu {
   constructor(title?: string);
+  /** Heading shown above the item list. */
   title: string;
   /** Which registered renderer to use. Falls back to Chat if the style's renderer is unregistered. */
   style: MenuStyle;
@@ -18,7 +68,9 @@ export declare class Menu {
   freezePlayer: boolean;
   /** (info, display) — `info` is returned to onSelect; `display` is shown. */
   addItem(info: string, display: string, opts?: { disabled?: boolean }): void;
+  /** Register the callback fired when a player picks an item. Replaces any previous handler. */
   onSelect(handler: (e: MenuSelectEvent) => void): void;
+  /** Register the callback fired when the menu closes without a selection (see {@link MenuCancelReason}). Replaces any previous handler. */
   onCancel(handler: (e: MenuCancelEvent) => void): void;
   /** Show to a 0-based slot for `seconds` (0 = until selection/cancel/disconnect). */
   display(slot: number, seconds?: number): void;
@@ -28,11 +80,44 @@ export declare class Menu {
   static registerRenderer(name: string, renderer: MenuRenderer): void;
 }
 
+/** A live display of one menu to one slot, passed to a {@link MenuRenderer}. Owns the page/cursor state and exposes the input verbs a renderer drives. */
 export interface MenuSession {
+  /** 0-based player slot this session is displayed to. */
   readonly slot: number;
+  /** The resolved snapshot the renderer paints: heading, per-line state, and 0-based page position. */
   view(): { title: string; lines: MenuLine[]; page: number; pageCount: number; exit: boolean };
+  /** Chat idiom: apply a number-key press against the current view (1..7 select, 8=Back, 9=Next, 0=Exit). */
   pickNumber(n: number): void;
-  moveUp(): void; moveDown(): void; confirm(): void; cancel(): void;
+  /** Center idiom: move the cursor up over the current page's nav targets (items + Back/Next/Exit), wrapping. */
+  moveUp(): void;
+  /** Center idiom: move the cursor down over the current page's nav targets, wrapping. */
+  moveDown(): void;
+  /** Center idiom: activate the current cursor target (select an item, paginate, or exit). */
+  confirm(): void;
+  /** Close this session with an {@link MenuCancelReason.Exit}. */
+  cancel(): void;
+}
+/** One rendered line of a {@link MenuSession} view. */
+export interface MenuLine {
+  /** The line's visible text. */
+  text: string;
+  /** The chat number key ("1".."0") that picks this line, or null for an unselectable/disabled line. */
+  key: string | null;
+  /** True if this line is a selectable item. */
+  selectable: boolean;
+  /** True if the center cursor is currently on this line (the renderer highlights it). */
+  cursor?: boolean;
+  /** For a control line, which control it is: `"back"`, `"next"`, or `"exit"` (absent on item lines). */
+  control?: string;
+  /** For an item line, its 0-based index into the menu's item list (absent on control lines). */
+  index?: number;
+}
+/** A display backend for {@link Menu} — registered via {@link Menu.registerRenderer}, driven with a {@link MenuSession}. */
+export interface MenuRenderer {
+  /** Show the session for the first time (the menu just opened). */
+  open(session: MenuSession): void;
+  /** Re-paint the session after a page/cursor change. */
+  update(session: MenuSession): void;
+  /** Tear down the display for `slot` (the menu closed). */
+  close(slot: number): void;
 }
-export interface MenuLine { text: string; key: string | null; selectable: boolean; cursor?: boolean; control?: string; index?: number; }
-export interface MenuRenderer { open(session: MenuSession): void; update(session: MenuSession): void; close(slot: number): void; }

package/net.d.ts

@@ -1,19 +1,43 @@
 /** @s2script/net — engine-generic raw TCP + UDP sockets (binary), off the game thread. */
+
+/** A connected TCP client socket — a per-plugin handle over a copied byte stream (no live socket crosses to JS). */
 export interface TcpSocket {
+  /** Send bytes; a `string` is sent as its UTF-8 encoding. */
   send(data: Uint8Array | string): void;
+  /** Register a handler invoked for each inbound chunk of bytes. */
   onData(handler: (bytes: Uint8Array) => void): void;
+  /** Register a handler for the peer closing the connection. */
   onClose(handler: () => void): void;
+  /** Register a handler for a transport error; `err` is the error text. */
   onError(handler: (err: string) => void): void;
+  /** Close the connection. */
   close(): void;
 }
+/** A bound UDP socket — a per-plugin handle for connectionless datagrams. */
 export interface UdpSocket {
+  /** Send a datagram to `host:port`; a `string` is sent as its UTF-8 encoding. */
   sendTo(host: string, port: number, data: Uint8Array | string): void;
+  /** Register a handler invoked for each inbound datagram; `from` is the sender's address. */
   onMessage(handler: (from: { host: string; port: number }, bytes: Uint8Array) => void): void;
+  /** Close the socket. */
   close(): void;
 }
+/** Entry point for opening raw TCP + UDP sockets. */
 export declare const Net: {
-  /** Connect a TCP client. Rejects on connect failure. */
+  /**
+   * Connect a TCP client to `host:port` off the game thread.
+   * @returns Resolves on connect with the live {@link TcpSocket} handle.
+   * @throws Rejects on connect failure (refused, unreachable, DNS error).
+   * @example
+   * import { Net } from "@s2script/sdk/net";
+   * const sock = await Net.connectTcp("127.0.0.1", 9000);
+   * sock.onData((bytes) => console.log("got " + bytes.length + " bytes"));
+   * sock.send("hello");
+   */
   connectTcp(host: string, port: number): Promise<TcpSocket>;
-  /** Bind a UDP socket on an ephemeral local port. */
+  /**
+   * Bind a UDP socket on an ephemeral local port.
+   * @returns Resolves with the bound {@link UdpSocket} handle.
+   */
   udp(): Promise<UdpSocket>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "s2script SDK — the builtin capability types (imported as @s2script/sdk/entity, …) plus the `s2s` CLI for building Source 2 / CS2 plugins.",
   "type": "module",
   "bin": {

package/plugin.d.ts

@@ -16,8 +16,16 @@ import type { TopMenuItem } from "./topmenu";
 import type { PrecacheContext } from "./sound";
 import type { UserCmdView } from "./usercmd";
 
+/** Game-event subscriptions on this plugin's load-scope ({@link PluginContext.events}). */
 export interface CtxEvents {
+  /**
+   * Subscribe to a fired game event (post-phase). The {@link GameEvent} is valid only synchronously.
+   * @example
+   * // plugins/disabled/nextmap/src/plugin.ts:133
+   * ctx.events.on("round_end", () => console.log("round ended"));
+   */
   on(name: string, handler: (ev: GameEvent) => void): void;
+  /** Pre-hook a game event: return a {@link HookResultValue} (`Handled`/`Stop` suppress the client broadcast). */
   onPre(name: string, handler: (ev: GameEvent) => HookResultValue | void): void;
 }
 /**
@@ -27,37 +35,73 @@ export interface CtxEvents {
  * out of its real order).
  */
 export interface CtxClients {
+  /** A client began connecting (pre-auth). */
   onConnect(handler: (client: Client) => void | Promise<void>): void;
+  /** A client's entity was put in the server (`ClientPutInServer`). */
   onPutInServer(handler: (client: Client) => void | Promise<void>): void;
+  /** A client became fully active (in-game, receiving snapshots). */
   onActive(handler: (client: Client) => void | Promise<void>): void;
+  /** A client finished authenticating (Steam ticket validated). */
   onFullyConnect(handler: (client: Client) => void | Promise<void>): void;
+  /** A client disconnected. */
   onDisconnect(handler: (client: Client) => void): void;
+  /** A client's convars/settings changed (`ClientSettingsChanged`). */
   onSettingsChanged(handler: (client: Client) => void): void;
+  /** A client sent a voice packet (per-frame while speaking). */
   onVoice(handler: (client: Client) => void): void;
+  /** A client's persisted cookies finished loading and are now readable. */
   onCookiesCached(handler: (client: Client) => void): void;
+  /** A client sent chat: return a {@link HookResultValue} to suppress it. @param teamonly - team-channel say. */
   onSay(handler: (slot: number, text: string, teamonly: boolean) => HookResultValue | void): void;
+  /** Per-tick usercmd hook (SM `OnPlayerRunCmd`): read/modify {@link UserCmdView}; return `Handled` to block the tick. */
   onRunCmd(handler: (cmd: UserCmdView, info: { slot: number }) => HookResultValue | void): void;
 }
+/** Entity lifecycle + damage subscriptions on this plugin's load-scope ({@link PluginContext.entities}). */
 export interface CtxEntities {
+  /** An entity of `className` was created (not yet spawned). @param className - match, or `"*"` for all. */
   onCreate(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  /** An entity of `className` spawned (post-`DispatchSpawn`). */
   onSpawn(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  /** An entity of `className` is being deleted; the ref goes stale right after. */
   onDelete(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  /** Hook a named entity output (`FireOutputInternal`); return a {@link HookResultValue} to suppress it. */
   onOutput(classname: string, output: string, handler: (ev: OutputEvent) => HookResultValue | void): void;
+  /**
+   * Damage pre-hook (SDKHooks-equivalent): read/modify {@link DamageInfo}; return `Handled` semantics via `info`.
+   * @example
+   * // plugins/basecommands/src/plugin.ts:81 — halve incoming damage
+   * ctx.entities.onDamage((info) => { info.damage = info.damage / 2; });
+   */
   onDamage(handler: (info: DamageInfo) => HookResultValue | void): void;
 }
+/** Per-frame + map/precache hooks on this plugin's load-scope ({@link PluginContext.server}). */
 export interface CtxServer {
+  /** Run `fn` every game frame. @param opts - `priority` orders it within the frame (`monitor` runs last, read-only). */
   onGameFrame(fn: () => void, opts?: { priority?: "high" | "normal" | "low" | "monitor" }): void;
+  /** A new map became live; `mapName` is the BSP name. */
   onMapStart(handler: (mapName: string) => void): void;
+  /** Precache window — register models/sounds to precache for the current map. */
   onPrecache(handler: (pc: PrecacheContext) => void): void;
 }
+/** Console/chat command registration on this plugin's load-scope ({@link PluginContext.commands}). */
 export interface CtxCommands {
+  /** Register a public command (any client may run it). */
   register(name: string, handler: (cmd: CommandInvocation) => void): void;
+  /** Register a server-only command (console/rcon, not client-runnable). */
   registerServer(name: string, handler: (cmd: CommandInvocation) => void): void;
+  /** Register an admin command gated by `flags` (an `ADMFLAG` bitmask; fail-safe default-deny). */
   registerAdmin(name: string, flags: number, handler: (cmd: CommandInvocation) => void): void;
 }
-export interface CtxConfig { onChange(handler: (cfg: Config) => void): void; }
+/** Config live-reload subscription on this plugin's load-scope ({@link PluginContext.config}). */
+export interface CtxConfig {
+  /** Fires when the plugin's config file is re-materialized on disk; re-read values inside. */
+  onChange(handler: (cfg: Config) => void): void;
+}
+/** TopMenu (adminmenu) contribution on this plugin's load-scope ({@link PluginContext.topmenu}). */
 export interface CtxTopMenu {
+  /** Add (or reuse) a top-level menu category. */
   addCategory(name: string): void;
+  /** Add an item under an existing category. */
   addItem(category: string, item: TopMenuItem): void;
 }
 
@@ -67,29 +111,49 @@ export type InterfaceHandle<T extends object> = T & {
   on(event: string, handler: (payload: any) => void): void;
 };
 
+/**
+ * A disposable bundle of subscriptions ({@link PluginContext.createScope}). Registering through a scope
+ * lets you drop the whole group at once with {@link Scope.clear} without unloading the plugin.
+ */
 export interface Scope {
+  /** Game-event subscriptions bound to this scope. */
   readonly events: CtxEvents;
+  /** Client-lifecycle subscriptions bound to this scope. */
   readonly clients: CtxClients;
+  /** Entity/damage subscriptions bound to this scope. */
   readonly entities: CtxEntities;
+  /** Per-frame/map subscriptions bound to this scope. */
   readonly server: CtxServer;
   /** Remove every subscription this scope holds; the scope stays usable (re-register on next open). */
   clear(): void;
   /** clear() + permanently retire the scope. Idempotent. */
   dispose(): void;
+  /** True once {@link Scope.dispose} has run. */
   readonly disposed: boolean;
 }
 
+/**
+ * The load-scoped context passed to a plugin's {@link PluginFactory}. Its sub-objects register every
+ * subscription; all registration is load-window only (buffered, armed at Active).
+ */
 export interface PluginContext {
   /** This plugin's id (manifest `id`). */
   readonly id: string;
   /** The revived hot-reload handoff (the previous instance's `state()` return), or undefined. */
   readonly previous: unknown;
+  /** Game-event subscriptions ({@link CtxEvents}). */
   readonly events: CtxEvents;
+  /** Client-lifecycle subscriptions ({@link CtxClients}). */
   readonly clients: CtxClients;
+  /** Entity/damage subscriptions ({@link CtxEntities}). */
   readonly entities: CtxEntities;
+  /** Per-frame/map/precache subscriptions ({@link CtxServer}). */
   readonly server: CtxServer;
+  /** Console/chat command registration ({@link CtxCommands}). */
   readonly commands: CtxCommands;
+  /** Config live-reload subscription ({@link CtxConfig}). */
   readonly config: CtxConfig;
+  /** TopMenu (adminmenu) contribution ({@link CtxTopMenu}). */
   readonly topmenu: CtxTopMenu;
   /** Publish this plugin's manifest-declared interface. Buffered; goes live at Active. */
   publish<T extends object>(name: string, impl: T): PublishHandle;
@@ -101,12 +165,31 @@ export interface PluginContext {
   createScope(): Scope;
 }
 
+/** Optional lifecycle hooks a {@link PluginFactory} may return to participate in unload + hot-reload. */
 export interface PluginHooks {
   /** Best-effort cleanup at unload (the ledger remains the teardown authority). */
   onUnload?(): void;
   /** Hot-reload handoff capture; JSON-serialized (EntityRef-aware) and revived as the next instance's ctx.previous. */
   state?(): unknown;
 }
+/**
+ * A plugin's body: called once at load with the {@link PluginContext}, optionally returning
+ * {@link PluginHooks}. May be async (the load waits for it to settle).
+ */
 export type PluginFactory = (ctx: PluginContext) => void | PluginHooks | Promise<void | PluginHooks>;
-export interface PluginDefinition { readonly __s2plugin: 1; }
+/** The opaque artifact {@link plugin} returns; a module must `export default` it to be a valid plugin. */
+export interface PluginDefinition {
+  /** Brand tag proving this object came from {@link plugin} (host-checked at load). */
+  readonly __s2plugin: 1;
+}
+/**
+ * Define a plugin from its factory. `export default` the result — the host calls the factory once at load.
+ * @example
+ * import { plugin } from "@s2script/sdk/plugin";
+ * // examples/greeter-plugin/src/plugin.ts:8
+ * export default plugin((ctx) => {
+ *   const handle = ctx.publish("@demo/greeter", impl);
+ *   ctx.server.onGameFrame(() => handle.emit("greeted", { slot: 0 }));
+ * });
+ */
 export declare function plugin(factory: PluginFactory): PluginDefinition;

package/plugins.d.ts

@@ -1,4 +1,6 @@
 /** @s2script/plugins — runtime plugin management (the SM `sm plugins` backend). NO runtime code (injected). */
+
+/** A snapshot of one plugin's identity and lifecycle state, as returned by {@link Plugins.list}. */
 export interface PluginInfo {
   /** the plugin id (from its manifest). */
   readonly id: string;
@@ -15,6 +17,13 @@ export interface PluginInfo {
    */
   readonly state: "running" | "loading" | "waiting" | "failed" | "unloaded";
 }
+/**
+ * Enumerate and drive the plugin set at runtime (list / load / unload / reload).
+ * @example
+ * import { Plugins } from "@s2script/sdk/plugins";
+ * // plugins/basecommands/src/plugin.ts:126 — sm plugins list
+ * for (const p of Plugins.list()) cmd.reply(p.id + " — " + p.state);
+ */
 export declare const Plugins: {
   /** Every loaded/unloaded plugin. */
   list(): PluginInfo[];

package/server.d.ts

@@ -1,4 +1,12 @@
 /** @s2script/server — server control (run console commands, query map validity). NO runtime code (injected at load). */
+
+/**
+ * Server console + globals: run commands, register/read/set cvars, and query map/time state.
+ * @example
+ * import { Server } from "@s2script/sdk/server";
+ * // plugins/basecommands/src/plugin.ts:46 — sm_map
+ * Server.command("changelevel " + map);
+ */
 export declare const Server: {
   /** Run `cmd` at the server console (queued; executes next frame). */
   command(cmd: string): void;

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;