@s2script/sdk 0.26.0 → 0.27.1

package/README.md

@@ -36,6 +36,19 @@ export function OnClientPostAdminCheck(client: Client): void {
 }
 ```
 
+For an existing plugin with `s2script.gamedata` declarations, run
+`npx @s2script/sdk migrate engine-functions [plugin-dir]`. The command analyzes the v1 declarations
+and source references, reports ambiguities, and writes `gamedata/functions.jsonc` only when the
+declared contract can be converted without loss. It refuses an existing destination unless you pass
+`--force`. Its JSON report lists files actually changed and the package/source edits you must make
+manually, including removal of the old `s2script.gamedata` field and authored engine permissions
+when adopting the v2 file. A successful conversion does not verify that the v1 declaration listed
+every native argument or that the resulting call works on the current game build. The command alone
+does not provide the runtime compatibility facades for old source code. V1 entity hooks are refused
+because their callbacks may receive a null receiver, which the current v2 receiver contract cannot
+preserve. With `--force`, the report identifies the exact create-or-replace path; concurrent prior
+existence cannot be established by the atomic rename.
+
 This package is **types-only** — the engine injects the implementation at load time, and
 `s2s build` marks `@s2script/*` external rather than bundling it. Capabilities are imported as
 per-capability subpaths (`@s2script/sdk/entity`, `@s2script/sdk/timers`, `@s2script/sdk/clients`, …);

package/config.d.ts

@@ -1,7 +1,7 @@
 /** @s2script/config — typed access to the plugin's materialized config. NO runtime code. */
 /** A materialized config value: a scalar, or a nested section object of further values. */
 export type ConfigValue = string | number | boolean | { [k: string]: ConfigValue };
-/** The whole materialized config: top-level keys to {@link ConfigValue}s. Passed to `ctx.config.onChange`. */
+/** The whole materialized config: top-level keys to {@link ConfigValue}s. Passed to `config.onChange` handlers. */
 export type Config = Record<string, ConfigValue>;
 /**
  * Typed access to this plugin's materialized config values (declared under `s2script.config` in the manifest).
@@ -25,7 +25,7 @@ export declare const config: {
   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`).
+   * Not load-window-gated (safe from `OnPluginStart` or from a `config.onChange` handler).
    */
   onChange(handler: (cfg: Config) => void): void;
 };

package/contracts/workshop.d.ts

@@ -10,7 +10,7 @@
  *
  * @example
  * import type { WorkshopService } from "@s2script/sdk/contracts/workshop";
- * const ws = ctx.tryUse<WorkshopService>("workshop");
+ * const ws = tryUse<WorkshopService>("workshop"); // in OnPluginStart
  * if (ws) {
  *   const map = await ws.currentMap();
  *   console.log(map ? `${map.title} (${map.id})` : "not a workshop map");

package/damage.d.ts

@@ -1,22 +1,26 @@
 /**
- * @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.
+ * @s2script/damage — the borrowed {@link DamageInfo} view of the current damage event.
+ * Type-only: the view is supplied by the selected game package (its damage function and damage-info
+ * layout are game facts; CS2 maps `CTakeDamageInfo`), through the engine-generic `SDKHook`.
  *
  * 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 an `OnTakeDamage` or
- * `OnTakeDamagePost` SDKHook).
+ * A borrowed view of the current damage event, valid only during the synchronous `OnTakeDamage` or
+ * `OnTakeDamagePost` SDKHook callback: reading or writing it afterwards (including after an `await`)
+ * throws "expired borrowed view". Returning `HookResult.Handled`/`Stop` from `OnTakeDamage` blocks the
+ * hit by setting damage to 0 after every handler ran; the engine's damage function still runs.
  * @example
  * import type { DamageInfo } from "@s2script/sdk";
  * function onTakeDamage(info: DamageInfo) { info.damage = info.damage / 2; }
  */
 export interface DamageInfo {
   /**
-   * 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).
+   * The damage amount (`m_flDamage`). On the pre-hook, assigning MODIFIES the damage the engine
+   * applies (later handlers see it); set to 0 to block. A non-finite value is refused (the damage
+   * keeps its prior value). On `OnTakeDamagePost`, assignment is ignored (the original already ran).
    */
   damage: number;
   /** The damage-type bit flags (m_bitsDamageType). */

package/db.d.ts

@@ -15,9 +15,16 @@ export interface ExecuteResult {
 
 /** A driver-owned connection — what a {@link Driver} hands back from {@link Driver.connect}. */
 export interface DriverConnection {
-  /** Run a SELECT and resolve every result {@link Row}; `params` bind `?` placeholders. */
+  /**
+   * Run a SELECT and resolve every result {@link Row}; `params` bind `?` placeholders. Rejects
+   * with `AsyncQueueFull` or `AsyncPayloadTooLarge` before acceptance; `DatabaseResultTooLarge`
+   * when rows or retained bytes exceed the configured limit.
+   */
   query(sql: string, params?: SqlValue[]): Promise<Row[]>;
-  /** Run a non-SELECT statement and resolve its {@link ExecuteResult}; `params` bind `?` placeholders. */
+  /**
+   * Run a non-SELECT statement and resolve its {@link ExecuteResult}; `params` bind `?`
+   * placeholders. Rejects with `AsyncQueueFull` or `AsyncPayloadTooLarge` before acceptance.
+   */
   execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
   /** Close the underlying connection. */
   close(): Promise<void>;
@@ -40,9 +47,16 @@ export interface Driver {
 }
 /** A live database connection (delegates to its driver). */
 export interface Database {
-  /** Run a SELECT and resolve every result {@link Row}; `params` bind `?` placeholders. */
+  /**
+   * Run a SELECT and resolve every result {@link Row}; `params` bind `?` placeholders. Rejects
+   * with `AsyncQueueFull` or `AsyncPayloadTooLarge` before acceptance; `DatabaseResultTooLarge`
+   * when rows or retained bytes exceed the configured limit.
+   */
   query(sql: string, params?: SqlValue[]): Promise<Row[]>;
-  /** Run a non-SELECT statement and resolve its {@link ExecuteResult}; `params` bind `?` placeholders. */
+  /**
+   * Run a non-SELECT statement and resolve its {@link ExecuteResult}; `params` bind `?`
+   * placeholders. Rejects with `AsyncQueueFull` or `AsyncPayloadTooLarge` before acceptance.
+   */
   execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
   /** Close the connection. */
   close(): Promise<void>;