@s2script/sdk 0.32.0 → 0.34.0

package/entity.d.ts

@@ -185,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.
    *
@@ -229,6 +261,35 @@ 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. */
@@ -274,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/index.d.ts

@@ -44,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.32.0",
+  "version": "0.34.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",
@@ -134,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/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[];
+};