@s2script/sdk 0.31.0 → 0.33.0

package/clients.d.ts

@@ -73,6 +73,94 @@ export declare class Client {
    * client.fakeCommand("say hello");   // as though the player typed it
    */
   fakeCommand(cmd: string): boolean;
+  /**
+   * Ask this client for its own value of a cvar (SourceMod `QueryClientConVar`). The client
+   * answers over the network, so this resolves on a later frame.
+   *
+   * Resolves `null` when no query was sent (a bot, a disconnected client, a name that is empty or
+   * contains whitespace, or a build where the reply hook is unavailable) or when the client
+   * disconnects or has not answered within 15 seconds. `value` is `""` unless `status` is `"ok"`.
+   *
+   * The value is what the client reports. A modified client can report anything, so treat it as a
+   * hint, not proof.
+   *
+   * @example
+   * const reply = await client.queryConVar("cl_interp_ratio");
+   * if (reply?.status === "ok") console.log(`${client.name}: ${reply.value}`);
+   */
+  queryConVar(name: string): Promise<ConVarQueryResult | null>;
+  /**
+   * Set this client's own copy of a replicated cvar without touching the server's value
+   * (SourceMod `SendConVarValue`). The client applies it only to cvars the server is allowed to
+   * replicate; the next server-side change to that cvar overwrites it. Booleans send `"1"`/`"0"`.
+   *
+   * Returns `false` for a bot, a disconnected client or an empty name.
+   *
+   * @example
+   * client.replicateConVar("sv_cheats", true);   // client-side only, e.g. for a practice HUD
+   */
+  replicateConVar(name: string, value: string | number | boolean): boolean;
+  /**
+   * One snapshot of this client's network counters, read from the engine's net channel
+   * (SourceMod `GetClientLatency`, `GetClientAvgLoss`, `GetClientAvgChoke`, `GetClientAvgData`,
+   * `GetClientAvgPackets`, `GetClientTime`, `IsClientTimingOut` and `GetClientDataRate` in one
+   * call). Read it again for fresh values; nothing in it updates on its own.
+   *
+   * Returns `null` for a bot (bots have no net channel), a disconnected client, or a server build
+   * whose net-channel layout this build has not been verified against.
+   *
+   * @example
+   * const stats = client.netStats();
+   * if (stats) console.log(`${client.name}: ${Math.round(stats.avgLatency * 1000)} ms, ` +
+   *   `${(stats.avgLoss.incoming * 100).toFixed(1)}% loss`);
+   */
+  netStats(): ClientNetStats | null;
+}
+/** A value measured separately for each direction, as seen from the server. */
+export interface NetFlowPair {
+  /** Server to client. */
+  outgoing: number;
+  /** Client to server. */
+  incoming: number;
+}
+/** What {@link Client.netStats} returns. Times are in seconds. */
+export interface ClientNetStats {
+  /** Average packet latency. */
+  avgLatency: number;
+  /** The engine's current round-trip estimate: more accurate than `avgLatency`, but jittery. */
+  engineLatency: number;
+  /** Average packet loss, from 0 to 1. */
+  avgLoss: NetFlowPair;
+  /** Average choke, from 0 to 1. */
+  avgChoke: NetFlowPair;
+  /** Average data rate in bytes per second. */
+  avgData: NetFlowPair;
+  /** Average packets per second. */
+  avgPackets: NetFlowPair;
+  /** Bytes sent or received since the client connected. */
+  totalData: NetFlowPair;
+  /** Packets sent or received since the client connected. */
+  totalPackets: NetFlowPair;
+  /** How long the client has been connected. */
+  timeConnected: number;
+  /** Time since the last packet from the client arrived. */
+  timeSinceLastReceived: number;
+  /** Whether the channel is about to time out. */
+  isTimingOut: boolean;
+  /** The send data rate the channel is allowed, in bytes per second. */
+  dataRate: number;
+}
+/**
+ * How a client answered {@link Client.queryConVar}: `"ok"` (value is set), `"notFound"` (no such
+ * cvar), `"notValid"` (the name is a command, not a cvar), `"protected"` (the client refused to
+ * reveal it), or `"unknown"` for a status this build does not recognise.
+ */
+export type ConVarQueryStatus = "ok" | "notFound" | "notValid" | "protected" | "unknown";
+/** The client's answer to {@link Client.queryConVar}. */
+export interface ConVarQueryResult {
+  status: ConVarQueryStatus;
+  /** The client's value, or `""` when `status` is not `"ok"`. */
+  value: string;
 }
 /**
  * Look up connected clients by slot or enumerate them all.

package/dist/cli.js

@@ -3517,7 +3517,7 @@ function stripJsonComments(src) {
 // src/gamedata/types.ts
 var PLATFORM = "linuxsteamrt64";
 var ARG_KINDS = ["bool", "int", "float", "string", "utlstring", "vector", "entity", "ptr"];
-var RET_KINDS = ["void", "bool", "int", "float", "entity", "ptr"];
+var RET_KINDS = ["void", "bool", "int", "float", "entity", "ptr", "utlstringlist"];
 var INT_CLASS_ARGS = /* @__PURE__ */ new Set(["bool", "int", "string", "utlstring", "vector", "entity", "ptr"]);
 var MAX_INT_ARGS = 9;
 var MAX_FLOAT_ARGS = 8;
@@ -3587,11 +3587,14 @@ function validatePluginGamedata(gd, opts) {
     }
     const decl = rawDecl;
     const recv = decl.receiver;
-    if (!recv || recv.kind !== "entity" && recv.kind !== "none") {
-      errs.push(`${where2}: receiver.kind must be "entity" or "none"`);
-    } else if (recv.kind === "none") {
+    if (!recv || recv.kind !== "entity" && recv.kind !== "none" && recv.kind !== "interface") {
+      errs.push(`${where2}: receiver.kind must be "entity", "none" or "interface"`);
+    } else if (recv.kind === "none" || recv.kind === "interface") {
       if (recv.via !== void 0) {
-        errs.push(`${where2}: receiver.kind "none" cannot carry a 'via' sub-object hop`);
+        errs.push(`${where2}: receiver.kind "${recv.kind}" cannot carry a 'via' sub-object hop`);
+      }
+      if (recv.kind === "interface" && (typeof recv.name !== "string" || !recv.name.length)) {
+        errs.push(`${where2}: receiver.kind "interface" needs a 'name' (the interface version string)`);
       }
     } else if (recv.via !== void 0) {
       const via = recv.via;
@@ -3959,14 +3962,15 @@ var RET_TS = {
   int: "number | null",
   float: "number | null",
   entity: "EntityRef | null",
-  ptr: "Ptr | null"
+  ptr: "Ptr | null",
+  utlstringlist: "string[] | null"
 };
 function generateGamedataTypes(gd) {
   const calls = gd.calls ?? {};
   const lines = Object.keys(calls).sort().map((name) => {
     const decl = calls[name];
     const names = decl.argNames;
-    const receiverless = decl.receiver?.kind === "none";
+    const receiverless = decl.receiver?.kind === "none" || decl.receiver?.kind === "interface";
     const params = [
       ...receiverless ? [] : ["self: EntityRef"],
       ...decl.args.map((a2, i2) => `${names?.[i2] ?? `a${i2}`}: ${ARG_TS[a2]}`)

package/entity.d.ts

@@ -88,6 +88,25 @@ export declare class EntityRef {
    *  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;
+  /**
+   * Zero-allocation bulk read for per-tick hot paths: one liveness check, then every field `plan`
+   * names, written as numbers into your preallocated `out` starting at `outIndex` (default 0).
+   *
+   * `plan` is a flat run of entries `[hops, hop0..hopN-1, finalOff, kind, count]`: follow `hops`
+   * (0..8) pointer offsets, then read `count` (1..16) contiguous {@link GatherKind} elements at
+   * `finalOff`. An entry whose chain hits a null pointer writes `NaN` into its slots; the rest of
+   * the plan still runs. Build the plan once and reuse both arrays every tick.
+   *
+   * Returns the slot count written, `-1` when the ref is stale, or `-2` for a malformed plan or an
+   * `out` too short for the whole plan (nothing is written in either failure case).
+   * @example
+   * import { GatherKind } from "@s2script/sdk/entity";
+   * // two floats at +0x10, then one u8 behind the pointer at +0x30
+   * const plan = new Int32Array([0, 0x10, GatherKind.Float32, 2, 1, 0x30, 0x8, GatherKind.UInt8, 1]);
+   * const out = new Float64Array(3);
+   * if (ref.gather(plan, out) === 3) console.log(out[0], out[1], out[2]);
+   */
+  gather(plan: Int32Array, out: Float64Array, outIndex?: number): number;
   /** The `Vector` at `offset`, or null if the ref is stale. */
   readVector(offset: number): Vector | null;
   /** The `QAngle` at `offset`, or null if the ref is stale. */
@@ -166,6 +185,38 @@ export declare class EntityRef {
    *  `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;
+  /**
+   * The index of the bone called `name` on this entity's model, for {@link getBoneTransform}.
+   * `-1` when the model has no such bone, the entity has no model, or the ref is stale.
+   *
+   * @example
+   * const head = pawn.ref.lookupBone("head_0");
+   * const t = head >= 0 ? pawn.ref.getBoneTransform(head) : null;
+   * if (t) console.log(`head at ${t.position}`);
+   */
+  lookupBone(name: string): number;
+  /**
+   * Where bone `bone` is right now, in world space: its position and its orientation as a
+   * quaternion. `null` for a stale ref, an entity with no model, or a negative index. An index past
+   * the model's last bone gives the entity's own transform, as the engine does.
+   */
+  getBoneTransform(bone: number): BoneTransform | null;
+  /**
+   * The index of the attachment called `name` on this entity's model (`"muzzle_flash"`,
+   * `"eyes"`), for {@link getAttachment}. `0` when there is no such attachment, the entity has no
+   * model, or the ref is stale; real attachments start at 1.
+   */
+  lookupAttachment(name: string): number;
+  /**
+   * Where attachment `attachment` is right now, in world space. `null` for a stale ref, an entity
+   * with no model, an index outside 1–255, or an attachment the engine did not find.
+   *
+   * @example
+   * const muzzle = weapon.ref.lookupAttachment("muzzle_flash");
+   * const at = weapon.ref.getAttachment(muzzle);
+   * if (at) console.log(`muzzle at ${at.origin}, facing ${at.angles}`);
+   */
+  getAttachment(attachment: number): AttachmentTransform | null;
   /** Set this entity's gravity multiplier (`CBaseEntity::SetGravityScale`). 1 is normal, 0 is
    *  weightless.
    *
@@ -210,8 +261,50 @@ export declare class EntityRef {
    *  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;
+  /**
+   * Deal `damage` to this entity through the game's own damage path, so `OnTakeDamage` hooks and
+   * the game's rules (god mode, friendly fire, armor) still apply. The engine may still refuse it,
+   * for example when the entity doesn't take damage at all. Returns false when the call was refused:
+   * a stale victim or option entity, a non-finite `damage`, or an unavailable game function.
+   * @example
+   * // 25 damage from `attacker`'s pawn, as a bullet (CS2's DMG_BULLET is 2).
+   * victim.takeDamage(25, { attacker: attackerPawn.ref, damageType: 2 });
+   */
+  takeDamage(damage: number, opts?: TakeDamageOptions): boolean;
 }
 
+/** An entity option of {@link EntityRef.takeDamage}: an EntityRef, or a wrapper that holds one. */
+export type DamageEntity = EntityRef | { readonly ref: EntityRef };
+
+/** Options for {@link EntityRef.takeDamage}. Every field is optional. */
+export interface TakeDamageOptions {
+  /** Who gets credit for the damage (the damage info's attacker). */
+  attacker?: DamageEntity | null;
+  /** What dealt it, such as a grenade or the attacker's weapon. Defaults to the attacker. */
+  inflictor?: DamageEntity | null;
+  /** The weapon or ability it came from (SourceMod's `weapon`). */
+  ability?: DamageEntity | null;
+  /** Damage-type bit flags; the values are game facts (CS2: `DamageTypes_t`). Defaults to 0 (generic). */
+  damageType?: number;
+  /** Damage force, `[x, y, z]`. Defaults to zero. */
+  force?: ArrayLike<number> | null;
+  /** Where the damage lands, `[x, y, z]`. Defaults to zero. */
+  position?: ArrayLike<number> | null;
+}
+
+/** Element kinds for {@link EntityRef.gather} plans — the scalar kinds a `Float64Array` holds exactly. */
+export declare const GatherKind: {
+  readonly Int32: number;
+  readonly Float32: number;
+  readonly Bool: number;
+  readonly Int8: number;
+  readonly Int16: number;
+  readonly UInt8: number;
+  readonly UInt16: number;
+  readonly UInt32: number;
+  readonly Float64: number;
+};
+
 /** 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). */
@@ -242,14 +335,58 @@ export interface OutputEvent {
   delay: number;
 }
 
+/** The payload delivered to an `onInput` handler. */
+export interface InputEvent {
+  /** The input's name as the engine spelled it (e.g. "Kill", "Open", "SetHealth"). */
+  input: string;
+  /** The entity receiving the input, or null if it is no longer live. */
+  entity: EntityRef | null;
+  /** The entity that activated the chain leading to this input, or null. */
+  activator: EntityRef | null;
+  /** The entity that sent the input (the output's owner, for map I/O), or null. */
+  caller: EntityRef | null;
+  /**
+   * The input's parameter, formatted as a string ("" when it has none). Inputs fired with a Pulse
+   * argument pack instead of a variant also report "".
+   */
+  value: string;
+}
+
 /**
- * Entry point for entity lookup by class name.
+ * Entry point for entity lookup by class name, targetname or position.
  * @example
  * import { Entity } from "@s2script/sdk/entity";
  * const triggers = Entity.findByClass("trigger_multiple");
  * for (const t of triggers) console.log(t.index, t.name);
+ * const doors = Entity.findByName("cell_doors");
+ * const nearby = Entity.findInSphere([0, 0, 64], 256, "prop_physics");
  */
 export declare const Entity: {
   /** Find every entity whose designer-name (class) exactly matches `className`. Returns liveness-gated refs. */
   findByClass(className: string): EntityRef[];
+  /** Find every entity whose targetname (`name`, the map's `targetname`) exactly matches `name`.
+   *  An empty `name` matches nothing. Returns liveness-gated refs. */
+  findByName(name: string): EntityRef[];
+  /** Every entity whose world origin is within `radius` units of `center` (inclusive), optionally only
+   *  those of `className`. Entities without a readable origin are skipped. Returns `[]` for a
+   *  non-finite center or a negative radius. Without `className` this walks every entity, so prefer
+   *  passing one in hot paths. */
+  findInSphere(center: Vector | { x: number; y: number; z: number } | [number, number, number],
+               radius: number, className?: string): EntityRef[];
 };
+
+/** What {@link EntityRef.getBoneTransform} returns. */
+export interface BoneTransform {
+  /** The bone's world position. */
+  position: Vector;
+  /** The bone's world orientation, as a unit quaternion. */
+  rotation: { x: number; y: number; z: number; w: number };
+}
+
+/** What {@link EntityRef.getAttachment} returns. */
+export interface AttachmentTransform {
+  /** The attachment's world position. */
+  origin: Vector;
+  /** The attachment's world angles. */
+  angles: QAngle;
+}

package/files.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @s2script/files — sandboxed, off-thread file IO. Reads, writes (optionally gzip-compressed),
+ * lists and removes run on the shared async runtime's worker threads; the game thread only copies
+ * the payload and later receives the result on a frame drain. NO runtime code (injected at load).
+ *
+ * Every path is relative to this plugin's own root (`<data dir>/files/<plugin id>/`), `/`-separated,
+ * with segments of `[A-Za-z0-9._-]` (no `.`/`..`, at most 8 deep, 256 bytes). Anything else rejects
+ * with an `InvalidPath` error before any IO. One payload is capped by the async policy's
+ * `input_item_bytes` (8 MiB by default, measured after decompression) — see docs/ASYNC_LIMITS.md.
+ */
+
+/** Options for {@link Files.read} / {@link Files.readText}. */
+export interface FileReadOptions {
+  /** Decompress a gzip file (written with `{ gzip: true }`) off-thread. Default false. */
+  gzip?: boolean;
+}
+
+/** Options for {@link Files.write}. */
+export interface FileWriteOptions {
+  /** Compress with gzip off-thread before writing. Default false. Cannot combine with `append`. */
+  gzip?: boolean;
+  /**
+   * Append instead of replace. Default false: a replacing write is atomic (temp file + rename), so
+   * a crash or a concurrent read never observes a torn file. Appends are not atomic.
+   */
+  append?: boolean;
+}
+
+/**
+ * Off-thread file IO in this plugin's sandbox. Promises reject with `AsyncQueueFull`,
+ * `AsyncPayloadTooLarge`, `AsyncCancelled` (the plugin unloaded first) or a descriptive IO error.
+ * @example
+ * import { Files } from "@s2script/sdk/files";
+ * // persist a binary blob compressed, then read it back — neither step blocks the game thread
+ * await Files.write("replays/surf_utopia/wr.bin", frames, { gzip: true });
+ * const back = await Files.read("replays/surf_utopia/wr.bin", { gzip: true });
+ * if (back) console.log(`replay is ${back.length} bytes`);
+ */
+export declare const Files: {
+  /** Read a file as bytes (a fresh `Uint8Array`). Resolves `null` when the file does not exist. */
+  read(path: string, opts?: FileReadOptions): Promise<Uint8Array | null>;
+  /** Read a file as UTF-8 text (invalid sequences become U+FFFD). Resolves `null` when absent. */
+  readText(path: string, opts?: FileReadOptions): Promise<string | null>;
+  /**
+   * Write `data` (bytes, or a string as UTF-8), creating parent directories. The payload is copied
+   * synchronously, so the caller may reuse its buffer as soon as this returns.
+   */
+  write(path: string, data: Uint8Array | string, opts?: FileWriteOptions): Promise<void>;
+  /** Delete a file. Resolves `true` if it existed. */
+  remove(path: string): Promise<boolean>;
+  /**
+   * The sorted entry names in a directory (default: the plugin root). Subdirectories end in `/`.
+   * A missing directory resolves `[]`.
+   */
+  list(dir?: string): Promise<string[]>;
+};

package/index.d.ts

@@ -24,6 +24,7 @@ export * from "./damage";
 export * from "./db";
 export * from "./entity";
 export * from "./events";
+export * from "./files";
 export * from "./http";
 export * from "./interfaces";
 export * from "./math";
@@ -43,5 +44,6 @@ export * from "./transmit";
 export * from "./usercmd";
 export * from "./usermessages";
 export * from "./voice";
+export * from "./stringtables";
 export * from "./votes";
 export * from "./ws";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.31.0",
+  "version": "0.33.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",
@@ -80,6 +80,9 @@
     "./http": {
       "types": "./http.d.ts"
     },
+    "./files": {
+      "types": "./files.d.ts"
+    },
     "./interfaces": {
       "types": "./interfaces.d.ts"
     },
@@ -131,6 +134,9 @@
     "./usermessages": {
       "types": "./usermessages.d.ts"
     },
+    "./stringtables": {
+      "types": "./stringtables.d.ts"
+    },
     "./voice": {
       "types": "./voice.d.ts"
     },

package/plugin.d.ts

@@ -18,7 +18,7 @@ import type {
  */
 import type { GameEvent, HookResultValue } from "./events";
 import type { Client } from "./clients";
-import type { EntityRef, OutputEvent } from "./entity";
+import type { EntityRef, InputEvent, OutputEvent } from "./entity";
 import type { CommandHandler } from "./commands";
 import type { Config } from "./config";
 import type { PublishHandle } from "./interfaces";
@@ -100,6 +100,12 @@ export interface CtxEntities {
     output: string,
     handler: (ev: OutputEvent) => HookResultValue | void
   ): void;
+  /** Hook an input an entity receives (`AcceptInput`); return a {@link HookResultValue} to drop it. */
+  onInput(
+    classname: string,
+    input: string,
+    handler: (ev: InputEvent) => HookResultValue | void
+  ): void;
 }
 /** Per-frame + map/precache hooks on this plugin's load-scope ({@link PluginContext.server}). */
 export interface CtxServer {
@@ -298,7 +304,7 @@ export interface PluginHooks {
  *
  * `OnGameFrame` is SourceMod's public (before simulation). Post-simulation paint is
  * {@link Scope}'s `server.onGameFrame(fn, { phase: "post" })` — Metamod's post hook, not a SM public.
- * Filtered entity I/O is {@link onOutput}, not a public — SourceMod `HookEntityOutput`.
+ * Filtered entity I/O is {@link onOutput} / {@link onInput}, not a public — SourceMod `HookEntityOutput`.
  * Per-entity damage is `SDKHook` (`SDKHookType.OnTakeDamage`), not a named public.
  */
 
@@ -328,6 +334,18 @@ export declare function onOutput(
   handler: (ev: OutputEvent) => HookResultValue | void
 ): void;
 
+/**
+ * Load-window entity input hook (SourceMod-style `AcceptEntityInput` pre-hook), called before the
+ * receiving entity runs the input. Keyed by `(classname, input)`; input names match
+ * case-insensitively and `"*"` wildcards either side. Return {@link HookResultValue} `Handled`/`Stop`
+ * to drop the input. Throws after settle.
+ */
+export declare function onInput(
+  classname: string,
+  input: string,
+  handler: (ev: InputEvent) => HookResultValue | void
+): void;
+
 /**
  * The revived hot-reload handoff (the previous instance's `OnPluginState` return), or `undefined`.
  * Load-window only.

package/sdkhooks.d.ts

@@ -2,7 +2,7 @@
  * @s2script/sdkhooks — per-entity SDKHooks (SourceMod `SDKHook` / `SDKUnhook`).
  * NO runtime code: the engine injects the implementation at load time.
  */
-import type { EntityRef } from "./entity";
+import type { DamageEntity, EntityRef } from "./entity";
 import type { DamageInfo } from "./damage";
 import type { HookResultValue } from "./events";
 import type { Client } from "./clients";
@@ -87,7 +87,10 @@ export declare const SDKHookType: {
   readonly Spawn: "Spawn";
   /** `Spawn` post. Return is ignored. */
   readonly SpawnPost: "SpawnPost";
-  /** `CBaseEntity::Think` pre. `Handled` / `Stop` skip the original virtual. */
+  /**
+   * `CBaseEntity::Think` pre. Source 2 has no Think virtual (thinks are `SetThink` function
+   * pointers), so on CS2 {@link SDKHook} returns `false` for this type.
+   */
   readonly Think: "Think";
   /** `Think` post. Return is ignored. */
   readonly ThinkPost: "ThinkPost";
@@ -99,7 +102,10 @@ export declare const SDKHookType: {
   readonly PostThink: "PostThink";
   /** `PostThink` post. Return is ignored. */
   readonly PostThinkPost: "PostThinkPost";
-  /** `CBaseEntity::Use` pre. `Handled` / `Stop` skip the original virtual. */
+  /**
+   * `CBaseEntity::Use` pre (`+use` on a door, button or prop). `Handled` / `Stop` skip the
+   * original virtual.
+   */
   readonly Use: "Use";
   /** `Use` post. Return is ignored. */
   readonly UsePost: "UsePost";
@@ -546,3 +552,20 @@ export declare function SDKUnhook(
   type: "ReloadPost",
   callback: ReloadPostCallback,
 ): boolean;
+
+/**
+ * SourceMod's `SDKHooks_TakeDamage`: deal damage to `entity` through the game's own damage path.
+ * The same call as {@link EntityRef.takeDamage}; `weapon` is its `ability`. Unlike SourceMod there
+ * is no `bypassHooks`: `OnTakeDamage` hooks always see damage a plugin deals. Returns false when
+ * the call was refused (a null or stale entity, a non-finite `damage`, an unavailable game function).
+ */
+export declare function SDKHooks_TakeDamage(
+  entity: DamageEntity | null,
+  inflictor: DamageEntity | null,
+  attacker: DamageEntity | null,
+  damage: number,
+  damageType?: number,
+  weapon?: DamageEntity | null,
+  force?: ArrayLike<number> | null,
+  position?: ArrayLike<number> | null,
+): boolean;

package/server.d.ts

@@ -63,4 +63,15 @@ export declare const Server: {
   readonly mapName: string;
   /** The current map time in seconds (`GetGlobals()->curtime`). `0` if unavailable. */
   readonly gameTime: number;
+  /**
+   * The integer simulation tick (`GetGlobals()->tickcount`). Monotonic within a map and frozen
+   * while the game is paused — count ticks for anything timer-grade instead of differencing the
+   * float {@link Server.gameTime}. `0` if unavailable.
+   */
+  readonly tickCount: number;
+  /**
+   * Seconds per simulation tick, from the game's own server config (`0.015625` on a 64-tick
+   * server). Fixed for the server's lifetime. `0` only when the engine cannot report it.
+   */
+  readonly tickInterval: number;
 };

package/sound.d.ts

@@ -1,5 +1,6 @@
 /** @s2script/sound — engine-generic sound: emit a named SoundEvent + register custom precache paths. */
 import type { EntityRef } from "./entity";
+import type { Vector } from "./math";
 
 /** Options for {@link Sound.emit} — the source entity, recipient slots, and volume. */
 export interface SoundEmitOptions {
@@ -14,6 +15,42 @@ export interface SoundEmitOptions {
   volume?: number;
 }
 
+/** Recipients for {@link SoundEvent.setParam} and {@link SoundEvent.stop}. */
+export interface SoundEventRecipients {
+  /** Player slots the change goes to. Omitted -> every valid client. Bots are skipped. */
+  recipients?: number[];
+}
+
+/**
+ * A sound started with {@link Sound.start}: the engine's event guid and stack hash. It is plain
+ * data, so it is safe to keep. Once the sound has finished, `setParam` and `stop` still return true
+ * but the engine ignores them.
+ */
+export interface SoundEvent {
+  /** The engine sound event guid, the same number {@link Sound.emit} returns. */
+  readonly guid: number;
+  /** The event's stack hash, which the engine needs alongside the guid to set a parameter. */
+  readonly stackHash: number;
+  /**
+   * Set a soundevent parameter on the playing sound, for example `"volume"`, `"pitch"` or
+   * `"position"`, or one of the event's own `public.*` fields. A number sets a float field and a
+   * Vector sets a three-float field.
+   *
+   * @example
+   * const ev = Sound.start("MyPack.Siren", { entity: pawn.ref });
+   * ev?.setParam("volume", 0.4);
+   * ev?.setParam("position", pawn.origin);
+   *
+   * Returns true when the engine was called. The engine does not report whether the event has a
+   * parameter by that name, and it drops a write to one that doesn't exist. Returns false for any
+   * other value type, a non-finite number, or when the engine function did not resolve.
+   */
+  setParam(name: string, value: number | Vector, opts?: SoundEventRecipients): boolean;
+  /** Stop this sound for the recipients. Returns false only when the engine function did not
+   *  resolve. */
+  stop(opts?: SoundEventRecipients): boolean;
+}
+
 /** 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). */
@@ -52,6 +89,23 @@ export declare const Sound: {
    *  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;
+  /** {@link Sound.emit}, keeping a handle so you can change the sound's parameters while it plays
+   *  or stop that one instance. Returns null where `emit` would return 0. */
+  start(name: string, opts?: SoundEmitOptions): SoundEvent | null;
+  /**
+   * The length of a sound event in seconds, as the engine's sound event manager reports it.
+   *
+   * @example
+   * const len = Sound.duration("MyPack.RoundMusic");
+   * if (len !== null) delay(len * 1000).then(() => Sound.emit("MyPack.RoundMusicEnd"));
+   *
+   * Returns null when the engine has no event by that name (check with {@link Sound.isValid}), or
+   * when the engine function did not resolve.
+   */
+  duration(name: string): number | null;
+  /** Whether the engine knows a sound event by that name: a loaded soundevents file defines it.
+   *  Returns false when the engine function did not resolve. */
+  isValid(name: string): boolean;
   /**
    * Stop a named SoundEvent playing on an entity — the counterpart to {@link Sound.emit}.
    *

package/stringtables.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @s2script/sdk/stringtables — the engine's network string tables. NO runtime code: the engine
+ * injects the implementation at load (`__s2pkg_stringtables`).
+ *
+ * String tables are how the server networks indexed strings to clients: precache lists, effect
+ * names, and per-entry user data. The engine rebuilds them on every map change, so a
+ * {@link StringTable} is plain data (its id and name) and every call looks the table up again. A
+ * handle kept past a map change answers -1 / null / false rather than reaching a freed table; get
+ * a fresh one with {@link StringTables.find}.
+ */
+
+/** A string table handle. Safe to keep: it holds no pointer. */
+export interface StringTable {
+  /** The table's id, its position in the container. */
+  readonly id: number;
+  /** The table's name, for example `"EffectDispatch"`. */
+  readonly name: string;
+  /** How many strings the table holds, or -1 when the handle is stale. */
+  count(): number;
+  /** The index of `value` in the table, or -1 when it is absent or the handle is stale. */
+  findString(value: string): number;
+  /** The string at `index`, or null for an index out of range or a stale handle. */
+  getString(index: number): string | null;
+  /**
+   * A copy of the user data stored with the string at `index`. An entry without user data gives an
+   * empty array; null means an index out of range or a stale handle.
+   */
+  getData(index: number): Uint8Array | null;
+  /**
+   * Replace the user data of the string at `index`. A string is stored as its UTF-8 bytes. Returns
+   * false for an index out of range, a stale handle, or a value that is neither bytes nor a string.
+   */
+  setData(index: number, data: Uint8Array | string): boolean;
+  /**
+   * Add `value` to the table, with optional user data, and return its index. Adding a string the
+   * table already has returns its existing index. Returns -1 when the table is full or the handle
+   * is stale. The engine networks the new entry to clients.
+   *
+   * @example
+   * const t = StringTables.find("EffectDispatch");
+   * const i = t?.addString("MyPack.Effect") ?? -1;
+   */
+  addString(value: string, data?: Uint8Array | string): number;
+}
+
+/**
+ * Find and list the server's string tables.
+ *
+ * @example
+ * import { StringTables } from "@s2script/sdk/stringtables";
+ * const effects = StringTables.find("EffectDispatch");
+ * const particle = effects?.findString("ParticleEffect") ?? -1;
+ */
+export declare const StringTables: {
+  /** The table with that name, or null. */
+  find(name: string): StringTable | null;
+  /** The table with that id, or null. */
+  get(id: number): StringTable | null;
+  /** How many tables the server has. 0 before the first map or when unavailable. */
+  count(): number;
+  /** Every table, in id order. */
+  all(): StringTable[];
+};