@defold-typescript/types 0.4.3 → 0.5.0

package/generated/socket.d.ts

@@ -6,18 +6,143 @@ declare global {
     type client = Opaque<"client">;
     type master = Opaque<"master">;
     type unconnected = Opaque<"unconnected">;
+    /**
+     * This constant contains the maximum number of sockets that the select function can handle.
+     */
     const _SETSIZE: number & { readonly __brand: "socket._SETSIZE" };
+    /**
+     * This constant has a string describing the current LuaSocket version.
+     */
     const _VERSION: number & { readonly __brand: "socket._VERSION" };
+    /**
+     * This function is a shortcut that creates and returns a TCP client object connected to a remote
+     * address at a given port. Optionally, the user can also specify the local address and port to
+     * bind (`locaddr` and `locport`), or restrict the socket family to `"inet"` or `"inet6"`.
+     * Without specifying family to connect, whether a tcp or tcp6 connection is created depends on
+     * your system configuration.
+     *
+     * @param address - the address to connect to.
+     * @param port - the port to connect to.
+     * @param locaddr - optional local address to bind to.
+     * @param locport - optional local port to bind to.
+     * @param family - optional socket family to use, `"inet"` or `"inet6"`.
+     */
     function connect(address: string, port: number, locaddr?: string, locport?: number, family?: string): LuaMultiReturn<[Opaque<"client"> | unknown, string | unknown]>;
+    /**
+     * Returns the time in seconds, relative to the system epoch (Unix epoch time since January 1, 1970 (UTC) or Windows file time since January 1, 1601 (UTC)).
+     * You should use the values returned by this function for relative measurements only.
+     *
+     * @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")
+     * ```
+     */
     function gettime(): number;
+    /**
+     * This function creates and returns a clean try function that allows for cleanup before the exception is raised.
+     * The `finalizer` function will be called in protected mode (see protect).
+     *
+     * @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()
+     * ```
+     */
     function newtry(finalizer: () => void): (...args: unknown[]) => unknown;
+    /**
+     * Converts a function that throws exceptions into a safe function. This function only catches exceptions thrown by try functions. It does not catch normal Lua errors.
+     * Beware that if your function performs some illegal operation that raises an error, the protected function will catch the error and return it as a string. This is because try functions uses errors as the mechanism to throw exceptions.
+     *
+     * @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)
+     *
+     * local n, error = dostuff()
+     * ```
+     */
     function protect(func: (...args: unknown[]) => unknown): (arg0: unknown) => void;
+    /**
+     * The function returns a list with the sockets ready for reading, a list with the sockets ready for writing and an error message. The error message is "timeout" if a timeout condition was met and nil otherwise. The returned tables are doubly keyed both by integers and also by the sockets themselves, to simplify the test if a specific socket has changed status.
+     * `Recvt` and `sendt` parameters can be empty tables or `nil`. Non-socket values (or values with non-numeric indices) in these arrays will be silently ignored.
+     * The returned tables are doubly keyed both by integers and also by the sockets themselves, to simplify the test if a specific socket has changed status.
+     * This function can monitor a limited number of sockets, as defined by the constant socket._SETSIZE. This number may be as high as 1024 or as low as 64 by default, depending on the system. It is usually possible to change this at compile time. Invoking select with a larger number of sockets will raise an error.
+     * A known bug in WinSock causes select to fail on non-blocking TCP sockets. The function may return a socket as writable even though the socket is not ready for sending.
+     * Calling select with a server socket in the receive parameter before a call to accept does not guarantee accept will return immediately. Use the settimeout method or accept might block forever.
+     * If you close a socket and pass it to select, it will be ignored.
+     * (Using select with non-socket objects: Any object that implements `getfd` and `dirty` can be used with select, allowing objects from other libraries to be used within a socket.select driven loop.)
+     *
+     * @param recvt - array with the sockets to test for characters available for reading.
+     * @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]>;
+    /**
+     * This function drops a number of arguments and returns the remaining.
+     * It is useful to avoid creation of dummy variables:
+     * `D` is the number of arguments to drop. `Ret1` to `retN` are the arguments.
+     * The function returns `retD+1` to `retN`.
+     *
+     * @param d - the number of arguments to drop.
+     * @param ret1 - argument 1.
+     * @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)(.?)")
+     *
+     * 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)(.?)"))
+     * ```
+     */
     function skip(d: number, ret1?: unknown, ret2?: unknown, retN?: unknown): LuaMultiReturn<[unknown, unknown, unknown]>;
+    /**
+     * Freezes the program execution during a given amount of time.
+     *
+     * @param time - the number of seconds to sleep for.
+     */
     function sleep(time: number): void;
+    /**
+     * Creates and returns an IPv4 TCP master object. A master object can be transformed into a server object with the method `listen` (after a call to `bind`) or into a client object with the method `connect`. The only other method supported by a master object is the `close` method.
+     */
     function tcp(): LuaMultiReturn<[Opaque<"master"> | unknown, string | unknown]>;
+    /**
+     * Creates and returns an IPv6 TCP master object. A master object can be transformed into a server object with the method `listen` (after a call to `bind`) or into a client object with the method connect. The only other method supported by a master object is the close method.
+     * Note: The TCP object returned will have the option "ipv6-v6only" set to true.
+     */
     function tcp6(): LuaMultiReturn<[Opaque<"master"> | unknown, string | unknown]>;
+    /**
+     * Creates and returns an unconnected IPv4 UDP object. Unconnected objects support the `sendto`, `receive`, `receivefrom`, `getoption`, `getsockname`, `setoption`, `settimeout`, `setpeername`, `setsockname`, and `close` methods. The `setpeername` method is used to connect the object.
+     */
     function udp(): LuaMultiReturn<[Opaque<"unconnected"> | unknown, string | unknown]>;
+    /**
+     * Creates and returns an unconnected IPv6 UDP object. Unconnected objects support the `sendto`, `receive`, `receivefrom`, `getoption`, `getsockname`, `setoption`, `settimeout`, `setpeername`, `setsockname`, and `close` methods. The `setpeername` method is used to connect the object.
+     * Note: The UDP object returned will have the option "ipv6-v6only" set to true.
+     */
     function udp6(): LuaMultiReturn<[Opaque<"unconnected"> | unknown, string | unknown]>;
   }
 }

package/generated/sound.d.ts

@@ -3,23 +3,269 @@ import type { Hash, Url } from "../src/core-types";
 
 declare global {
   namespace sound {
+    /**
+     * Get mixer group gain
+     *
+     * @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
+     * ```
+     */
     function get_group_gain(group: string | Hash): number;
+    /**
+     * Get a mixer group name as a string.
+     * This function is to be used for debugging and
+     * development tooling only. The function does a reverse hash lookup, which does not
+     * return a proper string value when the game is built in release mode.
+     *
+     * @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
+     * ```
+     */
     function get_group_name(group: string | Hash): string;
+    /**
+     * Get a table of all mixer group names (hashes).
+     *
+     * @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
+     * ```
+     */
     function get_groups(): Hash[];
+    /**
+     * Get peak value from mixer group.
+     * Note that gain is in linear scale, between 0 and 1.
+     * To get the dB value from the gain, use the formula `20 * log(gain)`.
+     * Inversely, to find the linear value from a dB value, use the formula
+     * `10db/20`.
+     * Also note that the returned value might be an approximation and in particular
+     * the effective window might be larger than specified.
+     *
+     * @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)
+     * ```
+     */
     function get_peak(group: string | Hash, window: number): LuaMultiReturn<[number, number]>;
+    /**
+     * Get RMS (Root Mean Square) value from mixer group. This value is the
+     * square root of the mean (average) value of the squared function of
+     * the instantaneous values.
+     * For instance: for a sinewave signal with a peak gain of -1.94 dB (0.8 linear),
+     * the RMS is `0.8 &times; 1/sqrt(2)` which is about 0.566.
+     * Note the returned value might be an approximation and in particular
+     * the effective window might be larger than specified.
+     *
+     * @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
+     * ```
+     */
     function get_rms(group: string | Hash, window: number): LuaMultiReturn<[number, number]>;
+    /**
+     * Checks if background music is playing, e.g. from iTunes.
+     * On non mobile platforms,
+     * this function always return `false`.
+     * On Android you can only get a correct reading
+     * of this state if your game is not playing any sounds itself. This is a limitation
+     * in the Android SDK. If your game is playing any sounds, *even with a gain of zero*, this
+     * function will return `false`.
+     * The best time to call this function is:
+     * - In the `init` function of your main collection script before any sounds are triggered
+     * - In a window listener callback when the window.WINDOW_EVENT_FOCUS_GAINED event is received
+     * Both those times will give you a correct reading of the state even when your application is
+     * swapped out and in while playing sounds and it works equally well on Android and iOS.
+     *
+     * @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
+     * ```
+     */
     function is_music_playing(): boolean;
+    /**
+     * Checks if a phone call is active. If there is an active phone call all
+     * other sounds will be muted until the phone call is finished.
+     * On non mobile platforms,
+     * this function always return `false`.
+     *
+     * @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
+     * ```
+     */
     function is_phone_call_active(): boolean;
+    /**
+     * Pause all active voices
+     *
+     * @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)
+     * ```
+     */
     function pause(url: string | Hash | Url, pause: boolean): void;
+    /**
+     * Make the sound component play its sound. Multiple voices are supported. The limit is set to 32 voices per sound component.
+     * A sound will continue to play even if the game object the sound component belonged to is deleted. You can call `sound.stop()` to stop the sound.
+     *
+     * @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.
+     * @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.
+     * @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 } )
+     *
+     * 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
+     *
+     * function init(self)
+     *   self.countdown_id = sound.play("#countdown", nil, sound_done)
+     * end
+     * ```
+     */
     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;
+    /**
+     * Set gain on all active playing voices of a sound.
+     *
+     * @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)
+     * ```
+     */
     function set_gain(url: string | Hash | Url, gain?: number): void;
+    /**
+     * Set mixer group gain
+     *
+     * @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)
+     * ```
+     */
     function set_group_gain(group: string | Hash, gain: number): void;
+    /**
+     * Set panning on all active playing voices of a sound.
+     * The valid range is from -1.0 to 1.0, representing -45 degrees left, to +45 degrees right.
+     *
+     * @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
+     * ```
+     */
     function set_pan(url: string | Hash | Url, pan?: number): void;
+    /**
+     * Stop playing all active voices or just one voice if `play_id` provided
+     *
+     * @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)
+     * @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})
+     * ```
+     */
     function stop(url: string | Hash | Url, stop_properties?: { play_id?: number }): void;
     interface properties {
+      /**
+       * The gain on the sound-component. Note that gain is in linear scale,
+       * between 0 and 1.
+       */
       gain: number;
+      /**
+       * The pan on the sound-component. The valid range is from -1.0 to 1.0,
+       * representing -45 degrees left, to +45 degrees right.
+       */
       pan: number;
+      /**
+       * The sound data used when playing the sound. The type of the property is hash.
+       */
       sound: Hash;
+      /**
+       * The speed on the sound-component 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.
+       */
       speed: number;
     }
   }

package/generated/sprite.d.ts

@@ -3,18 +3,129 @@ import type { Hash, Url, Vector3, Vector4 } from "../src/core-types";
 
 declare global {
   namespace sprite {
+    /**
+     * Play an animation on a sprite component from its tile set
+     * An optional completion callback function can be provided that will be called when
+     * the animation has completed playing. If no function is provided,
+     * a animation_done message is sent to the script that started the animation.
+     *
+     * @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`
+  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
+     * ```
+     */
     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;
+    /**
+     * Sets horizontal flipping of the provided sprite's animations.
+     * The sprite is identified by its URL.
+     * If the currently playing animation is flipped by default, flipping it again will make it appear like the original texture.
+     *
+     * @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.
+     * ```
+     */
     function set_hflip(url: string | Hash | Url, flip: boolean): void;
+    /**
+     * Sets vertical flipping of the provided sprite's animations.
+     * The sprite is identified by its URL.
+     * If the currently playing animation is flipped by default, flipping it again will make it appear like the original texture.
+     *
+     * @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.
+     * ```
+     */
     function set_vflip(url: string | Hash | Url, flip: boolean): void;
     interface properties {
+      /**
+       * READ ONLY The current animation id. An animation that plays currently for the sprite. The type of the property is hash.
+       */
       animation: Hash;
+      /**
+       * The normalized animation cursor. The type of the property is number.
+       */
       cursor: number;
+      /**
+       * READ ONLY The frame count of the currently playing animation.
+       */
       frame_count: Hash;
+      /**
+       * The image used when rendering the sprite. The type of the property is hash.
+       */
       image: Hash;
+      /**
+       * The material used when rendering the sprite. The type of the property is hash.
+       */
       material: Hash;
+      /**
+       * The animation playback rate. A multiplier to the animation playback rate. The type of the property is number.
+       * The playback_rate is a non-negative number, a negative value will be clamped to 0.
+       */
       playback_rate: number;
+      /**
+       * The non-uniform scale of the sprite. The type of the property is vector3.
+       */
       scale: Vector3;
+      /**
+       * The size of the sprite, not allowing for any additional scaling that may be applied.
+       * The type of the property is vector3. It is not possible to set the size if the size mode
+       * of the sprite is set to auto.
+       */
       size: Vector3;
+      /**
+       * The slice values of the sprite. The type of the property is a vector4 that corresponds to
+       * the left, top, right, bottom values of the sprite in the editor.
+       * It is not possible to set the slice property if the size mode of the sprite is set to auto.
+       */
       slice: Vector4;
     }
   }