@defold-typescript/types 0.52.0 → 0.53.0

package/src/api-identity.ts

@@ -1,6 +1,7 @@
 import type { ApiFunction, ApiModule, ApiParameter } from "./api-doc";
 import { DEFOLD_TYPE_MAP } from "./core-types";
 import { pinMatches } from "./correction-pins";
+import { engineTypeName } from "./engine-type-name";
 import { splitTopLevel } from "./luals-type-expr";
 
 /**
@@ -32,7 +33,7 @@ export interface IdentityCorrections {
   readonly parameterCorrections: Readonly<Record<string, IdentityCorrection>>;
   /** Keyed by element. */
   readonly returnCorrections: Readonly<Record<string, IdentityCorrection>>;
-  /** Constant-family aliases a correction may name (`window.DimModeStateSettable`), with members. */
+  /** Constant-family aliases a correction may name (`graphics.BLEND_FACTOR`), with members. */
   readonly constantFamilies: Readonly<Record<string, readonly string[]>>;
 }
 
@@ -117,6 +118,32 @@ const NUMERIC_LITERAL = /^-?\d+(\.\d+)?$/;
 const STRING_LITERAL = /^(".*"|'.*')$/;
 // The TypeScript table types a correction writes.
 const TS_TABLE = /^(Record|LuaMap|ReadonlyLuaMap|LuaTable)\b/;
+// A subset of a constant union a correction writes, which is still that union's value.
+const EXCLUDE = /^Exclude<([\w.]+),.*>$/;
+
+const REFERENCE_TYPE_PATHS = new WeakMap<IdentityVocabulary, ReadonlyMap<string, string>>();
+
+// The reference name a correction's TypeScript type path was derived from
+// (`gui.Anchor` -> `gui.ANCHOR`), so renaming a type re-keys no identity.
+function referenceTypePath(path: string, vocabulary: IdentityVocabulary): string {
+  let paths = REFERENCE_TYPE_PATHS.get(vocabulary);
+  if (paths === undefined) {
+    const built = new Map<string, string>();
+    for (const name of [
+      ...Object.keys(vocabulary.enums),
+      ...vocabulary.tables,
+      ...Object.keys(vocabulary.aliases),
+    ]) {
+      const dot = name.lastIndexOf(".");
+      if (dot < 0) continue;
+      const renamed = `${name.slice(0, dot + 1)}${engineTypeName(name.slice(dot + 1))}`;
+      if (renamed !== name) built.set(renamed, name);
+    }
+    paths = built;
+    REFERENCE_TYPE_PATHS.set(vocabulary, paths);
+  }
+  return paths.get(path) ?? path;
+}
 
 function canonicalLeaves(
   token: string,
@@ -136,6 +163,10 @@ function canonicalLeaves(
   if (trimmed.startsWith("typeof ")) {
     return canonicalLeaves(trimmed.slice("typeof ".length), vocabulary, expanding);
   }
+  const excluded = EXCLUDE.exec(trimmed);
+  if (excluded !== null) return canonicalLeaves(excluded[1] as string, vocabulary, expanding);
+  const reference = referenceTypePath(trimmed, vocabulary);
+  if (reference !== trimmed) return canonicalLeaves(reference, vocabulary, expanding);
   if (trimmed === "nil" || trimmed === "undefined") return ["nil"];
   // Every table shape — a bare or typed `table`, a list, an inline record, a
   // struct, a built-in message payload — is one Lua table at runtime; its

package/src/component-properties.d.ts

@@ -8,7 +8,7 @@ import type { Hash, Vector3 } from "./core-types";
 // evidence. A key the engine reads but never writes is `readonly`.
 declare global {
   namespace go {
-    interface properties {
+    interface Properties {
       /** The position's x component. `gameobject.cpp:GetProperty` reads one float. */
       "position.x": number;
       /** The position's y component. `gameobject.cpp:GetProperty` reads one float. */
@@ -45,7 +45,7 @@ declare global {
   }
 
   namespace label {
-    interface properties {
+    interface Properties {
       /** The scale's x component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
       "scale.x": number;
       /** The scale's y component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
@@ -100,7 +100,7 @@ declare global {
   }
 
   namespace sprite {
-    interface properties {
+    interface Properties {
       /** The scale's x component. `comp_sprite.cpp` and `comp_private.cpp` read and write one float. */
       "scale.x": number;
       /** The scale's y component. `comp_sprite.cpp` and `comp_private.cpp` read and write one float. */
@@ -146,7 +146,7 @@ declare global {
   }
 
   namespace model {
-    interface properties {
+    interface Properties {
       /**
        * The material resource the model renders with.
        * `comp_model.cpp:CompModelGetProperty` and `CompModelSetProperty` read
@@ -162,7 +162,7 @@ declare global {
   }
 
   namespace physics {
-    interface properties {
+    interface Properties {
       /**
        * Whether the body runs continuous collision detection as a fast-moving
        * bullet. Box2D only: `comp_collision_object_box2d.cpp` reads and writes
@@ -176,7 +176,7 @@ declare global {
     /**
      * Factory component properties. Upstream's factory reference declares none.
      */
-    interface properties {
+    interface Properties {
       /**
        * The path hash of the prototype the factory spawns. Read-only:
        * `comp_factory.cpp:CompFactoryGetProperty` reads it and the component
@@ -191,7 +191,7 @@ declare global {
      * Collection factory component properties. Upstream's collectionfactory
      * reference declares none.
      */
-    interface properties {
+    interface Properties {
       /**
        * The path hash of the collection prototype the factory spawns.
        * Read-only: `comp_collection_factory.cpp:CompCollectionFactoryGetProperty`
@@ -207,7 +207,7 @@ declare global {
    * `CompMeshSetProperty` handle.
    */
   namespace mesh {
-    interface properties {
+    interface Properties {
       /**
        * The buffer resource holding the mesh's vertex data.
        * `resource.get_buffer` and `resource.set_buffer` read it with

package/src/core-types.ts

@@ -198,8 +198,9 @@ declare const OpaqueBrand: unique symbol;
  * - GUI & rendering: `Opaque<"node">`, `Opaque<"texture">`,
  *   `Opaque<"render_target">`, `Opaque<"constant">`, `Opaque<"constant_buffer">`
  * - Buffers: `Opaque<"buffer">`, `Opaque<"bufferstream">`
- * - Sockets: `Opaque<"client">`, `Opaque<"server">`, `Opaque<"master">`,
- *   `Opaque<"connected">`, `Opaque<"unconnected">`
+ * - Sockets are not brands: `socket.socket_client`, `socket.socket_server`,
+ *   `socket.socket_master`, `socket.socket_connected` and
+ *   `socket.socket_unconnected` are interfaces carrying each handle's methods
  * - Box2D physics: `Opaque<"b2Body">`, `Opaque<"b2World">`
  * - Generic: `Opaque<"userdata">`
  *
@@ -248,6 +249,21 @@ export interface Url {
   set fragment(value: Hash | string | undefined);
 }
 
+// The receiver of each socket handle's colon methods (`client:send`) and the one
+// name its method-bearing interface takes inside `namespace socket` on every
+// target: the PascalCase name of the 1.13.2 TYPEDEF (`socket_client`). Older
+// references name the TYPEDEF after the receiver, so both spellings resolve to
+// the same interface.
+export const SOCKET_HANDLE_NAMES = {
+  client: "SocketClient",
+  connected: "SocketConnected",
+  master: "SocketMaster",
+  server: "SocketServer",
+  unconnected: "SocketUnconnected",
+} as const;
+
+export type SocketHandleReceiver = keyof typeof SOCKET_HANDLE_NAMES;
+
 const BUFFER_TYPE = 'Opaque<"buffer"> & { length: LuaLengthMethod<number> }';
 const BUFFERSTREAM_TYPE =
   'Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }';
@@ -301,14 +317,14 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   btRigidBody: 'Opaque<"btRigidBody">',
   b2BodyType:
     '(number & { readonly __brand: "b2d.body.B2_DYNAMIC_BODY" }) | (number & { readonly __brand: "b2d.body.B2_KINEMATIC_BODY" }) | (number & { readonly __brand: "b2d.body.B2_STATIC_BODY" })',
-  // socket handle types resolve to the method-bearing `interface <receiver>`
+  // socket handle types resolve to the method-bearing `interface Socket<Receiver>`
   // emitted inside `namespace socket`, not opaque brands — the documented
   // colon methods (`client:send`, …) make each handle structurally distinct.
-  client: "client",
-  connected: "connected",
-  master: "master",
-  server: "server",
-  unconnected: "unconnected",
+  client: SOCKET_HANDLE_NAMES.client,
+  connected: SOCKET_HANDLE_NAMES.connected,
+  master: SOCKET_HANDLE_NAMES.master,
+  server: SOCKET_HANDLE_NAMES.server,
+  unconnected: SOCKET_HANDLE_NAMES.unconnected,
   any: "unknown",
   // 1.13.2 renames of the leaves above, same slots. Upstream declares each only as
   // a `userdata`/`number` handle TYPEDEF, so each keeps its 1.13.1 mapping, with
@@ -323,9 +339,9 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   resource_data: "Hash",
   timer_handle: "number",
   render_predicate: 'Opaque<"render_predicate">',
-  socket_client: "client",
-  socket_connected: "connected",
-  socket_master: "master",
-  socket_server: "server",
-  socket_unconnected: "unconnected",
+  socket_client: SOCKET_HANDLE_NAMES.client,
+  socket_connected: SOCKET_HANDLE_NAMES.connected,
+  socket_master: SOCKET_HANDLE_NAMES.master,
+  socket_server: SOCKET_HANDLE_NAMES.server,
+  socket_unconnected: SOCKET_HANDLE_NAMES.unconnected,
 } as const;

package/src/doc-corrections.ts

@@ -94,6 +94,15 @@ export const DOC_CORRECTIONS: ReadonlyMap<string, DocCorrection> = new Map([
       html: "The scale of the label. <code>go.get</code> returns and <code>go.set</code> takes a vector3; <code>go.animate</code> also takes a number, which sets a uniform scale.",
     },
   ],
+  [
+    "model#property:textureN",
+    {
+      upstreamHash: "d6b885cb54de309f",
+      reason:
+        "the engine handles texture units 0-15 on 1.12.4 and later (render.h `MAX_TEXTURE_COUNT = 16`), while upstream's 0-7 holds on 1.11.0 and earlier, so the text names no range",
+      html: "The texture hash id of the model, read and written on the texture unit the key's number names (<code>texture3</code> is unit 3).",
+    },
+  ],
   [
     "buffer.get_bytes#brief",
     {