@defold-typescript/types 0.35.0 → 0.36.0

package/examples/translations.json

@@ -206,7 +206,7 @@
   "factory.create": [
     {
       "sourceHash": "d2cd2037a9127ec6",
-      "ts": "// How to create a new game object:\nexport default defineScript({\n  init(self) {\n    // create a new game object and provide property values\n    self.my_created_object = factory.create(\"#factory\", undefined, undefined, { my_value: 1 });\n    // communicate with the object\n    msg.post(self.my_created_object, \"hello\");\n  },\n});\n\n// And then let the new game object have a script attached:\ngo.property(\"my_value\", 0);\n\nexport default defineScript({\n  init(self) {\n    // do something with self.my_value which is now one\n  },\n});"
+      "ts": "// How to create a new game object:\nexport default defineScript({\n  init(self) {\n    // create a new game object and provide property values\n    const created = factory.create(\"#factory\", undefined, undefined, { my_value: 1 });\n    // communicate with the object\n    msg.post(created, \"hello\");\n  },\n});\n\n// And then let the new game object have a script attached, in its own file:\n//\n//   go.property(\"my_value\", 0);\n//\n//   export default defineScript({\n//     init(self) {\n//       // do something with self.my_value which is now one\n//     },\n//   });"
     }
   ],
   "factory.load": [
@@ -320,7 +320,7 @@
   "go.get_world_position": [
     {
       "sourceHash": "ab804a5cdcfd4f7d",
-      "ts": "// Get the world position of the game object the script is attached to:\nconst p = go.get_world_position();\n\n// Reach a sibling game object by its id \u2014 relative addressing, no socket prefix:\nconst p2 = go.get_world_position(\"x\");"
+      "ts": "// Get the world position of the game object the script is attached to:\nconst p = go.get_world_position();\n\n// Reach a sibling game object by its id — relative addressing, no socket prefix:\nconst p2 = go.get_world_position(\"x\");"
     }
   ],
   "go.get_world_rotation": [
@@ -368,7 +368,7 @@
   "go.set_position": [
     {
       "sourceHash": "ad83d0274d776e8f",
-      "ts": "// `p` is the desired position (a Vector3).\nconst p = vmath.vector3();\n\n// Set the position of the game object the script is attached to:\ngo.set_position(p);\n\n// Reach a sibling game object by its id \u2014 relative addressing, no socket prefix:\ngo.set_position(p, \"x\");"
+      "ts": "// `p` is the desired position (a Vector3).\nconst p = vmath.vector3();\n\n// Set the position of the game object the script is attached to:\ngo.set_position(p);\n\n// Reach a sibling game object by its id — relative addressing, no socket prefix:\ngo.set_position(p, \"x\");"
     }
   ],
   "go.set_rotation": [
@@ -770,7 +770,7 @@
   "on_message": [
     {
       "sourceHash": "bfed6bd72e3242e2",
-      "ts": "// This example demonstrates how a game object instance, called \"a\", can communicate with another instance, called \"b\". It\n// is assumed that both script components of the instances has id \"script\".\n\n// a.script \u2014 Script of instance \"a\":\nexport default defineScript({\n  init() {\n    // let b know about some important data\n    msg.post(\"b#script\", \"my_data\", { important_value: 1 });\n  },\n});\n\n// b.script \u2014 Script of instance \"b\":\nexport default defineScript({\n  init() {\n    // store the url of instance \"a\" for later use, by specifying undefined as socket we\n    // automatically use our own socket\n    return { a_url: msg.url(undefined, go.get_id(\"a\"), \"script\") };\n  },\n\n  on_message(self, message_id, message, sender) {\n    // check message and sender\n    if (message_id === hash(\"my_data\") && sender === self.a_url) {\n      // use the data in some way\n      self.important_value = message.important_value;\n    }\n  },\n});"
+      "ts": "// This example demonstrates how a game object instance, called \"a\", can communicate with another instance, called \"b\". It\n// is assumed that both script components of the instances has id \"script\".\n\n// a.script — Script of instance \"a\":\nexport default defineScript({\n  init() {\n    // let b know about some important data\n    msg.post(\"b#script\", \"my_data\", { important_value: 1 });\n  },\n});\n\n// b.script — Script of instance \"b\":\nexport default defineScript({\n  init() {\n    // store the url of instance \"a\" for later use, by specifying undefined as socket we\n    // automatically use our own socket\n    return { a_url: msg.url(undefined, go.get_id(\"a\"), \"script\") };\n  },\n\n  on_message(self, message_id, message, sender) {\n    // check message and sender\n    if (message_id === hash(\"my_data\") && sender === self.a_url) {\n      // use the data in some way\n      self.important_value = message.important_value;\n    }\n  },\n});"
     }
   ],
   "on_reload": [
@@ -928,7 +928,7 @@
   "render.clear": [
     {
       "sourceHash": "70406f065fc91216",
-      "ts": "// Clear the color buffer and the depth buffer.\nrender.clear({\n  [graphics.BUFFER_TYPE_COLOR0_BIT]: vmath.vector4(0, 0, 0, 0),\n  [graphics.BUFFER_TYPE_DEPTH_BIT]: 1,\n});"
+      "ts": "// Clear the color buffer and the depth buffer.\nconst buffers = new LuaMap<render.ClearBufferKey, number | Vector4>();\nbuffers.set(graphics.BUFFER_TYPE_COLOR0_BIT, vmath.vector4(0, 0, 0, 0));\nbuffers.set(graphics.BUFFER_TYPE_DEPTH_BIT, 1);\nrender.clear(buffers);"
     }
   ],
   "render.constant_buffer": [
@@ -1978,7 +1978,7 @@
   "zlib.inflate": [
     {
       "sourceHash": "6b8b8cc6d9afe679",
-      "ts": "const data = \"\\120\\94\\11\\201\\200\\44\\86\\0\\162\\68\\133\\226\\146\\162\\204\\188\\116\\133\\242\\204\\146\\12\\133\\210\\188\\228\\252\\220\\130\\162\\212\\226\\226\\212\\20\\133\\148\\196\\146\\68\\61\\0\\44\\67\\14\\201\";\nconst uncompressed_data = zlib.inflate(data);\nprint(uncompressed_data); //> This is a string with uncompressed data."
+      "ts": "const data =\n  \"\\x78\\x5e\\x0b\\xc9\\xc8\\x2c\\x56\\x00\\xa2\\x44\\x85\\xe2\\x92\\xa2\\xcc\\xbc\\x74\\x85\\xf2\\xcc\\x92\\x0c\\x85\\xd2\\xbc\\xe4\\xfc\\xdc\\x82\\xa2\\xd4\\xe2\\xe2\\xd4\\x14\\x85\\x94\\xc4\\x92\\x44\\x3d\\x00\\x2c\\x43\\x0e\\xc9\";\nconst uncompressed_data = zlib.inflate(data);\nprint(uncompressed_data); //> This is a string with uncompressed data."
     }
   ]
 }

package/generated/factory.d.ts

@@ -39,20 +39,21 @@ declare global {
      * export default defineScript({
      *   init(self) {
      *     // create a new game object and provide property values
-     *     self.my_created_object = factory.create("#factory", undefined, undefined, { my_value: 1 });
+     *     const created = factory.create("#factory", undefined, undefined, { my_value: 1 });
      *     // communicate with the object
-     *     msg.post(self.my_created_object, "hello");
+     *     msg.post(created, "hello");
      *   },
      * });
      *
-     * // And then let the new game object have a script attached:
-     * go.property("my_value", 0);
-     *
-     * export default defineScript({
-     *   init(self) {
-     *     // do something with self.my_value which is now one
-     *   },
-     * });
+     * // And then let the new game object have a script attached, in its own file:
+     * //
+     * //   go.property("my_value", 0);
+     * //
+     * //   export default defineScript({
+     * //     init(self) {
+     * //       // do something with self.my_value which is now one
+     * //     },
+     * //   });
      * ```
      */
     function create(url: string | Hash | Url, position?: Vector3, rotation?: Quaternion, properties?: Record<string | number, unknown>, scale?: number | Vector3): Hash;

package/generated/render.d.ts

@@ -38,13 +38,13 @@ declare global {
      * @example
      * ```ts
      * // Clear the color buffer and the depth buffer.
-     * render.clear({
-     *   [graphics.BUFFER_TYPE_COLOR0_BIT]: vmath.vector4(0, 0, 0, 0),
-     *   [graphics.BUFFER_TYPE_DEPTH_BIT]: 1,
-     * });
+     * const buffers = new LuaMap<render.ClearBufferKey, number | Vector4>();
+     * buffers.set(graphics.BUFFER_TYPE_COLOR0_BIT, vmath.vector4(0, 0, 0, 0));
+     * buffers.set(graphics.BUFFER_TYPE_DEPTH_BIT, 1);
+     * render.clear(buffers);
      * ```
      */
-    function clear(buffers: LuaMap<number, number | Vector4>): void;
+    function clear(buffers: LuaMap<number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR0_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_DEPTH_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_STENCIL_BIT" }, number | Vector4>): void;
     /**
      * Constant buffers are used to set shader program variables and are optionally passed to the `render.draw()` function.
      * The buffer's constant elements can be indexed like an ordinary Lua table, but you can't iterate over them with pairs() or ipairs().

package/generated/versions/defold-1.12.4/factory.d.ts

@@ -39,20 +39,21 @@ declare global {
      * export default defineScript({
      *   init(self) {
      *     // create a new game object and provide property values
-     *     self.my_created_object = factory.create("#factory", undefined, undefined, { my_value: 1 });
+     *     const created = factory.create("#factory", undefined, undefined, { my_value: 1 });
      *     // communicate with the object
-     *     msg.post(self.my_created_object, "hello");
+     *     msg.post(created, "hello");
      *   },
      * });
      *
-     * // And then let the new game object have a script attached:
-     * go.property("my_value", 0);
-     *
-     * export default defineScript({
-     *   init(self) {
-     *     // do something with self.my_value which is now one
-     *   },
-     * });
+     * // And then let the new game object have a script attached, in its own file:
+     * //
+     * //   go.property("my_value", 0);
+     * //
+     * //   export default defineScript({
+     * //     init(self) {
+     * //       // do something with self.my_value which is now one
+     * //     },
+     * //   });
      * ```
      */
     function create(url: string | Hash | Url, position?: Vector3, rotation?: Quaternion, properties?: Record<string | number, unknown>, scale?: number | Vector3): Hash;

package/generated/versions/defold-1.12.4/render.d.ts

@@ -46,13 +46,13 @@ declare global {
      * @example
      * ```ts
      * // Clear the color buffer and the depth buffer.
-     * render.clear({
-     *   [graphics.BUFFER_TYPE_COLOR0_BIT]: vmath.vector4(0, 0, 0, 0),
-     *   [graphics.BUFFER_TYPE_DEPTH_BIT]: 1,
-     * });
+     * const buffers = new LuaMap<render.ClearBufferKey, number | Vector4>();
+     * buffers.set(graphics.BUFFER_TYPE_COLOR0_BIT, vmath.vector4(0, 0, 0, 0));
+     * buffers.set(graphics.BUFFER_TYPE_DEPTH_BIT, 1);
+     * render.clear(buffers);
      * ```
      */
-    function clear(buffers: LuaMap<number, number | Vector4>): void;
+    function clear(buffers: LuaMap<number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR0_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_DEPTH_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_STENCIL_BIT" }, number | Vector4>): void;
     /**
      * Constant buffers are used to set shader program variables and are optionally passed to the `render.draw()` function.
      * The buffer's constant elements can be indexed like an ordinary Lua table, but you can't iterate over them with pairs() or ipairs().

package/generated/versions/defold-1.12.4/zlib.d.ts

@@ -28,7 +28,8 @@ declare global {
      * @returns inflated buffer
      * @example
      * ```ts
-     * const data = "\120\94\11\201\200\44\86\0\162\68\133\226\146\162\204\188\116\133\242\204\146\12\133\210\188\228\252\220\130\162\212\226\226\212\20\133\148\196\146\68\61\0\44\67\14\201";
+     * const data =
+     *   "\x78\x5e\x0b\xc9\xc8\x2c\x56\x00\xa2\x44\x85\xe2\x92\xa2\xcc\xbc\x74\x85\xf2\xcc\x92\x0c\x85\xd2\xbc\xe4\xfc\xdc\x82\xa2\xd4\xe2\xe2\xd4\x14\x85\x94\xc4\x92\x44\x3d\x00\x2c\x43\x0e\xc9";
      * const uncompressed_data = zlib.inflate(data);
      * print(uncompressed_data); //> This is a string with uncompressed data.
      * ```

package/generated/versions/defold-1.13.0/factory.d.ts

@@ -39,20 +39,21 @@ declare global {
      * export default defineScript({
      *   init(self) {
      *     // create a new game object and provide property values
-     *     self.my_created_object = factory.create("#factory", undefined, undefined, { my_value: 1 });
+     *     const created = factory.create("#factory", undefined, undefined, { my_value: 1 });
      *     // communicate with the object
-     *     msg.post(self.my_created_object, "hello");
+     *     msg.post(created, "hello");
      *   },
      * });
      *
-     * // And then let the new game object have a script attached:
-     * go.property("my_value", 0);
-     *
-     * export default defineScript({
-     *   init(self) {
-     *     // do something with self.my_value which is now one
-     *   },
-     * });
+     * // And then let the new game object have a script attached, in its own file:
+     * //
+     * //   go.property("my_value", 0);
+     * //
+     * //   export default defineScript({
+     * //     init(self) {
+     * //       // do something with self.my_value which is now one
+     * //     },
+     * //   });
      * ```
      */
     function create(url: string | Hash | Url, position?: Vector3, rotation?: Quaternion, properties?: Record<string | number, unknown>, scale?: number | Vector3): Hash;

package/generated/versions/defold-1.13.0/render.d.ts

@@ -38,13 +38,13 @@ declare global {
      * @example
      * ```ts
      * // Clear the color buffer and the depth buffer.
-     * render.clear({
-     *   [graphics.BUFFER_TYPE_COLOR0_BIT]: vmath.vector4(0, 0, 0, 0),
-     *   [graphics.BUFFER_TYPE_DEPTH_BIT]: 1,
-     * });
+     * const buffers = new LuaMap<render.ClearBufferKey, number | Vector4>();
+     * buffers.set(graphics.BUFFER_TYPE_COLOR0_BIT, vmath.vector4(0, 0, 0, 0));
+     * buffers.set(graphics.BUFFER_TYPE_DEPTH_BIT, 1);
+     * render.clear(buffers);
      * ```
      */
-    function clear(buffers: LuaMap<number, number | Vector4>): void;
+    function clear(buffers: LuaMap<number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR0_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_DEPTH_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_STENCIL_BIT" }, number | Vector4>): void;
     /**
      * Constant buffers are used to set shader program variables and are optionally passed to the `render.draw()` function.
      * The buffer's constant elements can be indexed like an ordinary Lua table, but you can't iterate over them with pairs() or ipairs().

package/generated/versions/defold-1.13.0/zlib.d.ts

@@ -28,7 +28,8 @@ declare global {
      * @returns inflated buffer
      * @example
      * ```ts
-     * const data = "\120\94\11\201\200\44\86\0\162\68\133\226\146\162\204\188\116\133\242\204\146\12\133\210\188\228\252\220\130\162\212\226\226\212\20\133\148\196\146\68\61\0\44\67\14\201";
+     * const data =
+     *   "\x78\x5e\x0b\xc9\xc8\x2c\x56\x00\xa2\x44\x85\xe2\x92\xa2\xcc\xbc\x74\x85\xf2\xcc\x92\x0c\x85\xd2\xbc\xe4\xfc\xdc\x82\xa2\xd4\xe2\xe2\xd4\x14\x85\x94\xc4\x92\x44\x3d\x00\x2c\x43\x0e\xc9";
      * const uncompressed_data = zlib.inflate(data);
      * print(uncompressed_data); //> This is a string with uncompressed data.
      * ```

package/generated/zlib.d.ts

@@ -28,7 +28,8 @@ declare global {
      * @returns inflated buffer
      * @example
      * ```ts
-     * const data = "\120\94\11\201\200\44\86\0\162\68\133\226\146\162\204\188\116\133\242\204\146\12\133\210\188\228\252\220\130\162\212\226\226\212\20\133\148\196\146\68\61\0\44\67\14\201";
+     * const data =
+     *   "\x78\x5e\x0b\xc9\xc8\x2c\x56\x00\xa2\x44\x85\xe2\x92\xa2\xcc\xbc\x74\x85\xf2\xcc\x92\x0c\x85\xd2\xbc\xe4\xfc\xdc\x82\xa2\xd4\xe2\xe2\xd4\x14\x85\x94\xc4\x92\x44\x3d\x00\x2c\x43\x0e\xc9";
      * const uncompressed_data = zlib.inflate(data);
      * print(uncompressed_data); //> This is a string with uncompressed data.
      * ```

package/index.d.ts

@@ -22,6 +22,7 @@ import "./generated/collectionproxy";
 import "./generated/compute";
 import "./generated/crash";
 import "./generated/factory";
+import "./generated/font";
 import "./generated/go";
 import "./src/go-overloads";
 import "./generated/graphics";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -68,7 +68,10 @@
     "!src/**/__snapshots__",
     "!scripts/lua-types-signature-index.ts",
     "!scripts/fidelity-audit.ts",
-    "!scripts/augmentation-namespaces.ts"
+    "!scripts/augmentation-namespaces.ts",
+    "!scripts/example-pins.ts",
+    "!scripts/example-surfaces.ts",
+    "!scripts/example-typecheck.ts"
   ],
   "publishConfig": {
     "access": "public"

package/scripts/generate-api-signatures.ts

@@ -1,5 +1,6 @@
 import { resolve } from "node:path";
 import { symbolIdentityKey } from "../src/api-availability";
+import type { SlotTypes } from "../src/emit-dts";
 import { selectCompleteVersionSurfaces, versionOf } from "./generate-api-availability";
 import {
   generateModuleSignatures,
@@ -15,6 +16,11 @@ const SIGNATURES_PATH = resolve(PACKAGE_ROOT, "api-signatures.json");
 export interface SignaturesArtifact {
   // version -> symbolIdentityKey -> authoritative TS signature text
   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
+  // (`api-surface-loader`, `combined-surface`, `version-window`) type that map's
+  // value as a string; a symbol documenting no slot is absent here.
+  readonly slotTypes: Record<string, Record<string, SlotTypes>>;
 }
 
 export interface BuildSignaturesOptions {
@@ -51,9 +57,9 @@ export function withheldSymbols(entry: ModuleManifestEntry): { key: string; fqn:
   return withheld;
 }
 
-function sortObjectKeys(record: Record<string, string>): Record<string, string> {
-  const sorted: Record<string, string> = {};
-  for (const key of Object.keys(record).sort()) sorted[key] = record[key] as string;
+function sortObjectKeys<T>(record: Record<string, T>): Record<string, T> {
+  const sorted: Record<string, T> = {};
+  for (const key of Object.keys(record).sort()) sorted[key] = record[key] as T;
   return sorted;
 }
 
@@ -62,21 +68,33 @@ export function buildSignaturesArtifact(options: BuildSignaturesOptions = {}): S
   const registryPath = options.registryPath ?? resolve(packageRoot, "api-targets.json");
   const targets = selectCompleteVersionSurfaces(loadApiTargets(registryPath));
   const versions: Record<string, Record<string, string>> = {};
+  const slotTypes: Record<string, Record<string, SlotTypes>> = {};
   for (const target of targets) {
     const version = versionOf(target);
     const perSymbol: Record<string, string> = {};
+    const perSymbolSlots: Record<string, SlotTypes> = {};
     for (const entry of loadTargetModules(target, packageRoot)) {
-      for (const { identity, tsSignature } of generateModuleSignatures(entry)) {
-        perSymbol[symbolIdentityKey(identity)] = tsSignature;
+      for (const signature of generateModuleSignatures(entry)) {
+        const key = symbolIdentityKey(signature.identity);
+        perSymbol[key] = signature.tsSignature;
+        if (Object.keys(signature.slotTypes).length > 0) {
+          perSymbolSlots[key] = sortObjectKeys({ ...signature.slotTypes });
+        }
       }
+      // An authored fold replaces the declaration text wholesale, so whatever
+      // slots the generated emit had recorded no longer describe it.
       for (const { key, fqn } of withheldSymbols(entry)) {
         const authored = authoredSignature(packageRoot, entry.namespace, fqn);
-        if (authored !== null) perSymbol[key] = authored;
+        if (authored !== null) {
+          perSymbol[key] = authored;
+          delete perSymbolSlots[key];
+        }
       }
     }
     versions[version] = sortObjectKeys(perSymbol);
+    slotTypes[version] = sortObjectKeys(perSymbolSlots);
   }
-  return { versions };
+  return { versions, slotTypes };
 }
 
 function biomeFormatJson(raw: string): string {
@@ -86,7 +104,14 @@ function biomeFormatJson(raw: string): string {
   if (out.exitCode !== 0) {
     throw new Error(`biome format failed: ${out.stderr.toString()}`);
   }
-  return out.stdout.toString();
+  const formatted = out.stdout.toString();
+  // Biome exits 0 and emits nothing for input it declined to read (a payload over
+  // `files.maxSize` is reported only on stderr), which would otherwise serialize
+  // the artifact as an empty file.
+  if (formatted.length === 0) {
+    throw new Error(`biome format produced no output: ${out.stderr.toString()}`);
+  }
+  return formatted;
 }
 
 export function serializeSignaturesArtifact(artifact: SignaturesArtifact): string {