@s2script/sdk 0.21.0 → 0.22.0

package/clients.d.ts

@@ -60,13 +60,8 @@ export declare class Client {
    * or a name that is not a registered console **command** (a ConVar such as `mp_friendlyfire` is
    * refused: use `Server.command` for those).
    *
-   * KNOWN LIMITATION: engine commands (`say`, `kill`, …) execute. A command registered by an
-   * s2script plugin is dispatched by the engine, but its JS handler will NOT run — the core holds
-   * the isolate borrow across all JS, so re-entering the dispatcher hits the documented
-   * re-entrancy skip. (This is not a permissions issue: every s2script command is registered
-   * client-executable, which is why a player can type it in their own console.) To invoke another
-   * plugin's behaviour, use a cross-plugin interface rather than faking its command. See
-   * docs/superpowers/specs/2026-07-25-client-command-design.md §12.
+   * Engine commands (`say`, `kill`, …) execute. A command registered by an s2script plugin runs
+   * that plugin's JS handler before this returns.
    *
    * @example
    * client.fakeCommand("say hello");   // as though the player typed it

package/dist/cli.js

@@ -3766,8 +3766,12 @@ function localDeclarationFiles(pluginDir) {
   return readdirSync2(srcDir).filter((f) => f.endsWith(".d.ts")).map((f) => join7(srcDir, f));
 }
 function generatedDeclarationFiles(pluginDir) {
-  const gd = join7(pluginDir, ".s2script", "gamedata.d.ts");
-  return existsSync6(gd) ? [gd] : [];
+  const out = [];
+  for (const name of ["gamedata.d.ts", "hooks.d.ts"]) {
+    const p = join7(pluginDir, ".s2script", name);
+    if (existsSync6(p)) out.push(p);
+  }
+  return out;
 }
 function gamePackageDeclarationFiles(pkg, packagesDir) {
   const deps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
@@ -4205,25 +4209,31 @@ function scanPluginProgram(program, pluginDir) {
 
 // src/gamedata/types.ts
 var PLATFORM = "linuxsteamrt64";
-var ARG_KINDS = ["bool", "int", "float", "string", "vector", "entity"];
+var ARG_KINDS = ["bool", "int", "float", "string", "utlstring", "vector", "entity"];
 var RET_KINDS = ["void", "bool", "int", "float", "entity"];
-var INT_CLASS_ARGS = /* @__PURE__ */ new Set(["bool", "int", "string", "vector", "entity"]);
+var INT_CLASS_ARGS = /* @__PURE__ */ new Set(["bool", "int", "string", "utlstring", "vector", "entity"]);
 var MAX_INT_ARGS = 9;
 var MAX_FLOAT_ARGS = 8;
+var HOOK_SHAPES = ["this_void", "this_f32_i32_i32_i32", "this_f32_i32_i64_i64", "this_i64_i32_i64", "this_i64_i64_i64"];
+function hookShapeArity(shape) {
+  if (!HOOK_SHAPES.includes(shape)) return void 0;
+  if (shape === "this_void") return 0;
+  return shape.slice("this_".length).split("_").length;
+}
 
 // src/gamedata/validate.ts
-var ALLOWED_SECTIONS = /* @__PURE__ */ new Set(["signatures", "calls"]);
+var ALLOWED_SECTIONS = /* @__PURE__ */ new Set(["signatures", "calls", "hooks"]);
 var IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 var RESERVED_CALL_NAMES = /* @__PURE__ */ new Set(["constructor", "prototype", "__proto__"]);
 var RESOLVE_KINDS = ["direct", "ctor-body-xref", "lea-disp"];
-var KNOWN_PERMISSIONS = ["engine:calls"];
+var KNOWN_PERMISSIONS = ["engine:calls", "engine:hooks"];
 function validatePluginGamedata(gd, opts) {
   const errs = [];
   if (gd == null || typeof gd !== "object" || Array.isArray(gd)) return ["gamedata must be an object"];
   const g = gd;
   for (const key of Object.keys(g)) {
     if (!ALLOWED_SECTIONS.has(key)) {
-      errs.push(`gamedata section '${key}' is not supported in v1 (allowed: signatures, calls)`);
+      errs.push(`gamedata section '${key}' is not supported in v1 (allowed: signatures, calls, hooks)`);
     }
   }
   const sigs = g.signatures ?? {};
@@ -4358,8 +4368,247 @@ function validatePluginGamedata(gd, opts) {
       errs.push(`${where2}: 'returns' must be one of ${RET_KINDS.join(", ")}`);
     }
   }
+  validateHooks(g, sigs, callNames, opts.permissions, errs);
   return errs;
 }
+function isNonEmptyObject(v) {
+  return v != null && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length > 0;
+}
+function validateHooks(g, sigs, callNames, permissions, errs) {
+  if (g.hooks === void 0) return;
+  if (g.hooks == null || typeof g.hooks !== "object" || Array.isArray(g.hooks)) {
+    errs.push("hooks must be an object");
+    return;
+  }
+  const hooks = g.hooks;
+  const hookNames = Object.keys(hooks);
+  if (hookNames.length && !permissions.includes("engine:hooks")) {
+    errs.push('gamedata declares a `hooks` section but the manifest does not declare permission "engine:hooks"');
+  }
+  for (const [name, rawDecl] of Object.entries(hooks)) {
+    const where2 = `hook '${name}'`;
+    if (!IDENTIFIER.test(name)) {
+      errs.push(
+        `${where2}: hook name must be a plain identifier matching ${IDENTIFIER.source} \u2014 it is emitted verbatim as a TypeScript interface member in the generated .s2script/hooks.d.ts`
+      );
+      continue;
+    }
+    if (RESERVED_CALL_NAMES.has(name)) {
+      errs.push(`${where2}: hook name '${name}' is reserved`);
+      continue;
+    }
+    if (rawDecl == null || typeof rawDecl !== "object" || Array.isArray(rawDecl)) {
+      errs.push(`${where2}: must be an object`);
+      continue;
+    }
+    const decl = rawDecl;
+    const ctx = decl.expose?.ctx;
+    if (typeof ctx !== "string" || !ctx.length) {
+      errs.push(`${where2}: missing 'expose.ctx' \u2014 nothing could subscribe to this hook`);
+    } else if (!IDENTIFIER.test(ctx)) {
+      errs.push(`${where2}: 'expose.ctx' must be a plain identifier, got ${JSON.stringify(ctx)}`);
+    }
+    const shape = decl.shape;
+    if (typeof shape !== "string" || !HOOK_SHAPES.includes(shape)) {
+      errs.push(
+        `${where2}: unknown hook shape ${JSON.stringify(shape)} (this build compiles thunks for: ${HOOK_SHAPES.join(", ")})`
+      );
+    }
+    const params = decl.params ?? [];
+    if (!Array.isArray(params)) {
+      errs.push(`${where2}: 'params' must be an array`);
+    } else {
+      const seen = /* @__PURE__ */ new Set();
+      for (let i2 = 0; i2 < params.length; i2++) {
+        const p = params[i2];
+        if (typeof p !== "string" || !IDENTIFIER.test(p)) {
+          errs.push(`${where2}: params[${i2}] = ${JSON.stringify(p)} must be a plain identifier`);
+          continue;
+        }
+        if (seen.has(p)) errs.push(`${where2}: param name ${JSON.stringify(p)} is declared more than once`);
+        seen.add(p);
+      }
+      const arity = typeof shape === "string" ? hookShapeArity(shape) : void 0;
+      if (arity !== void 0 && params.length > arity) {
+        errs.push(
+          `${where2}: declares ${params.length} 'params' but shape ${JSON.stringify(shape)} passes only ${arity}`
+        );
+      }
+      if (decl.mutable !== void 0) {
+        const mutable = decl.mutable;
+        if (!Array.isArray(mutable)) {
+          errs.push(`${where2}: 'mutable' must be an array`);
+        } else {
+          for (const m of mutable) {
+            if (typeof m !== "string" || !params.includes(m)) {
+              errs.push(`${where2}: 'mutable' names ${JSON.stringify(m)}, which is not one of this hook's params`);
+            }
+          }
+        }
+      }
+    }
+    const recv = decl.receiver;
+    if (recv !== void 0) {
+      if (recv == null || typeof recv !== "object") {
+        errs.push(`${where2}: 'receiver' must be an object`);
+      } else {
+        const rkind = recv.kind ?? "none";
+        if (rkind !== "none" && rkind !== "entity") {
+          errs.push(`${where2}: receiver.kind must be "none" or "entity"`);
+        } else if (rkind === "entity") {
+          if (typeof recv.as !== "string" || !IDENTIFIER.test(recv.as)) {
+            errs.push(`${where2}: receiver.kind "entity" needs a plain-identifier 'as' name`);
+          } else if (Array.isArray(params) && params.includes(recv.as)) {
+            errs.push(`${where2}: receiver 'as' name ${JSON.stringify(recv.as)} collides with a param name`);
+          }
+        }
+      }
+    }
+    if (decl.bypassWith !== void 0) {
+      if (typeof decl.bypassWith !== "string" || !decl.bypassWith.length) {
+        errs.push(`${where2}: 'bypassWith' must be a non-empty call name`);
+      } else if (!callNames.includes(decl.bypassWith)) {
+        errs.push(
+          `${where2}: 'bypassWith' names ${JSON.stringify(decl.bypassWith)}, which is not a 'calls' descriptor in this owner's gamedata`
+        );
+      }
+    }
+    const target = decl.target;
+    if (!target) {
+      errs.push(`${where2}: missing 'target'`);
+      continue;
+    }
+    if (target.kind === "signature") {
+      if (typeof target.name !== "string") {
+        errs.push(`${where2}: target.name must be a string`);
+      } else if (!(target.name in sigs)) {
+        errs.push(`${where2}: target.name '${target.name}' has no entry in 'signatures'`);
+      }
+      const sigPlat = typeof target.name === "string" ? sigs[target.name]?.[PLATFORM] : void 0;
+      const inherited = sigPlat?.validate;
+      if (!isNonEmptyObject(target.validate) && !isNonEmptyObject(inherited)) {
+        errs.push(
+          `${where2}: a hook target MUST carry a non-empty 'validate' (inline, or inherited from its named signature) \u2014 a wrong detour address overwrites the prologue of whatever is actually there`
+        );
+      }
+    } else if (target.kind === "vtable") {
+      if (typeof target.class !== "string") errs.push(`${where2}: vtable target requires 'class'`);
+      const plat = target[PLATFORM];
+      if (!plat) {
+        errs.push(`${where2}: vtable target missing platform '${PLATFORM}'`);
+      } else {
+        if (!Number.isInteger(plat.index) || plat.index < 0) {
+          errs.push(`${where2}: vtable index must be a non-negative integer`);
+        }
+        const prologue = plat.validate?.prologue;
+        if (typeof prologue !== "string" || !prologue.length) {
+          errs.push(`${where2}: a vtable target REQUIRES validate.prologue (a bare borrowed index is never trusted)`);
+        }
+      }
+    } else {
+      errs.push(`${where2}: target.kind must be "signature" or "vtable"`);
+    }
+  }
+}
+
+// src/hookgen/model.ts
+function capitalize(name) {
+  return name.length === 0 ? name : name.charAt(0).toUpperCase() + name.slice(1);
+}
+function hookDescriptor(name, decl) {
+  const paramNames = decl.params ?? [];
+  const mutableSet = new Set(decl.mutable ?? []);
+  const params = paramNames.map((p) => ({ name: p, mutable: mutableSet.has(p) }));
+  const receiverAs = decl.receiver?.kind === "entity" ? decl.receiver.as ?? null : null;
+  return { name, shape: decl.shape ?? "", viewIface: `${capitalize(name)}View`, params, receiverAs };
+}
+function buildPluginHookList(hooks) {
+  return Object.keys(hooks).sort().map((name) => hookDescriptor(name, hooks[name] ?? {}));
+}
+function buildHookModel(hooks) {
+  const byNs = /* @__PURE__ */ new Map();
+  for (const name of Object.keys(hooks).sort()) {
+    const decl = hooks[name] ?? {};
+    const ns = decl.expose?.ctx;
+    if (!ns) continue;
+    if (decl.expose?.handwritten) continue;
+    const list = byNs.get(ns) ?? [];
+    list.push(hookDescriptor(name, decl));
+    byNs.set(ns, list);
+  }
+  return Array.from(byNs.keys()).sort().map((ns) => ({ ns, ctxIface: `Ctx${capitalize(ns)}`, hooks: byNs.get(ns) }));
+}
+
+// src/hookgen/emit-dts.ts
+var HEADER = "// GENERATED by `s2script gen-hooks` from gamedata/cs2/game.cs2.jsonc's `hooks` \u2014 DO NOT EDIT.";
+var STRING_PARAMS = {
+  this_i64_i64_i64: /* @__PURE__ */ new Set([0])
+};
+function emitViewIface(h2) {
+  const out = [`export interface ${h2.viewIface} {`];
+  const strings = STRING_PARAMS[h2.shape] ?? /* @__PURE__ */ new Set();
+  h2.params.forEach((p, i2) => {
+    const mod = p.mutable ? "" : "readonly ";
+    out.push(`  ${mod}${p.name}: ${strings.has(i2) ? "string" : "number"};`);
+  });
+  if (h2.receiverAs !== null) {
+    out.push(`  readonly ${h2.receiverAs}: EntityRef | null;`);
+  }
+  out.push("}", "");
+  return out;
+}
+function emitHookDts(model) {
+  const out = [
+    HEADER,
+    'import type { HookResultValue } from "@s2script/sdk/events";',
+    'import type { EntityRef } from "@s2script/sdk/entity";',
+    ""
+  ];
+  for (const { hooks } of model) {
+    for (const h2 of hooks) {
+      out.push(...emitViewIface(h2));
+    }
+  }
+  for (const { ctxIface, hooks } of model) {
+    out.push(`export interface ${ctxIface} {`);
+    for (const h2 of hooks) {
+      out.push(`  ${h2.name}(handler: (view: ${h2.viewIface}) => HookResultValue | void): void;`);
+    }
+    out.push("}", "");
+  }
+  out.push('declare module "@s2script/sdk/plugin" {');
+  out.push("  interface PluginContext {");
+  for (const { ns, ctxIface } of model) {
+    out.push(`    readonly ${ns}: ${ctxIface};`);
+  }
+  out.push("  }");
+  out.push("}");
+  return out.join("\n") + "\n";
+}
+var PLUGIN_HEADER = "// GENERATED by `s2s build` from the plugin's gamedata \u2014 DO NOT EDIT.";
+function emitPluginHookDts(hooks) {
+  const list = buildPluginHookList(hooks);
+  const out = [
+    PLUGIN_HEADER,
+    "// The EntityRef / HookResultValue imports are REQUIRED: a `declare module` augmentation",
+    "// resolves type names in its own file scope.",
+    'import type { HookResultValue } from "@s2script/sdk/events";',
+    'import type { EntityRef } from "@s2script/sdk/entity";',
+    ""
+  ];
+  for (const h2 of list) {
+    out.push(...emitViewIface(h2));
+  }
+  out.push('declare module "@s2script/sdk/unsafe" {');
+  out.push("  interface EngineHooks {");
+  for (const h2 of list) {
+    out.push(`    ${h2.name}: (handler: (view: ${h2.viewIface}) => HookResultValue | void) => void;`);
+  }
+  out.push("  }");
+  out.push("}");
+  out.push("");
+  return out.join("\n");
+}
 
 // src/gamedata/gen-types.ts
 var VECTOR_TS = "{ readonly x: number; readonly y: number; readonly z: number }";
@@ -4368,6 +4617,7 @@ var ARG_TS = {
   int: "number",
   float: "number",
   string: "string",
+  utlstring: "string",
   vector: VECTOR_TS,
   entity: "EntityRef | null"
 };
@@ -4405,6 +4655,9 @@ ${lines.join("\n")}
     ""
   ].join("\n");
 }
+function generateHookTypes(gd) {
+  return emitPluginHookDts(gd.hooks ?? {});
+}
 
 // src/gamedata/jsonc.ts
 function stripJsonComments(src) {
@@ -4514,8 +4767,14 @@ async function buildPlugin(dir, packagesDir) {
     const genDir = join11(absDir, ".s2script");
     mkdirSync2(genDir, { recursive: true });
     writeFileSync3(join11(genDir, "gamedata.d.ts"), generateGamedataTypes(gamedata));
+    if (gamedata.hooks && Object.keys(gamedata.hooks).length) {
+      writeFileSync3(join11(genDir, "hooks.d.ts"), generateHookTypes(gamedata));
+    } else {
+      rmSync2(join11(genDir, "hooks.d.ts"), { force: true });
+    }
   } else {
     rmSync2(join11(absDir, ".s2script", "gamedata.d.ts"), { force: true });
+    rmSync2(join11(absDir, ".s2script", "hooks.d.ts"), { force: true });
   }
   const declaredDepNames = [
     ...Object.keys(s2.pluginDependencies ?? {}),
@@ -8837,7 +9096,7 @@ function buildModel(catalog, requested, embeddable = [], enumCatalog = {}) {
 }
 
 // src/schemagen/emit-dts.ts
-var HEADER = "// GENERATED by `s2script gen-schema` from schema-catalog.json \u2014 DO NOT EDIT.";
+var HEADER2 = "// GENERATED by `s2script gen-schema` from schema-catalog.json \u2014 DO NOT EDIT.";
 function emitDts(model) {
   const enumTs = new Map(model.enums.map((e) => [e.className, e.tsName]));
   const tsType = (f) => {
@@ -8845,7 +9104,7 @@ function emitDts(model) {
     return id ? `${id} | null` : TSTYPE[f.accessorKind];
   };
   const names = new Set(model.classes.map((c2) => c2.className));
-  const out = [HEADER, 'import type { EntityRef } from "@s2script/sdk/entity";'];
+  const out = [HEADER2, 'import type { EntityRef } from "@s2script/sdk/entity";'];
   const vecClasses = /* @__PURE__ */ new Set();
   for (const c2 of model.classes) for (const f of c2.ownFields) {
     const vi = VEC_INFO[f.accessorKind];
@@ -8913,7 +9172,7 @@ function emitDts(model) {
 }
 
 // src/schemagen/emit-js.ts
-var HEADER2 = "// GENERATED by `s2script gen-schema` from schema-catalog.json \u2014 DO NOT EDIT.";
+var HEADER3 = "// GENERATED by `s2script gen-schema` from schema-catalog.json \u2014 DO NOT EDIT.";
 var S = JSON.stringify;
 function resolveExpr(f) {
   const base = `off(${S(f.declaringClass)},${S(f.rawName)})`;
@@ -8940,7 +9199,7 @@ function accessorEntry(f, resolve22, guard2) {
   return entry;
 }
 function emitJs(model) {
-  const out = [HEADER2, "(function () {", "  var off = __s2_schema_offset;", "  var A = {};", "  var E = {};"];
+  const out = [HEADER3, "(function () {", "  var off = __s2_schema_offset;", "  var A = {};", "  var E = {};"];
   const vecClasses = /* @__PURE__ */ new Set();
   for (const c2 of model.classes) for (const f of c2.ownFields) {
     const vi = VEC_INFO[f.accessorKind];
@@ -9102,7 +9361,7 @@ function buildEventModel(catalog) {
 }
 
 // src/eventgen/emit-dts.ts
-var HEADER3 = "// GENERATED by `s2script gen-events` from event-catalog.json \u2014 DO NOT EDIT.";
+var HEADER4 = "// GENERATED by `s2script gen-events` from event-catalog.json \u2014 DO NOT EDIT.";
 var GETTER_RET = {
   getBool: "boolean",
   getFloat: "number",
@@ -9113,7 +9372,7 @@ var GETTER_RET = {
 };
 function emitEventDts(model) {
   const out = [
-    HEADER3,
+    HEADER4,
     'import type { GameEvent, HookResultValue } from "@s2script/sdk/events";',
     ""
   ];
@@ -9232,7 +9491,7 @@ function buildNavModel(config, catalog) {
 }
 
 // src/navgen/emit-js.ts
-var HEADER4 = "// GENERATED by `s2script gen-nav` from nav-targets.json \u2014 DO NOT EDIT.";
+var HEADER5 = "// GENERATED by `s2script gen-nav` from nav-targets.json \u2014 DO NOT EDIT.";
 var S2 = JSON.stringify;
 var READ_VIA = {
   f32: "readFloat32Via",
@@ -9250,7 +9509,7 @@ var WRITE_VIA = {
   i32: "writeInt32Via"
 };
 function emitNavJs(model) {
-  const out = [HEADER4, "(function () {", "  var off = __s2_schema_offset;"];
+  const out = [HEADER5, "(function () {", "  var off = __s2_schema_offset;"];
   const vecClasses = /* @__PURE__ */ new Set();
   for (const w of model.wrappers) {
     for (const f of w.fields) {
@@ -9332,7 +9591,7 @@ function emitNavJs(model) {
 }
 
 // src/navgen/emit-dts.ts
-var HEADER5 = "// GENERATED by `s2script gen-nav` from nav-targets.json \u2014 DO NOT EDIT.";
+var HEADER6 = "// GENERATED by `s2script gen-nav` from nav-targets.json \u2014 DO NOT EDIT.";
 function emitNavDts(model) {
   let needsEntityRef = false;
   let needsVector = false;
@@ -9345,7 +9604,7 @@ function emitNavDts(model) {
       if (vi?.cls === "QAngle") needsQAngle = true;
     }
   }
-  const out = [HEADER5];
+  const out = [HEADER6];
   const mathTypes = [];
   if (needsVector) mathTypes.push("Vector");
   if (needsQAngle) mathTypes.push("QAngle");
@@ -9416,72 +9675,6 @@ function runGenNav(repoRoot2, opts) {
 // src/hookgen/gen.ts
 import { readFileSync as readFileSync22, writeFileSync as writeFileSync17 } from "node:fs";
 import { join as join27 } from "node:path";
-
-// src/hookgen/model.ts
-function capitalize(name) {
-  return name.length === 0 ? name : name.charAt(0).toUpperCase() + name.slice(1);
-}
-function buildHookModel(hooks) {
-  const byNs = /* @__PURE__ */ new Map();
-  for (const name of Object.keys(hooks).sort()) {
-    const decl = hooks[name] ?? {};
-    const ns = decl.expose?.ctx;
-    if (!ns) continue;
-    const paramNames = decl.params ?? [];
-    const mutableSet = new Set(decl.mutable ?? []);
-    const params = paramNames.map((p) => ({ name: p, mutable: mutableSet.has(p) }));
-    const receiverAs = decl.receiver?.kind === "entity" ? decl.receiver.as ?? null : null;
-    const list = byNs.get(ns) ?? [];
-    list.push({ name, viewIface: `${capitalize(name)}View`, params, receiverAs });
-    byNs.set(ns, list);
-  }
-  return Array.from(byNs.keys()).sort().map((ns) => ({ ns, ctxIface: `Ctx${capitalize(ns)}`, hooks: byNs.get(ns) }));
-}
-
-// src/hookgen/emit-dts.ts
-var HEADER6 = "// GENERATED by `s2script gen-hooks` from gamedata/cs2/game.cs2.jsonc's `hooks` \u2014 DO NOT EDIT.";
-function emitViewIface(h2) {
-  const out = [`export interface ${h2.viewIface} {`];
-  for (const p of h2.params) {
-    const mod = p.mutable ? "" : "readonly ";
-    out.push(`  ${mod}${p.name}: number;`);
-  }
-  if (h2.receiverAs !== null) {
-    out.push(`  readonly ${h2.receiverAs}: EntityRef | null;`);
-  }
-  out.push("}", "");
-  return out;
-}
-function emitHookDts(model) {
-  const out = [
-    HEADER6,
-    'import type { HookResultValue } from "@s2script/sdk/events";',
-    'import type { EntityRef } from "@s2script/sdk/entity";',
-    ""
-  ];
-  for (const { hooks } of model) {
-    for (const h2 of hooks) {
-      out.push(...emitViewIface(h2));
-    }
-  }
-  for (const { ctxIface, hooks } of model) {
-    out.push(`export interface ${ctxIface} {`);
-    for (const h2 of hooks) {
-      out.push(`  ${h2.name}(handler: (view: ${h2.viewIface}) => HookResultValue | void): void;`);
-    }
-    out.push("}", "");
-  }
-  out.push('declare module "@s2script/sdk/plugin" {');
-  out.push("  interface PluginContext {");
-  for (const { ns, ctxIface } of model) {
-    out.push(`    readonly ${ns}: ${ctxIface};`);
-  }
-  out.push("  }");
-  out.push("}");
-  return out.join("\n") + "\n";
-}
-
-// src/hookgen/gen.ts
 var GAMEDATA_PATH = "gamedata/cs2/game.cs2.jsonc";
 var DTS_OUT4 = "packages/cs2/hooks.generated.d.ts";
 function runGenHooks(repoRoot2, opts) {

package/events.d.ts

@@ -52,9 +52,9 @@ export type HookResultValue = 0 | 1 | 2 | 3;
  * Events.fire("player_changename", { userid: p.userId, oldname, newname });
  */
 export declare const Events: {
-  /** Fire a game event. Returns the engine FireEvent result. */
+  /** Fire a game event (SourceMod `FireEvent`). Other plugins' `on` / `onPre`
+   *  handlers run before this returns. 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.
    *
@@ -73,6 +73,7 @@ export declare const Events: {
    * });
    */
   setRecipients(slots: readonly number[]): void;
-
+  /** Fire a game event to ONE client (SourceMod `FireToClient`). Does not go through
+   *  `IGameEventManager2::FireEvent` (no `onPre`). Returns false on miss. */
   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.21.0",
+  "version": "0.22.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/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/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;
 };