@defold-typescript/types 0.8.4 → 0.9.0

package/generated/sprite.d.ts

@@ -15,17 +15,22 @@ declare global {
      * @param url - the sprite that should play the animation
      * @param id - hashed id of the animation to play
      * @param complete_function - function to call when the animation has completed.
+     *
      * `self`
      * object The current object.
      * `message_id`
      * hash The name of the completion message, `"animation_done"`.
      * `message`
      * table Information about the completion:
+     *
      * - number `current_tile` - the current tile of the sprite.
+     *
      * - hash `id` - id of the animation that was completed.
+     *
      * `sender`
      * url The invoker of the callback: the sprite component.
      * @param play_properties - optional table with properties:
+     *
      * `offset`
      * number the normalized initial value of the animation cursor when the animation starts playing.
      * `playback_rate`

package/generated/sys.d.ts

@@ -19,6 +19,18 @@ declare global {
      * no network connection found
      */
     const NETWORK_DISCONNECTED: number & { readonly __brand: "sys.NETWORK_DISCONNECTED" };
+    /**
+     * an asyncronous request is unable to read the resource
+     */
+    const REQUEST_STATUS_ERROR_IO_ERROR: number & { readonly __brand: "sys.REQUEST_STATUS_ERROR_IO_ERROR" };
+    /**
+     * an asyncronous request is unable to locate the resource
+     */
+    const REQUEST_STATUS_ERROR_NOT_FOUND: number & { readonly __brand: "sys.REQUEST_STATUS_ERROR_NOT_FOUND" };
+    /**
+     * an asyncronous request has finished successfully
+     */
+    const REQUEST_STATUS_FINISHED: number & { readonly __brand: "sys.REQUEST_STATUS_FINISHED" };
     /**
      * This function will raise a Lua error if an error occurs while deserializing the buffer.
      *
@@ -75,6 +87,7 @@ declare global {
      *
      * @param app_string - platform specific string with application package or query, see above for details.
      * @returns table with application information in the following fields:
+     *
      * `installed`
      * boolean `true` if the application is installed, `false` otherwise.
      * @example
@@ -201,8 +214,11 @@ declare global {
      * On desktop, this function always return `sys.NETWORK_CONNECTED`.
      *
      * @returns network connectivity status:
+     *
      * - `sys.NETWORK_DISCONNECTED` (no network connection is found)
+     *
      * - `sys.NETWORK_CONNECTED_CELLULAR` (connected through mobile cellular)
+     *
      * - `sys.NETWORK_CONNECTED` (otherwise, Wifi)
      * @example
      * ```ts
@@ -217,6 +233,7 @@ declare global {
      * Returns a table with engine information.
      *
      * @returns table with engine information in the following fields:
+     *
      * `version`
      * string The current Defold engine version, i.e. "1.2.96"
      * `version_sha1`
@@ -255,6 +272,7 @@ declare global {
      * Returns an array of tables with information on network interfaces.
      *
      * @returns an array of tables. Each table entry contain the following fields:
+     *
      * `name`
      * string Interface name
      * `address`
@@ -315,6 +333,7 @@ declare global {
      * @param options - optional options table
      * - ignore_secure boolean this flag ignores values might be secured by OS e.g. `device_ident`
      * @returns table with system information in the following fields:
+     *
      * `device_model`
      * string Only available on iOS and Android.
      * `manufacturer`
@@ -364,6 +383,96 @@ declare global {
      * ```
      */
     function load(filename: string): Record<string | number, unknown>;
+    /**
+     * The sys.load_buffer function will first try to load the resource
+     * from any of the mounted resource locations and return the data if
+     * any matching entries found. If not, the path will be tried
+     * as is from the primary disk on the device.
+     * In order for the engine to include custom resources in the build process, you need
+     * to specify them in the "custom_resources" key in your "game.project" settings file.
+     * You can specify single resource files or directories. If a directory is included
+     * in the resource list, all files and directories in that directory is recursively
+     * included:
+     * For example "main/data/,assets/level_data.json".
+     *
+     * @param path - the path to load the buffer from
+     * @returns the buffer with data
+     * @example
+     * ```ts
+     * // Load binary data from a custom project resource:
+     * const my_buffer = sys.load_buffer("/assets/my_level_data.bin");
+     * const data_str = buffer.get_bytes(my_buffer, "data");
+     * const has_my_header = data_str.slice(0, 6) === "D3F0LD";
+     *
+     * // Load binary data from non-custom resource files on disk:
+     * const asset_1 = sys.load_buffer("folder_next_to_binary/my_level_asset.txt");
+     * const asset_2 = sys.load_buffer("/my/absolute/path");
+     * ```
+     */
+    function load_buffer(path: string): Opaque<"buffer">;
+    /**
+     * The sys.load_buffer function will first try to load the resource
+     * from any of the mounted resource locations and return the data if
+     * any matching entries found. If not, the path will be tried
+     * as is from the primary disk on the device.
+     * In order for the engine to include custom resources in the build process, you need
+     * to specify them in the "custom_resources" key in your "game.project" settings file.
+     * You can specify single resource files or directories. If a directory is included
+     * in the resource list, all files and directories in that directory is recursively
+     * included:
+     * For example "main/data/,assets/level_data.json".
+     * Note that issuing multiple requests of the same resource will yield
+     * individual buffers per request. There is no implic caching of the buffers
+     * based on request path.
+     *
+     * @param path - the path to load the buffer from
+     * @param status_callback - A status callback that will be invoked when a request has been handled, or an error occured. The result is a table containing:
+     *
+     * `status`
+     * number The status of the request, supported values are:
+     *
+     * - `resource.REQUEST_STATUS_FINISHED`
+     *
+     * - `resource.REQUEST_STATUS_ERROR_IO_ERROR`
+     *
+     * - `resource.REQUEST_STATUS_ERROR_NOT_FOUND`
+     *
+     * `buffer`
+     * buffer If the request was successfull, this will contain the request payload in a buffer object, and nil otherwise. Make sure to check the status before doing anything with the buffer value!
+     * @returns a handle to the request
+     * @example
+     * ```ts
+     * // Load binary data from a custom project resource and update a texture resource:
+     * function my_callback(self, request_id, result) {
+     *   if (result.status === resource.REQUEST_STATUS_FINISHED) {
+     *     resource.set_texture("/my_texture", {}, result.buf); // texture args
+     *   }
+     * }
+     *
+     * const my_request = sys.load_buffer_async("/assets/my_level_data.bin", my_callback);
+     *
+     * // Load binary data from non-custom resource files on disk:
+     * function my_callback(self, request_id, result) {
+     *   if (result.status !== sys.REQUEST_STATUS_FINISHED) {
+     *     // uh oh! File could not be found, do something graceful
+     *   } else if (request_id === self.first_asset) {
+     *     // result.buffer contains data from my_level_asset.bin
+     *   } else if (request_id === self.second_asset) {
+     *     // result.buffer contains data from 'my_level.bin'
+     *   }
+     * }
+     *
+     * export default defineScript({
+     *   init(self) {
+     *     self.first_asset = hash("folder_next_to_binary/my_level_asset.bin");
+     *     self.second_asset = hash("/some_absolute_path/my_level.bin");
+     *     self.first_request = sys.load_buffer_async(self.first_asset, my_callback);
+     *     self.second_request = sys.load_buffer_async(self.second_asset, my_callback);
+     *   },
+     * });
+     * ```
+     */
+    function load_buffer_async(path: string, status_callback: (self: unknown, request_id: unknown, result: unknown) => void): number;
     /**
      * Loads a custom resource. Specify the full filename of the resource that you want
      * to load. When loaded, the file data is returned as a string.
@@ -484,11 +593,27 @@ declare global {
      * ```
      */
     function set_connectivity_host(host: string): void;
+    /**
+     * Enables engine throttling.
+     *
+     * @param enable - true if throttling should be enabled
+     * @param cooldown - the time period to do update + render for (seconds)
+     * @example
+     * ```ts
+     * // Disable throttling
+     * sys.set_engine_throttle(false);
+     *
+     * // Enable throttling
+     * sys.set_engine_throttle(true, 1.5);
+     * ```
+     */
+    function set_engine_throttle(enable: boolean, cooldown: number): void;
     /**
      * Set the Lua error handler function.
      * The error handler is a function which is called whenever a lua runtime error occurs.
      *
      * @param error_handler - the function to be called on error
+     *
      * `source`
      * string The runtime context of the error. Currently, this is always `"lua"`.
      * `message`
@@ -519,6 +644,17 @@ declare global {
      * ```
      */
     function set_error_handler(error_handler: (source: unknown, message: unknown, traceback: unknown) => void): void;
+    /**
+     * Disables rendering
+     *
+     * @param enable - true if throttling should be enabled
+     * @example
+     * ```ts
+     * // Disable rendering
+     * sys.set_render_enable(false);
+     * ```
+     */
+    function set_render_enable(enable: boolean): void;
     /**
      * Set game update-frequency (frame cap). This option is equivalent to `display.update_frequency` in
      * the "game.project" settings but set in run-time. If `Vsync` checked in "game.project", the rate will

package/generated/tilemap.d.ts

@@ -115,6 +115,7 @@ declare global {
      * The coordinates of the tiles are indexed so that the "first" tile just
      * above and to the right of origin has coordinates 1,1.
      * Tiles to the left of and below origin are indexed 0, -1, -2 and so forth.
+     *
      * +-------+-------+------+------+
      * | 0,3 | 1,3 | 2,3 | 3,3 |
      * +-------+-------+------+------+
@@ -124,6 +125,7 @@ declare global {
      * +-------O-------+------+------+
      * | 0,0 | 1,0 | 2,0 | 3,0 |
      * +-------+-------+------+------+
+     *
      * The coordinates must be within the bounds of the tile map as it were created.
      * That is, it is not possible to extend the size of a tile map by setting tiles outside the edges.
      * To clear a tile, set the tile to number 0. Which tile map and layer to manipulate is identified by the URL and the layer name parameters.

package/generated/timer.d.ts

@@ -2,6 +2,7 @@
 declare global {
   /**
    * Timers allow you to set a delay and a callback to be called when the timer completes.
+   *
    * The timers created with this API are updated with the collection timer where they
    * are created. If you pause or speed up the collection (using `set_time_step`) it will
    * also affect the new timer.
@@ -39,6 +40,7 @@ declare global {
      * @param delay - time interval in seconds
      * @param repeating - true = repeat timer until cancel, false = one-shot timer
      * @param callback - timer callback function
+     *
      * `self`
      * object The current object
      * `handle`
@@ -70,6 +72,7 @@ declare global {
      *
      * @param handle - the timer handle returned by timer.delay()
      * @returns table or `nil` if timer is cancelled/completed. table with data in the following fields:
+     *
      * `time_remaining`
      * number Time remaining until the next time a timer.delay() fires.
      * `delay`

package/generated/vmath.d.ts

@@ -4,23 +4,30 @@ import type { Matrix4, Quaternion, Vector, Vector3, Vector4 } from "../src/core-
 declare global {
   /**
    * Functions for mathematical operations on vectors, matrices and quaternions.
+   *
    * - The vector types (`vmath.vector3` and `vmath.vector4`) supports addition and subtraction
    * with vectors of the same type. Vectors can be negated and multiplied (scaled) or divided by numbers.
    * - The quaternion type (`vmath.quat`) supports multiplication with other quaternions.
    * - The matrix type (`vmath.matrix4`) can be multiplied with numbers, other matrices
    * and `vmath.vector4` values.
    * - All types performs equality comparison by each component value.
+   *
    * The following components are available for the various types:
+   *
    * vector3
    * : `x`, `y` and `z`. Example: `v.y`
+   *
    * vector4
    * : `x`, `y`, `z`, and `w`. Example: `v.w`
+   *
    * quaternion
    * : `x`, `y`, `z`, and `w`. Example: `q.w`
+   *
    * matrix4
    * : `m00` to `m33` where the first number is the row (starting from 0) and the second
    * number is the column. Columns can be accessed with `c0` to `c3`, returning a `vector4`.
    * Example: `m.m21` which is equal to `m.c1.z`
+   *
    * vector
    * : indexed by number 1 to the vector length. Example: `v[3]`
    */
@@ -88,8 +95,11 @@ declare global {
      * The returned value is a scalar defined as:
      * `P ⋅ Q = |P| |Q| cos θ`
      * where θ is the angle between the vectors P and Q.
+     *
      * - If the dot product is positive then the angle between the vectors is below 90 degrees.
+     *
      * - If the dot product is zero the vectors are perpendicular (at right-angles to each other).
+     *
      * - If the dot product is negative then the angle between the vectors is more than 90 degrees.
      *
      * @param v1 - first vector
@@ -218,20 +228,22 @@ declare global {
      * @param q2 - quaternion to lerp to
      * @returns the lerped quaternion
      * @example
-     * ```lua
-     * function init(self)
-     *     self.t = 0
-     * end
+     * ```ts
+     * export default defineScript({
+     *   init(self) {
+     *     self.t = 0;
+     *   },
      *
-     * function update(self, dt)
-     *     self.t = self.t + dt
-     *     if self.t <= 1 then
-     *         local startrot = vmath.quat_rotation_z(0)
-     *         local endrot = vmath.quat_rotation_z(3.141592653)
-     *         local rot = vmath.lerp(self.t, startrot, endrot)
-     *         go.set_rotation(rot, "go")
-     *     end
-     * end
+     *   update(self, dt) {
+     *     self.t = self.t + dt;
+     *     if (self.t <= 1) {
+     *       const startrot = vmath.quat_rotation_z(0);
+     *       const endrot = vmath.quat_rotation_z(3.141592653);
+     *       const rot = vmath.lerp(self.t, startrot, endrot);
+     *       go.set_rotation(rot, "go");
+     *     }
+     *   },
+     * });
      * ```
      */
     function lerp(t: number, q1: Quaternion, q2: Quaternion): Quaternion;
@@ -245,20 +257,22 @@ declare global {
      * @param n2 - number to lerp to
      * @returns the lerped number
      * @example
-     * ```lua
-     * function init(self)
-     *     self.t = 0
-     * end
+     * ```ts
+     * export default defineScript({
+     *   init(self) {
+     *     self.t = 0;
+     *   },
      *
-     * function update(self, dt)
-     *     self.t = self.t + dt
-     *     if self.t <= 1 then
-     *         local startx = 0
-     *         local endx = 600
-     *         local x = vmath.lerp(self.t, startx, endx)
-     *         go.set_position(vmath.vector3(x, 100, 0), "go")
-     *     end
-     * end
+     *   update(self, dt) {
+     *     self.t = self.t + dt;
+     *     if (self.t <= 1) {
+     *       const startx = 0;
+     *       const endx = 600;
+     *       const x = vmath.lerp(self.t, startx, endx);
+     *       go.set_position(vmath.vector3(x, 100, 0), "go");
+     *     }
+     *   },
+     * });
      * ```
      */
     function lerp(t: number, n1: number, n2: number): number;
@@ -286,13 +300,13 @@ declare global {
      * @param m1 - existing matrix
      * @returns matrix which is a copy of the specified matrix
      * @example
-     * ```lua
-     * local mat1 = vmath.matrix4_rotation_x(3.141592653)
-     * local mat2 = vmath.matrix4(mat1)
-     * if mat1 == mat2 then
-     *     -- yes, they are equal
-     *     print(mat2) --> vmath.matrix4(1, 0, 0, 0, 0, -1, 8.7422776573476e-08, 0, 0, -8.7422776573476e-08, -1, 0, 0, 0, 0, 1)
-     * end
+     * ```ts
+     * const mat1 = vmath.matrix4_rotation_x(3.141592653);
+     * const mat2 = vmath.matrix4(mat1);
+     * if (mat1 === mat2) {
+     *   // yes, they are equal
+     *   print(mat2); // => vmath.matrix4(1, 0, 0, 0, 0, -1, 8.7422776573476e-08, 0, 0, -8.7422776573476e-08, -1, 0, 0, 0, 0, 1)
+     * }
      * ```
      */
     function matrix4(m1: Matrix4): Matrix4;
@@ -492,9 +506,9 @@ declare global {
      * @param scale - scale
      * @returns new matrix4
      * @example
-     * ```lua
-     * local result = vmath.matrix4_scale(0.5)
-     * print(result) --> vmath.matrix4(0.5, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 1)
+     * ```ts
+     * const result = vmath.matrix4_scale(0.5);
+     * print(result); // => vmath.matrix4(0.5, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 1)
      * ```
      */
     function matrix4_scale(scale: number): Matrix4;
@@ -506,9 +520,9 @@ declare global {
      * @param scale_z - scale along Z asis
      * @returns new matrix4
      * @example
-     * ```lua
-     * local result = vmath.matrix4_scale(1, 0.5, 0.5)
-     * print(result) --> vmath.matrix4(1, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 1)
+     * ```ts
+     * const result = vmath.matrix4_scale(1, 0.5, 0.5);
+     * print(result); // => vmath.matrix4(1, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 1)
      * ```
      */
     function matrix4_scale(scale_x: number, scale_y: number, scale_z: number): Matrix4;
@@ -600,10 +614,10 @@ declare global {
      *
      * @returns new identity quaternion
      * @example
-     * ```lua
-     * local quat = vmath.quat()
-     * print(quat) --> vmath.quat(0, 0, 0, 1)
-     * print(quat.w) --> 1
+     * ```ts
+     * const quat = vmath.quat();
+     * print(quat); // => vmath.quat(0, 0, 0, 1)
+     * print(quat.w); // => 1
      * ```
      */
     function quat(): Quaternion;
@@ -615,13 +629,13 @@ declare global {
      * @param q1 - existing quaternion
      * @returns new quaternion
      * @example
-     * ```lua
-     * local quat1 = vmath.quat(1, 2, 3, 4)
-     * local quat2 = vmath.quat(quat1)
-     * if quat1 == quat2 then
-     *     -- yes, they are equal
-     *     print(quat2) --> vmath.quat(1, 2, 3, 4)
-     * end
+     * ```ts
+     * const quat1 = vmath.quat(1, 2, 3, 4);
+     * const quat2 = vmath.quat(quat1);
+     * if (quat1 === quat2) {
+     *   // yes, they are equal
+     *   print(quat2); // => vmath.quat(1, 2, 3, 4)
+     * }
      * ```
      */
     function quat(q1: Quaternion): Quaternion;
@@ -833,20 +847,22 @@ declare global {
      * @param q2 - quaternion to slerp to
      * @returns the slerped quaternion
      * @example
-     * ```lua
-     * function init(self)
-     *     self.t = 0
-     * end
+     * ```ts
+     * export default defineScript({
+     *   init(self) {
+     *     self.t = 0;
+     *   },
      *
-     * function update(self, dt)
-     *     self.t = self.t + dt
-     *     if self.t <= 1 then
-     *         local startrot = vmath.quat_rotation_z(0)
-     *         local endrot = vmath.quat_rotation_z(3.141592653)
-     *         local rot = vmath.slerp(self.t, startrot, endrot)
-     *         go.set_rotation(rot, "go")
-     *     end
-     * end
+     *   update(self, dt) {
+     *     self.t = self.t + dt;
+     *     if (self.t <= 1) {
+     *       const startrot = vmath.quat_rotation_z(0);
+     *       const endrot = vmath.quat_rotation_z(3.141592653);
+     *       const rot = vmath.slerp(self.t, startrot, endrot);
+     *       go.set_rotation(rot, "go");
+     *     }
+     *   },
+     * });
      * ```
      */
     function slerp(t: number, q1: Quaternion, q2: Quaternion): Quaternion;
@@ -874,10 +890,10 @@ declare global {
      *
      * @returns new zero vector
      * @example
-     * ```lua
-     * local vec = vmath.vector3()
-     * pprint(vec) --> vmath.vector3(0, 0, 0)
-     * print(vec.x) --> 0
+     * ```ts
+     * const vec = vmath.vector3();
+     * pprint(vec); // => vmath.vector3(0, 0, 0)
+     * print(vec.x); // => 0
      * ```
      */
     function vector3(): Vector3;
@@ -888,10 +904,10 @@ declare global {
      * @param n - scalar value to splat
      * @returns new vector
      * @example
-     * ```lua
-     * local vec = vmath.vector3(1.0)
-     * print(vec) --> vmath.vector3(1, 1, 1)
-     * print(vec.x) --> 1
+     * ```ts
+     * const vec = vmath.vector3(1.0);
+     * print(vec); // => vmath.vector3(1, 1, 1)
+     * print(vec.x); // => 1
      * ```
      */
     function vector3(n: number): Vector3;
@@ -903,13 +919,13 @@ declare global {
      * @param v1 - existing vector
      * @returns new vector
      * @example
-     * ```lua
-     * local vec1 = vmath.vector3(1.0)
-     * local vec2 = vmath.vector3(vec1)
-     * if vec1 == vec2 then
-     *     -- yes, they are equal
-     *     print(vec2) --> vmath.vector3(1, 1, 1)
-     * end
+     * ```ts
+     * const vec1 = vmath.vector3(1.0);
+     * const vec2 = vmath.vector3(vec1);
+     * if (vec1 === vec2) {
+     *   // yes, they are equal
+     *   print(vec2); // => vmath.vector3(1, 1, 1)
+     * }
      * ```
      */
     function vector3(v1: Vector3): Vector3;
@@ -937,10 +953,10 @@ declare global {
      *
      * @returns new zero vector
      * @example
-     * ```lua
-     * local vec = vmath.vector4()
-     * print(vec) --> vmath.vector4(0, 0, 0, 0)
-     * print(vec.w) --> 0
+     * ```ts
+     * const vec = vmath.vector4();
+     * print(vec); // => vmath.vector4(0, 0, 0, 0)
+     * print(vec.w); // => 0
      * ```
      */
     function vector4(): Vector4;
@@ -951,10 +967,10 @@ declare global {
      * @param n - scalar value to splat
      * @returns new vector
      * @example
-     * ```lua
-     * local vec = vmath.vector4(1.0)
-     * print(vec) --> vmath.vector4(1, 1, 1, 1)
-     * print(vec.w) --> 1
+     * ```ts
+     * const vec = vmath.vector4(1.0);
+     * print(vec); // => vmath.vector4(1, 1, 1, 1)
+     * print(vec.w); // => 1
      * ```
      */
     function vector4(n: number): Vector4;
@@ -966,13 +982,13 @@ declare global {
      * @param v1 - existing vector
      * @returns new vector
      * @example
-     * ```lua
-     * local vect1 = vmath.vector4(1.0)
-     * local vect2 = vmath.vector4(vec1)
-     * if vec1 == vec2 then
-     *     -- yes, they are equal
-     *     print(vec2) --> vmath.vector4(1, 1, 1, 1)
-     * end
+     * ```ts
+     * const vec1 = vmath.vector4(1.0);
+     * const vec2 = vmath.vector4(vec1);
+     * if (vec1 === vec2) {
+     *   // yes, they are equal
+     *   print(vec2); // => vmath.vector4(1, 1, 1, 1)
+     * }
      * ```
      */
     function vector4(v1: Vector4): Vector4;

package/generated/window.d.ts

@@ -51,8 +51,11 @@ declare global {
      * On platforms that does not support dimming, `window.DIMMING_UNKNOWN` is always returned.
      *
      * @returns The mode for screen dimming
+     *
      * - `window.DIMMING_UNKNOWN`
+     *
      * - `window.DIMMING_ON`
+     *
      * - `window.DIMMING_OFF`
      */
     function get_dim_mode(): Opaque<"constant">;
@@ -74,15 +77,24 @@ declare global {
      * this returns the full window size and zero insets.
      *
      * @returns safe area data
+     *
      * `safe_area`
      * table table containing these keys:
+     *
      * - number `x`
+     *
      * - number `y`
+     *
      * - number `width`
+     *
      * - number `height`
+     *
      * - number `inset_left`
+     *
      * - number `inset_top`
+     *
      * - number `inset_right`
+     *
      * - number `inset_bottom`
      */
     function get_safe_area(): { safe_area: { x: number; y: number; width: number; height: number; inset_left: number; inset_top: number; inset_right: number; inset_bottom: number } };
@@ -96,7 +108,9 @@ declare global {
      * This function has no effect on platforms that does not support dimming.
      *
      * @param mode - The mode for screen dimming
+     *
      * - `window.DIMMING_ON`
+     *
      * - `window.DIMMING_OFF`
      */
     function set_dim_mode(mode: Opaque<"constant">): void;
@@ -104,18 +118,27 @@ declare global {
      * Sets a window event listener. Only one window event listener can be set at a time.
      *
      * @param callback - A callback which receives info about window events. Pass an empty function or `nil` if you no longer wish to receive callbacks.
+     *
      * `self`
      * object The calling script
      * `event`
      * constant The type of event. Can be one of these:
+     *
      * - `window.WINDOW_EVENT_FOCUS_LOST`
+     *
      * - `window.WINDOW_EVENT_FOCUS_GAINED`
+     *
      * - `window.WINDOW_EVENT_RESIZED`
+     *
      * - `window.WINDOW_EVENT_ICONIFIED`
+     *
      * - `window.WINDOW_EVENT_DEICONIFIED`
+     *
      * `data`
      * table The callback value `data` is a table which currently holds these values
+     *
      * - number `width`: The width of a resize event. nil otherwise.
+     *
      * - number `height`: The height of a resize event. nil otherwise.
      * @example
      * ```ts