@s2script/sdk 0.10.2 → 0.12.0

package/entity.d.ts

@@ -116,6 +116,20 @@ export declare class EntityRef {
   notifyStateChanged(offset: number): void;
   /** Raw identity-slot flags (engine m_flags), or null when stale/unavailable. Bit meanings are game-specific. */
   identityFlags(): number | null;
+  /**
+   * CLEAR identity-slot flag bits; returns the flags after the write, or null when stale.
+   *
+   * Clear-only by design: `mask` names bits to DROP and nothing can be raised, because handing a
+   * plugin the ability to set arbitrary identity bits is a far larger foot-gun than the one this
+   * closes. The invalid-ehandle bit is refused outright — a dead slot must never be presentable as
+   * live.
+   *
+   * The case this exists for is the staging bit. `setModel` asserts that an entity is NOT in the
+   * staging list, and a created-but-unspawned entity is, so the create -> setModel -> spawn ordering
+   * (what CS2's own body spawner does) is otherwise unavailable and the alternatives produce
+   * half-initialised entities that clients fail to copy.
+   */
+  clearIdentityFlags(mask: number): number | null;
   /** DispatchSpawn this created entity. With keyvalues, the entity's own Spawn() parses them (the
    *  SourceMod DispatchKeyValue / CSSharp DispatchSpawn(kv) mechanism). Returns false if stale,
    *  unresolved, or the keyvalue map is rejected (non-finite number, unsupported value type, empty

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.10.2",
+  "version": "0.12.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",
@@ -20,7 +20,8 @@
   },
   "devDependencies": {
     "@clack/prompts": "^1.7.0",
-    "fflate": "^0.8.2"
+    "fflate": "^0.8.2",
+    "semver": "^7.8.5"
   },
   "publishConfig": {
     "access": "public"

package/sound.d.ts

@@ -18,8 +18,23 @@ export interface SoundEmitOptions {
  *  only: a stashed context used after the handler returns (or past an await) is a no-op `false`
  *  (the engine manifest is gone). */
 export interface PrecacheContext {
-  /** Add a resource path (e.g. "soundevents/mypack.vsndevts") to the session resource manifest.
-   *  True iff the engine accepted the add. */
+  /**
+   * Add a resource path to the game session manifest — a soundevents file, a model, a particle.
+   *
+   * @example
+   * pc.add("soundevents/mypack.vsndevts");
+   * pc.add("models/props/cs_office/microwave.vmdl");
+   *
+   * Returns true iff the engine ACCEPTED the string, which is not the same as the resource existing
+   * or being loadable: it returns true for a path with no file behind it too. A model that was never
+   * really there still spawns as the pink-and-black ERROR box, and the engine only says so later, at
+   * spawn time, with "requested but is not in the system (Missing from a manifest?)". Treat a `false`
+   * as fatal and a `true` as "not rejected".
+   *
+   * TIMING: the manifest is built once per map, before plugins that load later exist. A plugin loaded
+   * AFTER that point — including on the boot map of a fresh server start — misses that map's
+   * precache, and its resources stay unusable until the next map change.
+   */
   add(path: string): boolean;
 }