@defold-typescript/types 0.40.0 → 0.41.0

package/generated/html5.d.ts

@@ -33,7 +33,7 @@ declare global {
      * @param callback - The interaction callback. Pass an empty function or `nil` if you no longer wish to receive callbacks.
      *
      * `self`
-     * object The calling script
+     * script_instance The calling script instance
      * @example
      * ```ts
      * function on_interaction(self: unknown) {
@@ -48,7 +48,7 @@ declare global {
      * });
      * ```
      */
-    function set_interaction_listener(callback?: (self: unknown) => void): void;
+    function set_interaction_listener(callback: ((self: unknown) => void) | undefined): void;
   }
 }
 

package/generated/http.d.ts

@@ -6,6 +6,31 @@ declare global {
    * Functions for performing HTTP and HTTPS requests.
    */
   namespace http {
+    /**
+     * HTTP request options
+     */
+    interface request_options {
+      /**
+       * timeout in seconds
+       */
+      timeout?: number;
+      /**
+       * absolute destination path; overwritten only for status 200
+       */
+      path?: string;
+      /**
+       * do not return cached data for status 304; unavailable on HTML5
+       */
+      ignore_cache?: boolean;
+      /**
+       * use chunked transfer encoding for HTTPS requests larger than 16 KB; defaults to true and is unavailable on HTML5
+       */
+      chunked_transfer?: boolean;
+      /**
+       * report transferred and total byte counts to the callback
+       */
+      report_progress?: boolean;
+    }
     /**
      * Perform a HTTP/HTTPS request.
      * If no timeout value is passed, the configuration value "network.http_timeout" is used. If that is not set, the timeout value is `0` (which blocks indefinitely).
@@ -15,44 +40,12 @@ declare global {
      * @param callback - response callback function
      *
      * `self`
-     * object The script instance
+     * script_instance The current script instance
      * `id`
      * hash Internal message identifier. Do not use!
-     * `response`
-     * table The response data. Contains the fields:
-     *
-     * - number `status`: the status of the response
-     *
-     * - string `response`: the response data (if not saved on disc)
-     *
-     * - table `headers`: all the returned headers (if status is 200 or 206)
-     *
-     * - string `path`: the stored path (if saved to disc)
-     *
-     * - string `error`: if any unforeseen errors occurred (e.g. file I/O)
-     *
-     * - number `bytes_received`: the amount of bytes received/sent for a request, only if option `report_progress` is true
-     *
-     * - number `bytes_total`: the total amount of bytes for a request, only if option `report_progress` is true
-     *
-     * - number `range_start`: the start offset into the requested file
-     *
-     * - number `range_end`: the end offset into the requested file (inclusive)
-     *
-     * - number `document_size`: the full size of the requested file
      * @param headers - optional table with custom headers
      * @param post_data - optional data to send
-     * @param options - optional table with request parameters. Supported entries:
-     *
-     * - number `timeout`: timeout in seconds
-     *
-     * - string `path`: path on disc where to download the file. Only overwrites the path if status is 200. Path should be absolute
-     *
-     * - boolean `ignore_cache`: don't return cached data if we get a 304. Not available in HTML5 build
-     *
-     * - boolean `chunked_transfer`: use chunked transfer encoding for https requests larger than 16kb. Defaults to true. Not available in HTML5 build
-     *
-     * - boolean `report_progress`: when it is true, the amount of bytes sent and/or received for a request will be passed into the callback function
+     * @param options - optional request options
      * @example
      * ```ts
      * function update_my_progress_bar(self: unknown, fraction: number) {
@@ -83,7 +76,7 @@ declare global {
      * });
      * ```
      */
-    function request(url: string, method: string, callback: (self: unknown, id: Hash, response: { status: number; response?: string; headers?: LuaMap<string, string>; path?: string; error?: string; bytes_received?: number; bytes_total?: number; range_start?: number; range_end?: number; document_size?: number }) => void, headers?: LuaMap<string, string> | Record<string, string>, post_data?: string, options?: { timeout?: number; path?: string; ignore_cache?: boolean; chunked_transfer?: boolean; report_progress?: boolean }): void;
+    function request(url: string, method: string, callback: (self: unknown, id: Hash, response: { status: number; response?: string; headers?: LuaMap<string, string>; path?: string; error?: string; bytes_received?: number; bytes_total?: number; range_start?: number; range_end?: number; document_size?: number }) => void, headers?: LuaMap<string, string> | Record<string, string>, post_data?: string, options?: http.request_options): void;
   }
 }
 

package/generated/image.d.ts

@@ -7,38 +7,111 @@ declare global {
    */
   namespace image {
     /**
-     * luminance image type
+     * ASTC image header
      */
-    const TYPE_LUMINANCE: number & { readonly __brand: "image.TYPE_LUMINANCE" };
+    interface astc_header {
+      /**
+       * Image width.
+       */
+      width: number;
+      /**
+       * Image height.
+       */
+      height: number;
+      /**
+       * Image depth.
+       */
+      depth: number;
+      /**
+       * Block size on the x-axis.
+       */
+      block_size_x: number;
+      /**
+       * Block size on the y-axis.
+       */
+      block_size_y: number;
+      /**
+       * Block size on the z-axis.
+       */
+      block_size_z: number;
+    }
     /**
-     * luminance image type
+     * Loaded buffer image data
      */
-    const TYPE_LUMINANCE_ALPHA: number & { readonly __brand: "image.TYPE_LUMINANCE_ALPHA" };
+    interface load_buffer_result {
+      /**
+       * Image width.
+       */
+      width: number;
+      /**
+       * Image height.
+       */
+      height: number;
+      /**
+       * Image type.
+       */
+      type: image.TYPE;
+      /**
+       * Script buffer containing the decompressed image data.
+       */
+      buffer: Opaque<"buffer">;
+    }
     /**
-     * RGB image type
+     * Image loading options
      */
-    const TYPE_RGB: number & { readonly __brand: "image.TYPE_RGB" };
+    interface load_options {
+      /**
+       * Whether to premultiply alpha into the color components. Defaults to `false`.
+       */
+      premultiply_alpha?: boolean;
+      /**
+       * Whether to flip the image contents vertically. Defaults to `false`.
+       */
+      flip_vertically?: boolean;
+    }
     /**
-     * RGBA image type
+     * Loaded string image data
      */
-    const TYPE_RGBA: number & { readonly __brand: "image.TYPE_RGBA" };
+    interface load_result {
+      /**
+       * Image width.
+       */
+      width: number;
+      /**
+       * Image height.
+       */
+      height: number;
+      /**
+       * Image type.
+       */
+      type: image.TYPE;
+      /**
+       * Raw image data.
+       */
+      buffer: string;
+    }
+    type TYPE = typeof image.TYPE_RGB | typeof image.TYPE_RGBA | typeof image.TYPE_LUMINANCE | typeof image.TYPE_LUMINANCE_ALPHA;
+    /**
+     * Luminance image type.
+     */
+    const TYPE_LUMINANCE: string & { readonly __brand: "image.TYPE_LUMINANCE" };
+    /**
+     * Luminance-alpha image type.
+     */
+    const TYPE_LUMINANCE_ALPHA: string & { readonly __brand: "image.TYPE_LUMINANCE_ALPHA" };
+    /**
+     * RGB image type.
+     */
+    const TYPE_RGB: string & { readonly __brand: "image.TYPE_RGB" };
+    /**
+     * RGBA image type.
+     */
+    const TYPE_RGBA: string & { readonly __brand: "image.TYPE_RGBA" };
     /**
      * get the header of an .astc buffer
      *
      * @param buffer - .astc file data buffer
-     * @returns header or `nil` if buffer is not a valid .astc. The header has these fields:
-     *
-     * - number `width`: image width
-     *
-     * - number `height`: image height
-     *
-     * - number `depth`: image depth
-     *
-     * - number `block_size_x`: block size x
-     *
-     * - number `block_size_y`: block size y
-     *
-     * - number `block_size_z`: block size z
+     * @returns header, or `nil` if the buffer is not a valid ASTC image
      * @example
      * ```ts
      * // How to get the block size and dimensions from a .astc file
@@ -49,34 +122,13 @@ declare global {
      * }
      * ```
      */
-    function get_astc_header(buffer: string): { width: number; height: number; depth: number; block_size_x: number; block_size_y: number; block_size_z: number } | undefined;
+    function get_astc_header(buffer: string): image.astc_header | undefined;
     /**
      * Load image (PNG or JPEG) from buffer.
      *
      * @param buffer - image data buffer
-     * @param options - An optional table containing parameters for loading the image. Supported entries:
-     *
-     * `premultiply_alpha`
-     * boolean True if alpha should be premultiplied into the color components. Defaults to `false`.
-     * `flip_vertically`
-     * boolean True if the image contents should be flipped vertically. Defaults to `false`.
-     * @returns object or `nil` if loading fails. The object is a table with the following fields:
-     *
-     * - number `width`: image width
-     *
-     * - number `height`: image height
-     *
-     * - constant `type`: image type
-     *
-     * - `image.TYPE_RGB`
-     *
-     * - `image.TYPE_RGBA`
-     *
-     * - `image.TYPE_LUMINANCE`
-     *
-     * - `image.TYPE_LUMINANCE_ALPHA`
-     *
-     * - string `buffer`: the raw image data
+     * @param options - Optional loading parameters. A boolean is accepted for backwards compatibility and controls `premultiply_alpha`.
+     * @returns loaded image, or `nil` if loading fails
      * @example
      * ```ts
      * // How to load an image from an URL and create a GUI texture from it:
@@ -89,34 +141,13 @@ declare global {
      * });
      * ```
      */
-    function load(buffer: string, options?: { premultiply_alpha?: boolean; flip_vertically?: boolean }): { width: number; height: number; type: Opaque<"constant">; buffer: string } | undefined;
+    function load(buffer: string, options?: boolean | image.load_options): image.load_result | undefined;
     /**
      * Load image (PNG or JPEG) from a string buffer.
      *
      * @param buffer - image data buffer
-     * @param options - An optional table containing parameters for loading the image. Supported entries:
-     *
-     * `premultiply_alpha`
-     * boolean True if alpha should be premultiplied into the color components. Defaults to `false`.
-     * `flip_vertically`
-     * boolean True if the image contents should be flipped vertically. Defaults to `false`.
-     * @returns object or `nil` if loading fails. The object is a table with the following fields:
-     *
-     * - number `width`: image width
-     *
-     * - number `height`: image height
-     *
-     * - constant `type`: image type
-     *
-     * - `image.TYPE_RGB`
-     *
-     * - `image.TYPE_RGBA`
-     *
-     * - `image.TYPE_LUMINANCE`
-     *
-     * - `image.TYPE_LUMINANCE_ALPHA`
-     *
-     * - buffer `buffer`: the script buffer that holds the decompressed image data. See buffer.create how to use the buffer.
+     * @param options - Optional loading parameters. A boolean is accepted for backwards compatibility and controls `premultiply_alpha`.
+     * @returns loaded image, or `nil` if loading fails
      * @example
      * ```ts
      * // Load an image from an URL as a buffer and create a texture resource from it:
@@ -126,12 +157,14 @@ declare global {
      *     response.response !== undefined
      *       ? image.load_buffer(response.response, { flip_vertically: true })
      *       : undefined;
-     *   if (img !== undefined) {
+     *   // the engine registers a texture format only when the driver supports it
+     *   const format = graphics.TEXTURE_FORMAT_RGBA;
+     *   if (img !== undefined && format !== undefined) {
      *     const tparams = {
      *       width: img.width,
      *       height: img.height,
      *       type: graphics.TEXTURE_TYPE_2D,
-     *       format: graphics.TEXTURE_FORMAT_RGBA,
+     *       format,
      *     };
      *
      *     const my_texture_id = resource.create_texture("/my_custom_texture.texturec", tparams, img.buffer);
@@ -141,7 +174,7 @@ declare global {
      * });
      * ```
      */
-    function load_buffer(buffer: string, options?: { premultiply_alpha?: boolean; flip_vertically?: boolean }): { width: number; height: number; type: Opaque<"constant">; buffer: Opaque<"buffer"> } | undefined;
+    function load_buffer(buffer: string, options?: boolean | image.load_options): image.load_buffer_result | undefined;
   }
 }
 

package/generated/json.d.ts

@@ -4,6 +4,24 @@ declare global {
    * Manipulation of JSON data strings.
    */
   namespace json {
+    /**
+     * JSON decoding options
+     */
+    export interface decode_options {
+      /**
+       * Decode JSON `null` as json.null instead of `nil`.
+       */
+      decode_null_as_userdata?: boolean;
+    }
+    /**
+     * JSON encoding options
+     */
+    export interface encode_options {
+      /**
+       * Encode an empty table as an object instead of an array. The default is true.
+       */
+      encode_empty_table_as_object?: boolean;
+    }
     /**
      * Represents the null primitive from a json file
      */
@@ -13,13 +31,11 @@ declare global {
      * A Lua error is raised for syntax errors.
      *
      * @param json - json data
-     * @param options - table with decode options
-     *
-     * - boolean `decode_null_as_userdata`: whether to decode a JSON null value as json.null or nil (default is nil)
-     * @returns decoded json
+     * @param options - optional decoding options
+     * @returns decoded JSON value
      * @example
+     * Converting a string containing JSON data into a Lua table:
      * ```ts
-     * // Converting a string containing JSON data into a table:
      * export default defineScript({
      *   init() {
      *     const jsonstring = '{"persons":[{"name":"John Doe"},{"name":"Darth Vader"}]}';
@@ -27,8 +43,10 @@ declare global {
      *     pprint(data);
      *   },
      * });
-     *
-     * // Results in the following printout:
+     * ```
+     * @example
+     * Results in the following printout:
+     * ```ts
      * // {
      * //   persons = {
      * //     1 = {
@@ -41,19 +59,17 @@ declare global {
      * // }
      * ```
      */
-    export function decode(json: string, options?: { decode_null_as_userdata?: boolean }): Record<string | number, unknown>;
+    export function decode(json: string, options?: json.decode_options): unknown;
     /**
      * Encode a lua table to a JSON string.
      * A Lua error is raised for syntax errors.
      *
-     * @param tbl - lua table to encode
-     * @param options - table with encode options
-     *
-     * - string `encode_empty_table_as_object`: whether to encode an empty table as an JSON object or array (default is object)
+     * @param tbl - Lua value to encode
+     * @param options - optional encoding options
      * @returns encoded json
      * @example
+     * Convert a lua table to a JSON string:
      * ```ts
-     * // Convert a table to a JSON string:
      * export default defineScript({
      *   init() {
      *     const tbl = {
@@ -63,12 +79,14 @@ declare global {
      *     pprint(jsonstring);
      *   },
      * });
-     *
-     * // Results in the following printout:
+     * ```
+     * @example
+     * Results in the following printout:
+     * ```ts
      * // {"persons":[{"name":"John Doe"},{"name":"Darth Vader"}]}
      * ```
      */
-    export function encode(tbl: Record<string | number, unknown>, options?: { encode_empty_table_as_object?: string }): string;
+    export function encode(tbl: unknown, options?: json.encode_options): string;
     export { _null as null };
   }
 }

package/generated/kinds/gui-script.d.ts

@@ -8,6 +8,12 @@ import "../b2d_joint";
 import "../b2d_shape";
 import "../b2d_world";
 import "../buffer";
+import "../bullet3d";
+import "../bullet3d_collision_object";
+import "../bullet3d_constraint";
+import "../bullet3d_rigid_body";
+import "../bullet3d_shape";
+import "../bullet3d_world";
 import "../camera";
 import "../collectionfactory";
 import "../collectionproxy";
@@ -47,6 +53,7 @@ import "../../src/go-overloads";
 import "../../src/message-guard";
 import "../../src/msg-overloads";
 import "../../src/scene-addresses";
+import "../../src/sys-overloads";
 import "../../src/vmath-overloads";
 import "../../src/window-event-guard";
 import "../builtin-messages";

package/generated/kinds/render-script.d.ts

@@ -8,6 +8,12 @@ import "../b2d_joint";
 import "../b2d_shape";
 import "../b2d_world";
 import "../buffer";
+import "../bullet3d";
+import "../bullet3d_collision_object";
+import "../bullet3d_constraint";
+import "../bullet3d_rigid_body";
+import "../bullet3d_shape";
+import "../bullet3d_world";
 import "../camera";
 import "../collectionfactory";
 import "../collectionproxy";
@@ -48,6 +54,7 @@ import "../../src/message-guard";
 import "../../src/msg-overloads";
 import "../../src/render-overloads";
 import "../../src/scene-addresses";
+import "../../src/sys-overloads";
 import "../../src/vmath-overloads";
 import "../../src/window-event-guard";
 import "../builtin-messages";

package/generated/kinds/script.d.ts

@@ -8,6 +8,12 @@ import "../b2d_joint";
 import "../b2d_shape";
 import "../b2d_world";
 import "../buffer";
+import "../bullet3d";
+import "../bullet3d_collision_object";
+import "../bullet3d_constraint";
+import "../bullet3d_rigid_body";
+import "../bullet3d_shape";
+import "../bullet3d_world";
 import "../camera";
 import "../collectionfactory";
 import "../collectionproxy";
@@ -47,6 +53,7 @@ import "../../src/go-overloads";
 import "../../src/message-guard";
 import "../../src/msg-overloads";
 import "../../src/scene-addresses";
+import "../../src/sys-overloads";
 import "../../src/vmath-overloads";
 import "../../src/window-event-guard";
 import "../builtin-messages";

package/generated/label.d.ts

@@ -6,16 +6,82 @@ declare global {
    * Label API documentation
    */
   namespace label {
+    /**
+     * Rich-text layout object
+     */
+    interface layout_object {
+      /**
+       * object type, currently `link` or `sprite`
+       */
+      type: string;
+      /**
+       * the object's `id` attribute, or its generated layout object id
+       */
+      id: Hash;
+      /**
+       * zero-based UTF-32 offset in the visible text
+       */
+      text_offset: number;
+      /**
+       * visible UTF-32 text length covered by the object
+       */
+      text_length: number;
+      /**
+       * lower-left x-coordinate relative to the label's upper-left layout origin
+       */
+      x: number;
+      /**
+       * lower-left y-coordinate relative to the label's upper-left layout origin
+       */
+      y: number;
+      /**
+       * resolved object width
+       */
+      width: number;
+      /**
+       * resolved object height
+       */
+      height: number;
+      /**
+       * markup attributes keyed by name
+       */
+      attributes: LuaTable<string, string>;
+    }
+    /**
+     * Returns the sprites and links found in the label's current layout.
+     * Each entry contains `type`, `id`, the zero-based UTF-32 `text_offset`,
+     * `text_length`, resolved `x`, `y`, `width`
+     * and `height`, and an `attributes` table. The position is the lower-left
+     * object corner relative to the label's upper-left layout origin.
+     * Inline resource rendering is not part of this MVP; sprites use their explicit
+     * dimensions or a one-em square fallback.
+     *
+     * @param url - the label to inspect
+     * @returns layout objects in source order. **0️⃣ `text_offset` is 0-based; passed to Defold unchanged.**
+     * @example
+     * ```ts
+     * const objects = label.get_layout_objects("#label");
+     * for (const object of objects) {
+     *   if (object.type === "link") {
+     *     print(object.attributes.get("src"), object.text_offset, object.text_length);
+     *   } else if (object.type === "sprite") {
+     *     print(object.attributes.get("src"), object.x, object.y, object.width, object.height);
+     *   }
+     * }
+     * ```
+     */
+    function get_layout_objects(url: string | Hash | Url): label.layout_object[];
     /**
      * Gets the text from a label component
+     * This function is deprecated. Use `go.get("#label", "text")` instead.
      *
      * @param url - the label to get the text from
      * @returns the label text
      * @example
      * ```ts
      * export default defineScript({
-     *   init(self) {
-     *     const text = label.get_text("#label");
+     *   init() {
+     *     const text = go.get<label.properties>()("#label", "text");
      *     print(text);
      *   },
      * });
@@ -24,6 +90,7 @@ declare global {
     function get_text(url: string | Hash | Url): string;
     /**
      * Sets the text of a label component
+     * This function is deprecated. Use `go.set("#label", "text", value)` instead.
      * This method uses the message passing that means the value will be set after `dispatch messages` step.
      * More information is available in the Application Lifecycle manual.
      *
@@ -32,8 +99,8 @@ declare global {
      * @example
      * ```ts
      * export default defineScript({
-     *   init(self) {
-     *     label.set_text("#label", "Hello World!");
+     *   init() {
+     *     go.set<label.properties>()("#label", "text", "Hello World!");
      *   },
      * });
      * ```
@@ -68,10 +135,9 @@ declare global {
        */
       outline: Vector4;
       /**
-       * The scale of the label. The type of the property is number (uniform)
-       * or vector3 (non uniform).
+       * The scale of the label. `go.get` returns and `go.set` takes a vector3; `go.animate` also takes a number, which sets a uniform scale.
        */
-      scale: number | Vector3;
+      scale: Vector3;
       /**
        * The shadow color of the label. The type of the property is vector4.
        */
@@ -81,6 +147,10 @@ declare global {
        * The type of the property is vector3.
        */
       size: Vector3;
+      /**
+       * The text of the label.
+       */
+      text: string;
       /**
        * The tracking of the label.
        * This value is used to adjust the vertical spacing of characters in the text.