@s2script/sdk 0.21.0 → 0.23.0

package/README.md

@@ -19,13 +19,21 @@ Copy the `.s2sp` into `addons/s2script/plugins/` on a running server and it load
 re-drop to hot-reload, delete to unload. No restart.
 
 ```ts
-import { plugin } from "@s2script/sdk/plugin";
+import { command, hook } from "@s2script/sdk";
+import type { Client } from "@s2script/sdk";
 
-export default plugin((ctx) => {
-  ctx.commands.register("hello", (cmd) => {
+export function OnPluginStart(): void {
+  command("hello", (cmd) => {
     cmd.reply("hello from s2script");
   });
-});
+  hook.on("player_spawn", (ev) => {
+    console.log("spawned", ev.getPlayerSlot("userid"));
+  });
+}
+
+export function OnClientPostAdminCheck(client: Client): void {
+  client.chat("welcome");
+}
 ```
 
 This package is **types-only** — the engine injects the implementation at load time, and

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

@@ -57,7 +57,7 @@ export interface CommandInvocation {
    *
    * @example
    * // `!help` answers in chat; `sm_help` typed at a console answers in that console.
-   * ctx.commands.register("sm_help", (cmd) => cmd.reply("[SM] Commands: …"));
+   * command("sm_help", (cmd) => { cmd.reply("[SM] Commands: …"); return HookResult.Handled; });
    */
   reply(message: string): void;
   /**
@@ -81,6 +81,53 @@ export interface CommandInvocation {
    * never in the way. */
   replyT(key: PhraseKey, ...args: (string | number)[]): void;
 }
+
+/** Alias for {@link CommandInvocation} — the SourceMod-shaped name for a parsed invocation. */
+export type Command = CommandInvocation;
+
+/**
+ * A command callback: the parsed invocation, plus an optional {@link HookResultValue}.
+ * SourceMod `Plugin_Handled` is {@link HookResult}.Handled — return it from a command you own
+ * (usage errors included; the command was still consumed). Omit the return (`void`) to continue —
+ * the same as returning {@link HookResult}.Continue. Engine SUPERCEDE-on-Continue is not this API;
+ * chat `!` vs `/` suppress is unchanged.
+ */
+export type CommandHandler = (
+  cmd: CommandInvocation,
+) => HookResultValue | void | Promise<HookResultValue | void>;
+
+/**
+ * Register a public command in the load window (SourceMod `RegConsoleCmd`).
+ * Callable only while `OnPluginStart` is running — throws after settle.
+ *
+ * `.admin` / `.server` are the `RegAdminCmd` / `RegServerCmd` shapes: name the handler anything.
+ *
+ * @example
+ * import { command, ADMFLAG, HookResult } from "@s2script/sdk";
+ * export function OnPluginStart(): void {
+ *   command.admin("sm_kick", ADMFLAG.KICK, kick);
+ * }
+ * function kick(cmd: CommandInvocation): HookResultValue {
+ *   cmd.reply("kicked");
+ *   return HookResult.Handled;
+ * }
+ */
+export declare const command: {
+  (name: string, handler: CommandHandler): void;
+  /** Register an admin command gated by `flags` (an `ADMFLAG` bitmask). */
+  admin(name: string, flags: number, handler: CommandHandler): void;
+  /** Register a server-only command (console/rcon, not client-runnable). */
+  server(name: string, handler: CommandHandler): void;
+  /**
+   * Observe an existing CLIENT command by name — SourceMod's `AddCommandListener`.
+   * Load-window only. Same contract as {@link CtxCommands.onClientCommand} (on PluginContext).
+   */
+  onClientCommand(
+    name: string,
+    handler: (slot: number, argString: string) => HookResultValue | void,
+  ): void;
+};
+
 /** A parsed chat trigger: which command + args, and whether it was the silent (`/`) trigger. */
 export interface ChatTrigger {
   /** `true` = the silent trigger (`/`, hidden); `false` = the public trigger (`!`). */
@@ -93,9 +140,9 @@ export interface ChatTrigger {
 
 /**
  * Command-registry utilities: dispatch by name, parse/route chat triggers, and enumerate the global
- * registry. Commands themselves are registered through the plugin context (`ctx.commands.register*`).
+ * registry. Commands themselves are registered in the load window via {@link command}.
  * @example
- * import { Commands } from "@s2script/sdk/commands";
+ * import { Commands } from "@s2script/sdk";
  * // sm_help backend: every registered command + its required admin flag mask.
  * const cmds = Commands.list().slice().sort((a, b) => (a.name < b.name ? -1 : 1));
  */
@@ -122,7 +169,7 @@ export declare const Commands: {
   /**
    * Observe a CLIENT command by name — SourceMod's `AddCommandListener`.
    *
-   * Unlike {@link register}, which CREATES a command, this hooks one that already exists — including
+   * Unlike {@link command}, which CREATES a command, this hooks one that already exists — including
    * commands the engine itself owns (`player_ping`, `jointeam`, `drop`, `buy`). Registering a
    * ConCommand of an engine-owned name fails outright ("unable to link multiple ConCommands named
    * X"), so this is the only way to see those.
@@ -133,7 +180,7 @@ export declare const Commands: {
    *
    * @example
    * // Middle-mouse ping opens the shop, and still places the ping.
-   * ctx.commands.onClientCommand("player_ping", (slot) => { openShop(slot); });
+   * command.onClientCommand("player_ping", (slot) => { openShop(slot); });
    */
   onClientCommand(name: string, handler: (slot: number, argString: string) => HookResultValue | void): void;
   /** Every globally-registered command with its required admin `flags`: `0` = anyone, `-1` = console/server-only,

package/config.d.ts

@@ -23,4 +23,9 @@ export declare const config: {
   readFile(name: string): string | null;
   /** Write a raw file to the configs dir (creates/overwrites). */
   writeFile(name: string, content: string): void;
+  /**
+   * Fires when this plugin's config file is re-materialized on disk. Ledgered per plugin.
+   * Not load-window-gated (safe from `OnPluginStart` or from `ctx.config.onChange`).
+   */
+  onChange(handler: (cfg: Config) => void): void;
 };

package/damage.d.ts

@@ -1,18 +1,23 @@
 /**
- * @s2script/damage — damage pre-hooks (SDKHooks-equivalent). NO runtime code (injected at load).
- * CTakeDamageInfo is a Source 2 engine type, so this module is engine-generic (lives in core).
+ * @s2script/damage — the block-scoped {@link DamageInfo} view of a live `CTakeDamageInfo`.
+ * NO runtime code (injected at load). Engine-generic: `CTakeDamageInfo` is a Source 2 type.
+ *
+ * Subscribe with `SDKHook` (`SDKHookType.OnTakeDamage` / `OnTakeDamagePost`), not a global mux.
  */
 import type { EntityRef } from "./entity";
 
 /**
- * A block-scoped view of the current damage event (valid only inside a Damage.onPre handler).
+ * A block-scoped view of the current damage event (valid only inside an `OnTakeDamage` or
+ * `OnTakeDamagePost` SDKHook).
  * @example
- * import type { DamageInfo } from "@s2script/sdk/damage";
- * // plugins/basecommands/src/plugin.ts:81 — halve the damage (assign 0 to block it entirely)
- * ctx.entities.onDamage((info: DamageInfo) => { info.damage = info.damage / 2; });
+ * import type { DamageInfo } from "@s2script/sdk";
+ * function onTakeDamage(info: DamageInfo) { info.damage = info.damage / 2; }
  */
 export interface DamageInfo {
-  /** The damage amount (m_flDamage). Assigning MODIFIES the live damage; set to 0 to block. */
+  /**
+   * The damage amount (`m_flDamage`). On the pre-hook, assigning MODIFIES the live damage; set to
+   * 0 to block. On `OnTakeDamagePost`, assignment is ignored (the original already ran).
+   */
   damage: number;
   /** The damage-type bit flags (m_bitsDamageType). */
   readonly damageType: number;