@defold-typescript/types 0.51.0 → 0.53.0

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. */
@@ -44,8 +44,97 @@ declare global {
     }
   }
 
+  namespace label {
+    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. */
+      "scale.y": number;
+      /** The scale's z component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "scale.z": number;
+      /**
+       * The scale's x and y components. `comp_label.cpp` reads it through
+       * `comp_private.cpp:GetProperty`, which returns the whole vector3. `go.set`
+       * also takes a number, which it applies to both x and y, as `go`'s
+       * `"scale.xy"` does.
+       */
+      "scale.xy": Vector3;
+      /** The size's x component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "size.x": number;
+      /** The size's y component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "size.y": number;
+      /** The size's z component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "size.z": number;
+      /**
+       * The size's x and y components. `comp_label.cpp` reads it through
+       * `comp_private.cpp:GetProperty`, which returns the whole vector3. `go.set`
+       * also takes a number, which it applies to both x and y, as `go`'s
+       * `"scale.xy"` does.
+       */
+      "size.xy": Vector3;
+      /** The color's x component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "color.x": number;
+      /** The color's y component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "color.y": number;
+      /** The color's z component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "color.z": number;
+      /** The color's w component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "color.w": number;
+      /** The outline color's x component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "outline.x": number;
+      /** The outline color's y component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "outline.y": number;
+      /** The outline color's z component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "outline.z": number;
+      /** The outline color's w component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "outline.w": number;
+      /** The shadow color's x component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "shadow.x": number;
+      /** The shadow color's y component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "shadow.y": number;
+      /** The shadow color's z component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "shadow.z": number;
+      /** The shadow color's w component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
+      "shadow.w": number;
+    }
+  }
+
   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. */
+      "scale.y": number;
+      /** The scale's z component. `comp_sprite.cpp` and `comp_private.cpp` read and write one float. */
+      "scale.z": number;
+      /**
+       * The scale's x and y components. `comp_sprite.cpp` reads it through
+       * `comp_private.cpp:GetProperty`, which returns the whole vector3. `go.set`
+       * also takes a number, which it applies to both x and y, as `go`'s
+       * `"scale.xy"` does.
+       */
+      "scale.xy": Vector3;
+      /** The size's x component. `comp_sprite.cpp` and `comp_private.cpp` read and write one float. */
+      "size.x": number;
+      /** The size's y component. `comp_sprite.cpp` and `comp_private.cpp` read and write one float. */
+      "size.y": number;
+      /** The size's z component. `comp_sprite.cpp` and `comp_private.cpp` read and write one float. */
+      "size.z": number;
+      /**
+       * The size's x and y components. `comp_sprite.cpp` reads it through
+       * `comp_private.cpp:GetProperty`, which returns the whole vector3. `go.set`
+       * also takes a number, which it applies to both x and y, as `go`'s
+       * `"scale.xy"` does.
+       */
+      "size.xy": Vector3;
+      /** The slice-9 border's x component. `comp_sprite.cpp` and `comp_private.cpp` read and write one float. */
+      "slice.x": number;
+      /** The slice-9 border's y component. `comp_sprite.cpp` and `comp_private.cpp` read and write one float. */
+      "slice.y": number;
+      /** The slice-9 border's z component. `comp_sprite.cpp` and `comp_private.cpp` read and write one float. */
+      "slice.z": number;
+      /** The slice-9 border's w component. `comp_sprite.cpp` and `comp_private.cpp` read and write one float. */
+      "slice.w": number;
       /**
        * The texture bound to the sprite's first sampler. Not in the sprite
        * ref-doc; `resource.set`'s example reads it with
@@ -57,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
@@ -73,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
@@ -87,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
@@ -102,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`
@@ -118,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

@@ -87,10 +87,30 @@ export interface Matrix4 {
   m31: number;
   m32: number;
   m33: number;
-  c0: Vector4;
-  c1: Vector4;
-  c2: Vector4;
-  c3: Vector4;
+  /**
+   * The first column. A read returns a new `Vector4`, so writing one of its
+   * fields changes nothing; assigning a whole `Vector4` sets the column.
+   */
+  get c0(): Readonly<Vector4>;
+  set c0(value: Vector4);
+  /**
+   * The second column. A read returns a new `Vector4`, so writing one of its
+   * fields changes nothing; assigning a whole `Vector4` sets the column.
+   */
+  get c1(): Readonly<Vector4>;
+  set c1(value: Vector4);
+  /**
+   * The third column. A read returns a new `Vector4`, so writing one of its
+   * fields changes nothing; assigning a whole `Vector4` sets the column.
+   */
+  get c2(): Readonly<Vector4>;
+  set c2(value: Vector4);
+  /**
+   * The fourth column. A read returns a new `Vector4`, so writing one of its
+   * fields changes nothing; assigning a whole `Vector4` sets the column.
+   */
+  get c3(): Readonly<Vector4>;
+  set c3(value: Vector4);
   mul: LuaMultiplicationMethod<Matrix4, Matrix4> &
     LuaMultiplicationMethod<Vector4, Vector4> &
     LuaMultiplicationMethod<number, Matrix4>;
@@ -178,11 +198,14 @@ 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">`
  *
+ * A buffer's `buf.length()` compiles to `#buf` and returns its element count.
+ *
  * @example
  * Handles always come back from the engine — for instance:
  * ```ts
@@ -209,21 +232,39 @@ export interface Opaque<Name extends string> {
  *
  * @remarks
  * Each field is writable and takes a `Hash` or a string, which the engine
- * hashes. Every `msg.url` form resolves a socket, so `socket` is always set.
- * `path` and `fragment` read `undefined` when unset: a socket-only address
- * (`msg.url("main:")`) has no `path`, so narrow it before use. Assigning
- * `undefined` clears `path` or `fragment`.
+ * hashes. Every field reads `undefined` when unset, so narrow it before use. A
+ * socket-only address (`msg.url("main:")`) has no `path`. `socket` is unset on
+ * the `sender` of an engine message posted with no sender, such as
+ * `ray_cast_response` and `ray_cast_missed` from `physics.raycast_async`,
+ * `animation_done` from a `model.play_anim` with no callback, and
+ * `window_resized` in a render script, and after `url.socket = undefined`.
+ * Assigning `undefined` clears any of the three fields.
  */
 export interface Url {
-  get socket(): Hash;
-  set socket(value: Hash | string);
+  get socket(): Hash | undefined;
+  set socket(value: Hash | string | undefined);
   get path(): Hash | undefined;
   set path(value: Hash | string | undefined);
   get fragment(): Hash | undefined;
   set fragment(value: Hash | string | undefined);
 }
 
-const BUFFER_TYPE = 'Opaque<"buffer">';
+// 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> }';
 
@@ -276,29 +317,31 @@ 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
-  // two exceptions: `script_instance` is the untyped `self` a callback recovery
-  // emits, and `resource_data` (1.13.1 `resource`, only in the hand-authored
-  // `go.get`/`go.set`/`go.property` slots) is a path hash.
+  // three exceptions: `script_instance` is the untyped `self` a callback recovery
+  // emits, `resource_data` (1.13.1 `resource`, only in the hand-authored
+  // `go.get`/`go.set`/`go.property` slots) is a path hash, and `render_predicate`
+  // (1.13.1 `number`) is the userdata `render.predicate` returns and
+  // render_script.cpp:RenderScriptPredicate_Check reads.
   buffer_data: BUFFER_TYPE,
   buffer_stream: BUFFERSTREAM_TYPE,
   script_instance: "unknown",
   resource_data: "Hash",
   timer_handle: "number",
-  render_predicate: "number",
-  socket_client: "client",
-  socket_connected: "connected",
-  socket_master: "master",
-  socket_server: "server",
-  socket_unconnected: "unconnected",
+  render_predicate: 'Opaque<"render_predicate">',
+  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

@@ -2,14 +2,15 @@ import { fnv1a64 } from "./fnv1a";
 
 // A function slot whose upstream doc HTML is malformed badly enough to misread,
 // replaced wholesale with authored HTML that keeps upstream's wording, or a
-// property description that contradicts what the engine does. Each
+// function or property doc that contradicts what the engine does. Each
 // entry is pinned by the FNV-1a hash of the exact upstream HTML it replaces: the
 // parse applies it only while the vendored doc still hashes to that value, so a
 // fixed or reworded upstream doc wins by itself, and
 // `doc-correction-provenance.test.ts` reds until the stale entry is deleted.
 //
-// Keyed `<function>#param:<name>`, `<function>#return:<name>`, or
-// `<namespace>#property:<name>` (the ref-doc `PROPERTY` element's bare name).
+// Keyed `<function>#param:<name>`, `<function>#return:<name>`, `<function>#brief`,
+// `<function>#description`, or `<namespace>#property:<name>` (the ref-doc
+// `PROPERTY` element's bare name).
 export interface DocCorrection {
   readonly upstreamHash: string;
   readonly html: string;
@@ -19,6 +20,9 @@ export interface DocCorrection {
 const li = (name: string, type: string, doc: string) =>
   `<li><code>${name}</code> <span class="type">${type}</span> ${doc}</li>`;
 
+const GET_BYTES_REASON =
+  "script_buffer.cpp:GetBytes reads only argument 1 with CheckBufferUnpack and pushes every byte of the buffer, so no stream is selected";
+
 export const DOC_CORRECTIONS: ReadonlyMap<string, DocCorrection> = new Map([
   [
     "graphics.get_adapter_info#return:info",
@@ -90,14 +94,67 @@ 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",
+    {
+      upstreamHash: "e30a9df6b7f4f67d",
+      reason: GET_BYTES_REASON,
+      html: "gets all the bytes of a buffer",
+    },
+  ],
+  [
+    "buffer.get_bytes#description",
+    {
+      upstreamHash: "0f16f8e9dce4eb3a",
+      reason: GET_BYTES_REASON,
+      html: "Get a copy of all the bytes of the buffer, every stream included, as a Lua string.",
+    },
+  ],
+  [
+    "buffer.get_bytes#param:stream_name",
+    {
+      upstreamHash: "cfd40e4525c59409",
+      reason: GET_BYTES_REASON,
+      html: "the name of the stream; the engine ignores it and returns every byte of the buffer",
+    },
+  ],
+  [
+    "gui.clone_tree#param:node",
+    {
+      upstreamHash: "5c72743d24931629",
+      reason:
+        "gui_script.cpp:LuaCloneTree tests argument 1 with lua_isnil after pushing its result table, so nil selects the whole scene and an absent argument raises",
+      html: "root node to clone, or <code>nil</code> to clone the whole scene; leaving the argument out raises an error",
+    },
+  ],
+  [
+    "gui.get_tree#param:node",
+    {
+      upstreamHash: "47ef2cdd6bf46434",
+      reason:
+        "gui_script.cpp:LuaGetTree tests argument 1 with lua_isnil after pushing its result table, so nil selects the whole scene and an absent argument raises",
+      html: "root node to get node tree from, or <code>nil</code> to get the whole scene; leaving the argument out raises an error",
+    },
+  ],
 ]);
 
+export function docCorrectionKey(owner: string, slot: "brief" | "description"): string;
 export function docCorrectionKey(
   owner: string,
   slot: "param" | "return" | "property",
   name: string,
-): string {
-  return `${owner}#${slot}:${name}`;
+): string;
+export function docCorrectionKey(owner: string, slot: string, name?: string): string {
+  return name === undefined ? `${owner}#${slot}` : `${owner}#${slot}:${name}`;
 }
 
 // The slot's doc with its correction applied, or `doc` itself when the slot has