@s2script/sdk 0.26.0 → 0.27.0

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/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). */