@defold-typescript/types 0.38.0 → 0.39.0

package/generated/versions/defold-1.13.0/sys.d.ts

@@ -1,5 +1,5 @@
 /** @noSelfInFile */
-import type { Opaque } from "../../../src/core-types";
+import type { Hash, Opaque } from "../../../src/core-types";
 
 declare global {
   /**
@@ -7,6 +7,7 @@ declare global {
    * error handling and debugging.
    */
   namespace sys {
+    type NetworkConnectivity = typeof sys.NETWORK_DISCONNECTED | typeof sys.NETWORK_CONNECTED_CELLULAR | typeof sys.NETWORK_CONNECTED;
     /**
      * network connected through other, non cellular, connection
      */
@@ -39,6 +40,7 @@ declare global {
      * @example
      * ```ts
      * // Deserialize a table that was previously serialized:
+     * const my_table = { score: 100, level: 3 };
      * const buffer = sys.serialize(my_table);
      * const table = sys.deserialize(buffer);
      * ```
@@ -53,6 +55,7 @@ declare global {
      * @example
      * ```ts
      * // Load data but return nil if path didn't exist
+     * const path = "/save/game.dat";
      * if (!sys.exists(path)) {
      *   return undefined;
      * }
@@ -228,7 +231,7 @@ declare global {
      * }
      * ```
      */
-    function get_connectivity(): number & { readonly __brand: "sys.NETWORK_DISCONNECTED" } | number & { readonly __brand: "sys.NETWORK_CONNECTED_CELLULAR" } | number & { readonly __brand: "sys.NETWORK_CONNECTED" };
+    function get_connectivity(): sys.NetworkConnectivity;
     /**
      * Returns a table with engine information.
      *
@@ -259,6 +262,7 @@ declare global {
      * @example
      * ```ts
      * // Save data on the host
+     * const mytable = { score: 100, level: 3 };
      * const host_path = sys.get_host_path("logs/test.txt");
      * sys.save(host_path, mytable);
      *
@@ -443,21 +447,23 @@ declare global {
      * @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
+     * function my_callback(self: unknown, request_id: unknown, result: unknown) {
+     *   const { status, buf } = result as { status: number; buf: Opaque<"buffer"> };
+     *   if (status === resource.REQUEST_STATUS_FINISHED) {
+     *     resource.set_texture("/my_texture", {}, 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) {
+     * function my_callback(self: unknown, request_id: unknown, result: unknown) {
+     *   const { first_asset, second_asset } = self as { first_asset: Hash; second_asset: Hash };
+     *   if ((result as { status: number }).status !== sys.REQUEST_STATUS_FINISHED) {
      *     // uh oh! File could not be found, do something graceful
-     *   } else if (request_id === self.first_asset) {
+     *   } else if (request_id === first_asset) {
      *     // result.buffer contains data from my_level_asset.bin
-     *   } else if (request_id === self.second_asset) {
+     *   } else if (request_id === second_asset) {
      *     // result.buffer contains data from 'my_level.bin'
      *   }
      * }
@@ -623,7 +629,7 @@ declare global {
      * @example
      * ```ts
      * // Install error handler that just prints the errors
-     * function my_error_handler(source, message, traceback) {
+     * function my_error_handler(source: unknown, message: unknown, traceback: unknown) {
      *   print(source); //> lua
      *   print(message); //> main/my.script:10: attempt to perform arithmetic on a string value
      *   print(traceback); //> stack traceback:

package/generated/versions/defold-1.13.0/tilemap.d.ts

@@ -55,8 +55,10 @@ declare global {
      * @returns index of the tile
      * @example
      * ```ts
-     * // get the tile under the player.
-     * const tileno = tilemap.get_tile("/level#tilemap", "foreground", self.player_x, self.player_y);
+     * function tile_under_player(self: { player_x: number; player_y: number }) {
+     *   // get the tile under the player.
+     *   const tileno = tilemap.get_tile("/level#tilemap", "foreground", self.player_x, self.player_y);
+     * }
      * ```
      */
     function get_tile(url: string | Hash | Url, layer: string | Hash, x: number, y: number): number;
@@ -74,15 +76,17 @@ declare global {
      * @returns index of the tile
      * @example
      * ```ts
-     * // get the tile under the player.
-     * const tile_info = tilemap.get_tile_info("/level#tilemap", "foreground", self.player_x, self.player_y);
-     * pprint(tile_info);
-     * // {
-     * //    index = 0,
-     * //    h_flip = false,
-     * //    v_flip = true,
-     * //    rotate_90 = false
-     * // }
+     * function tile_info_under_player(self: { player_x: number; player_y: number }) {
+     *   // get the tile under the player.
+     *   const tile_info = tilemap.get_tile_info("/level#tilemap", "foreground", self.player_x, self.player_y);
+     *   pprint(tile_info);
+     *   // {
+     *   //    index = 0,
+     *   //    h_flip = false,
+     *   //    v_flip = true,
+     *   //    rotate_90 = false
+     *   // }
+     * }
      * ```
      */
     function get_tile_info(url: string | Hash | Url, layer: string | Hash, x: number, y: number): { index: number; h_flip: boolean; v_flip: boolean; rotate_90: boolean };
@@ -103,7 +107,7 @@ declare global {
      * let count = 0;
      * for (let row_index = bottom; row_index <= bottom + rows_count - 1; row_index++) {
      *   for (let column_index = left; column_index <= left + columns_count - 1; column_index++) {
-     *     tile = tiles[row_index][column_index];
+     *     tile = tiles.get(row_index)?.get(column_index) ?? 0;
      *     count = count + 1;
      *   }
      * }
@@ -155,14 +159,16 @@ declare global {
      * @param transform_bitmask - optional flip and/or rotation should be applied to the tile
      * @example
      * ```ts
-     * // Clear the tile under the player.
-     * tilemap.set_tile("/level#tilemap", "foreground", self.player_x, self.player_y, 0);
+     * function set_tiles(self: { player_x: number; player_y: number }, x: number, y: number) {
+     *   // Clear the tile under the player.
+     *   tilemap.set_tile("/level#tilemap", "foreground", self.player_x, self.player_y, 0);
      *
-     * // Set tile with different combination of flip and rotation
-     * tilemap.set_tile("#tilemap", "layer1", x, y, 0, tilemap.H_FLIP + tilemap.V_FLIP + tilemap.ROTATE_90);
-     * tilemap.set_tile("#tilemap", "layer1", x, y, 0, tilemap.H_FLIP + tilemap.ROTATE_270);
-     * tilemap.set_tile("#tilemap", "layer1", x, y, 0, tilemap.V_FLIP + tilemap.H_FLIP);
-     * tilemap.set_tile("#tilemap", "layer1", x, y, 0, tilemap.ROTATE_180);
+     *   // Set tile with different combination of flip and rotation
+     *   tilemap.set_tile("#tilemap", "layer1", x, y, 0, tilemap.H_FLIP + tilemap.V_FLIP + tilemap.ROTATE_90);
+     *   tilemap.set_tile("#tilemap", "layer1", x, y, 0, tilemap.H_FLIP + tilemap.ROTATE_270);
+     *   tilemap.set_tile("#tilemap", "layer1", x, y, 0, tilemap.V_FLIP + tilemap.H_FLIP);
+     *   tilemap.set_tile("#tilemap", "layer1", x, y, 0, tilemap.ROTATE_180);
+     * }
      * ```
      */
     function set_tile(url: string | Hash | Url, layer: string | Hash, x: number, y: number, tile: number, transform_bitmask?: number): void;

package/generated/versions/defold-1.13.0/timer.d.ts

@@ -20,11 +20,13 @@ declare global {
      * @returns if the timer was active, false if the timer is already cancelled / complete
      * @example
      * ```ts
-     * self.handle = timer.delay(1, true, () => print("print every second"));
-     * // ...
-     * const result = timer.cancel(self.handle);
-     * if (!result) {
-     *   print("the timer is already cancelled");
+     * function cancel_ticking(self: { handle: number }) {
+     *   self.handle = timer.delay(1, true, () => print("print every second"));
+     *   // ...
+     *   const result = timer.cancel(self.handle);
+     *   if (!result) {
+     *     print("the timer is already cancelled");
+     *   }
      * }
      * ```
      */
@@ -54,16 +56,19 @@ declare global {
      * timer.delay(1, false, () => print("print in one second"));
      *
      * // Repetitive timer which canceled after 10 calls
-     * function call_every_second(self, handle, time_elapsed) {
-     *   self.counter = self.counter + 1;
-     *   print("Call #", self.counter);
-     *   if (self.counter === 10) {
-     *     timer.cancel(handle); // cancel timer after 10 calls
+     * function call_every_second(self: unknown, handle: unknown, time_elapsed: unknown) {
+     *   const state = self as { counter: number };
+     *   state.counter = state.counter + 1;
+     *   print("Call #", state.counter);
+     *   if (state.counter === 10) {
+     *     timer.cancel(handle as number); // cancel timer after 10 calls
      *   }
      * }
      *
-     * self.counter = 0;
-     * timer.delay(1, true, call_every_second);
+     * function start_counting(self: { counter: number }) {
+     *   self.counter = 0;
+     *   timer.delay(1, true, call_every_second);
+     * }
      * ```
      */
     function delay(delay: number, repeating: boolean, callback: (self: unknown, handle: unknown, time_elapsed: unknown) => void): number;
@@ -81,13 +86,15 @@ declare global {
      * boolean true = repeat timer until cancel, false = one-shot timer.
      * @example
      * ```ts
-     * self.handle = timer.delay(1, true, () => print("print every second"));
-     * // ...
-     * const result = timer.get_info(self.handle);
-     * if (!result) {
-     *   print("the timer is already cancelled or complete");
-     * } else {
-     *   pprint(result); // delay, time_remaining, repeating
+     * function report_ticking(self: { handle: number }) {
+     *   self.handle = timer.delay(1, true, () => print("print every second"));
+     *   // ...
+     *   const result = timer.get_info(self.handle);
+     *   if (!result) {
+     *     print("the timer is already cancelled or complete");
+     *   } else {
+     *     pprint(result); // delay, time_remaining, repeating
+     *   }
      * }
      * ```
      */
@@ -99,11 +106,13 @@ declare global {
      * @returns if the timer was active, false if the timer is already cancelled / complete
      * @example
      * ```ts
-     * self.handle = timer.delay(1, true, () => print("print every second or manually by timer.trigger"));
-     * // ...
-     * const result = timer.trigger(self.handle);
-     * if (!result) {
-     *   print("the timer is already cancelled or complete");
+     * function trigger_ticking(self: { handle: number }) {
+     *   self.handle = timer.delay(1, true, () => print("print every second or manually by timer.trigger"));
+     *   // ...
+     *   const result = timer.trigger(self.handle);
+     *   if (!result) {
+     *     print("the timer is already cancelled or complete");
+     *   }
      * }
      * ```
      */

package/generated/versions/defold-1.13.0/vmath.d.ts

@@ -84,6 +84,9 @@ declare global {
      * @returns dot product
      * @example
      * ```ts
+     * const vector1 = vmath.vector3(1, 0, 0);
+     * const vector2 = vmath.vector3(0, 1, 0);
+     *
      * if (vmath.dot(vector1, vector2) === 0) {
      *   // The two vectors are perpendicular (at right-angles to each other)
      *   // ...
@@ -119,12 +122,14 @@ declare global {
      * @returns length
      * @example
      * ```ts
-     * if (vmath.length(self.velocity) < max_velocity) {
-     *   // The speed (velocity vector) is below max.
+     * function below_max_speed(self: { velocity: Vector3 }, max_velocity: number) {
+     *   if (vmath.length(self.velocity) < max_velocity) {
+     *     // The speed (velocity vector) is below max.
      *
-     *   // TODO: max_velocity can be expressed as squared
-     *   // so we can compare with length_sqr() instead.
-     *   // ...
+     *     // TODO: max_velocity can be expressed as squared
+     *     // so we can compare with length_sqr() instead.
+     *     // ...
+     *   }
      * }
      * ```
      */
@@ -136,6 +141,9 @@ declare global {
      * @returns squared length
      * @example
      * ```ts
+     * const vector1 = vmath.vector3(1, 0, 0);
+     * const vector2 = vmath.vector3(0, 2, 0);
+     *
      * if (vmath.length_sqr(vector1) < vmath.length_sqr(vector2)) {
      *   // Vector 1 has less magnitude than vector 2
      *   // ...

package/generated/versions/defold-1.13.0/window.d.ts

@@ -5,6 +5,8 @@ declare global {
    * and screen dimming.
    */
   namespace window {
+    type DimModeState = typeof window.DIMMING_UNKNOWN | typeof window.DIMMING_ON | typeof window.DIMMING_OFF;
+    type DimModeStateSettable = typeof window.DIMMING_ON | typeof window.DIMMING_OFF;
     /**
      * Dimming mode is used to control whether or not a mobile device should dim the screen after a period without user interaction.
      */
@@ -56,7 +58,7 @@ declare global {
      *
      * - `window.DIMMING_OFF`
      */
-    function get_dim_mode(): number & { readonly __brand: "window.DIMMING_UNKNOWN" } | number & { readonly __brand: "window.DIMMING_ON" } | number & { readonly __brand: "window.DIMMING_OFF" };
+    function get_dim_mode(): window.DimModeState;
     /**
      * This returns the content scale of the current display.
      *
@@ -111,7 +113,7 @@ declare global {
      *
      * - `window.DIMMING_OFF`
      */
-    function set_dim_mode(mode: number & { readonly __brand: "window.DIMMING_ON" } | number & { readonly __brand: "window.DIMMING_OFF" }): void;
+    function set_dim_mode(mode: window.DimModeStateSettable): void;
     /**
      * Sets a window event listener. Only one window event listener can be set at a time.
      *
@@ -140,7 +142,7 @@ declare global {
      * - number `height`: The height of a resize event. nil otherwise.
      * @example
      * ```ts
-     * function window_callback(self, event, data) {
+     * function window_callback(self: unknown, event: unknown, data: Record<string | number, unknown>) {
      *   if (event === window.WINDOW_EVENT_FOCUS_LOST) {
      *     print("window.WINDOW_EVENT_FOCUS_LOST");
      *   } else if (event === window.WINDOW_EVENT_FOCUS_GAINED) {

package/generated/vmath.d.ts

@@ -84,6 +84,9 @@ declare global {
      * @returns dot product
      * @example
      * ```ts
+     * const vector1 = vmath.vector3(1, 0, 0);
+     * const vector2 = vmath.vector3(0, 1, 0);
+     *
      * if (vmath.dot(vector1, vector2) === 0) {
      *   // The two vectors are perpendicular (at right-angles to each other)
      *   // ...
@@ -119,12 +122,14 @@ declare global {
      * @returns length
      * @example
      * ```ts
-     * if (vmath.length(self.velocity) < max_velocity) {
-     *   // The speed (velocity vector) is below max.
+     * function below_max_speed(self: { velocity: Vector3 }, max_velocity: number) {
+     *   if (vmath.length(self.velocity) < max_velocity) {
+     *     // The speed (velocity vector) is below max.
      *
-     *   // TODO: max_velocity can be expressed as squared
-     *   // so we can compare with length_sqr() instead.
-     *   // ...
+     *     // TODO: max_velocity can be expressed as squared
+     *     // so we can compare with length_sqr() instead.
+     *     // ...
+     *   }
      * }
      * ```
      */
@@ -136,6 +141,9 @@ declare global {
      * @returns squared length
      * @example
      * ```ts
+     * const vector1 = vmath.vector3(1, 0, 0);
+     * const vector2 = vmath.vector3(0, 2, 0);
+     *
      * if (vmath.length_sqr(vector1) < vmath.length_sqr(vector2)) {
      *   // Vector 1 has less magnitude than vector 2
      *   // ...

package/generated/window.d.ts

@@ -5,6 +5,8 @@ declare global {
    * and screen dimming.
    */
   namespace window {
+    type DimModeState = typeof window.DIMMING_UNKNOWN | typeof window.DIMMING_ON | typeof window.DIMMING_OFF;
+    type DimModeStateSettable = typeof window.DIMMING_ON | typeof window.DIMMING_OFF;
     /**
      * Dimming mode is used to control whether or not a mobile device should dim the screen after a period without user interaction.
      */
@@ -56,7 +58,7 @@ declare global {
      *
      * - `window.DIMMING_OFF`
      */
-    function get_dim_mode(): number & { readonly __brand: "window.DIMMING_UNKNOWN" } | number & { readonly __brand: "window.DIMMING_ON" } | number & { readonly __brand: "window.DIMMING_OFF" };
+    function get_dim_mode(): window.DimModeState;
     /**
      * This returns the content scale of the current display.
      *
@@ -111,7 +113,7 @@ declare global {
      *
      * - `window.DIMMING_OFF`
      */
-    function set_dim_mode(mode: number & { readonly __brand: "window.DIMMING_ON" } | number & { readonly __brand: "window.DIMMING_OFF" }): void;
+    function set_dim_mode(mode: window.DimModeStateSettable): void;
     /**
      * Sets a window event listener. Only one window event listener can be set at a time.
      *
@@ -140,7 +142,7 @@ declare global {
      * - number `height`: The height of a resize event. nil otherwise.
      * @example
      * ```ts
-     * function window_callback(self, event, data) {
+     * function window_callback(self: unknown, event: unknown, data: Record<string | number, unknown>) {
      *   if (event === window.WINDOW_EVENT_FOCUS_LOST) {
      *     print("window.WINDOW_EVENT_FOCUS_LOST");
      *   } else if (event === window.WINDOW_EVENT_FOCUS_GAINED) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -70,6 +70,7 @@
     "!scripts/fidelity-audit.ts",
     "!scripts/augmentation-namespaces.ts",
     "!scripts/example-pins.ts",
+    "!scripts/example-semantics.ts",
     "!scripts/example-surfaces.ts",
     "!scripts/example-typecheck.ts"
   ],

package/src/api-doc.ts

@@ -20,6 +20,10 @@ export interface ApiTypedef {
   name: string;
   functions?: ApiFunction[];
   properties?: ApiVariable[];
+  /** A union alias's top-level arms; a shape with members carries none. */
+  types?: string[];
+  /** The type text of each parent an interface-backed typedef extends. */
+  extends?: string[];
   /** See {@link ApiFunction.global}. */
   global?: true;
 }
@@ -164,10 +168,14 @@ export function parseDefoldApiDoc(input: unknown): ApiModule {
 function parseTypedef(element: Record<string, unknown>): ApiTypedef {
   const functions = parseFunctionList(element.functions);
   const properties = parseVariableList(element.properties);
+  const types = parseStringArray(element.types);
+  const parents = parseStringArray(element.extends);
   return {
     name: stringOr(element.name, ""),
     ...(functions.length > 0 ? { functions } : {}),
     ...(properties.length > 0 ? { properties } : {}),
+    ...(types.length > 0 ? { types } : {}),
+    ...(parents.length > 0 ? { extends: parents } : {}),
     ...globalKey(element),
   };
 }