@defold-typescript/types 0.39.0 → 0.41.0

package/generated/sound.d.ts

@@ -7,6 +7,54 @@ declare global {
    * mixer groups.
    */
   namespace sound {
+    /**
+     * Data passed to the completion callback of sound.play. The callback's
+     * `message_id` indicates whether playback finished or was stopped manually.
+     */
+    interface play_completion {
+      /**
+       * The sequential play identifier for the playback.
+       */
+      play_id: number;
+    }
+    /**
+     * Sound playback properties
+     */
+    interface play_properties {
+      /**
+       * Delay in seconds before playback starts. The default is 0.
+       */
+      delay?: number;
+      /**
+       * Gain from 0 to 1. The default is 1; this combines with the group and master gains.
+       */
+      gain?: number;
+      /**
+       * Pan from -1 to 1. The default is 0; this is added to the component pan.
+       */
+      pan?: number;
+      /**
+       * Playback speed from 0 to 50. The default is 1; this is multiplied by the component speed.
+       */
+      speed?: number;
+      /**
+       * Playback offset in seconds. Mutually exclusive with `start_frame`.
+       */
+      start_time?: number;
+      /**
+       * Playback offset in frames or samples. Takes precedence over `start_time`.
+       */
+      start_frame?: number;
+    }
+    /**
+     * Sound stop properties
+     */
+    interface stop_properties {
+      /**
+       * Sequential playback identifier returned by sound.play.
+       */
+      play_id?: number;
+    }
     /**
      * Get mixer group gain
      *
@@ -38,7 +86,7 @@ declare global {
      * }
      * ```
      */
-    function get_group_name(group: string | Hash): string;
+    function get_group_name(group: Hash): string;
     /**
      * Get a table of all mixer group names (hashes).
      *
@@ -83,7 +131,7 @@ declare global {
      * 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 × 1/sqrt(2)` which is about 0.566.
+     * the RMS is `0.8 × 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.
      *
@@ -108,7 +156,6 @@ declare global {
      * 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
@@ -159,40 +206,26 @@ declare global {
      * 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 play_properties - optional playback properties
      * @param complete_function - function to call when the sound has finished playing or stopped manually via sound.stop.
      *
      * `self`
-     * object The current object.
+     * script_instance The current script instance.
      * `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.
-     *
+     * sound.play_completion Information about the completed or stopped playback.
      * `sender`
      * url The invoker of the callback: the sound component.
      * @returns The identifier for the sound voice
      * @example
+     * 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:
      * ```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:
+     * ```
+     * @example
+     * Using the callback argument, you can chain several sounds together:
+     * ```ts
      * function sound_done(self: unknown, message_id: unknown, message: unknown, sender: unknown) {
      *   // play 'boom' sound fx when the countdown has completed
      *   const { play_id } = message as { play_id: number };
@@ -202,13 +235,13 @@ declare global {
      * }
      *
      * export default defineScript({
-     *   init(self) {
-     *     self.countdown_id = sound.play("#countdown", undefined, sound_done);
+     *   init() {
+     *     return { 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;
+    function play(url: string | Hash | Url, play_properties?: sound.play_properties, complete_function?: (self: unknown, message_id: Hash, message: sound.play_completion, sender: Url) => void): number;
     /**
      * Set gain on all active playing voices of a sound.
      *
@@ -221,7 +254,7 @@ declare global {
      * sound.set_gain("#sound", 0.9);
      * ```
      */
-    function set_gain(url: string | Hash | Url, gain?: number): void;
+    function set_gain(url: string | Hash | Url, gain: number): void;
     /**
      * Set mixer group gain
      *
@@ -247,14 +280,12 @@ declare global {
      * sound.set_pan("#sound", 0.5); // pan to the right
      * ```
      */
-    function set_pan(url: string | Hash | Url, pan?: number): void;
+    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)
+     * @param stop_properties - optional playback to stop
      * @example
      * ```ts
      * // Assuming the script belongs to an instance with a sound-component with id
@@ -264,7 +295,7 @@ declare global {
      * sound.stop("#sound", { play_id: id });
      * ```
      */
-    function stop(url: string | Hash | Url, stop_properties?: { play_id?: number }): void;
+    function stop(url: string | Hash | Url, stop_properties?: sound.stop_properties): void;
     interface properties {
       /**
        * The gain on the sound-component. Note that gain is in linear scale,

package/generated/sprite.d.ts

@@ -6,6 +6,19 @@ declare global {
    * Sprite API documentation
    */
   namespace sprite {
+    /**
+     * Sprite flipbook playback properties
+     */
+    interface play_properties {
+      /**
+       * Normalized initial animation cursor.
+       */
+      offset?: number;
+      /**
+       * Positive animation playback rate.
+       */
+      playback_rate?: number;
+    }
     /**
      * Play an animation on a sprite component from its tile set
      * An optional completion callback function can be provided that will be called when
@@ -17,28 +30,29 @@ declare global {
      * @param complete_function - function to call when the animation has completed.
      *
      * `self`
-     * object The current object.
+     * script_instance The current script instance.
      * `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.
-     *
+     * message.sprite.animation_done Information about the completion.
      * `sender`
      * url The invoker of the callback: the sprite component.
-     * @param play_properties - optional table with properties:
+     * @param play_properties - optional playback properties
+     * @example
+     * The following examples assumes that the model has id "sprite".
+     * How to play the "jump" animation followed by the "run" animation:
+     * ```ts
+     * const url = msg.url("#sprite");
      *
-     * `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.
+     * function anim_done(self: unknown, message_id: Hash, message: { id: Hash }) {
+     *   if (message_id === hash("animation_done") && message.id === hash("jump")) {
+     *     // jump animation done, chain with "run"
+     *     sprite.play_flipbook(url, "run");
+     *   }
+     * }
+     * ```
      * @example
      * ```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");
@@ -52,7 +66,7 @@ declare global {
      * });
      * ```
      */
-    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;
+    function play_flipbook(url: string | Hash | Url, id: string | Hash, complete_function?: (self: unknown, message_id: Hash, message: { current_tile: number; id: Hash }, sender: Url) => void, play_properties?: sprite.play_properties): void;
     /**
      * Resets a shader constant for a sprite component.
      * The constant must be defined in the material assigned to the sprite.
@@ -79,6 +93,10 @@ declare global {
      * // 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({
+     *   init() {
+     *     return { velocity: vmath.vector3() };
+     *   },
+     *
      *   update(self, dt) {
      *     // calculate self.velocity somehow
      *     sprite.set_hflip("#sprite", self.velocity.x < 0);
@@ -100,6 +118,10 @@ declare global {
      * // assumed that the sprite component has id "sprite" and the original animation
      * // is up-right):
      * export default defineScript({
+     *   init() {
+     *     return { up_side_down: false };
+     *   },
+     *
      *   update(self, dt) {
      *     // calculate self.up_side_down somehow, then:
      *     sprite.set_vflip("#sprite", self.up_side_down);
@@ -112,7 +134,7 @@ declare global {
       /**
        * READ ONLY The current animation id. An animation that plays currently for the sprite. The type of the property is hash.
        */
-      animation: Hash;
+      readonly animation: Hash;
       /**
        * The normalized animation cursor. The type of the property is number.
        */
@@ -120,7 +142,7 @@ declare global {
       /**
        * READ ONLY The frame count of the currently playing animation.
        */
-      frame_count: number;
+      readonly frame_count: number;
       /**
        * The image used when rendering the sprite. The type of the property is hash.
        */