@defold-typescript/types 0.50.1 → 0.52.0

package/src/component-properties.d.ts

@@ -1,24 +1,210 @@
 /** @noSelfInFile */
 
-import type { Hash } from "./core-types";
+import type { Hash, Vector3 } from "./core-types";
 
-// Component property keys upstream examples read through `go.get` while no
-// ref-doc catalog declares them. Only evidenced keys belong here.
+// Property keys the engine handles while no ref-doc catalog declares them. Each
+// key comes from the component's `GetProperty` / `SetProperty` branches in the
+// engine source, or from an upstream example that reads it, and cites that
+// evidence. A key the engine reads but never writes is `readonly`.
 declare global {
+  namespace go {
+    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. */
+      "position.y": number;
+      /** The position's z component. `gameobject.cpp:GetProperty` reads one float. */
+      "position.z": number;
+      /** The rotation quaternion's x component. `gameobject.cpp:GetProperty` reads one float. */
+      "rotation.x": number;
+      /** The rotation quaternion's y component. `gameobject.cpp:GetProperty` reads one float. */
+      "rotation.y": number;
+      /** The rotation quaternion's z component. `gameobject.cpp:GetProperty` reads one float. */
+      "rotation.z": number;
+      /** The rotation quaternion's w component. `gameobject.cpp:GetProperty` reads one float. */
+      "rotation.w": number;
+      /** The euler rotation's x angle, in degrees. `gameobject.cpp:GetProperty` reads one float. */
+      "euler.x": number;
+      /** The euler rotation's y angle, in degrees. `gameobject.cpp:GetProperty` reads one float. */
+      "euler.y": number;
+      /** The euler rotation's z angle, in degrees. `gameobject.cpp:GetProperty` reads one float. */
+      "euler.z": number;
+      /** The scale's x component. `gameobject.cpp:GetProperty` reads one float. */
+      "scale.x": number;
+      /** The scale's y component. `gameobject.cpp:GetProperty` reads one float. */
+      "scale.y": number;
+      /** The scale's z component. `gameobject.cpp:GetProperty` reads one float. */
+      "scale.z": number;
+      /**
+       * The scale's x and y components. `gameobject.cpp:GetProperty` reads a
+       * vector3 whose z is always 1. `go.set` also takes a number, which it
+       * applies to both x and y.
+       */
+      "scale.xy": Vector3;
+    }
+  }
+
+  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 {
+      /** 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
-       * `go.get("#sprite", "texture0")`.
+       * `go.get("#sprite", "texture0")`. Read-only:
+       * `comp_sprite.cpp:CompSpriteSetProperty` has no branch for it.
        */
-      texture0: Hash;
+      readonly texture0: Hash;
+    }
+  }
+
+  namespace model {
+    interface properties {
+      /**
+       * The material resource the model renders with.
+       * `comp_model.cpp:CompModelGetProperty` and `CompModelSetProperty` read
+       * and write it as a resource path hash.
+       */
+      material: Hash;
+      /**
+       * The skin the model's rig uses. `comp_model.cpp:CompModelGetProperty` and
+       * `CompModelSetProperty` read and write it as a hash.
+       */
+      skin: Hash;
+    }
+  }
+
+  namespace physics {
+    interface properties {
+      /**
+       * Whether the body runs continuous collision detection as a fast-moving
+       * bullet. Box2D only: `comp_collision_object_box2d.cpp` reads and writes
+       * it, while Bullet3D logs a warning and reports the property as not found.
+       */
+      bullet: boolean;
+    }
+  }
+
+  namespace factory {
+    /**
+     * Factory component properties. Upstream's factory reference declares none.
+     */
+    interface properties {
+      /**
+       * The path hash of the prototype the factory spawns. Read-only:
+       * `comp_factory.cpp:CompFactoryGetProperty` reads it and the component
+       * registers no set handler.
+       */
+      readonly prototype: Hash;
+    }
+  }
+
+  namespace collectionfactory {
+    /**
+     * Collection factory component properties. Upstream's collectionfactory
+     * reference declares none.
+     */
+    interface properties {
+      /**
+       * The path hash of the collection prototype the factory spawns.
+       * Read-only: `comp_collection_factory.cpp:CompCollectionFactoryGetProperty`
+       * reads it and the component registers no set handler.
+       */
+      readonly prototype: Hash;
     }
   }
 
   /**
    * Mesh component properties. Upstream ships no mesh API module, so this
-   * catalog holds only the keys upstream examples read.
+   * catalog holds the keys `comp_mesh.cpp:CompMeshGetProperty` and
+   * `CompMeshSetProperty` handle.
    */
   namespace mesh {
     interface properties {
@@ -28,6 +214,40 @@ declare global {
        * `go.get("#mesh", "vertices")`.
        */
       vertices: Hash;
+      /** The material resource the mesh renders with, as a resource path hash. */
+      material: Hash;
+      /** The texture on unit 0, as a resource path hash. The engine holds units 0-15. */
+      texture0: Hash;
+      /** The texture on unit 1, as a resource path hash. */
+      texture1: Hash;
+      /** The texture on unit 2, as a resource path hash. */
+      texture2: Hash;
+      /** The texture on unit 3, as a resource path hash. */
+      texture3: Hash;
+      /** The texture on unit 4, as a resource path hash. */
+      texture4: Hash;
+      /** The texture on unit 5, as a resource path hash. */
+      texture5: Hash;
+      /** The texture on unit 6, as a resource path hash. */
+      texture6: Hash;
+      /** The texture on unit 7, as a resource path hash. */
+      texture7: Hash;
+      /** The texture on unit 8, as a resource path hash. */
+      texture8: Hash;
+      /** The texture on unit 9, as a resource path hash. */
+      texture9: Hash;
+      /** The texture on unit 10, as a resource path hash. */
+      texture10: Hash;
+      /** The texture on unit 11, as a resource path hash. */
+      texture11: Hash;
+      /** The texture on unit 12, as a resource path hash. */
+      texture12: Hash;
+      /** The texture on unit 13, as a resource path hash. */
+      texture13: Hash;
+      /** The texture on unit 14, as a resource path hash. */
+      texture14: Hash;
+      /** The texture on unit 15, as a resource path hash. */
+      texture15: Hash;
     }
   }
 }

package/src/core-types.ts

@@ -1,11 +1,18 @@
 /// <reference types="@typescript-to-lua/language-extensions" />
 
 /**
- * A read-only numeric vector accessed by index; `length` is its component count.
+ * A numeric vector of any size, accessed by index for reads and writes;
+ * `v.length()` is its component count.
+ *
+ * @remarks
+ * The index is 1-based and passed to Defold unchanged: `v[1]` is the first
+ * component, and an index outside `1..v.length()` raises. `v.length()` compiles
+ * to the Lua length operator `#v`; reading `v.length` as a field raises, since
+ * the engine accepts only integer keys.
  */
 export interface Vector {
-  readonly [index: number]: number;
-  readonly length: number;
+  [index: number]: number;
+  length: LuaLengthMethod<number>;
 }
 
 /**
@@ -80,11 +87,46 @@ export interface Matrix4 {
   m31: number;
   m32: number;
   m33: number;
-  c0: Vector4;
-  c1: Vector4;
-  c2: Vector4;
-  c3: Vector4;
-  mul: LuaMultiplicationMethod<Matrix4, Matrix4> & LuaMultiplicationMethod<Vector4, 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>;
+}
+
+/**
+ * An array constant read back from a constant buffer: the engine's 1-based
+ * proxy over the constant's slots, not a Lua table.
+ *
+ * @remarks
+ * `cb.lights[1]` reads the first slot and an index below 1 raises. The proxy
+ * has no length, so it does not support `#` or `.length`; assign a whole new
+ * array (`cb.lights = [a, b]`) to change how many slots the constant holds.
+ */
+export interface ConstantArray<T> {
+  [index: number]: T;
 }
 
 declare const HashBrand: unique symbol;
@@ -145,9 +187,12 @@ declare const OpaqueBrand: unique symbol;
  * types, and passing a texture where a node is expected is a compile error,
  * exactly as a wrong primitive would be. The brand is a phantom `unique symbol`
  * property that lives only in the type system and is erased at transpile — at
- * runtime the value is just the engine's userdata. Because the symbol is never
- * exported, your code cannot fabricate a handle or inspect or construct one; the
- * engine API is the only source.
+ * runtime the value is whatever the engine hands out: usually its userdata, but a
+ * plain number for render-target and texture handles (`render.render_target`,
+ * the `handle` field of `resource.get_texture_info`). The brand exists only at
+ * compile time either way. Because the symbol is never exported, your code
+ * cannot fabricate a handle or inspect or construct one; the engine API is the
+ * only source.
  *
  * The handle kinds modeled today:
  * - GUI & rendering: `Opaque<"node">`, `Opaque<"texture">`,
@@ -158,6 +203,8 @@ declare const OpaqueBrand: unique symbol;
  * - 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
@@ -181,14 +228,27 @@ export interface Opaque<Name extends string> {
 
 /**
  * A message-passing address with `socket`, `path`, and `fragment` components.
+ *
+ * @remarks
+ * Each field is writable and takes a `Hash` or a string, which the engine
+ * 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 {
-  readonly socket: Hash;
-  readonly path: Hash;
-  readonly fragment: Hash | undefined;
+  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">';
+const BUFFER_TYPE = 'Opaque<"buffer"> & { length: LuaLengthMethod<number> }';
 const BUFFERSTREAM_TYPE =
   'Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }';
 
@@ -219,7 +279,7 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   render_target: 'Opaque<"render_target">',
   constant: 'Opaque<"constant">',
   constant_buffer:
-    'Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | Matrix4[] }',
+    'Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | ConstantArray<Vector4> | ConstantArray<Matrix4> }',
   buffer: BUFFER_TYPE,
   bufferstream: BUFFERSTREAM_TYPE,
   userdata: 'Opaque<"userdata">',
@@ -252,15 +312,17 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   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",
+  render_predicate: 'Opaque<"render_predicate">',
   socket_client: "client",
   socket_connected: "connected",
   socket_master: "master",

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,58 @@ 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.",
     },
   ],
+  [
+    "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