@s2script/sdk 0.9.0 → 0.10.1

package/clients.d.ts

@@ -36,6 +36,42 @@ export declare class Client {
    * reason in the server log), setting is an inert no-op and reads stay false.
    */
   voiceMuted: boolean;
+  /**
+   * Tell this client to run `cmd` in their own console, as if they had typed it
+   * (SourceMod `ClientCommand`).
+   *
+   * Requires a real client: a bot has no console, so this is a no-op on bots — use
+   * {@link Client.fakeCommand} for server-side execution. Returns `false` when the command was not
+   * dispatched (empty text, bad slot, or the engine interface is unavailable on this build), never
+   * a silent no-op.
+   *
+   * @example
+   * client.command("play sounds/ui/beep.vsnd");
+   */
+  command(cmd: string): boolean;
+  /**
+   * Have the SERVER process `cmd` as if this client had sent it (SourceMod `FakeClientCommand`).
+   *
+   * Unlike {@link Client.command} this works on bots, because nothing is sent to a client — the
+   * engine dispatches the command itself, attributed to this player's slot. Live-verified:
+   * `fakeCommand("say hi")` on slot 0 prints as that player, not as Console.
+   *
+   * Returns `false` — never a silent no-op — for a bad slot, empty text, an unavailable interface,
+   * 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.
+   *
+   * @example
+   * client.fakeCommand("say hello");   // as though the player typed it
+   */
+  fakeCommand(cmd: string): boolean;
 }
 /**
  * Look up connected clients by slot or enumerate them all.

package/contracts/README.md

@@ -0,0 +1,37 @@
+# Standard interface contracts
+
+These are **type-only contracts for inter-plugin interfaces** — not SDK capability modules.
+
+The framework deliberately ships **no implementation** for anything in here. Each contract describes
+a shape that a *community plugin* implements and publishes, so that consumers can depend on one
+agreed interface instead of a different ad-hoc shape per plugin:
+
+```ts
+// producer
+import type { EconService } from "@s2script/cs2/econ";
+const impl: EconService = { /* … */ };
+ctx.publish("econ", impl);          // manifest: s2script.publishes
+
+// consumer
+import type { EconService } from "@s2script/cs2/econ";
+const econ = ctx.tryUse<EconService>("econ");   // null while unpublished
+```
+
+**Why contracts and not features.** Skins and workshop integration are Valve-backend and
+game-content concerns, not engine touchpoints. Implementing them in the framework would drag the
+core toward a specific game's economy and Steam's services, against *the core is engine-generic* and
+*dependencies point one way: game → core*. Publishing the contract gets the ecosystem interop
+without the framework taking on that surface.
+
+**Rules that apply to every contract here** (they cross the plugin boundary, see
+`docs/ARCHITECTURE.md`):
+
+- Arguments and return values cross by **structured copy as JSON**. A `BigInt` throws and silently
+  drops the whole payload, so every 64-bit value (Steam IDs, workshop IDs, item IDs) is typed as a
+  **decimal string**, never `number` or `bigint`.
+- `EntityRef` is the one live-ish exception: it crosses tagged and is revived serial-gated on the
+  other side, so it stays `T | null`-safe.
+- A hard dependency (`ctx.use`) throws `InterfaceUnavailable` if the producer is absent; an optional
+  one (`ctx.tryUse`) returns `null`. For anything in here, prefer `tryUse` — these are third-party.
+- Contracts are semver-governed. Adding an optional member is a minor; changing or removing one is a
+  major.

package/contracts/workshop.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `@s2script/sdk/contracts/workshop` — the standard contract for a **workshop / UGC** plugin.
+ *
+ * TYPE-ONLY. The framework ships no implementation: subscribing to, downloading and mounting UGC is
+ * a Steam-services concern, not a Source 2 engine touchpoint. A community plugin implements this and
+ * publishes it; consumers depend on the one agreed shape. See `contracts/README.md`.
+ *
+ * Engine-generic on purpose — every Source 2 title has workshop content, so nothing here is
+ * CS2-specific. Game-specific economy lives in `@s2script/cs2/econ`.
+ *
+ * @example
+ * import type { WorkshopService } from "@s2script/sdk/contracts/workshop";
+ * const ws = ctx.tryUse<WorkshopService>("workshop");
+ * if (ws) {
+ *   const map = await ws.currentMap();
+ *   console.log(map ? `${map.title} (${map.id})` : "not a workshop map");
+ * }
+ */
+
+/**
+ * A workshop item. `id` is a **decimal string**, never a number: published-file IDs are 64-bit and a
+ * `BigInt` cannot cross the plugin boundary (it throws and drops the whole payload).
+ */
+export interface WorkshopItem {
+  /** Published-file ID as a decimal string, e.g. `"3070288894"`. */
+  readonly id: string;
+  /** Item title, or `""` when metadata has not been fetched yet. */
+  readonly title: string;
+  /** Owning author's SteamID64 as a decimal string, or `""` if unknown. */
+  readonly authorSteamId: string;
+  /** Bytes on disk once installed; `0` when not installed or unknown. */
+  readonly sizeBytes: number;
+  /** Last-updated Unix seconds; `0` if unknown. */
+  readonly updatedAt: number;
+}
+
+/** An installed workshop map, as reported by {@link WorkshopService.currentMap}. */
+export interface WorkshopMap extends WorkshopItem {
+  /** The BSP name the engine loads (what `Server.mapName` reports once live). */
+  readonly mapName: string;
+}
+
+/** Progress for an in-flight download. */
+export interface WorkshopDownloadProgress {
+  readonly id: string;
+  readonly bytesDownloaded: number;
+  readonly bytesTotal: number;
+}
+
+/**
+ * The contract a workshop plugin publishes.
+ *
+ * Everything that touches Steam is asynchronous — an implementation must not block the game frame.
+ * Methods resolve to `null`/`false` rather than throwing when an item is unknown or Steam is
+ * unreachable, so a consumer degrades instead of crashing (the framework's standing posture).
+ */
+export interface WorkshopService {
+  /** The currently-running workshop map, or `null` when the server is on a stock map. */
+  currentMap(): Promise<WorkshopMap | null>;
+
+  /** Metadata for `id`, or `null` if unknown/unreachable. */
+  info(id: string): Promise<WorkshopItem | null>;
+
+  /**
+   * Ensure `id` is installed and up to date, resolving `true` once usable.
+   * Implementations should be idempotent — calling it for an already-current item is a cheap `true`.
+   */
+  ensureInstalled(id: string): Promise<boolean>;
+
+  /** In-flight download progress, or `null` when nothing is downloading for `id`. */
+  progress(id: string): Promise<WorkshopDownloadProgress | null>;
+
+  /**
+   * Change level to a workshop map. Resolves `false` when the item is not a map, is not installed
+   * and could not be fetched, or the change was refused. On success the server changes level, so a
+   * caller should not assume any code after this runs on the same map.
+   */
+  changeMap(id: string): Promise<boolean>;
+
+  /** Every installed workshop item known to the implementation. */
+  installed(): Promise<readonly WorkshopItem[]>;
+}

package/dist/cli.js

@@ -1217,6 +1217,10 @@ function typecheckPlugin(pluginDir, opts) {
       // dirs are deleted). tsc picks the longest matching prefix, so `@s2script/sdk/*` wins for
       // sdk imports.
       "@s2script/sdk/*": ["sdk/*.d.ts"],
+      // Game-package SUBPATHS (e.g. @s2script/cs2/econ -> packages/cs2/econ.d.ts). Needed because
+      // the `@s2script/*` fallback below maps to `<pkg>/index.d.ts`, which cannot express a
+      // subpath. tsc picks the longest matching prefix, so this wins for cs2 subpath imports.
+      "@s2script/cs2/*": ["cs2/*.d.ts"],
       "@s2script/*": ["*/index.d.ts"],
       ...contractPaths
     }
@@ -4636,9 +4640,15 @@ var ATOMIC = {
   uint32: { k: "u32", w: true },
   uint64: { k: "u64", w: false },
   int64: { k: "i64", w: false },
-  float64: { k: "f64", w: false }
+  float64: { k: "f64", w: false },
   // no narrow 64-bit writers
+  // `Color` is a 4-byte RGBA struct, not a scalar, but it is laid out exactly as a little-endian
+  // uint32 (R in the low byte) and every engine consumer treats it that way. Mapping it here rather
+  // than adding a value class keeps the surface small and matches how packed colours are already
+  // passed elsewhere in the SDK (e.g. the fade user-message).
+  Color: { k: "u32", w: true }
 };
+var ENUM_WIDTH = { 1: "u8", 2: "u16", 4: "u32", 8: "u64" };
 var VEC = { Vector: "vector", VectorWS: "vector", QAngle: "qangle" };
 var VEC_INFO = {
   vector: { cls: "Vector", count: 3 },
@@ -4651,7 +4661,13 @@ function idiomaticName(raw) {
   const core = m && KNOWN_TAGS.has(m[1]) ? m[2] : s;
   return core.charAt(0).toLowerCase() + core.slice(1);
 }
-function classifyField(type) {
+function transparentValue(catalog, className) {
+  const e = catalog[className];
+  if (!e || e.parent || e.fields.length !== 1) return null;
+  const f = e.fields[0];
+  return f.name === "m_Value" && f.type.kind === "atomic" ? f : null;
+}
+function classifyField(type, embeddable = /* @__PURE__ */ new Set()) {
   if (type.kind === "handle") return { accessorKind: "handle", writable: false };
   if (type.kind === "atomic") {
     const vk = VEC[type.name ?? ""];
@@ -4665,8 +4681,16 @@ function classifyField(type) {
     if (cm) return { accessorKind: "str", writable: false, strLen: parseInt(cm[1], 10) };
     return { skip: `unmapped 'unknown' type '${type.name ?? ""}'` };
   }
-  if (type.kind === "enum") return { skip: "enum byte-width absent from catalog (deferred)" };
-  if (type.kind === "class") return { skip: `embedded class '${type.name ?? ""}' deferred` };
+  if (type.kind === "enum") {
+    const w = ENUM_WIDTH[type.size ?? 0];
+    if (w) return { accessorKind: w, writable: WRITE[w] !== void 0 };
+    return { skip: `enum '${type.name ?? ""}' byte width not stated by the schema` };
+  }
+  if (type.kind === "class") {
+    const n3 = type.name ?? "";
+    if (embeddable.has(n3)) return { embedded: n3 };
+    return { skip: `embedded class '${n3}' deferred` };
+  }
   if (type.kind === "ptr") return { skip: "raw pointer" };
   return { skip: `unmapped kind '${type.kind}'` };
 }
@@ -4681,7 +4705,11 @@ function flattenedFields(model, className) {
   }
   return chain.flatMap((c2) => c2.ownFields);
 }
-function buildModel(catalog, requested) {
+function buildModel(catalog, requested, embeddable = []) {
+  for (const n3 of embeddable) if (!catalog[n3]) throw new Error(`gen-schema: embedded class '${n3}' is not in the catalog`);
+  const restrict = embeddable.length > 0 ? new Set(embeddable) : null;
+  const canEmbed = (n3) => !!catalog[n3] && transparentValue(catalog, n3) === null && (restrict === null || restrict.has(n3));
+  const embedSet = new Set(Object.keys(catalog).filter(canEmbed));
   const inClosure = /* @__PURE__ */ new Set();
   for (const start of requested) {
     if (!catalog[start]) throw new Error(`gen-schema: requested class '${start}' is not in the catalog`);
@@ -4700,34 +4728,98 @@ function buildModel(catalog, requested) {
     return d;
   };
   const ordered = [...inClosure].sort((a2, b) => depth(a2) - depth(b) || (a2 < b ? -1 : a2 > b ? 1 : 0));
-  const classes = ordered.map((className) => {
-    const parent = catalog[className].parent;
-    const ownFields = [];
-    const skipped = [];
-    for (const f of catalog[className].fields) {
-      const c2 = classifyField(f.type);
+  const usedEmbeds = /* @__PURE__ */ new Set();
+  const classify = (f) => {
+    if (f.type.kind === "class") {
+      const inner = transparentValue(catalog, f.type.name ?? "");
+      if (inner) {
+        const c2 = classifyField(inner.type);
+        if (!("skip" in c2) && !("embedded" in c2)) return { ...c2, addOffset: inner.offset };
+      }
+    }
+    return classifyField(f.type, embedSet);
+  };
+  const fieldsOf = (owner, out, emb, skipped) => {
+    for (const f of catalog[owner].fields) {
+      const c2 = classify(f);
       if ("skip" in c2) {
-        skipped.push({ className, rawName: f.name, reason: c2.skip });
+        skipped.push({ className: owner, rawName: f.name, reason: c2.skip });
+        continue;
+      }
+      if ("embedded" in c2) {
+        usedEmbeds.add(c2.embedded);
+        emb.push({ propName: idiomaticName(f.name), rawName: f.name, declaringClass: owner, embeddedClass: c2.embedded });
         continue;
       }
-      ownFields.push({ propName: idiomaticName(f.name), rawName: f.name, declaringClass: className, accessorKind: c2.accessorKind, writable: c2.writable, strLen: c2.strLen });
+      out.push({ propName: idiomaticName(f.name), rawName: f.name, declaringClass: owner, accessorKind: c2.accessorKind, writable: c2.writable, strLen: c2.strLen, addOffset: c2.addOffset });
     }
-    return { className, parent: parent && inClosure.has(parent) ? parent : null, ownFields, skipped };
+  };
+  const classes = ordered.map((className) => {
+    const parent = catalog[className].parent;
+    const ownFields = [];
+    const embeddedFields = [];
+    const skipped = [];
+    fieldsOf(className, ownFields, embeddedFields, skipped);
+    return { className, parent: parent && inClosure.has(parent) ? parent : null, ownFields, embeddedFields, skipped };
   });
+  const embedded = [];
+  const done = /* @__PURE__ */ new Set();
+  for (; ; ) {
+    const next = [...usedEmbeds].filter((n3) => !done.has(n3)).sort();
+    if (next.length === 0) break;
+    for (const className of next) {
+      done.add(className);
+      const fields = [];
+      const embeddedFields = [];
+      const skipped = [];
+      const chain = [];
+      for (let cur = className; cur && catalog[cur]; cur = catalog[cur].parent) chain.unshift(cur);
+      for (const owner of chain) fieldsOf(owner, fields, embeddedFields, skipped);
+      embedded.push({ className, fields, embeddedFields, skipped });
+    }
+  }
+  embedded.sort((a2, b) => a2.className < b.className ? -1 : a2.className > b.className ? 1 : 0);
+  const ancestors = (cls) => {
+    const out = /* @__PURE__ */ new Set();
+    for (let cur = catalog[cls]?.parent ?? null; cur && catalog[cur]; cur = catalog[cur].parent) out.add(cur);
+    return out;
+  };
   const byProp = /* @__PURE__ */ new Map();
-  for (const c2 of classes) for (const f of c2.ownFields) {
+  for (const c2 of classes) for (const f of [...c2.ownFields, ...c2.embeddedFields]) {
     (byProp.get(f.propName) ?? byProp.set(f.propName, []).get(f.propName)).push(f);
   }
   const collisions = [];
   for (const [prop, fields] of byProp) {
-    const distinct = new Set(fields.map((f) => `${f.declaringClass}.${f.rawName}`));
-    if (distinct.size >= 2) {
-      for (const f of fields) f.propName = f.rawName;
-      collisions.push(`${prop} \u2190 ${[...distinct].sort().join(", ")}`);
+    const decls = /* @__PURE__ */ new Map();
+    for (const f of fields) (decls.get(`${f.declaringClass}.${f.rawName}`) ?? decls.set(`${f.declaringClass}.${f.rawName}`, []).get(`${f.declaringClass}.${f.rawName}`)).push(f);
+    if (decls.size < 2) continue;
+    const keys = [...decls.keys()].sort();
+    const clsOf = (k) => decls.get(k)[0].declaringClass;
+    const conflicting = /* @__PURE__ */ new Set();
+    for (let i2 = 0; i2 < keys.length; i2++) {
+      for (let j = i2 + 1; j < keys.length; j++) {
+        const a2 = clsOf(keys[i2]), b = clsOf(keys[j]);
+        if (a2 === b || ancestors(a2).has(b) || ancestors(b).has(a2)) {
+          conflicting.add(keys[i2]);
+          conflicting.add(keys[j]);
+        }
+      }
     }
+    if (conflicting.size === 0) continue;
+    const depthOf = (k) => ancestors(clsOf(k)).size;
+    const inConflict = [...conflicting].sort((x, y) => depthOf(x) - depthOf(y) || (x < y ? -1 : 1));
+    const winnerCls = clsOf(inConflict[0]);
+    const soleWinner = inConflict.filter((k) => clsOf(k) === winnerCls).length === 1;
+    const renamed = [];
+    for (const k of inConflict) {
+      if (soleWinner && k === inConflict[0]) continue;
+      for (const f of decls.get(k)) f.propName = f.rawName;
+      renamed.push(k);
+    }
+    collisions.push(`${prop} <- ${renamed.sort().join(", ")}${soleWinner ? ` (kept by ${winnerCls})` : ""}`);
   }
   collisions.sort();
-  return { classes, collisions };
+  return { classes, embedded, collisions };
 }
 
 // src/schemagen/emit-dts.ts
@@ -4740,8 +4832,20 @@ function emitDts(model) {
     const vi = VEC_INFO[f.accessorKind];
     if (vi) vecClasses.add(vi.cls);
   }
+  for (const e of model.embedded) for (const f of e.fields) {
+    const vi = VEC_INFO[f.accessorKind];
+    if (vi) vecClasses.add(vi.cls);
+  }
   if (vecClasses.size) out.push(`import type { ${[...vecClasses].sort().join(", ")} } from "@s2script/sdk/math";`);
   out.push("");
+  for (const e of model.embedded) {
+    out.push(`export interface ${e.className} {`);
+    for (const f of e.fields) {
+      out.push(`  ${f.writable ? "" : "readonly "}${f.propName}: ${TSTYPE[f.accessorKind]};`);
+    }
+    for (const f of e.embeddedFields) out.push(`  readonly ${f.propName}: ${f.embeddedClass};`);
+    out.push("}", "");
+  }
   for (const c2 of model.classes) {
     const ext = c2.parent && names.has(c2.parent) ? ` extends ${c2.parent}` : "";
     out.push(`export interface ${c2.className}${ext} {`);
@@ -4749,18 +4853,66 @@ function emitDts(model) {
       const ro = f.writable ? "" : "readonly ";
       out.push(`  ${ro}${f.propName}: ${TSTYPE[f.accessorKind]};`);
     }
+    for (const f of c2.embeddedFields) out.push(`  readonly ${f.propName}: ${f.embeddedClass};`);
     out.push("}", "");
   }
+  out.push("/** Every wrappable entity class, by schema name. */", "export interface SchemaClasses {");
+  for (const c2 of model.classes) out.push(`  ${c2.className}: ${c2.className};`);
+  out.push("}", "");
+  out.push(
+    "/**",
+    " * Apply this schema class's field accessors to an entity reference.",
+    " *",
+    " * `createEntity` returns a bare `EntityRef` with no schema fields on it \u2014 this is how you get",
+    " * them. `Player.pawn` is already wrapped; this is for entities you create or resolve yourself.",
+    " *",
+    " * The wrapper is a view, not a copy: it holds the ref and reads through it on every access, so",
+    " * it stays correct as the entity changes and costs nothing to keep. Field reads return null",
+    " * once the ref goes stale, exactly as they do on a pawn.",
+    " *",
+    " * @example",
+    ' * const prop = createEntity("prop_dynamic");',
+    " * prop.spawn();",
+    ' * const fields = wrapEntity("CBaseModelEntity", prop);',
+    " * fields.glow.glowing = true;",
+    " */",
+    "export declare function wrapEntity<K extends keyof SchemaClasses>(className: K, ref: EntityRef): SchemaClasses[K];",
+    ""
+  );
   return out.join("\n");
 }
 
 // src/schemagen/emit-js.ts
 var HEADER2 = "// GENERATED by `s2script gen-schema` from schema-catalog.json \u2014 DO NOT EDIT.";
 var S = JSON.stringify;
+function resolveExpr(f) {
+  const base = `off(${S(f.declaringClass)},${S(f.rawName)})`;
+  return f.addOffset ? `${base} + ${f.addOffset}` : base;
+}
+function accessorEntry(f, resolve13, guard2) {
+  const g = guard2 === "" ? "" : `${guard2} `;
+  const gs = guard2 === "" ? "" : `${guard2.replace("return null;", "return;")} `;
+  let entry;
+  if (f.accessorKind === "str") {
+    entry = `get: function () { ${g}return this.ref.readString(${resolve13}, ${f.strLen}); }`;
+  } else if (f.accessorKind === "u64" || f.accessorKind === "i64") {
+    entry = `get: function () { ${g}var v = this.ref.${READ[f.accessorKind]}(${resolve13}); return v === null ? null : v.toString(); }`;
+  } else if (VEC_INFO[f.accessorKind]) {
+    const vi = VEC_INFO[f.accessorKind];
+    entry = `get: function () { ${g}var a = this.ref.readFloats(${resolve13}, ${vi.count}); return a === null ? null : new ${vi.cls}(a[0], a[1], a[2]); }`;
+  } else {
+    entry = `get: function () { ${g}return this.ref.${READ[f.accessorKind]}(${resolve13}); }`;
+  }
+  if (f.writable) {
+    const wm = WRITE[f.accessorKind];
+    entry += `, set: function (v) { ${gs}var o = ${resolve13}; if (this.ref.${wm}(o, v)) this.ref.notifyStateChanged(o); }`;
+  }
+  return entry;
+}
 function emitJs(model) {
-  const out = [HEADER2, "(function () {", "  var off = __s2_schema_offset;", "  var A = {};"];
+  const out = [HEADER2, "(function () {", "  var off = __s2_schema_offset;", "  var A = {};", "  var E = {};"];
   const vecClasses = /* @__PURE__ */ new Set();
-  for (const c2 of model.classes) for (const f of flattenedFields(model, c2.className)) {
+  for (const c2 of model.classes) for (const f of c2.ownFields) {
     const vi = VEC_INFO[f.accessorKind];
     if (vi) vecClasses.add(vi.cls);
   }
@@ -4769,36 +4921,58 @@ function emitJs(model) {
   }
   for (const c2 of model.classes) {
     out.push(`  A[${S(c2.className)}] = {`);
-    for (const f of flattenedFields(model, c2.className)) {
-      const resolve13 = `off(${S(f.declaringClass)},${S(f.rawName)})`;
-      let entry;
-      if (f.accessorKind === "str") {
-        entry = `get: function () { return this.ref.readString(${resolve13}, ${f.strLen}); }`;
-      } else if (f.accessorKind === "u64" || f.accessorKind === "i64") {
-        entry = `get: function () { var v = this.ref.${READ[f.accessorKind]}(${resolve13}); return v === null ? null : v.toString(); }`;
-      } else if (VEC_INFO[f.accessorKind]) {
-        const vi = VEC_INFO[f.accessorKind];
-        entry = `get: function () { var a = this.ref.readFloats(${resolve13}, ${vi.count}); return a === null ? null : new ${vi.cls}(a[0], a[1], a[2]); }`;
-      } else {
-        entry = `get: function () { return this.ref.${READ[f.accessorKind]}(${resolve13}); }`;
-      }
-      if (f.writable) {
-        const wm = WRITE[f.accessorKind];
-        entry += `, set: function (v) { var o = ${resolve13}; if (this.ref.${wm}(o, v)) this.ref.notifyStateChanged(o); }`;
-      }
+    for (const f of c2.ownFields) {
+      const entry = accessorEntry(f, resolveExpr(f), "");
       out.push(`    ${S(f.propName)}: { ${entry} },`);
     }
+    for (const f of c2.embeddedFields) {
+      out.push(`    ${S(f.propName)}: { get: function () { return embed(${S(f.embeddedClass)}, this.ref, off(${S(f.declaringClass)},${S(f.rawName)})); } },`);
+    }
+    out.push("  };");
+  }
+  for (const e of model.embedded) {
+    out.push(`  E[${S(e.className)}] = {`);
+    for (const f of e.fields) {
+      const sub = `off(${S(f.declaringClass)},${S(f.rawName)})`;
+      const resolve13 = f.addOffset ? `this.base + ${sub} + ${f.addOffset}` : `this.base + ${sub}`;
+      const guard2 = `if (this.base < 0 || ${sub} < 0) return null;`;
+      out.push(`    ${S(f.propName)}: { ${accessorEntry(f, resolve13, guard2)} },`);
+    }
+    for (const f of e.embeddedFields) {
+      const sub = `off(${S(f.declaringClass)},${S(f.rawName)})`;
+      out.push(`    ${S(f.propName)}: { get: function () { var s = ${sub}; return embed(${S(f.embeddedClass)}, this.ref, (this.base < 0 || s < 0) ? -1 : this.base + s); } },`);
+    }
     out.push("  };");
   }
+  out.push("  var P = {");
+  for (const c2 of model.classes) if (c2.parent) out.push(`    ${S(c2.className)}: ${S(c2.parent)},`);
+  out.push("  };");
   out.push(
+    "  // Walk the ancestor chain rather than storing every inherited accessor per class. Flattening",
+    "  // into each table duplicated the whole chain 3.77x on the CS2 class set and grew as",
+    "  // O(classes * depth), so every class added inflated every other one; this is O(total fields).",
+    "  // Ancestors are applied FIRST so a derived class's own definition wins if a name repeats.",
     "  function applyAccessors(proto, className) {",
-    "    var defs = A[className]; if (!defs) return;",
-    "    for (var name in defs) {",
-    "      Object.defineProperty(proto, name, { get: defs[name].get, set: defs[name].set, enumerable: true, configurable: true });",
+    "    var chain = [], c = className;",
+    "    for (; c; c = P[c]) chain.unshift(c);",
+    "    for (var i = 0; i < chain.length; i++) {",
+    "      var defs = A[chain[i]]; if (!defs) continue;",
+    "      for (var name in defs) {",
+    "        Object.defineProperty(proto, name, { get: defs[name].get, set: defs[name].set, enumerable: true, configurable: true });",
+    "      }",
     "    }",
     "  }",
     "  function wrap(className, ref) { var o = { ref: ref }; applyAccessors(o, className); return o; }",
+    "  function embed(className, ref, base) {",
+    "    var o = { ref: ref, base: base }, defs = E[className];",
+    "    if (defs) for (var name in defs) {",
+    "      Object.defineProperty(o, name, { get: defs[name].get, set: defs[name].set, enumerable: true, configurable: true });",
+    "    }",
+    "    return o;",
+    "  }",
     "  globalThis.__s2pkg_cs2_schema = { applyAccessors: applyAccessors, wrap: wrap };",
+    "  // Merge (not overwrite): this prelude runs FIRST, and pawn.js merges onto whatever it finds.",
+    "  globalThis.__s2pkg_cs2 = Object.assign({}, globalThis.__s2pkg_cs2, { wrapEntity: wrap });",
     "})();"
   );
   return out.join("\n");
@@ -4807,12 +4981,18 @@ function emitJs(model) {
 // src/schemagen/gen.ts
 var CATALOG_PATH = "games/cs2/gamedata/schema-catalog.json";
 var LIST_PATH = "games/cs2/codegen-classes.json";
+var EMBED_PATH = "games/cs2/codegen-embedded.json";
 var JS_OUT = "games/cs2/js/schema.generated.js";
 var DTS_OUT = "packages/cs2/schema.generated.d.ts";
 function runGenSchema(repoRoot2, opts) {
   const catalog = JSON.parse(readFileSync13(join13(repoRoot2, CATALOG_PATH), "utf8"));
   const list = JSON.parse(readFileSync13(join13(repoRoot2, LIST_PATH), "utf8"));
-  const model = buildModel(catalog, list);
+  let embed = [];
+  try {
+    embed = JSON.parse(readFileSync13(join13(repoRoot2, EMBED_PATH), "utf8"));
+  } catch {
+  }
+  const model = buildModel(catalog, list, embed);
   const dts = emitDts(model);
   const js = emitJs(model);
   const fields = model.classes.reduce((n3, c2) => n3 + c2.ownFields.length, 0);
@@ -4963,27 +5143,44 @@ var SUPPORTED_NAV_KINDS = /* @__PURE__ */ new Set([
   "vector",
   "qangle"
 ]);
+var WRITABLE_NAV_KINDS = /* @__PURE__ */ new Set(["f32", "bool", "i32"]);
 function buildNavModel(config, catalog) {
   const targetClasses = [...new Set(config.map((e) => e.target))];
   const schemaModel = buildModel(catalog, targetClasses);
   const sorted = [...config].sort((a2, b) => a2.wrapper < b.wrapper ? -1 : a2.wrapper > b.wrapper ? 1 : 0);
   const wrappers = sorted.map((entry) => {
     const all = flattenedFields(schemaModel, entry.target);
+    const wantWritable = new Set(entry.writable ?? []);
     const fields = [];
     const skippedKinds = [];
     for (const f of all) {
       if (SUPPORTED_NAV_KINDS.has(f.accessorKind)) {
-        fields.push(f);
+        fields.push({ ...f, navWritable: wantWritable.has(f.rawName) });
       } else {
         skippedKinds.push({ propName: f.propName, accessorKind: f.accessorKind });
       }
     }
+    for (const raw of wantWritable) {
+      const f = fields.find((x) => x.rawName === raw);
+      if (!f) {
+        const known = all.some((x) => x.rawName === raw);
+        throw new Error(
+          `nav-targets: ${entry.wrapper}.writable lists ${JSON.stringify(raw)}, which ` + (known ? `exists on ${entry.target} but has an unsupported accessor kind, so it has no nav accessor at all.` : `does not exist on ${entry.target} or any of its ancestors (renamed or removed?).`)
+        );
+      }
+      if (!WRITABLE_NAV_KINDS.has(f.accessorKind)) {
+        throw new Error(
+          `nav-targets: ${entry.wrapper}.writable lists ${JSON.stringify(raw)} (kind '${f.accessorKind}'), but there is no EntityRef.write*Via for that kind. Add the native and extend WRITABLE_NAV_KINDS, or drop the field from the allowlist.`
+        );
+      }
+    }
     return {
       wrapper: entry.wrapper,
       prop: entry.prop,
       source: entry.source,
       target: entry.target,
       path: entry.path,
+      base: entry.base ?? [],
       fields,
       skippedKinds
     };
@@ -5004,6 +5201,11 @@ var READ_VIA = {
   u16: "readUInt16Via",
   u32: "readUInt32Via"
 };
+var WRITE_VIA = {
+  f32: "writeFloat32Via",
+  bool: "writeBoolVia",
+  i32: "writeInt32Via"
+};
 function emitNavJs(model) {
   const out = [HEADER4, "(function () {", "  var off = __s2_schema_offset;"];
   const vecClasses = /* @__PURE__ */ new Set();
@@ -5017,10 +5219,12 @@ function emitNavJs(model) {
     out.push(`  var ${cls} = __s2require("@s2script/sdk/math").${cls};`);
   }
   for (const w of model.wrappers) {
-    out.push(`  function ${w.wrapper}(root, path) { this.root = root; this.path = path; }`);
+    out.push(`  function ${w.wrapper}(root, path, base) { this.root = root; this.path = path; this.base = base; }`);
     out.push(`  Object.defineProperties(${w.wrapper}.prototype, {`);
     for (const f of w.fields) {
-      const resolve13 = `off(${S2(f.declaringClass)},${S2(f.rawName)})`;
+      const own = `off(${S2(f.declaringClass)},${S2(f.rawName)})`;
+      const withDelta = f.addOffset ? `${own} + ${f.addOffset}` : own;
+      const resolve13 = `${withDelta} + this.base`;
       let getter;
       const kind = f.accessorKind;
       if (kind === "u64") {
@@ -5037,7 +5241,9 @@ function emitNavJs(model) {
         if (!method) continue;
         getter = `get: function () { return this.root.${method}(this.path, ${resolve13}); }`;
       }
-      out.push(`    ${S2(f.propName)}: { ${getter} },`);
+      const wmethod = f.navWritable ? WRITE_VIA[kind] : void 0;
+      const setter = wmethod ? `, set: function (v) { this.root.${wmethod}(this.path, ${resolve13}, v); }` : "";
+      out.push(`    ${S2(f.propName)}: { ${getter}${setter} },`);
     }
     out.push("  });");
   }
@@ -5057,7 +5263,16 @@ function emitNavJs(model) {
         const h2 = w.path[i2];
         out.push(`          var o${i2} = off(${S2(h2.cls)},${S2(h2.field)}); if (o${i2} < 0) return null; _p.push(o${i2});`);
       }
-      out.push(`          return new ${w.wrapper}(this.ref, _p);`);
+      if (w.base.length > 0) {
+        out.push(`          var _b = 0;`);
+        for (let i2 = 0; i2 < w.base.length; i2++) {
+          const h2 = w.base[i2];
+          out.push(`          var b${i2} = off(${S2(h2.cls)},${S2(h2.field)}); if (b${i2} < 0) return null; _b += b${i2};`);
+        }
+        out.push(`          return new ${w.wrapper}(this.ref, _p, _b);`);
+      } else {
+        out.push(`          return new ${w.wrapper}(this.ref, _p, 0);`);
+      }
       out.push(`        }, enumerable: true, configurable: true,`);
       out.push(`      });`);
     }
@@ -5092,9 +5307,20 @@ function emitNavDts(model) {
   if (needsEntityRef) out.push('import type { EntityRef } from "@s2script/sdk/entity";');
   out.push("");
   for (const w of model.wrappers) {
+    if (w.fields.some((f) => f.navWritable)) {
+      out.push(`/**`);
+      out.push(` * Fields NOT marked \`readonly\` are writable.`);
+      out.push(` *`);
+      out.push(` * A write takes effect immediately \u2014 the server reads these during movement \u2014 but it is **not**`);
+      out.push(` * flagged for replication, because this object is reached through a pointer chain and the`);
+      out.push(` * change-notifier addresses the root entity. A client predicting the old value may therefore`);
+      out.push(` * see brief mismatch until the next authoritative correction. SourceMod's \`SetEntPropFloat\``);
+      out.push(` * on the same fields behaves the same way.`);
+      out.push(` */`);
+    }
     out.push(`export interface ${w.wrapper} {`);
     for (const f of w.fields) {
-      out.push(`  readonly ${f.propName}: ${TSTYPE[f.accessorKind]};`);
+      out.push(`  ${f.navWritable ? "" : "readonly "}${f.propName}: ${TSTYPE[f.accessorKind]};`);
     }
     out.push("}", "");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "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",
@@ -30,7 +30,8 @@
     "*.d.ts",
     "README.md",
     "LICENSE-MIT",
-    "LICENSE-APACHE"
+    "LICENSE-APACHE",
+    "contracts"
   ],
   "exports": {
     "./admin": {
@@ -120,13 +121,19 @@
     "./usermessages": {
       "types": "./usermessages.d.ts"
     },
+    "./voice": {
+      "types": "./voice.d.ts"
+    },
     "./votes": {
       "types": "./votes.d.ts"
     },
     "./ws": {
       "types": "./ws.d.ts"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./contracts/workshop": {
+      "types": "./contracts/workshop.d.ts"
+    }
   },
   "repository": {
     "type": "git",

package/server.d.ts

@@ -35,6 +35,28 @@ export declare const Server: {
     min?: number;
     max?: number;
   }): boolean;
+  /**
+   * Watch a cvar for changes (SourceMod `HookConVarChange`, ModSharp's cvar change hook).
+   *
+   * `name` is a cvar name, or `"*"` for every cvar. The handler receives the cvar's name and its
+   * new and old values as strings — for `"*"` the name tells you which one moved.
+   *
+   * NOTIFY-only: the engine's global change callback runs **after** the value has been applied, so
+   * a handler cannot veto a change; returning anything is ignored. A handler that throws is logged
+   * and contained, and the remaining handlers still run.
+   *
+   * Subscriptions are ledgered — unload removes them whether or not `dispose()` is called.
+   *
+   * @example
+   * import { Server } from "@s2script/sdk/server";
+   * Server.onCvarChange("mp_friendlyfire", (name, next, prev) => {
+   *   console.log(`${name}: ${prev} -> ${next}`);
+   * });
+   */
+  onCvarChange(
+    name: string,
+    handler: (name: string, newValue: string, oldValue: string) => void,
+  ): { dispose(): void };
   /** The server's configured max client count (`GetMaxClients()`). `0` if unavailable. */
   readonly maxPlayers: number;
   /** The current map name (`GetMapName()`, the BSP). `""` if unavailable. */

package/timers.d.ts

@@ -20,3 +20,42 @@ export declare function nextFrame(): Promise<void>;
  * Only valid inside a threadSleep-capable fiber context.
  */
 export declare function threadSleep(ms: number): void;
+
+/**
+ * A live callback timer, returned by {@link after} and {@link every}. Ledgered against the creating
+ * plugin: unload kills it whether or not `kill()` was called, so a repeating timer can never outlive
+ * its plugin and fire into a dead context.
+ */
+export interface Timer {
+  /** False once the timer has fired (one-shot), been killed, or had its plugin unloaded. */
+  readonly alive: boolean;
+  /** Cancel it. Idempotent — returns false if it was already dead. Safe to call from inside the callback. */
+  kill(): boolean;
+}
+
+/**
+ * Run `fn` once after `ms` milliseconds (SourceMod `CreateTimer` without `TIMER_REPEAT`).
+ *
+ * Prefer {@link delay} when you can `await`; use this when you need something cancellable.
+ * A throwing callback is reported and contained — it never kills the frame or the timer system.
+ *
+ * @example
+ * import { after } from "@s2script/sdk/timers";
+ * const t = after(5000, () => console.log("5s later"));
+ * t.kill();   // ...unless cancelled first
+ */
+export declare function after(ms: number, fn: () => void): Timer;
+
+/**
+ * Run `fn` every `ms` milliseconds until killed (SourceMod `CreateTimer` with `TIMER_REPEAT`).
+ *
+ * The next firing is scheduled *after* the callback returns, so a slow callback cannot pile up.
+ * `ms` must be greater than 0 — a zero-interval repeat would re-arm every drain and starve the
+ * frame, so it throws rather than degrading.
+ *
+ * @example
+ * import { every } from "@s2script/sdk/timers";
+ * const tick = every(1000, () => console.log("tick"));
+ * // later: tick.kill();
+ */
+export declare function every(ms: number, fn: () => void): Timer;

package/unsafe.d.ts

@@ -14,6 +14,15 @@
  */
 export interface EngineCalls {}
 
+/**
+ * Plugin-declared engine calls, resolved from this plugin's own gamedata.
+ *
+ * @example
+ * import { Engine } from "@s2script/sdk/unsafe";
+ * // Resolve ONCE at load — null means the descriptor failed a load-time gate.
+ * const ignite = Engine.call("ignite");
+ * if (!ignite) console.log(`unavailable: ${Engine.status("ignite")}`);
+ */
 export declare const Engine: {
   /**
    * The declared call, or `null` when its descriptor failed a load-time gate (signature miss,

package/voice.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @s2script/sdk/voice — who can hear whom. NO runtime code: the engine injects the implementation
+ * at load (`__s2pkg_voice`).
+ *
+ * Layered UNDER `Client.voiceMuted`: a muted sender is inaudible to everyone regardless of any rule
+ * here, so admin moderation always beats a gameplay rule.
+ *
+ * Rules are declarative state, not a callback. The engine's listen matrix is re-asserted
+ * continuously and the underlying hook fires per (receiver, sender) pair, so a per-pair JS callback
+ * would run up to 64x64 times per refresh. Set a rule; the shim enforces it.
+ */
+
+/** Hot-path measurement counters returned by {@link Voice.stats}. */
+export interface VoiceStats {
+  /** Listen-matrix decisions the engine has asked about. */
+  calls: number;
+  /** Senders currently carrying a merged rule. */
+  entries: number;
+  /** Times a rule actually silenced a pair. THE effect counter — a rule that never rewrites is not working. */
+  rewrites: number;
+}
+
+/**
+ * Per-(receiver, sender) voice hearability.
+ *
+ * @example
+ * import { Voice } from "@s2script/sdk/voice";
+ * // A dead player is heard only by other dead players.
+ * Voice.setAudibleTo(deadSlot, otherDeadSlots);
+ * // ...and on respawn, hand the slot back to the engine.
+ * Voice.reset(deadSlot);
+ */
+export declare const Voice: {
+  /**
+   * This sender is audible ONLY to `receivers` (0-based slots). An empty array means audible to
+   * nobody — distinct from {@link Voice.reset}, which removes the rule and lets the engine decide.
+   * Rules from multiple plugins AND-merge, so another plugin can only ever narrow yours, never widen it.
+   *
+   * A rule is dropped automatically when the sender disconnects: slots are recycled, and a rule is
+   * about the player who occupied one, not the seat.
+   *
+   * Returns `false` — never throws — when the rule was NOT applied: voice control is degraded or its
+   * engine hook never installed on this build, `sender` is outside `[0, 64)`, or any element of
+   * `receivers` is. Note this differs from {@link import("./transmit").Transmit.setVisibleTo}, which
+   * throws `RangeError` on a bad slot; check the return value here rather than relying on a throw.
+   *
+   * @throws `TypeError` if `receivers` is not an array.
+   */
+  setAudibleTo(sender: number, receivers: readonly number[]): boolean;
+  /**
+   * Drop THIS plugin's rule for `sender`; other plugins' rules survive and are re-merged.
+   * `false` when you had no rule for that sender.
+   */
+  reset(sender: number): boolean;
+  /** Drop every rule this plugin owns. Unload does this automatically. */
+  resetAll(): void;
+  /** Hot-path counters, or null when the running shim predates this capability. */
+  stats(): VoiceStats | null;
+};