@s2script/sdk 0.13.0 → 0.14.0

package/events.d.ts

@@ -55,5 +55,24 @@ 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;
   /** Fire a game event to ONE client (SourceMod FireToClient). Same field type-inference as `fire`. Returns false on miss. */
+  /**
+   * Restrict the event currently being pre-dispatched to `slots`, instead of hiding it from everyone.
+   *
+   * Only meaningful from inside an `onPre` handler that ALSO returns `HookResult.Handled`. The pair
+   * means "do not broadcast this normally — deliver it to exactly these viewers". An empty array hides
+   * it from every client.
+   *
+   * This exists because CS2 fans a game event out to clients as one message PER CLIENT, so plain
+   * suppression is all-or-nothing. Naming recipients keeps every field the engine populated, which
+   * re-firing a rebuilt copy per viewer does not.
+   *
+   * @example
+   * ctx.events.onPre("player_death", () => {
+   *   Events.setRecipients(traitorSlots);   // only Traitors see the kill
+   *   return HookResult.Handled;
+   * });
+   */
+  setRecipients(slots: readonly number[]): void;
+
   fireToClient(slot: number, name: string, fields?: Record<string, string | number | boolean | bigint>): boolean;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "license": "MIT OR Apache-2.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",

package/plugin.d.ts

@@ -77,7 +77,18 @@ export interface CtxEntities {
 /** 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;
+  /**
+   * Run `fn` every game frame.
+   *
+   * `phase` picks WHERE in the frame it runs and defaults to `"pre"` (before simulation). Use
+   * `"post"` when the work must land after the engine's own per-frame writes — re-asserting a netvar
+   * the engine re-derives during simulation is overwritten if written in `"pre"`, because the
+   * derivation happens after and the outgoing snapshot carries the engine's value.
+   */
+  onGameFrame(
+    fn: () => void,
+    opts?: { priority?: "high" | "normal" | "low" | "monitor"; phase?: "pre" | "post" },
+  ): 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. */