@s2script/sdk 0.2.0 → 0.3.0

package/clients.d.ts

@@ -27,6 +27,13 @@ export declare class Client {
   readonly ip: string;
   /** Show `reason` (chat + console) once the client is in-game, then kick after `delaySeconds` (default 5). Intended to be called from a Clients.onConnect handler. */
   kickWithReason(reason: string, delaySeconds?: number): void;
+  /**
+   * Server-side voice mute: while true, this client's OUTGOING voice is silenced for every receiver.
+   * Framework state (not an engine field): cleared automatically on disconnect, persists across map
+   * changes while connected. If the voice descriptor is degraded (hook/validation failure — named
+   * reason in the server log), setting is an inert no-op and reads stay false.
+   */
+  voiceMuted: boolean;
 }
 export declare const Clients: {
   /** Fires when a client connects (all clients incl. bots; carries name/xuid). May be async. */
@@ -41,6 +48,12 @@ export declare const Clients: {
   onDisconnect(handler: (client: Client) => void): void;
   /** Fires when a client's settings (name/cvars) change. */
   onSettingsChanged(handler: (client: Client) => void): void;
+  /**
+   * Fires while a client transmits voice. Throttled to at most one dispatch per client per second;
+   * the FIRST packet of a transmission always fires (a lazy mute-on-talk lands immediately).
+   * Handlers should be idempotent. Never fires for bots.
+   */
+  onVoice(handler: (client: Client) => void): void;
   /** The client in `slot`, or null if the slot is empty. */
   fromSlot(slot: number): Client | null;
   /** Every currently-connected client. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.2.0",
+  "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": {
@@ -103,6 +103,9 @@
     "./translations": {
       "types": "./translations.d.ts"
     },
+    "./transmit": {
+      "types": "./transmit.d.ts"
+    },
     "./usercmd": {
       "types": "./usercmd.d.ts"
     },

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/usermessages.d.ts

@@ -1,3 +1,5 @@
+import type { HookResultValue } from "./events";
+
 /** A general protobuf user-message builder. Build then send in one synchronous burst. */
 export class UserMessage {
   constructor(name: string);
@@ -12,3 +14,36 @@ export class UserMessage {
   /** 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;
+};