@s2script/sdk 0.20.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/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.20.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;
 };