@defold-typescript/types 0.39.0 → 0.40.0

package/generated/vmath.d.ts

@@ -49,7 +49,7 @@ declare global {
     function conj(q1: Quaternion): Quaternion;
     /**
      * Given two linearly independent vectors P and Q, the cross product,
-     * P × Q, is a vector that is perpendicular to both P and Q and
+     * P × Q, is a vector that is perpendicular to both P and Q and
      * therefore normal to the plane containing them.
      * If the two vectors have the same direction (or have the exact
      * opposite direction from one another, i.e. are not linearly independent)
@@ -70,8 +70,8 @@ declare global {
     function cross(v1: Vector3, v2: Vector3): Vector3;
     /**
      * The returned value is a scalar defined as:
-     * `P ⋅ Q = |P| |Q| cos θ`
-     * where θ is the angle between the vectors P and Q.
+     * `P ⋅ Q = |P| |Q| cos θ`
+     * where θ is the angle between the vectors P and Q.
      *
      * - If the dot product is positive then the angle between the vectors is below 90 degrees.
      *
@@ -437,8 +437,8 @@ declare global {
     /**
      * Calculates the extent the projection of the first vector onto the second.
      * The returned value is a scalar p defined as:
-     * `p = |P| cos θ / |Q|`
-     * where θ is the angle between the vectors P and Q.
+     * `p = |P| cos θ / |Q|`
+     * where θ is the angle between the vectors P and Q.
      *
      * @param v1 - vector to be projected on the second
      * @param v2 - vector onto which the first will be projected, must not have zero length

package/index.d.ts

@@ -25,6 +25,7 @@ import "./generated/factory";
 import "./generated/font";
 import "./generated/go";
 import "./src/go-overloads";
+import "./src/component-properties";
 import "./generated/graphics";
 import "./generated/gui";
 import "./generated/html5";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {

package/scripts/generate-api-signatures.ts

@@ -14,7 +14,8 @@ const PACKAGE_ROOT = resolve(import.meta.dir, "..");
 const SIGNATURES_PATH = resolve(PACKAGE_ROOT, "api-signatures.json");
 
 export interface SignaturesArtifact {
-  // version -> symbolIdentityKey -> authoritative TS signature text
+  // version -> symbolIdentityKey -> authoritative TS signature text; a symbol
+  // with several declared arms carries one arm per line, primary first
   readonly versions: Record<string, Record<string, string>>;
   // The same axis and keys, carrying each documented slot's rendered type. Kept
   // parallel rather than folded into `versions` because three consumers

package/scripts/prose-constants.ts

@@ -0,0 +1,96 @@
+import type { ModuleManifestEntry } from "./regen";
+
+// A constant family the engine registers and one function's parameter prose
+// lists, but no ref-doc element declares. Each release's own list is the
+// evidence, so a surface declares exactly the members its release documents.
+interface ProseConstantFamily {
+  readonly namespace: string;
+  readonly prefix: string;
+  readonly describes: string;
+  readonly evidence: {
+    readonly namespace: string;
+    readonly function: string;
+    readonly parameter: string;
+  };
+}
+
+const PROSE_CONSTANT_FAMILIES: readonly ProseConstantFamily[] = [
+  {
+    namespace: "graphics",
+    prefix: "SEMANTIC_TYPE_",
+    describes: "Vertex attribute semantic type",
+    evidence: {
+      namespace: "material",
+      function: "material.set_vertex_attributes",
+      parameter: "attributes",
+    },
+  },
+];
+
+interface DocElement {
+  readonly type: string;
+  readonly name: string;
+  readonly parameters?: readonly { readonly name: string; readonly doc?: string }[];
+}
+
+interface ApiDoc {
+  readonly elements: readonly DocElement[];
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function evidencedNames(family: ProseConstantFamily, modules: readonly ModuleManifestEntry[]) {
+  const source = modules.find((m) => m.namespace === family.evidence.namespace);
+  if (!source) return [];
+  const fn = (source.doc as ApiDoc).elements.find(
+    (e) => e.type === "FUNCTION" && e.name === family.evidence.function,
+  );
+  const prose = fn?.parameters?.find((p) => p.name === family.evidence.parameter)?.doc ?? "";
+  const item = new RegExp(
+    `<li><code>(${escapeRegExp(`${family.namespace}.${family.prefix}`)}\\w+)</code></li>`,
+    "g",
+  );
+  return [...new Set(Array.from(prose.matchAll(item), (m) => m[1] as string))];
+}
+
+function constantElement(name: string, brief: string) {
+  return {
+    type: "CONSTANT",
+    name,
+    brief,
+    description: "",
+    returnvalues: [],
+    parameters: [],
+    examples: "",
+    replaces: "",
+    error: "",
+    tparams: [],
+    members: [],
+    notes: [],
+    language: "",
+  };
+}
+
+export function synthesizeProseConstants(
+  modules: readonly ModuleManifestEntry[],
+): ModuleManifestEntry[] {
+  let out = [...modules];
+  for (const family of PROSE_CONSTANT_FAMILIES) {
+    const names = evidencedNames(family, out);
+    if (names.length === 0) continue;
+    const index = out.findIndex((m) => m.namespace === family.namespace);
+    const target = out[index];
+    if (!target) continue;
+    const doc = target.doc as ApiDoc;
+    const declared = new Set(doc.elements.map((e) => e.name));
+    const brief = `${family.describes}, for \`${family.evidence.function}\`.`;
+    const added = names.filter((n) => !declared.has(n)).map((n) => constantElement(n, brief));
+    if (added.length === 0) continue;
+    out = out.map((m, i) =>
+      i === index ? { ...m, doc: { ...doc, elements: [...doc.elements, ...added] } } : m,
+    );
+  }
+  return out;
+}

package/scripts/regen.ts

@@ -26,6 +26,7 @@ import {
   resolveRefDoc,
 } from "./doc-source";
 import { loadTranslations } from "./example-store-io";
+import { synthesizeProseConstants } from "./prose-constants";
 import { type readZip, SYNC_MANIFEST, type SyncManifestEntry } from "./sync-api-docs";
 
 export interface ApiTargetModule {
@@ -99,7 +100,7 @@ export function loadTargetModules(
   target: ApiTarget,
   packageRoot: string = PACKAGE_ROOT,
 ): ModuleManifestEntry[] {
-  return target.modules.map((module) => {
+  const modules = target.modules.map((module) => {
     const path = resolve(packageRoot, target.fixturesDir, module.fixture);
     let raw: string;
     try {
@@ -117,6 +118,7 @@ export function loadTargetModules(
     };
     return module.skipFunctions ? { ...entry, skipFunctions: module.skipFunctions } : entry;
   });
+  return synthesizeProseConstants(modules);
 }
 
 export interface ModuleManifestEntry {
@@ -168,7 +170,7 @@ export async function resolveTargetModules(
     ...(opts.fetchChannelInfo ? { fetchChannelInfo: opts.fetchChannelInfo } : {}),
   });
   const syncManifest = opts.syncManifest ?? SYNC_MANIFEST;
-  return target.modules.map((module) => {
+  const modules = target.modules.map((module) => {
     const sync = syncManifest.find((s) => s.namespace === module.namespace);
     if (!sync) {
       throw new Error(
@@ -184,6 +186,7 @@ export async function resolveTargetModules(
     };
     return module.skipFunctions ? { ...entry, skipFunctions: module.skipFunctions } : entry;
   });
+  return synthesizeProseConstants(modules);
 }
 
 const API_TARGETS = loadApiTargets();
@@ -556,6 +559,7 @@ const UNIVERSAL_EXTRA_IMPORTS: readonly UniversalExtraImport[] = [
   { specifier: "../../src/window-event-guard" },
   { specifier: "../../src/scene-addresses" },
   { specifier: "../../src/go-overloads" },
+  { specifier: "../../src/component-properties" },
   { specifier: "../../src/render-overloads", restrictedTo: "render" },
   { specifier: "../../src/vmath-overloads" },
 ];

package/src/component-properties.d.ts

@@ -0,0 +1,33 @@
+/** @noSelfInFile */
+
+import type { Hash } from "./core-types";
+
+// Component property keys upstream examples read through `go.get` while no
+// ref-doc catalog declares them. Only evidenced keys belong here.
+declare global {
+  namespace sprite {
+    interface properties {
+      /**
+       * The texture bound to the sprite's first sampler. Not in the sprite
+       * ref-doc; `resource.set`'s example reads it with
+       * `go.get("#sprite", "texture0")`.
+       */
+      texture0: Hash;
+    }
+  }
+
+  /**
+   * Mesh component properties. Upstream ships no mesh API module, so this
+   * catalog holds only the keys upstream examples read.
+   */
+  namespace mesh {
+    interface properties {
+      /**
+       * The buffer resource holding the mesh's vertex data.
+       * `resource.get_buffer` and `resource.set_buffer` read it with
+       * `go.get("#mesh", "vertices")`.
+       */
+      vertices: Hash;
+    }
+  }
+}

package/src/core-types.ts

@@ -214,9 +214,11 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   texture: 'Opaque<"texture">',
   render_target: 'Opaque<"render_target">',
   constant: 'Opaque<"constant">',
-  constant_buffer: 'Opaque<"constant_buffer">',
+  constant_buffer:
+    'Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | Matrix4[] }',
   buffer: 'Opaque<"buffer">',
-  bufferstream: 'Opaque<"bufferstream"> & { [index: number]: number }',
+  bufferstream:
+    'Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }',
   userdata: 'Opaque<"userdata">',
   // Vocabulary, not a shipped brand: no current ref-doc fixture types a slot
   // `resource`, so nothing hand-written may name `Opaque<"resource">`. Kept so a

package/src/custom-messages.d.ts

@@ -41,14 +41,15 @@ declare global {
   // diagnostic at the call site rather than the declaration.
   /**
    * The payload declared for a message id: its `BuiltinMessages` entry, else
-   * its `CustomMessages` entry, else the open record an undeclared id keeps.
-   * An id declared in both resolves to the built-in payload.
+   * its `CustomMessages` entry, else the open table an undeclared id keeps: a
+   * record or a Lua sequence. An id declared in both resolves to the built-in
+   * payload.
    */
   type MessagePayload<K> = K extends BuiltinMessageId
     ? BuiltinMessages[K]
     : K extends keyof CustomMessages
       ? CustomMessages[K]
-      : Record<string | number, unknown>;
+      : Record<string | number, unknown> | readonly unknown[];
 }
 
 export {};

package/src/doc-comment.ts

@@ -1,19 +1,42 @@
 const NAMED_ENTITIES: Record<string, string> = {
-  "&lt;": "<",
-  "&gt;": ">",
-  "&quot;": '"',
-  "&#39;": "'",
-  "&apos;": "'",
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  // A non-breaking space in JSDoc is invisible noise; a plain space reads the same.
+  nbsp: " ",
+  times: "×",
+  copy: "©",
+  mdash: "—",
+  ndash: "–",
+  hellip: "…",
+  middot: "·",
+  deg: "°",
+  plusmn: "±",
+  le: "≤",
+  ge: "≥",
+  ne: "≠",
+  rarr: "→",
+  larr: "←",
+  lsquo: "‘",
+  rsquo: "’",
+  ldquo: "“",
+  rdquo: "”",
 };
 
+// One pass over the text, so a character an entity decodes to (`&amp;` -> `&`)
+// is never read as the start of another entity.
 function decodeEntities(text: string): string {
-  let out = text;
-  for (const [entity, char] of Object.entries(NAMED_ENTITIES)) {
-    out = out.split(entity).join(char);
-  }
-  out = out.replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code)));
-  // `&amp;` last so an already-decoded `&` is never re-interpreted.
-  return out.split("&amp;").join("&");
+  return text.replace(/&(?:#[xX]([0-9a-fA-F]+)|#(\d+)|([a-zA-Z]+));/g, (entity, hex, dec, name) => {
+    if (hex !== undefined) return codePointOr(Number.parseInt(hex, 16), entity);
+    if (dec !== undefined) return codePointOr(Number(dec), entity);
+    return Object.hasOwn(NAMED_ENTITIES, name) ? (NAMED_ENTITIES[name] ?? entity) : entity;
+  });
+}
+
+function codePointOr(code: number, fallback: string): string {
+  return code <= 0x10ffff ? String.fromCodePoint(code) : fallback;
 }
 
 /**