@s2script/sdk 0.0.1 → 0.2.0

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/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,14 @@
+/** 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;
+}

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