@defold-typescript/types 0.5.1 → 0.5.3

package/generated/sound.d.ts

@@ -152,28 +152,28 @@ declare global {
      *
      * @param url - the sound that should play
      * @param play_properties - optional table with properties:
-  `delay`
-  number delay in seconds before the sound starts playing, default is 0.
-  `gain`
-  number sound gain between 0 and 1, default is 1. The final gain of the sound will be a combination of this gain, the group gain and the master gain.
-  `pan`
-  number sound pan between -1 and 1, default is 0. The final pan of the sound will be an addition of this pan and the sound pan.
-  `speed`
-  number sound speed where 1.0 is normal speed, 0.5 is half speed and 2.0 is double speed. Valid range is 0.0 to 50.0. The final speed of the sound will be a multiplication of this speed and the sound speed.
-  `start_time`
-  number start playback offset (seconds). Optional, mutually exclusive with `start_frame`.
-  `start_frame`
-  number start playback offset (frames/samples). Optional, mutually exclusive with `start_time`. If both are provided, `start_frame` is used.
+     * `delay`
+     * number delay in seconds before the sound starts playing, default is 0.
+     * `gain`
+     * number sound gain between 0 and 1, default is 1. The final gain of the sound will be a combination of this gain, the group gain and the master gain.
+     * `pan`
+     * number sound pan between -1 and 1, default is 0. The final pan of the sound will be an addition of this pan and the sound pan.
+     * `speed`
+     * number sound speed where 1.0 is normal speed, 0.5 is half speed and 2.0 is double speed. Valid range is 0.0 to 50.0. The final speed of the sound will be a multiplication of this speed and the sound speed.
+     * `start_time`
+     * number start playback offset (seconds). Optional, mutually exclusive with `start_frame`.
+     * `start_frame`
+     * number start playback offset (frames/samples). Optional, mutually exclusive with `start_time`. If both are provided, `start_frame` is used.
      * @param complete_function - function to call when the sound has finished playing or stopped manually via sound.stop.
-  `self`
-  object The current object.
-  `message_id`
-  hash The name of the completion message, which can be either `"sound_done"` if the sound has finished playing, or `"sound_stopped"` if it was stopped manually.
-  `message`
-  table Information about the completion:
-  - number `play_id` - the sequential play identifier that was given by the sound.play function.
-  `sender`
-  url The invoker of the callback: the sound component.
+     * `self`
+     * object The current object.
+     * `message_id`
+     * hash The name of the completion message, which can be either `"sound_done"` if the sound has finished playing, or `"sound_stopped"` if it was stopped manually.
+     * `message`
+     * table Information about the completion:
+     * - number `play_id` - the sequential play identifier that was given by the sound.play function.
+     * `sender`
+     * url The invoker of the callback: the sound component.
      * @returns The identifier for the sound voice
      * @example
      * ```lua
@@ -236,8 +236,8 @@ declare global {
      *
      * @param url - the sound component that should stop
      * @param stop_properties - optional table with properties:
-  `play_id`
-  number the sequential play identifier that should be stopped (was given by the sound.play() function)
+     * `play_id`
+     * number the sequential play identifier that should be stopped (was given by the sound.play() function)
      * @example
      * ```lua
      * Assuming the script belongs to an instance with a sound-component with id "sound", this will make the component stop all playing voices:

package/generated/sprite.d.ts

@@ -12,21 +12,21 @@ 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.
+     * `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`
-  number the rate with which the animation will be played. Must be positive.
+     * `offset`
+     * number the normalized initial value of the animation cursor when the animation starts playing.
+     * `playback_rate`
+     * number the rate with which the animation will be played. Must be positive.
      * @example
      * ```lua
      * The following examples assumes that the model has id "sprite".

package/generated/sys.d.ts

@@ -68,8 +68,8 @@ 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.
+     * `installed`
+     * boolean `true` if the application is installed, `false` otherwise.
      * @example
      * ```lua
      * Check if twitter is installed:
@@ -194,9 +194,9 @@ 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)
+     * - `sys.NETWORK_DISCONNECTED` (no network connection is found)
+     * - `sys.NETWORK_CONNECTED_CELLULAR` (connected through mobile cellular)
+     * - `sys.NETWORK_CONNECTED` (otherwise, Wifi)
      * @example
      * ```lua
      * Check if we are connected through a cellular connection
@@ -210,12 +210,12 @@ 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`
-  string The SHA1 for the current engine build, i.e. "0060183cce2e29dbd09c85ece83cbb72068ee050"
-  `is_debug`
-  boolean If the engine is a debug or release version
+     * `version`
+     * string The current Defold engine version, i.e. "1.2.96"
+     * `version_sha1`
+     * string The SHA1 for the current engine build, i.e. "0060183cce2e29dbd09c85ece83cbb72068ee050"
+     * `is_debug`
+     * boolean If the engine is a debug or release version
      * @example
      * ```lua
      * How to retrieve engine information:
@@ -248,16 +248,16 @@ 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`
-  string IP address. might be `nil` if not available.
-  `mac`
-  string Hardware MAC address. might be nil if not available.
-  `up`
-  boolean `true` if the interface is up (available to transmit and receive data), `false` otherwise.
-  `running`
-  boolean `true` if the interface is running, `false` otherwise.
+     * `name`
+     * string Interface name
+     * `address`
+     * string IP address. might be `nil` if not available.
+     * `mac`
+     * string Hardware MAC address. might be nil if not available.
+     * `up`
+     * boolean `true` if the interface is up (available to transmit and receive data), `false` otherwise.
+     * `running`
+     * boolean `true` if the interface is running, `false` otherwise.
      * @example
      * ```lua
      * How to get the IP address of interface "en0":
@@ -306,30 +306,30 @@ declare global {
      * Returns a table with system information.
      *
      * @param options - optional options table
-  - ignore_secure boolean this flag ignores values might be secured by OS e.g. `device_ident`
+     * - 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`
-  string Only available on iOS and Android.
-  `system_name`
-  string The system name: "Darwin", "Linux", "Windows", "HTML5", "Android" or "iPhone OS"
-  `system_version`
-  string The system OS version.
-  `api_version`
-  string The API version on the system.
-  `language`
-  string Two character ISO-639 format, i.e. "en".
-  `device_language`
-  string Two character ISO-639 format (i.e. "sr") and, if applicable, followed by a dash (-) and an ISO 15924 script code (i.e. "sr-Cyrl" or "sr-Latn"). Reflects the device preferred language.
-  `territory`
-  string Two character ISO-3166 format, i.e. "US".
-  `gmt_offset`
-  number The current offset from GMT (Greenwich Mean Time), in minutes.
-  `device_ident`
-  string This value secured by OS. "identifierForVendor" on iOS. "android_id" on Android. On Android, you need to add `READ_PHONE_STATE` permission to be able to get this data. We don't use this permission in Defold.
-  `user_agent`
-  string The HTTP user agent, i.e. "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/602.4.8 (KHTML, like Gecko) Version/10.0.3 Safari/602.4.8"
+     * `device_model`
+     * string Only available on iOS and Android.
+     * `manufacturer`
+     * string Only available on iOS and Android.
+     * `system_name`
+     * string The system name: "Darwin", "Linux", "Windows", "HTML5", "Android" or "iPhone OS"
+     * `system_version`
+     * string The system OS version.
+     * `api_version`
+     * string The API version on the system.
+     * `language`
+     * string Two character ISO-639 format, i.e. "en".
+     * `device_language`
+     * string Two character ISO-639 format (i.e. "sr") and, if applicable, followed by a dash (-) and an ISO 15924 script code (i.e. "sr-Cyrl" or "sr-Latn"). Reflects the device preferred language.
+     * `territory`
+     * string Two character ISO-3166 format, i.e. "US".
+     * `gmt_offset`
+     * number The current offset from GMT (Greenwich Mean Time), in minutes.
+     * `device_ident`
+     * string This value secured by OS. "identifierForVendor" on iOS. "android_id" on Android. On Android, you need to add `READ_PHONE_STATE` permission to be able to get this data. We don't use this permission in Defold.
+     * `user_agent`
+     * string The HTTP user agent, i.e. "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/602.4.8 (KHTML, like Gecko) Version/10.0.3 Safari/602.4.8"
      * @example
      * ```lua
      * How to get system information:
@@ -388,13 +388,13 @@ declare global {
      *
      * @param url - url to open
      * @param attributes - table with attributes
-  `target`
-  - string : Optional. Specifies the target attribute or the name of the window. The following values are supported:
-  - `_self` - (default value) URL replaces the current page.
-  - `_blank` - URL is loaded into a new window, or tab.
-  - `_parent` - URL is loaded into the parent frame.
-  - `_top` - URL replaces any framesets that may be loaded.
-  - `name` - The name of the window (Note: the name does not specify the title of the new window).
+     * `target`
+     * - string : Optional. Specifies the target attribute or the name of the window. The following values are supported:
+     * - `_self` - (default value) URL replaces the current page.
+     * - `_blank` - URL is loaded into a new window, or tab.
+     * - `_parent` - URL is loaded into the parent frame.
+     * - `_top` - URL replaces any framesets that may be loaded.
+     * - `name` - The name of the window (Note: the name does not specify the title of the new window).
      * @returns a boolean indicating if the url could be opened or not
      * @example
      * ```lua
@@ -482,12 +482,12 @@ declare global {
      * 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`
-  string The source file, line number and error message.
-  `traceback`
-  string The stack traceback.
+     * `source`
+     * string The runtime context of the error. Currently, this is always `"lua"`.
+     * `message`
+     * string The source file, line number and error message.
+     * `traceback`
+     * string The stack traceback.
      * @example
      * ```lua
      * Install error handler that just prints the errors

package/generated/timer.d.ts

@@ -33,12 +33,12 @@ 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`
-  number The handle of the timer
-  `time_elapsed`
-  number The elapsed time - on first trigger it is time since timer.delay call, otherwise time since last trigger
+     * `self`
+     * object The current object
+     * `handle`
+     * number The handle of the timer
+     * `time_elapsed`
+     * number The elapsed time - on first trigger it is time since timer.delay call, otherwise time since last trigger
      * @returns identifier for the create timer, returns timer.INVALID_TIMER_HANDLE if the timer can not be created
      * @example
      * ```lua
@@ -64,12 +64,12 @@ 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`
-  number Time interval.
-  `repeating`
-  boolean true = repeat timer until cancel, false = one-shot timer.
+     * `time_remaining`
+     * number Time remaining until the next time a timer.delay() fires.
+     * `delay`
+     * number Time interval.
+     * `repeating`
+     * boolean true = repeat timer until cancel, false = one-shot timer.
      * @example
      * ```lua
      * self.handle = timer.delay(1, true, function() print("print every second") end)

package/generated/window.d.ts

@@ -47,9 +47,9 @@ 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`
+     * - `window.DIMMING_UNKNOWN`
+     * - `window.DIMMING_ON`
+     * - `window.DIMMING_OFF`
      */
     function get_dim_mode(): Opaque<"constant">;
     /**
@@ -70,16 +70,16 @@ 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`
+     * `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 } };
     /**
@@ -92,27 +92,27 @@ 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`
+     * - `window.DIMMING_ON`
+     * - `window.DIMMING_OFF`
      */
     function set_dim_mode(mode: Opaque<"constant">): void;
     /**
      * 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.
+     * `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
      * ```lua
      * function window_callback(self, event, data)

package/index.d.ts

@@ -1,5 +1,7 @@
 import "./generated/builtin-messages";
 import "./src/msg-overloads";
+import "./src/message-guard";
+import "./src/message-dispatch";
 import "./src/go-overloads";
 import "./src/engine-globals";
 import "./generated/b2d";
@@ -59,6 +61,8 @@ export {
   type InputAction,
   type InputTouch,
   type RenderScriptHooks,
+  SCRIPT_HOOK_NAMES,
+  type ScriptHookName,
   type ScriptHooks,
 } from "./src/lifecycle";
 export { type WrapOptions, wrapAsAmbientGlobal } from "./src/publish-dts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "type": "module",

package/scripts/regen.ts

@@ -209,6 +209,7 @@ export const RESTRICTED_NAMESPACES: Readonly<Record<string, string>> = {
 const UNIVERSAL_EXTRA_IMPORTS: readonly string[] = [
   "../builtin-messages",
   "../../src/msg-overloads",
+  "../../src/message-guard",
   "../../src/go-overloads",
 ];
 

package/src/doc-comment.ts

@@ -100,10 +100,18 @@ export function renderDocComment(parts: DocCommentParts): string[] {
   }
 
   for (const param of params) {
-    lines.push(` * @param ${param.name} - ${param.doc}`);
+    const [first, ...rest] = param.doc.split("\n");
+    lines.push(` * @param ${param.name} - ${first}`);
+    for (const line of rest) {
+      lines.push(line === "" ? " *" : ` * ${line}`);
+    }
   }
   if (returns !== "") {
-    lines.push(` * @returns ${returns}`);
+    const [first, ...rest] = returns.split("\n");
+    lines.push(` * @returns ${first}`);
+    for (const line of rest) {
+      lines.push(line === "" ? " *" : ` * ${line}`);
+    }
   }
   if (example !== "") {
     lines.push(" * @example");

package/src/index.ts

@@ -20,6 +20,8 @@ export {
   type InputAction,
   type InputTouch,
   type RenderScriptHooks,
+  SCRIPT_HOOK_NAMES,
+  type ScriptHookName,
   type ScriptHooks,
 } from "./lifecycle";
 export { type WrapOptions, wrapAsAmbientGlobal } from "./publish-dts";

package/src/message-dispatch.d.ts

@@ -0,0 +1,23 @@
+/** @noSelfInFile */
+import type { Hash, Url } from "./core-types";
+
+declare global {
+  // DU-style dispatcher built on `isMessage`'s receive-side narrowing
+  // (message-guard.d.ts): each handler key is a `BuiltinMessageId` and its
+  // `message` param narrows to that id's `BuiltinMessages` payload. It returns
+  // an `on_message` handler so it reads as `on_message: onMessage<Self>({ ... })`;
+  // `self` threads via the explicit type argument, mirroring `defineScript<Self>`.
+  // The transpiler lowers the call to a flat `message_id == hash("...")`
+  // if/elseif chain (message-dispatch-lowering.ts), keeping this package free of
+  // runtime Lua.
+  function onMessage<TSelf = Record<never, never>>(
+    handlers: Partial<{
+      [K in BuiltinMessageId]: (self: TSelf, message: BuiltinMessages[K], sender: Url) => void;
+    }>,
+  ): (
+    self: TSelf,
+    message_id: Hash,
+    message: Record<string | number, unknown>,
+    sender: Url,
+  ) => void;
+}

package/src/message-guard.d.ts

@@ -0,0 +1,16 @@
+/** @noSelfInFile */
+import type { Hash } from "./core-types";
+
+declare global {
+  // Receive-side mirror of `msg.post`'s send-side narrowing (msg-overloads.d.ts).
+  // Defold delivers `message_id` as a pre-hashed `Hash`, so the literal a
+  // discriminated union would need is gone; re-introducing it here lets the
+  // untyped `message` record narrow to its `BuiltinMessages` payload. The
+  // transpiler lowers the call to `message_id == hash("...")`
+  // (message-guard-lowering.ts), keeping this package free of runtime Lua.
+  function isMessage<K extends BuiltinMessageId>(
+    message_id: Hash,
+    message: Record<string | number, unknown>,
+    expected: K,
+  ): message is BuiltinMessages[K];
+}