@s2script/sdk 0.21.0 → 0.23.0

package/sdkhooks.d.ts

@@ -0,0 +1,543 @@
+/**
+ * @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 { DamageInfo } from "./damage";
+import type { HookResultValue } from "./events";
+import type { Client } from "./clients";
+
+type TouchCallback = (entity: EntityRef, other: EntityRef | null) => HookResultValue | void;
+type TouchPostCallback = (entity: EntityRef, other: EntityRef | null) => void;
+type WeaponCallback = (entity: EntityRef, weapon: EntityRef | null) => HookResultValue | void;
+type WeaponPostCallback = (entity: EntityRef, weapon: EntityRef | null) => void;
+type ThisCallback = (entity: EntityRef) => HookResultValue | void;
+type ThisVoidCallback = (entity: EntityRef) => void;
+type FireBulletsPostCallback = (entity: EntityRef, shots: number, weaponName: string) => void;
+type ReloadPostCallback = (weapon: EntityRef, successful: boolean) => void;
+type UseCallback = (
+  entity: EntityRef,
+  activator: EntityRef | null,
+  caller: EntityRef | null,
+  type: UseTypeValue,
+  value: number,
+) => HookResultValue | void;
+type UsePostCallback = (
+  entity: EntityRef,
+  activator: EntityRef | null,
+  caller: EntityRef | null,
+  type: UseTypeValue,
+  value: number,
+) => void;
+
+/**
+ * `CBaseEntity::Use` use-type (`USE_OFF` / `USE_ON` / `USE_SET` / `USE_TOGGLE`).
+ */
+export type UseTypeValue = 0 | 1 | 2 | 3;
+
+/**
+ * `CBaseEntity::Use` use-type constants (wiki `USE_*`).
+ */
+export declare const UseType: {
+  /** `USE_OFF` — turn off. */
+  readonly Off: 0;
+  /** `USE_ON` — turn on. */
+  readonly On: 1;
+  /** `USE_SET` — set to `value`. */
+  readonly Set: 2;
+  /** `USE_TOGGLE` — toggle. */
+  readonly Toggle: 3;
+};
+
+/**
+ * Shipped SDKHook types. Wiki names without the `SDKHook_` prefix. A wiki name whose engine
+ * backing failed or is absent returns `false` from {@link SDKHook} (does not throw). A string
+ * that is not a member here throws.
+ */
+export declare const SDKHookType: {
+  /** Pre-apply damage (`DispatchTraceAttack`). Mutate {@link DamageInfo.damage} in place. */
+  readonly OnTakeDamage: "OnTakeDamage";
+  /**
+   * CheckTransmit mux (wiki `SDKHook_SetTransmit`). `Handled` / `Stop` hide this entity from this
+   * viewer. AND-merge with `Transmit.setVisibleTo`: either API can hide; SetTransmit cannot
+   * un-hide a native mask clear. There is no `SetTransmitPost`.
+   */
+  readonly SetTransmit: "SetTransmit";
+  /** `CBaseEntity::StartTouch` pre. `Handled` / `Stop` skip the original virtual. */
+  readonly StartTouch: "StartTouch";
+  /** `CBaseEntity::Touch` pre. `Handled` / `Stop` skip the original virtual. */
+  readonly Touch: "Touch";
+  /** `CBaseEntity::EndTouch` pre. `Handled` / `Stop` skip the original virtual. */
+  readonly EndTouch: "EndTouch";
+  /** `CBaseEntity::Blocked` pre. `Handled` / `Stop` skip the original virtual. */
+  readonly Blocked: "Blocked";
+  /** `StartTouch` post. Return is ignored. */
+  readonly StartTouchPost: "StartTouchPost";
+  /** `Touch` post. Return is ignored. */
+  readonly TouchPost: "TouchPost";
+  /** `EndTouch` post. Return is ignored. */
+  readonly EndTouchPost: "EndTouchPost";
+  /** `Blocked` post. Return is ignored. */
+  readonly BlockedPost: "BlockedPost";
+  /** `CBaseEntity::Spawn` pre. `Handled` / `Stop` skip the original virtual. */
+  readonly Spawn: "Spawn";
+  /** `Spawn` post. Return is ignored. */
+  readonly SpawnPost: "SpawnPost";
+  /** `CBaseEntity::Think` pre. `Handled` / `Stop` skip the original virtual. */
+  readonly Think: "Think";
+  /** `Think` post. Return is ignored. */
+  readonly ThinkPost: "ThinkPost";
+  /** Player `PreThink`. Return is ignored. */
+  readonly PreThink: "PreThink";
+  /** `PreThink` post. Return is ignored. */
+  readonly PreThinkPost: "PreThinkPost";
+  /** Player `PostThink`. Return is ignored. */
+  readonly PostThink: "PostThink";
+  /** `PostThink` post. Return is ignored. */
+  readonly PostThinkPost: "PostThinkPost";
+  /** `CBaseEntity::Use` pre. `Handled` / `Stop` skip the original virtual. */
+  readonly Use: "Use";
+  /** `Use` post. Return is ignored. */
+  readonly UsePost: "UsePost";
+  /** `GetMaxHealth`. Mutate `info.maxHealth`. `Handled` / `Stop` SUPERCEDE the original. */
+  readonly GetMaxHealth: "GetMaxHealth";
+  /** `ShouldCollide`. Return a boolean (not {@link HookResultValue}); last defined wins. */
+  readonly ShouldCollide: "ShouldCollide";
+  /** `VPhysicsUpdate`. Return is ignored. */
+  readonly VPhysicsUpdate: "VPhysicsUpdate";
+  /** `VPhysicsUpdate` post. Return is ignored. */
+  readonly VPhysicsUpdatePost: "VPhysicsUpdatePost";
+  /** `GroundEntChanged` post. Return is ignored. */
+  readonly GroundEntChangedPost: "GroundEntChangedPost";
+  /** `CanBeAutobalanced`. Return a boolean (not {@link HookResultValue}); last defined wins. */
+  readonly CanBeAutobalanced: "CanBeAutobalanced";
+  /**
+   * Post-apply damage (`DispatchTraceAttack` after the original). {@link DamageInfo} is read-only
+   * for effect; mutations are not written back. Return is ignored.
+   */
+  readonly OnTakeDamagePost: "OnTakeDamagePost";
+  /**
+   * `OnTakeDamageAlive` pre. CS2 has no distinct function yet — {@link SDKHook} returns `false`.
+   */
+  readonly OnTakeDamageAlive: "OnTakeDamageAlive";
+  /**
+   * `OnTakeDamageAlive` post. CS2 has no distinct function yet — {@link SDKHook} returns `false`.
+   */
+  readonly OnTakeDamageAlivePost: "OnTakeDamageAlivePost";
+  /**
+   * `TraceAttack` pre ({@link TraceAttackInfo}). No distinct CS2 virtual yet — {@link SDKHook}
+   * returns `false` (OnTakeDamage remains the DTA mux).
+   */
+  readonly TraceAttack: "TraceAttack";
+  /**
+   * `TraceAttack` post. No distinct CS2 virtual yet — {@link SDKHook} returns `false`.
+   */
+  readonly TraceAttackPost: "TraceAttackPost";
+  /**
+   * `FireBulletsPost`. Wiki already documents this as often absent. {@link SDKHook} returns `false`
+   * until a live path is found.
+   */
+  readonly FireBulletsPost: "FireBulletsPost";
+  /** Weapon reload pre. `Handled` / `Stop` skip the original virtual. Missing VP → `false`. */
+  readonly Reload: "Reload";
+  /** Weapon reload post. `(weapon, successful)`. No bool-return thunk yet — {@link SDKHook} returns `false`. */
+  readonly ReloadPost: "ReloadPost";
+  /** `WeaponCanUse` pre. Callback is `(entity, weapon)`. Missing ItemServices VP → `false`. */
+  readonly WeaponCanUse: "WeaponCanUse";
+  /** `WeaponCanUse` post. Return is ignored. Missing VP → `false`. */
+  readonly WeaponCanUsePost: "WeaponCanUsePost";
+  /** `WeaponCanSwitchTo` pre. Callback is `(entity, weapon)`. Missing VP → `false`. */
+  readonly WeaponCanSwitchTo: "WeaponCanSwitchTo";
+  /** `WeaponCanSwitchTo` post. Return is ignored. Missing VP → `false`. */
+  readonly WeaponCanSwitchToPost: "WeaponCanSwitchToPost";
+  /** `WeaponDrop` pre. Callback is `(entity, weapon)`. Missing VP → `false`. */
+  readonly WeaponDrop: "WeaponDrop";
+  /** `WeaponDrop` post. Return is ignored. Missing VP → `false`. */
+  readonly WeaponDropPost: "WeaponDropPost";
+  /** `WeaponEquip` pre. Callback is `(entity, weapon)`. Missing VP → `false`. */
+  readonly WeaponEquip: "WeaponEquip";
+  /** `WeaponEquip` post. Return is ignored. Missing VP → `false`. */
+  readonly WeaponEquipPost: "WeaponEquipPost";
+  /** `WeaponSwitch` pre. Callback is `(entity, weapon)`. Missing VP → `false`. */
+  readonly WeaponSwitch: "WeaponSwitch";
+  /** `WeaponSwitch` post. Return is ignored. Missing VP → `false`. */
+  readonly WeaponSwitchPost: "WeaponSwitchPost";
+};
+
+/**
+ * Block-scoped view of a `TraceAttack` callback. Mutate {@link TraceAttackInfo.damage} on the
+ * pre-hook. Valid only during the handler.
+ */
+export interface TraceAttackInfo {
+  /** Incoming damage. Mutate in place on the pre-hook. */
+  damage: number;
+  /** Damage type bits. */
+  readonly damageType: number;
+  /** Ammo type index. */
+  readonly ammoType: number;
+  /** Hitbox index. */
+  readonly hitbox: number;
+  /** Hitgroup index. */
+  readonly hitgroup: number;
+  /** Attacking entity, books-gated. */
+  readonly attacker: EntityRef | null;
+  /** Inflicting entity, books-gated. */
+  readonly inflictor: EntityRef | null;
+  /** Victim entity, books-gated. */
+  readonly victim: EntityRef | null;
+}
+
+/**
+ * Hook `entity` for `type`. Auto-unhooked on entity destroy and plugin unload.
+ *
+ * Not load-window-only — call from `OnEntityCreated`, `OnPluginStart` (ents already live), or any
+ * time you hold a live {@link EntityRef}.
+ *
+ * `OnTakeDamage`: mutate `info.damage` in place. No return needed. Return `HookResult.Handled` to
+ * zero the hit; `HookResult.Stop` to also skip later hooks.
+ *
+ * @returns `true` if the hook was recorded. `false` on `null`/stale `entity` (does not throw).
+ * @example
+ * import { SDKHook, SDKHookType, Entity } from "@s2script/sdk";
+ * import type { EntityRef, DamageInfo } from "@s2script/sdk";
+ *
+ * export function OnPluginStart(): void {
+ *   for (const pawn of Entity.findByClass("player")) {
+ *     SDKHook(pawn, SDKHookType.OnTakeDamage, onTakeDamage);
+ *   }
+ * }
+ * export function OnEntityCreated(entity: EntityRef | null, className: string): void {
+ *   if (!entity || className !== "player") return;
+ *   SDKHook(entity, SDKHookType.OnTakeDamage, onTakeDamage);
+ * }
+ * function onTakeDamage(info: DamageInfo) {
+ *   info.damage /= 2;
+ * }
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "OnTakeDamage",
+  callback: (info: DamageInfo) => HookResultValue | void,
+): boolean;
+/**
+ * Post-apply damage. {@link DamageInfo} is a read of the live info after the original ran.
+ * Return is ignored; Handled does not zero the hit (that is the pre-hook).
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "OnTakeDamagePost",
+  callback: (info: DamageInfo) => void,
+): boolean;
+/**
+ * `OnTakeDamageAlive` pre. No CS2 backing yet — always returns `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "OnTakeDamageAlive",
+  callback: (info: DamageInfo) => HookResultValue | void,
+): boolean;
+/**
+ * `OnTakeDamageAlive` post. No CS2 backing yet — always returns `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "OnTakeDamageAlivePost",
+  callback: (info: DamageInfo) => void,
+): boolean;
+/**
+ * `TraceAttack` pre. No distinct CS2 virtual yet — always returns `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "TraceAttack",
+  callback: (info: TraceAttackInfo) => HookResultValue | void,
+): boolean;
+/**
+ * `TraceAttack` post. No distinct CS2 virtual yet — always returns `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "TraceAttackPost",
+  callback: (info: TraceAttackInfo) => void,
+): boolean;
+/**
+ * `FireBulletsPost`. No CS2 backing yet — always returns `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "FireBulletsPost",
+  callback: FireBulletsPostCallback,
+): boolean;
+/**
+ * Touch-family pre-hook. Callback is `(entity, other)`. Omit return = Continue.
+ * `Handled` / `Stop` SUPERCEDE the original virtual (`Stop` also skips later callbacks).
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "StartTouch" | "Touch" | "EndTouch" | "Blocked",
+  callback: TouchCallback,
+): boolean;
+/**
+ * Touch-family post-hook. Return is ignored; the original virtual already ran.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "StartTouchPost" | "TouchPost" | "EndTouchPost" | "BlockedPost",
+  callback: TouchPostCallback,
+): boolean;
+/**
+ * Spawn / Think pre-hook. Callback is `(entity)`. Omit return = Continue.
+ * `Handled` / `Stop` SUPERCEDE the original virtual (`Stop` also skips later callbacks).
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "Spawn" | "Think" | "Reload",
+  callback: ThisCallback,
+): boolean;
+/**
+ * Void this-only hooks (Posts, PreThink/PostThink, VPhysicsUpdate, GroundEntChangedPost).
+ * Return is ignored.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type:
+    | "SpawnPost"
+    | "ThinkPost"
+    | "PreThink"
+    | "PreThinkPost"
+    | "PostThink"
+    | "PostThinkPost"
+    | "VPhysicsUpdate"
+    | "VPhysicsUpdatePost"
+    | "GroundEntChangedPost",
+  callback: ThisVoidCallback,
+): boolean;
+/**
+ * `Use` pre-hook. `Handled` / `Stop` SUPERCEDE the original virtual.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "Use",
+  callback: UseCallback,
+): boolean;
+/**
+ * `Use` post-hook. Return is ignored.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "UsePost",
+  callback: UsePostCallback,
+): boolean;
+/**
+ * `GetMaxHealth`. Mutate `info.maxHealth` in place. `Handled` / `Stop` SUPERCEDE with the new value.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "GetMaxHealth",
+  callback: (info: { maxHealth: number }) => HookResultValue | void,
+): boolean;
+/**
+ * `ShouldCollide`. Return a boolean (not HookResult); last defined return wins, default original.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "ShouldCollide",
+  callback: (
+    entity: EntityRef,
+    collisionGroup: number,
+    contentsMask: number,
+    originalResult: boolean,
+  ) => boolean,
+): boolean;
+/**
+ * `CanBeAutobalanced`. Return a boolean (not HookResult); last defined return wins, default original.
+ * Callback is skipped when the hooked entity has no {@link Client} — never a raw slot `0`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "CanBeAutobalanced",
+  callback: (client: Client, origRet: boolean) => boolean,
+): boolean;
+/**
+ * SetTransmit. Callback is `(entity, client)`. Omit return = Continue.
+ * `Handled` / `Stop` hide this entity from this viewer (AND-merge with `Transmit.setVisibleTo`;
+ * cannot un-hide a native mask clear). `Stop` also skips later SetTransmit callbacks on that pair.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "SetTransmit",
+  callback: (entity: EntityRef, client: Client) => HookResultValue | void,
+): boolean;
+/**
+ * Weapon-family pre-hook. Callback is `(entity, weapon)`. Omit return = Continue.
+ * `Handled` / `Stop` SUPERCEDE the original virtual. Missing ItemServices VP → `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "WeaponCanUse" | "WeaponCanSwitchTo" | "WeaponDrop" | "WeaponEquip" | "WeaponSwitch",
+  callback: WeaponCallback,
+): boolean;
+/**
+ * Weapon-family post-hook. Return is ignored. Missing VP → `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type:
+    | "WeaponCanUsePost"
+    | "WeaponCanSwitchToPost"
+    | "WeaponDropPost"
+    | "WeaponEquipPost"
+    | "WeaponSwitchPost",
+  callback: WeaponPostCallback,
+): boolean;
+/**
+ * `ReloadPost`. Callback is `(weapon, successful)`. No CS2 backing yet — always returns `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "ReloadPost",
+  callback: ReloadPostCallback,
+): boolean;
+
+/**
+ * Remove one matching `(entity, type, callback)` hook. Callback identity is the function reference.
+ * @returns `true` if an entry was removed.
+ */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "OnTakeDamage",
+  callback: (info: DamageInfo) => HookResultValue | void,
+): boolean;
+/** Remove an `OnTakeDamagePost` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "OnTakeDamagePost",
+  callback: (info: DamageInfo) => void,
+): boolean;
+/** Remove an `OnTakeDamageAlive` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "OnTakeDamageAlive",
+  callback: (info: DamageInfo) => HookResultValue | void,
+): boolean;
+/** Remove an `OnTakeDamageAlivePost` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "OnTakeDamageAlivePost",
+  callback: (info: DamageInfo) => void,
+): boolean;
+/** Remove a `TraceAttack` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "TraceAttack",
+  callback: (info: TraceAttackInfo) => HookResultValue | void,
+): boolean;
+/** Remove a `TraceAttackPost` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "TraceAttackPost",
+  callback: (info: TraceAttackInfo) => void,
+): boolean;
+/** Remove a `FireBulletsPost` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "FireBulletsPost",
+  callback: FireBulletsPostCallback,
+): boolean;
+/** Remove a Touch-family pre-hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "StartTouch" | "Touch" | "EndTouch" | "Blocked",
+  callback: TouchCallback,
+): boolean;
+/** Remove a Touch-family post-hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "StartTouchPost" | "TouchPost" | "EndTouchPost" | "BlockedPost",
+  callback: TouchPostCallback,
+): boolean;
+/** Remove a Spawn / Think pre-hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "Spawn" | "Think" | "Reload",
+  callback: ThisCallback,
+): boolean;
+/** Remove a void this-only hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type:
+    | "SpawnPost"
+    | "ThinkPost"
+    | "PreThink"
+    | "PreThinkPost"
+    | "PostThink"
+    | "PostThinkPost"
+    | "VPhysicsUpdate"
+    | "VPhysicsUpdatePost"
+    | "GroundEntChangedPost",
+  callback: ThisVoidCallback,
+): boolean;
+/** Remove a `Use` pre-hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "Use",
+  callback: UseCallback,
+): boolean;
+/** Remove a `Use` post-hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "UsePost",
+  callback: UsePostCallback,
+): boolean;
+/** Remove a `GetMaxHealth` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "GetMaxHealth",
+  callback: (info: { maxHealth: number }) => HookResultValue | void,
+): boolean;
+/** Remove a `ShouldCollide` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "ShouldCollide",
+  callback: (
+    entity: EntityRef,
+    collisionGroup: number,
+    contentsMask: number,
+    originalResult: boolean,
+  ) => boolean,
+): boolean;
+/** Remove a `CanBeAutobalanced` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "CanBeAutobalanced",
+  callback: (client: Client, origRet: boolean) => boolean,
+): boolean;
+/** Remove a SetTransmit hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "SetTransmit",
+  callback: (entity: EntityRef, client: Client) => HookResultValue | void,
+): boolean;
+/** Remove a Weapon-family pre-hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "WeaponCanUse" | "WeaponCanSwitchTo" | "WeaponDrop" | "WeaponEquip" | "WeaponSwitch",
+  callback: WeaponCallback,
+): boolean;
+/** Remove a Weapon-family post-hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type:
+    | "WeaponCanUsePost"
+    | "WeaponCanSwitchToPost"
+    | "WeaponDropPost"
+    | "WeaponEquipPost"
+    | "WeaponSwitchPost",
+  callback: WeaponPostCallback,
+): boolean;
+/** Remove a `ReloadPost` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "ReloadPost",
+  callback: ReloadPostCallback,
+): boolean;

package/server.d.ts

@@ -15,16 +15,16 @@ export declare const Server: {
   /** A cvar's current value as a string. `""` if the cvar doesn't exist (or an unsupported type → `"<type>"`). */
   getCvar(name: string): string;
   /**
-   * Set a cvar via the server console (so any type is accepted). SECURITY: this builds and runs a console
-   * command (`<name> <value>`), which the console splits on `;` — treat `value` like `command()` input and
-   * sanitize/quote any untrusted value to avoid command injection. Queued: applies next frame.
+   * Set a cvar through `ICvar` now (SourceMod `SetConVarString`). Not a console command: `;` in
+   * `value` is data, not a second command. `getCvar` and `onCvarChange` see the new value before
+   * this returns. `false` if the cvar does not exist or the string cannot become that type.
    */
-  setCvar(name: string, value: string): void;
+  setCvar(name: string, value: string): boolean;
   /**
    * Register a plugin-owned ConVar (CSSharp FakeConVar / SM CreateConVar parity). Idempotent —
    * re-registering an existing name is a no-op success, and the cvar + its value persist across
    * plugin reloads (SourceMod parity). The shim adds FCVAR_RELEASE (customer-visible); `flags`
-   * are additive raw FCVAR bits. Read the value with `getCvar`; set it with `setCvar`/the console.
+   * are additive raw FCVAR bits. Read the value with `getCvar`; set it with `setCvar`.
    * `min`/`max` apply to numeric types only.
    */
   registerCvar(name: string, opts: {

package/translations.d.ts

@@ -13,13 +13,15 @@ export type Phrases = Record<string, string>;
  * for it automatically, the same rule SourceMod's `LoadTranslations` enforces:
  *
  * @example
- * export default plugin((ctx) => {
- *   ctx.translations.load("basecomm", "common");
- *   ctx.commands.registerAdmin("sm_gag", ADMFLAG.CHAT, (cmd) => {
+ * import { command, translations } from "@s2script/sdk";
+ * import { ADMFLAG } from "@s2script/sdk";
+ * export function OnPluginStart(): void {
+ *   translations.load("basecomm", "common");
+ *   command.admin("sm_gag", ADMFLAG.CHAT, (cmd) => {
  *     cmd.replyT("Usage Gag");                                  // key-checked
  *     Chat.toSlot(p.slot, Translations.translate(p.slot, "Gagged Player", n));
  *   });
- * });
+ * }
  *
  * Keys are checked against the files that plugin loads — see `@s2script/sdk/phrases`.
  */

package/unsafe.d.ts

@@ -1,11 +1,13 @@
 /**
- * @s2script/sdk/unsafe — plugin-declared engine calls. NO runtime code: the engine injects the
- * implementation at load (`__s2pkg_unsafe`).
+ * @s2script/sdk/unsafe — plugin-declared engine calls and inbound hooks. NO runtime code: the
+ * engine injects the implementation at load (`__s2pkg_unsafe`).
  *
- * UNSAFE by design. A declared call reaches a real engine function. The framework validates every
- * descriptor at load and degrades a failure to `null`, but it cannot prove your signature or vtable
- * index names the function you meant. Requires manifest `permissions: ["engine:calls"]` AND an
- * operator allow-list entry (see docs/superpowers/specs/2026-07-24-plugin-gamedata-design.md §6).
+ * UNSAFE by design. A declared call reaches a real engine function; a declared hook patches
+ * that function's prologue. The framework validates every descriptor at load and degrades a
+ * failure to `null`, but it cannot prove your signature or vtable index names the function you
+ * meant. Calls require manifest `permissions: ["engine:calls"]`; hooks require the separate
+ * `"engine:hooks"` permission. Both also need an operator allow-list entry
+ * (see docs/superpowers/specs/2026-07-24-plugin-gamedata-design.md §6 and ARCHITECTURE.md §2.0.7).
  */
 
 /**
@@ -15,13 +17,21 @@
 export interface EngineCalls {}
 
 /**
- * Plugin-declared engine calls, resolved from this plugin's own gamedata.
+ * The inbound hooks this plugin declares. The base interface is EMPTY — `s2s build` generates
+ * `.s2script/hooks.d.ts`, which augments this from your gamedata's `hooks` section.
+ */
+export interface EngineHooks {}
+
+/**
+ * Plugin-declared engine calls and inbound hooks, resolved from this plugin's own gamedata.
  *
  * @example
  * import { Engine } from "@s2script/sdk/unsafe";
  * // Resolve ONCE at load — null means the descriptor failed a load-time gate.
  * const ignite = Engine.call("ignite");
  * if (!ignite) console.log(`unavailable: ${Engine.status("ignite")}`);
+ * const onFoo = Engine.hook("onFoo");
+ * if (onFoo) onFoo((view) => { view.reason = 0; });
  */
 export declare const Engine: {
   /**
@@ -30,6 +40,16 @@ export declare const Engine: {
    * operator-allow-listed). Guard once at load; the returned function is a plain callable.
    */
   call<K extends keyof EngineCalls>(name: K): EngineCalls[K] | null;
-  /** Why a descriptor is unavailable; `"available"` when it resolved. For diagnostics/operator reports. */
+  /** Why a call descriptor is unavailable; `"available"` when it resolved. For diagnostics/operator reports. */
   status(name: string): string;
+  /**
+   * The declared hook's subscribe function, or `null` when its descriptor failed a load-time
+   * gate (same class of reasons as {@link Engine.call}, plus a missing `validate` or an unknown
+   * thunk shape). Guard once at load; the returned function records the handler and lazily
+   * installs the detour. The owner is always the calling plugin — you cannot subscribe to
+   * another plugin's hook through this factory (game-package hooks hang off `ctx.*`).
+   */
+  hook<K extends keyof EngineHooks>(name: K): EngineHooks[K] | null;
+  /** Why a hook descriptor is unavailable; `"available"` when it resolved. */
+  hookStatus(name: string): string;
 };