@s2script/sdk 0.19.0 → 0.21.0

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

@@ -3769,6 +3769,12 @@ function generatedDeclarationFiles(pluginDir) {
   const gd = join7(pluginDir, ".s2script", "gamedata.d.ts");
   return existsSync6(gd) ? [gd] : [];
 }
+function gamePackageDeclarationFiles(pkg, packagesDir) {
+  const deps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+  if (!("@s2script/cs2" in deps)) return [];
+  const hooks = join7(packagesDir, "cs2", "hooks.generated.d.ts");
+  return existsSync6(hooks) ? [hooks] : [];
+}
 function declaredModules(dtsFiles) {
   const out = /* @__PURE__ */ new Set();
   for (const f of dtsFiles) {
@@ -3837,7 +3843,8 @@ function typecheckPlugin(pluginDir, opts) {
     entry,
     join7(packagesDir, "sdk", "globals.d.ts"),
     ...localDts,
-    ...generatedDeclarationFiles(absDir)
+    ...generatedDeclarationFiles(absDir),
+    ...gamePackageDeclarationFiles(pkg, packagesDir)
   ];
   const tmp = mkdtempSync(join7(tmpdir(), "s2tc-"));
   try {
@@ -8528,7 +8535,7 @@ async function run8(argv2) {
 }
 
 // src/commands/codegen.ts
-import { dirname as dirname6, join as join27 } from "node:path";
+import { dirname as dirname6, join as join28 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/schemagen/gen.ts
@@ -9406,9 +9413,102 @@ function runGenNav(repoRoot2, opts) {
   return { wrappers: model.wrappers.length, fields, drift };
 }
 
+// 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) {
+  const raw = readFileSync22(join27(repoRoot2, GAMEDATA_PATH), "utf8");
+  const gd = JSON.parse(stripJsonComments(raw));
+  const hooks = gd.hooks ?? {};
+  const model = buildHookModel(hooks);
+  const dts = emitHookDts(model);
+  const drift = [];
+  const abs = join27(repoRoot2, DTS_OUT4);
+  if (opts.check) {
+    let cur = "";
+    try {
+      cur = readFileSync22(abs, "utf8");
+    } catch {
+    }
+    if (cur !== dts) drift.push(DTS_OUT4);
+  } else {
+    writeFileSync17(abs, dts);
+  }
+  const hookCount = model.reduce((n3, ns) => n3 + ns.hooks.length, 0);
+  return { hooks: hookCount, drift };
+}
+
 // src/commands/codegen.ts
 function repoRoot() {
-  return join27(dirname6(fileURLToPath3(import.meta.url)), "..", "..", "..");
+  return join28(dirname6(fileURLToPath3(import.meta.url)), "..", "..", "..");
 }
 async function run9(kind, argv2) {
   const root = repoRoot();
@@ -9437,7 +9537,7 @@ async function run9(kind, argv2) {
     } else {
       console.log(`gen-events: wrote ${r2.events} events`);
     }
-  } else {
+  } else if (kind === "nav") {
     const r2 = runGenNav(root, { check });
     if (check) {
       if (r2.drift.length) {
@@ -9449,6 +9549,18 @@ async function run9(kind, argv2) {
     } else {
       console.log(`gen-nav: wrote ${r2.wrappers} wrappers, ${r2.fields} fields`);
     }
+  } else {
+    const r2 = runGenHooks(root, { check });
+    if (check) {
+      if (r2.drift.length) {
+        console.error(`FAIL: generated files out of date \u2014 run \`s2s gen-hooks\`:
+  ${r2.drift.join("\n  ")}`);
+        process.exit(1);
+      }
+      console.log(`hook codegen up to date (${r2.hooks} hooks)`);
+    } else {
+      console.log(`gen-hooks: wrote ${r2.hooks} hooks`);
+    }
   }
 }
 
@@ -9464,7 +9576,8 @@ var COMMANDS = [
   { name: "config", summary: "Emit a plugin's default config file(s)", run: run8 },
   { name: "gen-schema", summary: "Regenerate schema accessors", run: (a2) => run9("schema", a2) },
   { name: "gen-events", summary: "Regenerate the event catalog", run: (a2) => run9("events", a2) },
-  { name: "gen-nav", summary: "Regenerate nav accessors", run: (a2) => run9("nav", a2) }
+  { name: "gen-nav", summary: "Regenerate nav accessors", run: (a2) => run9("nav", a2) },
+  { name: "gen-hooks", summary: "Regenerate the ctx hook augmentation", run: (a2) => run9("hooks", a2) }
 ];
 function find(name) {
   if (name === "publish") return COMMANDS.find((c2) => c2.name === "deploy");
@@ -9487,7 +9600,7 @@ var argv = process.argv.slice(2);
 var command = argv[0];
 function usage() {
   console.error(
-    "Usage:\n  s2s create [path] [--game cs2|none] [--name <pkg>] [--template minimal] [--library]\n             [--install npm|pnpm|yarn|bun|none] [--no-install] [-y]\n  s2s create --workspace <dir>\n  s2s build [dir|workspace root] [--filter <pattern>]... [--stamp-version <v>]\n            [--packages-dir <path>]\n  s2s login [--token s2s_\u2026] [--registry <url>]\n  s2s deploy [dir|workspace root] [--filter <pattern>]... [--dry-run] [--yes|--ci]\n             [--registry <url>] [--packages-dir <path>]\n  s2s version [dir] [--since <ref>]\n  s2s add <pkg>[@range] [--dir <plugin>] [--registry <url>]\n  s2s install [name[@range]...] [--file <path>] [--dir <plugins dir>] [--registry <url>]\n  s2s config gen <plugin.s2sp...> --out <dir>\n  s2s gen-schema [--check]\n  s2s gen-events [--check]\n  s2s gen-nav [--check]\n\nEnv: S2SCRIPT_REGISTRY_URL  S2SCRIPT_TOKEN (CI deploy)"
+    "Usage:\n  s2s create [path] [--game cs2|none] [--name <pkg>] [--template minimal] [--library]\n             [--install npm|pnpm|yarn|bun|none] [--no-install] [-y]\n  s2s create --workspace <dir>\n  s2s build [dir|workspace root] [--filter <pattern>]... [--stamp-version <v>]\n            [--packages-dir <path>]\n  s2s login [--token s2s_\u2026] [--registry <url>]\n  s2s deploy [dir|workspace root] [--filter <pattern>]... [--dry-run] [--yes|--ci]\n             [--registry <url>] [--packages-dir <path>]\n  s2s version [dir] [--since <ref>]\n  s2s add <pkg>[@range] [--dir <plugin>] [--registry <url>]\n  s2s install [name[@range]...] [--file <path>] [--dir <plugins dir>] [--registry <url>]\n  s2s config gen <plugin.s2sp...> --out <dir>\n  s2s gen-schema [--check]\n  s2s gen-events [--check]\n  s2s gen-nav [--check]\n  s2s gen-hooks [--check]\n\nEnv: S2SCRIPT_REGISTRY_URL  S2SCRIPT_TOKEN (CI deploy)"
   );
 }
 if (!command) {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.19.0",
+  "version": "0.21.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/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;
 };