@s2script/sdk 0.0.1 → 0.3.0

package/entity.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @s2script/entity — author-time type stubs for the injected entity API.
+ * NO runtime code: the engine injects the implementation at load time.
+ */
+import type { HookResultValue } from "./events";
+
+/**
+ * A serial-gated handle to a live entity. Wraps the `__s2_ent_ref_*` natives; the raw
+ * entity pointer never crosses to JS. All accessors degrade safely (return null/false)
+ * when the entity slot has been reused or the ops table is absent.
+ */
+export declare class EntityRef {
+  readonly index: number;
+  readonly serial: number;
+  /** This entity's targetname (`CEntityIdentity::m_name`) — e.g. a map trigger's `"map_start"`. `""` if
+   *  the entity has no targetname; `null` if the ref is stale/invalid. */
+  readonly name: string | null;
+  constructor(index: number, serial: number);
+  /** True iff the slot's current serial still matches the captured serial. */
+  isValid(): boolean;
+  /** Read an i32 at `offset` bytes into the entity, or null if the ref is stale. */
+  readInt32(offset: number): number | null;
+  /** Write an i32 at `offset` bytes into the entity. Returns true on success, false if stale. */
+  writeInt32(offset: number, value: number): boolean;
+  /** Read an f32 at `offset` bytes into the entity, or null if the ref is stale. */
+  readFloat32(offset: number): number | null;
+  /** Write an f32 at `offset`. Returns true on success, false if stale. */
+  writeFloat32(offset: number, value: number): boolean;
+  /** Read a bool at `offset`, or null if the ref is stale. */
+  readBool(offset: number): boolean | null;
+  /** Write a bool at `offset`. Returns true on success, false if stale. */
+  writeBool(offset: number, value: boolean): boolean;
+  /** Read an i8 (sign-extended to number) at `offset`, or null if the ref is stale. */
+  readInt8(offset: number): number | null;
+  /** Read an i16 (sign-extended to number) at `offset`, or null if the ref is stale. */
+  readInt16(offset: number): number | null;
+  /** Read a u8 at `offset`, or null if the ref is stale. */
+  readUInt8(offset: number): number | null;
+  /** Read a u16 at `offset`, or null if the ref is stale. */
+  readUInt16(offset: number): number | null;
+  /** Read a u32 at `offset`, or null if the ref is stale. */
+  readUInt32(offset: number): number | null;
+  /** Write an i8 (truncated) at `offset`. Returns true on success, false if stale. */
+  writeInt8(offset: number, value: number): boolean;
+  /** Write an i16 (truncated) at `offset`. Returns true on success, false if stale. */
+  writeInt16(offset: number, value: number): boolean;
+  /** Write a u8 (truncated) at `offset`. Returns true on success, false if stale. */
+  writeUInt8(offset: number, value: number): boolean;
+  /** Write a u16 (truncated) at `offset`. Returns true on success, false if stale. */
+  writeUInt16(offset: number, value: number): boolean;
+  /** Write a u32 at `offset`. Returns true on success, false if stale. */
+  writeUInt32(offset: number, value: number): boolean;
+  /** Read a u64 at `offset` as a BigInt, or null if the ref is stale. */
+  readUInt64(offset: number): bigint | null;
+  /** Read an i64 at `offset` as a BigInt, or null if the ref is stale. */
+  readInt64(offset: number): bigint | null;
+  /** Read an f64 at `offset`, or null if the ref is stale. */
+  readFloat64(offset: number): number | null;
+  /** Read a NUL-terminated string (up to `maxLen` bytes) at `offset`, or null if the ref is stale. */
+  readString(offset: number, maxLen: number): string | null;
+  /** Write a bounded, NUL-terminated string into an inline `char[maxLen]` field at `offset` (truncated to
+   *  `maxLen-1` bytes + always NUL-terminated). Returns true on success, false if the ref is stale. */
+  writeString(offset: number, maxLen: number, value: string): boolean;
+  /** Read `count` (1..4) contiguous float32s at `offset` into a number[], or null if the ref is stale. */
+  readFloats(offset: number, count: number): number[] | null;
+  /** Follow a chain of pointer derefs (each an offset into the current target), then read `count` (1..4) floats
+   *  at `finalOff` into a number[]. All in-core (raw pointers never cross); null if the root is stale or any hop
+   *  is null. */
+  readFloatsChain(ptrOffs: number[], finalOff: number, count: number): number[] | null;
+  /** Follow a pointer chain (each an offset), then read a scalar at `finalOff`. null if the root is stale or any
+   *  hop is null. `readHandleVia` decodes a handle field → a serial-gated EntityRef; vectors use readFloatsChain. */
+  readInt32Via(pathOffs: number[], finalOff: number): number | null;
+  /** Write an int32 at the end of a pointer chain (each hop deref'd, serial-gated at the root). Returns
+   *  false on a stale ref or a null hop. Used to clear a flag on a pointer-referenced sub-object. */
+  writeInt32Via(pathOffs: number[], finalOff: number, value: number): boolean;
+  readInt8Via(pathOffs: number[], finalOff: number): number | null;
+  readInt16Via(pathOffs: number[], finalOff: number): number | null;
+  readUInt8Via(pathOffs: number[], finalOff: number): number | null;
+  readUInt16Via(pathOffs: number[], finalOff: number): number | null;
+  readUInt32Via(pathOffs: number[], finalOff: number): number | null;
+  readFloat32Via(pathOffs: number[], finalOff: number): number | null;
+  readBoolVia(pathOffs: number[], finalOff: number): boolean | null;
+  readUInt64Via(pathOffs: number[], finalOff: number): bigint | null;
+  readInt64Via(pathOffs: number[], finalOff: number): bigint | null;
+  readHandleVia(pathOffs: number[], finalOff: number): EntityRef | null;
+  /** Write a scalar through a pointer chain (write mirror of `read*Via`). Serial-gated at the root;
+   *  returns false on a stale ref, an unresolved hop, or a bad offset/kind. Does NOT notifyStateChanged —
+   *  the caller decides (many sub-object fields, e.g. the fire gate, are server-authoritative).
+   *  (`writeInt32Via` is declared above alongside `readInt32Via`.) */
+  writeFloat32Via(pathOffs: number[], finalOff: number, value: number): boolean;
+  writeBoolVia(pathOffs: number[], finalOff: number, value: boolean): boolean;
+  /** Read a `CEntityHandle` at `offset`, decode it, and return a live `EntityRef` — or null if stale/invalid. */
+  readHandle(offset: number): EntityRef | null;
+  /** Notify the engine that the field at `offset` changed (triggers network replication). No-op if stale. */
+  notifyStateChanged(offset: number): void;
+  /** DispatchSpawn this created entity. With keyvalues, the entity's own Spawn() parses them (the
+   *  SourceMod DispatchKeyValue / CSSharp DispatchSpawn(kv) mechanism). Returns false if stale,
+   *  unresolved, or the keyvalue map is rejected (non-finite number, unsupported value type, empty
+   *  key) — a rejection spawns NOTHING (never a partially-configured entity). */
+  spawn(keyvalues?: EntityKeyValueMap): boolean;
+  /** Teleport this entity. origin/angles/velocity are [x,y,z] triples; any may be null. False if stale. */
+  teleport(origin: number[] | null, angles?: number[] | null, velocity?: number[] | null): boolean;
+  /** Remove (UTIL_Remove) this entity from the world. Returns false if stale/unresolved. */
+  remove(): boolean;
+  /** Register this entity's collision bounds in the spatial partition (zones real-trigger backend).
+   *  A runtime-created trigger_multiple needs this to fire touch; false if the op is unavailable. */
+  activateCollision(): boolean;
+  /** Give this entity a model (and its collision) via `CBaseEntity::SetModel`. A runtime
+   *  `trigger_multiple` needs a model to build the physics volume that fires touch. Returns false
+   *  if the op is unavailable or the ref is stale. */
+  setModel(name: string): boolean;
+  /** Read a CUtlVector<CHandle> at (ptrOffs chain -> vectorOff) as live serial-gated EntityRefs.
+   *  Follows the pointer chain, reads count@+0 / elements@+8, caps at maxCount. [] if stale/unresolved. */
+  readHandleVector(ptrOffs: number[], vectorOff: number, maxCount?: number): EntityRef[];
+  /** Fire an entity input (e.g. "Kill"/"Ignite"/"SetHealth"/"Enable"/"Open"/"FireUser1"/"AddOutput")
+   *  via `AddEntityIOEvent` — the game's own input-firing path (map I/O and `FireOutputInternal` route
+   *  through it). `value` is the input's string argument (Source parses it per the input's field type;
+   *  omit for a value-less input). `activator`/`caller` are optional entities threaded through to any
+   *  output the input triggers. `delay` queues the event on the engine's same-tick I/O pump (0 = fires
+   *  this same tick — NOT synchronous-within-the-call). Returns false with no op / a stale ref. */
+  acceptInput(input: string, value?: string, activator?: EntityRef, caller?: EntityRef, delay?: number): boolean;
+}
+
+/** Keyvalues for a CEntityKeyValues-configured spawn. Inference: string -> SetString,
+ *  boolean -> SetBool, integer (int32) -> SetInt, other finite number -> SetFloat.
+ *  Keys are case-insensitive (hashed via MurmurHash2LowerCase, the engine's own keying). */
+export type EntityKeyValueMap = { [key: string]: string | number | boolean };
+
+/** Create a new entity by class name. WITHOUT keyvalues: create only — set fields, then call
+ *  `.spawn()`. WITH keyvalues: create + DispatchSpawn(keyvalues) in one call — a non-null result is
+ *  a LIVE, SPAWNED entity (on spawn failure the entity is removed and null returned). The created
+ *  entity is game-world-owned (NOT auto-removed on plugin unload) — the plugin owns cleanup. */
+export declare function createEntity(className: string, keyvalues?: EntityKeyValueMap): EntityRef | null;
+
+/** The payload delivered to an `Entity.onOutput` handler. */
+export interface OutputEvent {
+  /** The output's name (e.g. "OnTrigger", "OnPressed", "OnStartTouch"). */
+  output: string;
+  /** The entity that activated the chain leading to this output firing, or null. */
+  activator: EntityRef | null;
+  /** The entity that owns/fired this output (the `this` of `FireOutputInternal`), or null. */
+  caller: EntityRef | null;
+  /** The output's value, formatted as a string (MVP — typed `CVariant` marshalling is deferred). */
+  value: string;
+  /** The output's fire delay in seconds (0 = same-tick). */
+  delay: number;
+}
+
+/**
+ * Hook Source 2 entity outputs (`func_button`→`OnPressed`, `trigger_multiple`→`OnStartTouch`,
+ * `logic_relay`→`OnTrigger`, …) via a `FireOutputInternal` detour. `classname`/`output` accept `"*"`
+ * wildcards. The handler runs SYNCHRONOUSLY (may block): returning a `HookResultValue >= Handled`
+ * (2/3) SUPPRESSES the output — the original `FireOutputInternal` call is skipped.
+ */
+export declare const Entity: {
+  onOutput(classname: string, output: string, handler: (ev: OutputEvent) => HookResultValue | void): void;
+  /**
+   * Fire when the engine CREATES an entity of `className` (`"*"` = all) — earliest hook; the entity is
+   * barely constructed, schema fields may be zero/default. The handler receives the serial-gated
+   * `entity` (may be `null`) plus its `className`. Prefer `onSpawn` to read fields.
+   */
+  onCreate(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  /**
+   * Fire after the engine SPAWNS an entity of `className` (`"*"` = all) — `Spawn()` has run, so schema
+   * fields/keyvalues are populated. The useful hook for reading state.
+   */
+  onSpawn(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  /**
+   * Fire as the engine DELETES an entity of `className` (`"*"` = all). The entity is still readable
+   * during the synchronous handler; a stashed ref reads `null` once the slot is freed (serial gate),
+   * never garbage.
+   */
+  onDelete(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  /** Find every entity whose designer-name (class) exactly matches `className`. Returns serial-gated refs. */
+  findByClass(className: string): EntityRef[];
+};

package/events.d.ts

@@ -0,0 +1,46 @@
+/** @s2script/events — author-time stubs for the injected game-event API. NO runtime code. */
+
+/** 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 {
+  readonly name: string;
+  getInt(key: string): number;
+  getFloat(key: string): number;
+  getBool(key: string): boolean;
+  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;
+  setInt(key: string, value: number): void;
+  setFloat(key: string, value: number): void;
+  setBool(key: string, value: boolean): void;
+  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;
+}
+
+/** 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 type HookResultValue = 0 | 1 | 2 | 3;
+
+export declare const Events: {
+  /** Subscribe to a game event by name. The handler runs synchronously when the event fires. */
+  on(name: string, handler: (ev: GameEvent) => void): void;
+  /**
+   * Unsubscribe from a game event by name.
+   *
+   * **Note:** `off` removes ALL of the calling plugin's handlers for the given event name —
+   * handler identity is NOT compared. This matches the engine-op semantics: the mux removes
+   * every subscription the current plugin holds for `name` in one call. Avoid double-subscribing
+   * the same name with different handlers if you need selective removal.
+   */
+  off(name: string, handler: (ev: GameEvent) => void): void;
+  /** Pre-hook: runs before the event broadcasts; may read+modify `ev` and return a HookResult to block. */
+  onPre(name: string, handler: (ev: GameEvent) => HookResultValue | void): void;
+  /** Fire a game event. Returns the engine FireEvent result. */
+  fire(name: string, fields?: Record<string, number | string | boolean | bigint>, dontBroadcast?: boolean): boolean;
+  /** Fire a game event to ONE client (SourceMod FireToClient). Same field type-inference as `fire`. Returns false on miss. */
+  fireToClient(slot: number, name: string, fields?: Record<string, string | number | boolean | bigint>): boolean;
+};

package/frame.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @s2script/frame — author-time type stubs for the per-frame subscription API.
+ * NO runtime code: the engine injects the implementation at load time.
+ */
+
+export interface SubscribeOptions {
+  priority?: number;
+}
+
+export declare const OnGameFrame: {
+  /** Register a callback that fires every game frame. */
+  subscribe(fn: () => void, opts?: SubscribeOptions): void;
+};

package/globals.d.ts

@@ -0,0 +1,12 @@
+// @s2script/globals — ambient declarations for the globals the engine injects into EVERY plugin
+// context. NO runtime code, NO import/export (this is a global/script .d.ts). Included by the
+// 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). */
+declare const console: {
+  log(...data: any[]): void;
+  error(...data: any[]): void;
+  warn(...data: any[]): void;
+  info(...data: any[]): void;
+};

package/http.d.ts

@@ -0,0 +1,11 @@
+/** @s2script/http — async HTTP. NO runtime code (injected as __s2pkg_http). */
+export interface FetchOptions { method?: string; headers?: Record<string, string>; body?: string; timeoutMs?: number; }
+export interface Response {
+  readonly status: number; readonly ok: boolean; readonly statusText: string;
+  readonly headers: Record<string, string>;
+  text(): string;
+  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. */
+export declare function fetch(url: string, options?: FetchOptions): Promise<Response>;

package/interfaces.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @s2script/interfaces — author-time type stubs for typed inter-plugin interfaces.
+ * NO runtime code: the engine injects the implementation at load time.
+ */
+
+/**
+ * Handle returned by {@link publishInterface}: lets the producer emit forwarded
+ * 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(event: string, payload: unknown): void;
+}
+
+/**
+ * Publish a typed inter-plugin interface under `name`. `impl`'s methods become the
+ * natives consumers call (`interface.method(...)`); the returned handle's `emit` fans
+ * forwarded events out to consumers' `on(event, …)` subscriptions.
+ *
+ * The interface's VERSION is injected by the host from this plugin's manifest
+ * `publishes` map — never passed here, and never written in TypeScript source.
+ * Publishing a name the manifest does not declare is refused at load.
+ *
+ * `impl` is generic over `object` rather than `Record<string, Function>` so that a
+ * producer can bind it to its contract — `const impl: Zones = {…}` — which is what
+ * actually proves the implementation matches the published `.d.ts`. A TypeScript
+ * `interface` has no implicit index signature (only a `type` alias does), so a
+ * `Record<…>` parameter would reject every interface-typed contract. The host
+ * enumerates `impl`'s own function properties; non-function properties are ignored.
+ *
+ * Auto-ledgered: the interface is withdrawn (and hard-dep consumers degraded) on unload.
+ */
+export declare function publishInterface<T extends object>(
+  name: string,
+  impl: T,
+): PublishHandle;

package/math.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @s2script/math — author-time type stubs for the injected math value types.
+ * 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). */
+export declare class Vector {
+  x: number;
+  y: number;
+  z: number;
+  constructor(x: number, y: number, z: number);
+  /** Euclidean magnitude — e.g. speed from a velocity vector. */
+  length(): number;
+  toString(): string;
+}
+
+/** A Source 2 Euler angle value (x=pitch, y=yaw, z=roll), a copied snapshot. */
+export declare class QAngle {
+  x: number;
+  y: number;
+  z: number;
+  constructor(x: number, y: number, z: number);
+  toString(): string;
+}
+
+/** The unit forward-direction vector for a Euler angle (pitch=`a.x`, yaw=`a.y`; ignores roll). */
+export declare function forwardVector(a: QAngle): Vector;

package/menu.d.ts

@@ -0,0 +1,38 @@
+/** @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; }
+
+export declare class Menu {
+  constructor(title?: string);
+  title: string;
+  /** Which registered renderer to use. Falls back to Chat if the style's renderer is unregistered. */
+  style: MenuStyle;
+  /** Append an auto Exit control (default true). */
+  exitButton: boolean;
+  /** When true, a renderer that supports it (the CS2 center renderer) freezes the player's movement
+   *  while the menu is open and restores it on close — buttons still register, so WASD nav still works.
+   *  The chat renderer ignores it. Default false (movement allowed, the normal behavior). */
+  freezePlayer: boolean;
+  /** (info, display) — `info` is returned to onSelect; `display` is shown. */
+  addItem(info: string, display: string, opts?: { disabled?: boolean }): void;
+  onSelect(handler: (e: MenuSelectEvent) => void): void;
+  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;
+  /** Close an open menu for `slot` early. */
+  close(slot: number): void;
+  /** Register a display backend under a MenuStyle value (used by the CS2 center renderer). */
+  static registerRenderer(name: string, renderer: MenuRenderer): void;
+}
+
+export interface MenuSession {
+  readonly slot: number;
+  view(): { title: string; lines: MenuLine[]; page: number; pageCount: number; exit: boolean };
+  pickNumber(n: number): void;
+  moveUp(): void; moveDown(): void; confirm(): void; cancel(): 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

@@ -0,0 +1,19 @@
+/** @s2script/net — engine-generic raw TCP + UDP sockets (binary), off the game thread. */
+export interface TcpSocket {
+  send(data: Uint8Array | string): void;
+  onData(handler: (bytes: Uint8Array) => void): void;
+  onClose(handler: () => void): void;
+  onError(handler: (err: string) => void): void;
+  close(): void;
+}
+export interface UdpSocket {
+  sendTo(host: string, port: number, data: Uint8Array | string): void;
+  onMessage(handler: (from: { host: string; port: number }, bytes: Uint8Array) => void): void;
+  close(): void;
+}
+export declare const Net: {
+  /** Connect a TCP client. Rejects on connect failure. */
+  connectTcp(host: string, port: number): Promise<TcpSocket>;
+  /** Bind a UDP socket on an ephemeral local port. */
+  udp(): Promise<UdpSocket>;
+};

package/package.json

@@ -1,13 +1,125 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.0.1",
-  "description": "s2script SDK — types + CLI for building Source 2 / CS2 plugins. Placeholder release that bootstraps the package name + OIDC trusted publishing; the real per-capability type subpaths (@s2script/sdk/entity, …) and the `s2s` CLI land in 0.1.0 via the consolidation (Part C).",
+  "version": "0.3.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",
+  "bin": {
+    "s2s": "dist/cli.js"
+  },
+  "scripts": {
+    "prepare": "node build.mjs",
+    "build": "node build.mjs",
+    "test": "node --experimental-strip-types --no-warnings --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "esbuild": "^0.25.0",
+    "adm-zip": "^0.5.16",
+    "typescript": "^5.6.0"
+  },
+  "devDependencies": {
+    "@types/adm-zip": "^0.5.7"
+  },
   "publishConfig": {
     "access": "public"
   },
   "files": [
+    "dist",
+    "*.d.ts",
     "README.md"
   ],
+  "exports": {
+    "./admin": {
+      "types": "./admin.d.ts"
+    },
+    "./bans": {
+      "types": "./bans.d.ts"
+    },
+    "./chat": {
+      "types": "./chat.d.ts"
+    },
+    "./clients": {
+      "types": "./clients.d.ts"
+    },
+    "./commands": {
+      "types": "./commands.d.ts"
+    },
+    "./config": {
+      "types": "./config.d.ts"
+    },
+    "./console": {
+      "types": "./console.d.ts"
+    },
+    "./cookies": {
+      "types": "./cookies.d.ts"
+    },
+    "./damage": {
+      "types": "./damage.d.ts"
+    },
+    "./db": {
+      "types": "./db.d.ts"
+    },
+    "./entity": {
+      "types": "./entity.d.ts"
+    },
+    "./events": {
+      "types": "./events.d.ts"
+    },
+    "./frame": {
+      "types": "./frame.d.ts"
+    },
+    "./http": {
+      "types": "./http.d.ts"
+    },
+    "./interfaces": {
+      "types": "./interfaces.d.ts"
+    },
+    "./math": {
+      "types": "./math.d.ts"
+    },
+    "./menu": {
+      "types": "./menu.d.ts"
+    },
+    "./net": {
+      "types": "./net.d.ts"
+    },
+    "./plugins": {
+      "types": "./plugins.d.ts"
+    },
+    "./server": {
+      "types": "./server.d.ts"
+    },
+    "./sound": {
+      "types": "./sound.d.ts"
+    },
+    "./timers": {
+      "types": "./timers.d.ts"
+    },
+    "./topmenu": {
+      "types": "./topmenu.d.ts"
+    },
+    "./trace": {
+      "types": "./trace.d.ts"
+    },
+    "./translations": {
+      "types": "./translations.d.ts"
+    },
+    "./transmit": {
+      "types": "./transmit.d.ts"
+    },
+    "./usercmd": {
+      "types": "./usercmd.d.ts"
+    },
+    "./usermessages": {
+      "types": "./usermessages.d.ts"
+    },
+    "./votes": {
+      "types": "./votes.d.ts"
+    },
+    "./ws": {
+      "types": "./ws.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/GabeHirakawa/s2script.git"

package/plugins.d.ts

@@ -0,0 +1,18 @@
+/** @s2script/plugins — runtime plugin management (the SM `sm plugins` backend). NO runtime code (injected). */
+export interface PluginInfo {
+  /** the plugin id (from its manifest). */
+  readonly id: string;
+  /** true = running; false = manually unloaded (on disk but not running, via `unload`). */
+  readonly loaded: boolean;
+}
+export declare const Plugins: {
+  /** Every loaded/unloaded plugin. */
+  list(): PluginInfo[];
+  /** Unload a running plugin (deferred to the next frame drain). false if it isn't loaded. It stays
+   * unloaded (not auto-reloaded by the file-watcher) until `load`/`reload`. */
+  unload(id: string): boolean;
+  /** Reload a plugin (unload + load from disk, deferred). false if the id is unknown. */
+  reload(id: string): boolean;
+  /** Load a previously-unloaded plugin (deferred). false if it isn't currently unloaded. */
+  load(id: string): boolean;
+};

package/server.d.ts

@@ -0,0 +1,43 @@
+/** @s2script/server — server control (run console commands, query map validity). NO runtime code (injected at load). */
+export declare const Server: {
+  /** Run `cmd` at the server console (queued; executes next frame). */
+  command(cmd: string): void;
+  /** Whether `map` is an installed, valid map file. */
+  isMapValid(map: string): boolean;
+  /** A cvar's current value as a string. `""` if the cvar doesn't exist (or an unsupported type → `"<type>"`). */
+  getCvar(name: string): string;
+  /**
+   * Set a cvar via the server console (so any type is accepted). SECURITY: this builds and runs a console
+   * command (`<name> <value>`), which the console splits on `;` — treat `value` like `command()` input and
+   * sanitize/quote any untrusted value to avoid command injection. Queued: applies next frame.
+   */
+  setCvar(name: string, value: string): void;
+  /**
+   * Register a plugin-owned ConVar (CSSharp FakeConVar / SM CreateConVar parity). Idempotent —
+   * re-registering an existing name is a no-op success, and the cvar + its value persist across
+   * plugin reloads (SourceMod parity). The shim adds FCVAR_RELEASE (customer-visible); `flags`
+   * are additive raw FCVAR bits. Read the value with `getCvar`; set it with `setCvar`/the console.
+   * `min`/`max` apply to numeric types only.
+   */
+  registerCvar(name: string, opts: {
+    type: "bool" | "int" | "float" | "string";
+    default: boolean | number | string;
+    help?: string;
+    flags?: number;
+    min?: number;
+    max?: number;
+  }): boolean;
+  /**
+   * Subscribe to map start (fires on every server map startup — the framework event that replaces
+   * polling `Server.mapName` on OnGameFrame). Boot-loaded plugins receive the first map's fire;
+   * a plugin hot-loaded mid-map does NOT get a synthetic fire for the current map — read
+   * `Server.mapName` at load. Torn down automatically on plugin unload.
+   */
+  onMapStart(handler: (mapName: string) => void): void;
+  /** The server's configured max client count (`GetMaxClients()`). `0` if unavailable. */
+  readonly maxPlayers: number;
+  /** The current map name (`GetMapName()`, the BSP). `""` if unavailable. */
+  readonly mapName: string;
+  /** The current map time in seconds (`GetGlobals()->curtime`). `0` if unavailable. */
+  readonly gameTime: number;
+};

package/sound.d.ts

@@ -0,0 +1,35 @@
+/** @s2script/sound — engine-generic sound: emit a named SoundEvent + register custom precache paths. */
+import type { EntityRef } from "./entity";
+
+export interface SoundEmitOptions {
+  /** Source entity (serial-gated; a stale ref emits nothing and returns 0). Omitted -> worldspawn
+   *  (a global/2D sound). */
+  entity?: EntityRef;
+  /** Recipient player slots. Omitted -> every valid client. Bot slots are always skipped
+   *  (no netchannel); an all-bot-skipped set still emits to nobody (a real, safe engine call),
+   *  whereas requesting NO recipients (an empty array) returns 0 without emitting. */
+  recipients?: number[];
+  /** Volume in [0, 1]. Default 1.0 (out-of-range/NaN clamps to 1.0). */
+  volume?: number;
+}
+
+/** Block-scoped precache context — valid ONLY during the onPrecache dispatch. Synchronous use
+ *  only: a stashed context used after the handler returns (or past an await) is a no-op `false`
+ *  (the engine manifest is gone). */
+export interface PrecacheContext {
+  /** Add a resource path (e.g. "soundevents/mypack.vsndevts") to the session resource manifest.
+   *  True iff the engine accepted the add. */
+  add(path: string): boolean;
+}
+
+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
+   *  function / stale source entity / an empty `recipients` array). An all-bot-skipped recipient
+   *  set still emits to nobody (a real engine call, may return a nonzero GUID). */
+  emit(name: string, opts?: SoundEmitOptions): number;
+  /** Subscribe to the session resource-manifest build (fires at map load / mapchange). Register
+   *  custom .vsndevts/.vsnd content here so a later emit can play it. A plugin hot-loaded mid-map
+   *  gets its first fire at the NEXT map change. */
+  onPrecache(handler: (ctx: PrecacheContext) => void): void;
+};

package/timers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @s2script/timers — author-time type stubs for the async timing API.
+ * NO runtime code: the engine injects the implementation at load time.
+ */
+
+/** Await a delay of `ms` milliseconds before continuing. */
+export declare function delay(ms: number): Promise<void>;
+/** Yield to the next microtick. */
+export declare function nextTick(): Promise<void>;
+/** Yield until the next game frame. */
+export declare function nextFrame(): Promise<void>;
+/**
+ * Block the current thread (fiber) for `ms` milliseconds.
+ * Only valid inside a threadSleep-capable fiber context.
+ */
+export declare function threadSleep(ms: number): void;