@s2script/sdk 0.20.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/commands.d.ts

@@ -1,4 +1,5 @@
 /** @s2script/commands — register server commands. NO runtime code (injected at load). */
+import type { PhraseKey } from "./phrases";
 
 import type { HookResultValue } from "./events";
 
@@ -72,9 +73,13 @@ export interface CommandInvocation {
    * is printed immediately. The server console (`callerSlot` `-1`) prints to the server console.
    */
   replyToConsole(message: string): void;
-  /** reply to the caller, translated for THEIR language (SM's `%t` on the reply path). Soft-deps
-   * `@s2script/translations` — degrades to the raw `key` if it isn't loaded. */
-  replyT(key: string, ...args: (string | number)[]): void;
+  /** Reply to the caller, translated for THEIR language (SM's `%t` on the reply path). Soft-deps
+   * `@s2script/translations` — degrades to the raw `key` if it isn't loaded.
+   *
+   * `key` is checked against this plugin's phrase file plus the shared one (see
+   * `@s2script/sdk/phrases`); it widens to `string` in a plugin that has no phrase file, so this is
+   * never in the way. */
+  replyT(key: PhraseKey, ...args: (string | number)[]): void;
 }
 /** A parsed chat trigger: which command + args, and whether it was the silent (`/`) trigger. */
 export interface ChatTrigger {

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/entity.d.ts

@@ -158,6 +158,40 @@ 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;
+  /** Set this entity's gravity multiplier (`CBaseEntity::SetGravityScale`). 1 is normal, 0 is
+   *  weightless.
+   *
+   *  Use this rather than writing `m_flGravityScale`: the engine setter early-returns when the value
+   *  is unchanged and maintains a second field (`m_flActualGravityScale`), so a raw field write
+   *  appears to succeed and does nothing. Returns false if the op is unavailable, the ref is stale,
+   *  or `scale` is not finite. */
+  setGravityScale(scale: number): boolean;
+  /** Add to this entity's velocity, physics-aware (`CBaseEntity::ApplyAbsVelocityImpulse`) — for
+   *  knockback, boosts, explosions.
+   *
+   *  Additive, unlike `teleport(null, null, velocity)` which sets velocity absolutely; and unlike a
+   *  direct `m_vecAbsVelocity` write, which skips the partition/physics update. `impulse` is an
+   *  [x,y,z] triple. A zero impulse is a legal no-op. Returns false if the op is unavailable, the ref
+   *  is stale, or any component is not finite. */
+  applyAbsVelocityImpulse(impulse: number[]): boolean;
+  /** Stop a sound playing on this entity (`CBaseEntity::StopSound`). `Sound.stop(name, { entity })`
+   *  in `@s2script/sdk/sound` is the same call spelled next to `Sound.emit`, and
+   *  `pawn.stopSound(name)` in `@s2script/cs2` is the pawn-shaped one. Returns false if the op is
+   *  unavailable or the ref is stale. */
+  stopSound(name: string): boolean;
+  /** Set a model body group by name (`CBaseModelEntity::SetBodyGroupByName`).
+   *
+   *  There is no schema equivalent — `m_bodyGroupChoices` is a `CUtlOrderedMap`, not a writable
+   *  scalar. `group` is 32-bit engine-side. Returns false if the op is unavailable, the ref is stale,
+   *  or `group` is out of 32-bit range. */
+  setBodyGroupByName(name: string, group: number): boolean;
+  /** Set this entity's model scale (`CBaseModelEntity::SetModelScale`).
+   *
+   *  The argument shape is confirmed against the pinned build; the function's NAME is a catalogue
+   *  attribution its body does not itself prove, so verify the effect before relying on this in a
+   *  shipped plugin — see the gamedata comment. Calling it is safe either way. Returns false if the
+   *  op is unavailable, the ref is stale, or `scale` is not finite. */
+  setModelScale(scale: number): boolean;
   /** Read a CUtlVector<CHandle> at (ptrOffs chain -> vectorOff) as live liveness-gated EntityRefs.
    *  Follows the pointer chain, reads count@+0 / elements@+8, caps at maxCount. [] if stale/unresolved. */
   readHandleVector(ptrOffs: number[], vectorOff: number, maxCount?: number): EntityRef[];

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.20.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/phrases.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @s2script/phrases — the phrase keys your plugin is allowed to use.
+ *
+ * **You do not import this module.** It exists so that `cmd.replyT(...)` and
+ * `Translations.translate(...)` know which keys are valid in your plugin, and the build fills it in
+ * from the phrase files you load.
+ *
+ * @example
+ * export default plugin((ctx) => {
+ *   ctx.translations.load("basecomm", "common");
+ *
+ *   cmd.replyT("Usage Gag");            // ok — in translations/basecomm.phrases.json
+ *   cmd.replyT("No matching players");  // ok — in translations/common.phrases.json
+ *   cmd.replyT("Usage Gagg");           // compile error — no such key in either
+ * });
+ *
+ * ## Writing phrases
+ *
+ * Create `translations/<your-plugin>.phrases.json` — a flat key to English map. `{1}`, `{2}` … are
+ * positional slots filled by the trailing arguments; `{green}`, `{default}` … are colour tags
+ * expanded on output (see `@s2script/sdk/chat`). Keys are human-readable English on purpose: an
+ * unresolved key renders as the key itself, so it should still read as a sentence.
+ *
+ * ```json
+ * { "Gagged Player": "{green}[SM]{default} Gagged {1} player." }
+ * ```
+ *
+ * A translator adds `translations/<code>/<your-plugin>.phrases.json` — no code change, no rebuild.
+ *
+ * ## How the checking works
+ *
+ * The build reads your `ctx.translations.load(...)` call and writes `src/phrases.generated.d.ts`,
+ * filling in {@link PhraseKeys} with the keys of exactly those files. Load a file and its keys
+ * become valid; don't, and they don't — so a forgotten `load` is a compile error rather than raw key
+ * text printed to a player at runtime. SourceMod enforces the same rule, but only when it happens.
+ *
+ * That file is derived and gitignored. Until it has been written — a brand-new plugin, say — keys
+ * fall back to plain `string` and go unchecked, so nothing is blocked on the build having run.
+ */
+
+/**
+ * The set of valid phrase keys, filled in per plugin by its generated declaration.
+ *
+ * Empty here deliberately. Each plugin's `src/phrases.generated.d.ts` augments this interface, and
+ * interface merging turns that into the exact union {@link PhraseKey} resolves to. Never add keys
+ * here by hand — this is the shared module, and a key added here would apply to every plugin.
+ */
+export interface PhraseKeys {}
+
+/**
+ * Every phrase key valid in this plugin — the union of the keys in every file it loads.
+ *
+ * Falls back to `string` when nothing has augmented {@link PhraseKeys}, so a plugin that loads no
+ * phrases (or whose generated declaration has not been written yet) compiles unchecked rather than
+ * failing to compile at all.
+ */
+export type PhraseKey = [keyof PhraseKeys] extends [never] ? string : Extract<keyof PhraseKeys, string>;

package/plugin.d.ts

@@ -114,6 +114,26 @@ export interface CtxCommands {
     handler: (slot: number, argString: string) => HookResultValue | void,
   ): void;
 }
+/**
+ * The phrase files this plugin uses ({@link PluginContext.translations}).
+ *
+ * Nothing is loaded automatically — a plugin declares what it needs, the same rule SourceMod's
+ * `LoadTranslations` enforces. The build reads this call to work out which keys `cmd.replyT` and
+ * `Translations.translate` will accept, so a key from a file you did not load is a compile error.
+ */
+export interface CtxTranslations {
+  /**
+   * Load `translations/<name>.phrases.json` for each name, in the order given.
+   *
+   * Order is significant: `translate` takes the first hit within each of its two passes (the
+   * client's language, then English), so list your own set before any shared one if you want to be
+   * able to override a shared phrase.
+   *
+   * @example ctx.translations.load("basecomm", "common");
+   */
+  load(...names: string[]): void;
+}
+
 /** Config live-reload subscription on this plugin's load-scope ({@link PluginContext.config}). */
 export interface CtxConfig {
   /** Fires when the plugin's config file is re-materialized on disk; re-read values inside. */
@@ -175,6 +195,8 @@ export interface PluginContext {
   readonly commands: CtxCommands;
   /** Config live-reload subscription ({@link CtxConfig}). */
   readonly config: CtxConfig;
+  /** Phrase files this plugin uses ({@link CtxTranslations}). */
+  readonly translations: CtxTranslations;
   /** TopMenu (adminmenu) contribution ({@link CtxTopMenu}). */
   readonly topmenu: CtxTopMenu;
   /** Publish this plugin's manifest-declared interface. Buffered; goes live at Active. */

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/sound.d.ts

@@ -52,4 +52,18 @@ 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;
+  /**
+   * Stop a named SoundEvent playing on an entity — the counterpart to {@link Sound.emit}.
+   *
+   * **`opts.entity` is required**, unlike `emit`. The engine call behind this is an instance method
+   * on the entity, so there is no global/2D form to default to the way `emit` falls back to
+   * worldspawn. `recipients` and `volume` do not apply: the engine stops the sound for everyone
+   * hearing it.
+   *
+   * Equivalent to `entity.stopSound(name)`; this is the discoverable spelling next to `emit`.
+   * `pawn.stopSound(name)` in `@s2script/cs2` is the pawn-shaped one.
+   *
+   * Returns false when `opts.entity` is absent or stale, or the engine op is unavailable.
+   */
+  stop(name: string, opts: { entity: EntityRef }): boolean;
 };

package/translations.d.ts

@@ -1,20 +1,50 @@
 /** @s2script/translations — SourceMod-style i18n (per-client language, phrase files, {1} formatting). */
+import type { PhraseKey } from "./phrases";
 
 /** A phrase set: key → template string, where `{1}`/`{2}`/… are positional substitution slots. */
 export type Phrases = Record<string, string>;
+
 /**
- * SourceMod-style translation registry: seed a default phrase set, override it per language from
- * `translations/<code>/<name>.phrases.json`, then translate a key for a given client's language.
+ * SourceMod-style translation registry. Phrases live in `translations/<name>.phrases.json`, shipped
+ * with the addon and edited by operators; `translations/<code>/<name>.phrases.json` overrides per
+ * language, added by a translator with no code change.
+ *
+ * A plugin declares the files it uses with {@link PluginContext.translations} — nothing is loaded
+ * for it automatically, the same rule SourceMod's `LoadTranslations` enforces:
+ *
  * @example
- * import { Translations } from "@s2script/sdk/translations";
- * Translations.load("trdemo", { Greeting: "Hello {1}", Bye: "Goodbye {1}" });
- * console.log(Translations.translate(-1, "Greeting", "world")); // "Hello world"
+ * export default plugin((ctx) => {
+ *   ctx.translations.load("basecomm", "common");
+ *   ctx.commands.registerAdmin("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`.
  */
 export declare const Translations: {
-  /** Register a phrase set: `seed` is the built-in English default; translations/<code>/<name>.phrases.json overrides per language. */
-  load(name: string, seed: Phrases): void;
-  /** Translate `key` for `slot`'s language (slot < 0 = the server default), substituting positional {1}/{2} args. */
-  translate(slot: number, key: string, ...args: (string | number)[]): string;
+  /**
+   * Register a phrase set by name, populating it from `translations/<name>.phrases.json`.
+   *
+   * Prefer {@link PluginContext.translations}`.load(...)`, which is what the build reads to work out
+   * which keys your plugin may use. This is the lower-level form, for a name computed at runtime or
+   * a set with an in-code default — a `seed` here is the starting content, which the file overrides.
+   *
+   * Registration order is significant: `translate` takes the first hit within each of its two passes
+   * (the client's language, then English), so load your own set before any shared one if you want to
+   * override a shared phrase.
+   */
+  load(name: string, seed?: Phrases): void;
+  /**
+   * Translate `key` for `slot`'s language (slot < 0 = the server default), substituting positional
+   * {1}/{2} args.
+   *
+   * `key` is checked against the phrase files this plugin loads; it widens to `string` in a plugin
+   * that loads none, so this is never in the way. A key found in no loaded set returns the key
+   * itself — which is what the checking exists to prevent reaching a player.
+   */
+  translate(slot: number, key: PhraseKey, ...args: (string | number)[]): string;
   /** Set the server/console default language code (default "" = root/English). */
   setDefaultLanguage(code: string): void;
 };

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;
 };