@defold-typescript/types 0.51.0 → 0.52.0

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>;
@@ -183,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
@@ -209,21 +231,24 @@ 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">';
+const BUFFER_TYPE = 'Opaque<"buffer"> & { length: LuaLengthMethod<number> }';
 const BUFFERSTREAM_TYPE =
   'Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }';
 
@@ -287,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