@s2script/sdk 0.10.0 → 0.10.1

package/dist/cli.js

@@ -4640,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 },
@@ -4655,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 ?? ""];
@@ -4669,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}'` };
 }
@@ -4685,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`);
@@ -4704,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;
       }
-      ownFields.push({ propName: idiomaticName(f.name), rawName: f.name, declaringClass: className, accessorKind: c2.accessorKind, writable: c2.writable, strLen: c2.strLen });
+      if ("embedded" in c2) {
+        usedEmbeds.add(c2.embedded);
+        emb.push({ propName: idiomaticName(f.name), rawName: f.name, declaringClass: owner, embeddedClass: c2.embedded });
+        continue;
+      }
+      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
@@ -4744,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} {`);
@@ -4753,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);
   }
@@ -4773,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");
@@ -4811,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);
@@ -5004,6 +5180,7 @@ function buildNavModel(config, catalog) {
       source: entry.source,
       target: entry.target,
       path: entry.path,
+      base: entry.base ?? [],
       fields,
       skippedKinds
     };
@@ -5042,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") {
@@ -5084,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(`      });`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.10.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",