@s2script/sdk 0.0.1 → 0.3.0

package/topmenu.d.ts

@@ -0,0 +1,25 @@
+/** @s2script/topmenu — the extensible admin/top menu registry. NO runtime code (injected at load). */
+export interface TopMenuItem {
+  /** Plugin-namespaced unique id, e.g. "playercommands:slap". A duplicate id replaces. */
+  id: string;
+  /** Shown label. */
+  name: string;
+  /** Required ADMFLAG bit mask (adminmenu hides items the caller lacks flags for). */
+  flags: number;
+  /** Runs in THIS plugin's context when an admin selects the item; receives the admin's 0-based slot. */
+  onSelect: (adminSlot: number) => void;
+}
+export interface TopMenuSnapshot {
+  categories: string[];
+  items: { id: string; category: string; name: string; flags: number }[];
+}
+export declare const TopMenu: {
+  /** Register a category (idempotent; order = first-registration order). */
+  addCategory(name: string): void;
+  /** Register/replace an item under a category (auto-creates the category). */
+  addItem(category: string, item: TopMenuItem): void;
+  /** All categories + item metadata (no handlers) — the adminmenu renderer reads this. */
+  snapshot(): TopMenuSnapshot;
+  /** Fire an item's onSelect (dispatched post-frame to the owner's context). */
+  select(id: string, slot: number): void;
+};

package/trace.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @s2script/trace — author-time type stubs for the injected ray-tracing API.
+ * NO runtime code: the engine injects the implementation (core prelude) at load time.
+ *
+ * ENGINE-GENERIC (Source-2 physics) — over `CNavPhysicsInterface::TraceShape`, RTTI-resolved
+ * shim-side. Degrades to a MISS `TraceHit` (`didHit:false, fraction:1, entity:null`) when the
+ * underlying vtable can't be resolved (a different Source 2 game build, or in-isolate tests) —
+ * never a crash.
+ */
+import type { Vector, QAngle } from "./math";
+import type { EntityRef } from "./entity";
+
+/** Named `InteractionLayers` bitmasks for `TraceOptions.mask`/`exclude` (bitwise-OR combinable). */
+export declare const TraceMask: {
+  /** World + player-clip + windows + players/NPCs/physics-props — a bullet trace (the default). */
+  readonly ShotPhysics: number;
+  /** Hitboxes only (headshot-style detection). */
+  readonly ShotHitbox: number;
+  /** Physics + hitboxes (a full bullet trace: world geometry AND hitbox precision). */
+  readonly ShotFull: number;
+  /** World geometry only, no entities at all. */
+  readonly WorldOnly: number;
+  /** Grenade trajectory trace (world + physics props, no players). */
+  readonly Grenade: number;
+  /** Brushes only (no clip volumes, no entities). */
+  readonly BrushOnly: number;
+  /** Player movement collision (world + player-clip). */
+  readonly PlayerMove: number;
+  /** NPC movement collision (world + npc-clip). */
+  readonly NPCMove: number;
+};
+
+/** The result of a `Trace.line`/`ray`/`hull` call. */
+export interface TraceHit {
+  /** True iff the trace hit something before reaching `endPos`. */
+  didHit: boolean;
+  /** 0..1 — the fraction of the start->end segment traveled before the hit (1 = no hit). */
+  fraction: number;
+  /** The trace's final position (the hit point, or the requested end on a miss). */
+  endPos: Vector;
+  /** The surface normal at the hit point ((0,0,0) on a miss). */
+  normal: Vector;
+  /** The hit entity, or null if none was hit (or it went stale in the same frame). */
+  entity: EntityRef | null;
+  /** True iff the trace STARTED embedded in solid geometry (Source `startsolid`; CS2's CGameTrace
+   *  exposes only `m_bStartInSolid`, not a whole-segment `allsolid` flag — don't confuse with SM's TR_AllSolid). */
+  startSolid: boolean;
+}
+
+/** Options shared by `Trace.line`/`ray`/`hull`. */
+export interface TraceOptions {
+  /** `InteractionLayers` bits the trace should interact with. Default `TraceMask.ShotPhysics`. */
+  mask?: number;
+  /** `InteractionLayers` bits to explicitly exclude. Default 0 (none). */
+  exclude?: number;
+  /** An entity to ignore (e.g. the tracing pawn itself, for `pawn.aimTrace`'s self-ignore). */
+  ignoreEntity?: EntityRef;
+}
+
+export declare const Trace: {
+  /** A line trace from `start` to `end`. */
+  line(start: Vector, end: Vector, opts?: TraceOptions): TraceHit;
+  /** A line trace from `start` along `angles`' forward direction, `distance` units long. */
+  ray(start: Vector, angles: QAngle, distance: number, opts?: TraceOptions): TraceHit;
+  /** A swept-box (hull) trace from `start` to `end` with the given `mins`/`maxs` extents. */
+  hull(start: Vector, end: Vector, mins: Vector, maxs: Vector, opts?: TraceOptions): TraceHit;
+};

package/translations.d.ts

@@ -0,0 +1,10 @@
+/** @s2script/translations — SourceMod-style i18n (per-client language, phrase files, {1} formatting). */
+export type Phrases = Record<string, string>;
+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;
+  /** Translate `key` for `slot`'s language (slot < 0 = the server default), substituting positional {1}/{2} args. */
+  translate(slot: number, key: string, ...args: (string | number)[]): string;
+  /** Set the server/console default language code (default "" = root/English). */
+  setDefaultLanguage(code: string): void;
+};

package/transmit.d.ts

@@ -0,0 +1,32 @@
+/** @s2script/transmit — per-client entity visibility filtering (Source2 CheckTransmit).
+ *  Declarative rules: a plugin says "this entity is visible only to these viewer slots" and the
+ *  engine-side hook enforces it every snapshot — zero JS runs in the per-client hot path. */
+import type { EntityRef } from "./entity";
+
+export interface TransmitStats {
+  /** CheckTransmit invocations observed since load/reset. */
+  snapshots: number;
+  /** Live rule entries in the native table. */
+  entries: number;
+  /** Total transmit bits cleared since load/reset. */
+  bitsCleared: number;
+  /** Nanoseconds spent in the post-hook, last invocation. */
+  nsLast: number;
+  /** Worst single invocation (ns) since load/reset. */
+  nsMax: number;
+}
+
+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
+   *  viewer only if every plugin holding a rule on it allows that viewer. Returns false if the ref is
+   *  stale or the capability is unavailable/disabled. Throws RangeError on a slot outside [0, 64). */
+  setVisibleTo(entity: EntityRef, viewers: readonly number[]): boolean;
+  /** Remove this plugin's rule for `entity` (visible to all again, as far as this plugin is
+   *  concerned). Returns false if the ref is stale or the capability is unavailable. */
+  reset(entity: EntityRef): boolean;
+  /** Remove all of this plugin's rules. */
+  resetAll(): void;
+  /** Hot-path counters for measurement/debugging. */
+  stats(): TransmitStats;
+};

package/usercmd.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @s2script/usercmd — a SourceMod `OnPlayerRunCmd`-equivalent: intercept, read, modify, and block a
+ * player's per-tick input (buttons, view angles, movement, impulse) before the game processes it.
+ * NO runtime code (injected at load) — `CBaseUserCmdPB`/`CMsgQAngle`/`CInButtonStatePB` are a
+ * Source2-shared concept (`usercmd.proto`), so this module is engine-generic.
+ */
+import type { QAngle } from "./math";
+import type { HookResultValue } from "./events";
+
+/**
+ * A block-scoped view of the CURRENT tick's usercmd (valid only during a `UserCmd.onRun` handler —
+ * a stashed `Cmd` used after the handler returns, or across an `await`, reads/writes nothing).
+ * There is exactly ONE `Cmd` instance for the whole process; every handler call operates on it.
+ */
+export interface Cmd {
+  /** +forward / -back. Normalized to roughly [-1, 1] (not the legacy ±450 units). */
+  forwardMove: number;
+  /**
+   * +right / -left (SourceMod convention). Assigning MODIFIES the live input.
+   * Note: internally negated from the raw protobuf `leftmove` (which is +LEFT) — this field is
+   * already sign-corrected, so `sideMove > 0` always means "moving right".
+   */
+  sideMove: number;
+  /** +up / -down (e.g. crouch-jump analog). */
+  upMove: number;
+  /** The pressed impulse (e.g. 100 = +usering). */
+  impulse: number;
+  /** The pressed-button mask (`IN_*` bit values, mirrors `pawn.buttons`). 64-bit — always a real `bigint`. */
+  buttons: bigint;
+  /** View angles for this tick ({x: pitch, y: yaw, z: roll}). Assigning writes all three fields. */
+  viewAngles: QAngle;
+  /**
+   * Drop this tick's subtick analog-move deltas (optional helper). A coarse `forwardMove`/`sideMove`/
+   * `upMove` write already takes effect without this (live-verified) — call it only if you need to
+   * make sure no residual subtick analog data survives your modify. No-op if there are none.
+   */
+  clearSubtickMoves(): void;
+}
+
+export declare const UserCmd: {
+  /**
+   * Subscribe to the per-tick input hook. The handler runs SYNCHRONOUSLY during the engine's
+   * usercmd processing, once per player per batched tick; `cmd` is the singleton, block-scoped
+   * current usercmd and `ctx.slot` is the firing player's 0-based slot.
+   *
+   * Return a `HookResultValue >= Handled` to SUPPRESS this tick's input (the game processes a
+   * zeroed/idle command instead); return `Continue`/`undefined` to let the (possibly modified)
+   * command through unblocked.
+   */
+  onRun(handler: (cmd: Cmd, ctx: { slot: number }) => HookResultValue | void): void;
+};

package/usermessages.d.ts

@@ -0,0 +1,49 @@
+import type { HookResultValue } from "./events";
+
+/** A general protobuf user-message builder. Build then send in one synchronous burst. */
+export class UserMessage {
+  constructor(name: string);
+  setInt(field: string, value: number): this;
+  setFloat(field: string, value: number): this;
+  setString(field: string, value: string): this;
+  setBool(field: string, value: boolean): this;
+  /** Infer the setter from the JS value type. */
+  set(field: string, value: number | string | boolean): this;
+  /** Send to one slot or a list of slots. Returns true if delivered to >=1 real client. */
+  send(slots: number | number[]): boolean;
+  /** Broadcast to all connected non-bot clients. */
+  sendAll(): boolean;
+}
+
+// --- UserMessage interception (usermsg-hook slice) ---
+
+/** A BLOCK-SCOPED view of an intercepted outbound user message — valid only during a
+ *  UserMessages.onPre handler; across an await (or stashed) all reads return null/[]/"". */
+export interface UserMessageView {
+  /** Canonical unscoped message name (e.g. "CMsgTEFireBullets"). */
+  readonly name: string;
+  /** Numeric network-message id (e.g. 452). */
+  readonly id: number;
+  /** Recipient slots (0-based) this post targets; a broadcast decodes to all live slots. Read-only in v1. */
+  readonly recipients: number[];
+  /** protobuf TextFormat dump — the documented FALLBACK for unmapped messages only; prefer typed reads. */
+  readonly debugString: string;
+  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;
+  readFloat(path: string): number | null;
+  readBool(path: string): boolean | null;
+  readString(path: string): string | null;
+}
+
+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
+   *  to SUPPRESS the send for every recipient; Continue/undefined passes it through. THROWS at
+   *  subscribe time on an unresolvable name or a degraded intercept descriptor. */
+  onPre(name: string, handler: (msg: UserMessageView) => HookResultValue | void): void;
+  /** Removes ALL of the calling plugin's handlers for this name (mux off semantics — handler
+   *  identity not compared, matching Events.off). */
+  off(name: string, handler?: (msg: UserMessageView) => HookResultValue | void): void;
+};

package/votes.d.ts

@@ -0,0 +1,23 @@
+/** @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; }
+export interface VoteConfig {
+  question: string;
+  /** 2..9 options (chat votes are single-digit). */
+  options: string[];
+  /** seconds. */
+  duration: number;
+  /** show a live center tally (default false — the SM chat-only way). */
+  showLiveTally?: boolean;
+  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; }
+export declare const Vote: {
+  /** Start a vote (chat ballot to all connected players). Returns false if one is already active. */
+  start(config: VoteConfig): boolean;
+  isActive(): boolean;
+  /** Abort the active vote (no onEnd). */
+  cancel(): void;
+  /** Register the live-tally renderer (the CS2 center-HTML renderer). */
+  registerTallyRenderer(renderer: VoteTallyRenderer): void;
+};

package/ws.d.ts

@@ -0,0 +1,12 @@
+/** @s2script/ws — client WebSocket. NO runtime code (injected as __s2pkg_ws). */
+export interface WebSocket {
+  onMessage(handler: (data: string) => void): void;
+  onClose(handler: (code: number, reason: string) => void): void;
+  onError(handler: (err: string) => void): void;
+  send(data: string): void;
+  close(): void;
+}
+export declare const WebSocket: {
+  /** Connect to a WebSocket server (wss:// for TLS). Resolves on the open handshake; rejects on connect failure. */
+  connect(url: string): Promise<WebSocket>;
+};