@defold-typescript/types 0.5.4 → 0.6.0

package/generated/socket.d.ts

@@ -2,6 +2,22 @@
 import type { Opaque } from "../src/core-types";
 
 declare global {
+  /**
+   * [LuaSocket](https://github.com/diegonehab/luasocket) is a Lua extension library that provides
+   * support for the TCP and UDP transport layers. Defold provides the "socket" namespace in
+   * runtime, which contain the core C functionality. Additional LuaSocket support modules for
+   * SMTP, HTTP, FTP etc are not part of the core included, but can be easily added to a project
+   * and used.
+   * [icon:html5] On HTML5, the non-network helpers remain available, but TCP, UDP and
+   * `socket.select()` are not supported.
+   * Note the included helper module "socket.lua" in "builtins/scripts/socket.lua". Require this
+   * module to add some additional functions and shortcuts to the namespace:
+   * ```lua
+   * require "builtins.scripts.socket"
+   * ```
+   * LuaSocket is Copyright © 2004-2007 Diego Nehab. All rights reserved.
+   * LuaSocket is free software, released under the MIT license (same license as the Lua core).
+   */
   namespace socket {
     type client = Opaque<"client">;
     type master = Opaque<"master">;
@@ -34,11 +50,11 @@ declare global {
      *
      * @returns the number of seconds elapsed.
      * @example
-     * ```lua
-     * How to use the gettime() function to measure running time:
-     * t = socket.gettime()
-     * -- do stuff
-     * print(socket.gettime() - t .. " seconds elapsed")
+     * ```ts
+     * // How to use the gettime() function to measure running time:
+     * const t = socket.gettime();
+     * // do stuff
+     * print(`${socket.gettime() - t} seconds elapsed`);
      * ```
      */
     function gettime(): number;
@@ -49,16 +65,16 @@ declare global {
      * @param finalizer - a function that will be called before the try throws the exception.
      * @returns the customized try function.
      * @example
-     * ```lua
-     * Perform operations on an open socket c:
-     * -- create a try function that closes 'c' on error
-     * local try = socket.newtry(function() c:close() end)
-     * -- do everything reassured c will be closed
-     * try(c:send("hello there?\r\n"))
-     * local answer = try(c:receive())
-     * ...
-     * try(c:send("good bye\r\n"))
-     * c:close()
+     * ```ts
+     * // Perform operations on an open socket c:
+     * // create a try function that closes 'c' on error
+     * const try_ = socket.newtry(() => c.close());
+     * // do everything reassured c will be closed
+     * try_(c.send("hello there?\r\n"));
+     * const answer = try_(c.receive());
+     * // ...
+     * try_(c.send("good bye\r\n"));
+     * c.close();
      * ```
      */
     function newtry(finalizer: () => void): (...args: unknown[]) => unknown;
@@ -69,17 +85,17 @@ declare global {
      * @param func - a function that calls a try function (or assert, or error) to throw exceptions.
      * @returns an equivalent function that instead of throwing exceptions, returns `nil` followed by an error message.
      * @example
-     * ```lua
-     * local dostuff = socket.protect(function()
-     *     local try = socket.newtry()
-     *     local c = try(socket.connect("myserver.com", 80))
-     *     try = socket.newtry(function() c:close() end)
-     *     try(c:send("hello?\r\n"))
-     *     local answer = try(c:receive())
-     *     c:close()
-     * end)
+     * ```ts
+     * const dostuff = socket.protect(() => {
+     *   let try_ = socket.newtry();
+     *   const c = try_(socket.connect("myserver.com", 80));
+     *   try_ = socket.newtry(() => c.close());
+     *   try_(c.send("hello?\r\n"));
+     *   const answer = try_(c.receive());
+     *   c.close();
+     * });
      *
-     * local n, error = dostuff()
+     * const [n, error] = dostuff();
      * ```
      */
     function protect(func: (...args: unknown[]) => unknown): (arg0: unknown) => void;
@@ -97,7 +113,7 @@ declare global {
      * @param sendt - array with sockets that are watched to see if it is OK to immediately write on them.
      * @param timeout - the maximum amount of time (in seconds) to wait for a change in status. Nil, negative or omitted timeout value allows the function to block indefinitely.
      */
-    function select(recvt: Record<string | number, unknown>, sendt: Record<string | number, unknown>, timeout?: number): LuaMultiReturn<[Record<string | number, unknown>, Record<string | number, unknown>, string | unknown]>;
+    function select(recvt: (Opaque<"client"> | Opaque<"master"> | Opaque<"unconnected">)[], sendt: (Opaque<"client"> | Opaque<"master"> | Opaque<"unconnected">)[], timeout?: number): LuaMultiReturn<[(Opaque<"client"> | Opaque<"master"> | Opaque<"unconnected">)[], (Opaque<"client"> | Opaque<"master"> | Opaque<"unconnected">)[], string | unknown]>;
     /**
      * This function drops a number of arguments and returns the remaining.
      * It is useful to avoid creation of dummy variables:
@@ -109,14 +125,14 @@ declare global {
      * @param ret2 - argument 2.
      * @param retN - argument N.
      * @example
-     * ```lua
-     * Instead of doing the following with dummy variables:
-     * -- get the status code and separator from SMTP server reply
-     * local dummy1, dummy2, code, sep = string.find(line, "^(%d%d%d)(.?)")
+     * ```ts
+     * // Instead of doing the following with dummy variables:
+     * // get the status code and separator from SMTP server reply
+     * const [dummy1, dummy2, code, sep] = string.find(line, "^(%d%d%d)(.?)");
      *
-     * You can skip a number of variables:
-     * -- get the status code and separator from SMTP server reply
-     * local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
+     * // You can skip a number of variables:
+     * // get the status code and separator from SMTP server reply
+     * const [code, sep] = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"));
      * ```
      */
     function skip(d: number, ret1?: unknown, ret2?: unknown, retN?: unknown): LuaMultiReturn<[unknown, unknown, unknown]>;

package/generated/sound.d.ts

@@ -2,6 +2,10 @@
 import type { Hash, Url } from "../src/core-types";
 
 declare global {
+  /**
+   * Functions and messages for controlling sound components and
+   * mixer groups.
+   */
   namespace sound {
     /**
      * Get mixer group gain
@@ -9,10 +13,10 @@ declare global {
      * @param group - group name
      * @returns gain in [0 1] range ([-60dB.. 0dB])
      * @example
-     * ```lua
-     * Get the mixer group gain for the "soundfx" and convert to dB:
-     * local gain = sound.get_group_gain("soundfx")
-     * local gain_db = 60 * gain
+     * ```ts
+     * // Get the mixer group gain for the "soundfx" and convert to dB:
+     * const gain = sound.get_group_gain("soundfx");
+     * const gain_db = 60 * gain;
      * ```
      */
     function get_group_gain(group: string | Hash): number;
@@ -25,13 +29,13 @@ declare global {
      * @param group - group name
      * @returns group name
      * @example
-     * ```lua
-     * Get the mixer group string names so we can show them as labels on a dev mixer overlay:
-     * local groups = sound.get_groups()
-     * for _,group in ipairs(groups) do
-     *     local name = sound.get_group_name(group)
-     *     msg.post("/mixer_overlay#gui", "set_mixer_label", { group = group, label = name})
-     * end
+     * ```ts
+     * // Get the mixer group string names so we can show them as labels on a dev mixer overlay:
+     * const groups = sound.get_groups();
+     * for (const group of groups) {
+     *   const name = sound.get_group_name(group);
+     *   msg.post("/mixer_overlay#gui", "set_mixer_label", { group: group, label: name });
+     * }
      * ```
      */
     function get_group_name(group: string | Hash): string;
@@ -40,17 +44,17 @@ declare global {
      *
      * @returns table of mixer group names
      * @example
-     * ```lua
-     * Get the mixer groups, set all gains to 0 except for "master" and "soundfx"
-     * where gain is set to 1:
-     * local groups = sound.get_groups()
-     * for _,group in ipairs(groups) do
-     *     if group == hash("master") or group == hash("soundfx") then
-     *         sound.set_group_gain(group, 1)
-     *     else
-     *         sound.set_group_gain(group, 0)
-     *     end
-     * end
+     * ```ts
+     * // Get the mixer groups, set all gains to 0 except for "master" and "soundfx"
+     * // where gain is set to 1:
+     * const groups = sound.get_groups();
+     * for (const group of groups) {
+     *   if (group === hash("master") || group === hash("soundfx")) {
+     *     sound.set_group_gain(group, 1);
+     *   } else {
+     *     sound.set_group_gain(group, 0);
+     *   }
+     * }
      * ```
      */
     function get_groups(): Hash[];
@@ -66,11 +70,11 @@ declare global {
      * @param group - group name
      * @param window - window length in seconds
      * @example
-     * ```lua
-     * Get the peak gain from the "master" group and convert to dB for displaying:
-     * local left_p, right_p = sound.get_peak("master", 0.1)
-     * left_p_db = 20 * log(left_p)
-     * right_p_db = 20 * log(right_p)
+     * ```ts
+     * // Get the peak gain from the "master" group and convert to dB for displaying:
+     * const [left_p, right_p] = sound.get_peak("master", 0.1);
+     * const left_p_db = 20 * Math.log(left_p);
+     * const right_p_db = 20 * Math.log(right_p);
      * ```
      */
     function get_peak(group: string | Hash, window: number): LuaMultiReturn<[number, number]>;
@@ -86,10 +90,10 @@ declare global {
      * @param group - group name
      * @param window - window length in seconds
      * @example
-     * ```lua
-     * Get the RMS from the "master" group where a mono -1.94 dB sinewave is playing:
-     * local rms = sound.get_rms("master", 0.1) -- throw away right channel.
-     * print(rms) --> 0.56555819511414
+     * ```ts
+     * // Get the RMS from the "master" group where a mono -1.94 dB sinewave is playing:
+     * const [rms] = sound.get_rms("master", 0.1); // throw away right channel.
+     * print(rms); // => 0.56555819511414
      * ```
      */
     function get_rms(group: string | Hash, window: number): LuaMultiReturn<[number, number]>;
@@ -109,12 +113,12 @@ declare global {
      *
      * @returns `true` if music is playing, otherwise `false`.
      * @example
-     * ```lua
-     * If music is playing, mute "master":
-     * if sound.is_music_playing() then
-     *     -- mute "master"
-     *     sound.set_group_gain("master", 0)
-     * end
+     * ```ts
+     * // If music is playing, mute "master":
+     * if (sound.is_music_playing()) {
+     *   // mute "master"
+     *   sound.set_group_gain("master", 0);
+     * }
      * ```
      */
     function is_music_playing(): boolean;
@@ -126,11 +130,11 @@ declare global {
      *
      * @returns `true` if there is an active phone call, `false` otherwise.
      * @example
-     * ```lua
-     * Test if a phone call is on-going:
-     * if sound.is_phone_call_active() then
-     *     -- do something sensible.
-     * end
+     * ```ts
+     * // Test if a phone call is on-going:
+     * if (sound.is_phone_call_active()) {
+     *   // do something sensible.
+     * }
      * ```
      */
     function is_phone_call_active(): boolean;
@@ -140,9 +144,10 @@ declare global {
      * @param url - the sound that should pause
      * @param pause - true if the sound should pause
      * @example
-     * ```lua
-     * Assuming the script belongs to an instance with a sound-component with id "sound", this will make the component pause all playing voices:
-     * sound.pause("#sound", true)
+     * ```ts
+     * // Assuming the script belongs to an instance with a sound-component with id
+     * // "sound", this will make the component pause all playing voices:
+     * sound.pause("#sound", true);
      * ```
      */
     function pause(url: string | Hash | Url, pause: boolean): void;
@@ -176,21 +181,24 @@ declare global {
      * url The invoker of the callback: the sound component.
      * @returns The identifier for the sound voice
      * @example
-     * ```lua
-     * Assuming the script belongs to an instance with a sound-component with id "sound", this will make the component play its sound after 1 second:
-     * sound.play("#sound", { delay = 1, gain = 0.9, pan = -1.0 } )
+     * ```ts
+     * // Assuming the script belongs to an instance with a sound-component with id
+     * // "sound", this will make the component play its sound after 1 second:
+     * sound.play("#sound", { delay: 1, gain: 0.9, pan: -1.0 });
      *
-     * Using the callback argument, you can chain several sounds together:
-     * local function sound_done(self, message_id, message, sender)
-     *   -- play 'boom' sound fx when the countdown has completed
-     *   if message_id == hash("sound_done") and message.play_id == self.countdown_id then
-     *     sound.play("#boom", nil, sound_done)
-     *   end
-     * end
+     * // Using the callback argument, you can chain several sounds together:
+     * function sound_done(self, message_id, message, sender) {
+     *   // play 'boom' sound fx when the countdown has completed
+     *   if (message_id === hash("sound_done") && message.play_id === self.countdown_id) {
+     *     sound.play("#boom", undefined, sound_done);
+     *   }
+     * }
      *
-     * function init(self)
-     *   self.countdown_id = sound.play("#countdown", nil, sound_done)
-     * end
+     * export default defineScript({
+     *   init(self) {
+     *     self.countdown_id = sound.play("#countdown", undefined, sound_done);
+     *   },
+     * });
      * ```
      */
     function play(url: string | Hash | Url, play_properties?: { delay?: number; gain?: number; pan?: number; speed?: number; start_time?: number; start_frame?: number }, complete_function?: (self: unknown, message_id: unknown, message: unknown, sender: unknown) => void): number;
@@ -200,9 +208,10 @@ declare global {
      * @param url - the sound to set the gain of
      * @param gain - sound gain between 0 and 1 [-60dB .. 0dB]. The final gain of the sound will be a combination of this gain, the group gain and the master gain.
      * @example
-     * ```lua
-     * Assuming the script belongs to an instance with a sound-component with id "sound", this will set the gain to 0.9
-     * sound.set_gain("#sound", 0.9)
+     * ```ts
+     * // Assuming the script belongs to an instance with a sound-component with id
+     * // "sound", this will set the gain to 0.9
+     * sound.set_gain("#sound", 0.9);
      * ```
      */
     function set_gain(url: string | Hash | Url, gain?: number): void;
@@ -212,9 +221,9 @@ declare global {
      * @param group - group name
      * @param gain - gain in range [0..1] mapped to [0 .. -60dB]
      * @example
-     * ```lua
-     * Set mixer group gain on the "soundfx" group to 50% (-30dB):
-     * sound.set_group_gain("soundfx", 0.5)
+     * ```ts
+     * // Set mixer group gain on the "soundfx" group to 50% (-30dB):
+     * sound.set_group_gain("soundfx", 0.5);
      * ```
      */
     function set_group_gain(group: string | Hash, gain: number): void;
@@ -225,9 +234,10 @@ declare global {
      * @param url - the sound to set the panning value to
      * @param pan - sound panning between -1.0 and 1.0
      * @example
-     * ```lua
-     * Assuming the script belongs to an instance with a sound-component with id "sound", this will set the gain to 0.5
-     * sound.set_pan("#sound", 0.5) -- pan to the right
+     * ```ts
+     * // Assuming the script belongs to an instance with a sound-component with id
+     * // "sound", this will set the gain to 0.5
+     * sound.set_pan("#sound", 0.5); // pan to the right
      * ```
      */
     function set_pan(url: string | Hash | Url, pan?: number): void;
@@ -239,11 +249,12 @@ declare global {
      * `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:
-     * sound.stop("#sound")
-     * local id = sound.play("#sound")
-     * sound.stop("#sound", {play_id = id})
+     * ```ts
+     * // Assuming the script belongs to an instance with a sound-component with id
+     * // "sound", this will make the component stop all playing voices:
+     * sound.stop("#sound");
+     * const id = sound.play("#sound");
+     * sound.stop("#sound", { play_id: id });
      * ```
      */
     function stop(url: string | Hash | Url, stop_properties?: { play_id?: number }): void;

package/generated/sprite.d.ts

@@ -2,6 +2,9 @@
 import type { Hash, Url, Vector3, Vector4 } from "../src/core-types";
 
 declare global {
+  /**
+   * Functions, messages and properties used to manipulate sprite components.
+   */
   namespace sprite {
     /**
      * Play an animation on a sprite component from its tile set
@@ -28,22 +31,20 @@ declare global {
      * `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".
-     * How to play the "jump" animation followed by the "run" animation:
-     * local function anim_done(self, message_id, message, sender)
-     *   if message_id == hash("animation_done") then
-     *     if message.id == hash("jump") then
-     *       -- jump animation done, chain with "run"
-     *       sprite.play_flipbook(url, "run")
-     *     end
-     *   end
-     * end
-     *
-     * function init(self)
-     *   local url = msg.url("#sprite")
-     *   sprite.play_flipbook(url, "jump", anim_done)
-     * end
+     * ```ts
+     * // Assuming the sprite has id "sprite": play the "jump" animation followed by the
+     * // "run" animation:
+     * export default defineScript({
+     *   init() {
+     *     const url = msg.url("#sprite");
+     *     sprite.play_flipbook(url, "jump", (self, message_id, message) => {
+     *       if (message_id === hash("animation_done") && message.id === hash("jump")) {
+     *         // jump animation done, chain with "run"
+     *         sprite.play_flipbook(url, "run");
+     *       }
+     *     });
+     *   },
+     * });
      * ```
      */
     function play_flipbook(url: string | Hash | Url, id: string | Hash, complete_function?: (self: unknown, message_id: unknown, message: unknown, sender: unknown) => void, play_properties?: { offset?: number; playback_rate?: number }): void;
@@ -55,14 +56,15 @@ declare global {
      * @param url - the sprite that should flip its animations
      * @param flip - `true` if the sprite should flip its animations, `false` if not
      * @example
-     * ```lua
-     * How to flip a sprite so it faces the horizontal movement:
-     * function update(self, dt)
-     *   -- calculate self.velocity somehow
-     *   sprite.set_hflip("#sprite", self.velocity.x < 0)
-     * end
-     *
-     * It is assumed that the sprite component has id "sprite" and that the original animations faces right.
+     * ```ts
+     * // How to flip a sprite so it faces the horizontal movement (it is assumed that
+     * // the sprite component has id "sprite" and the original animation faces right):
+     * export default defineScript({
+     *   update(self, dt) {
+     *     // calculate self.velocity somehow
+     *     sprite.set_hflip("#sprite", self.velocity.x < 0);
+     *   },
+     * });
      * ```
      */
     function set_hflip(url: string | Hash | Url, flip: boolean): void;
@@ -74,14 +76,16 @@ declare global {
      * @param url - the sprite that should flip its animations
      * @param flip - `true` if the sprite should flip its animations, `false` if not
      * @example
-     * ```lua
-     * How to flip a sprite in a game which negates gravity as a game mechanic:
-     * function update(self, dt)
-     *   -- calculate self.up_side_down somehow, then:
-     *   sprite.set_vflip("#sprite", self.up_side_down)
-     * end
-     *
-     * It is assumed that the sprite component has id "sprite" and that the original animations are up-right.
+     * ```ts
+     * // How to flip a sprite in a game which negates gravity as a game mechanic (it is
+     * // assumed that the sprite component has id "sprite" and the original animation
+     * // is up-right):
+     * export default defineScript({
+     *   update(self, dt) {
+     *     // calculate self.up_side_down somehow, then:
+     *     sprite.set_vflip("#sprite", self.up_side_down);
+     *   },
+     * });
      * ```
      */
     function set_vflip(url: string | Hash | Url, flip: boolean): void;