@defold-typescript/types 0.51.0 → 0.52.0

package/generated/versions/defold-1.13.2/image.d.ts

@@ -54,7 +54,7 @@ declare global {
       /**
        * Script buffer containing the decompressed image data.
        */
-      buffer: Opaque<"buffer">;
+      buffer: Opaque<"buffer"> & { length: LuaLengthMethod<number> };
     }
     /**
      * Image loading options
@@ -141,7 +141,59 @@ declare global {
      * });
      * ```
      */
-    function load(buffer: string, options?: boolean | image.load_options): image.load_result | undefined;
+    function load(buffer: string): image.load_result | undefined;
+    /**
+     * Load image (PNG or JPEG) from buffer.
+     *
+     * @param buffer - image data buffer
+     * @param options - Optional loading parameters. A boolean is accepted for backwards compatibility and controls `premultiply_alpha`.
+     * @returns loaded image, or `nil` if loading fails
+     * @example
+     * ```ts
+     * // How to load an image from an URL and create a GUI texture from it:
+     * const imgurl = "http://www.site.com/image.png";
+     * http.request(imgurl, "GET", (self, id, response) => {
+     *   const img = response.response !== undefined ? image.load(response.response) : undefined;
+     *   if (img !== undefined) {
+     *     const tx = gui.new_texture("image_node", img.width, img.height, img.type, img.buffer);
+     *   }
+     * });
+     * ```
+     */
+    function load(buffer: string, options: boolean | image.load_options): image.load_result | undefined;
+    /**
+     * Load image (PNG or JPEG) from a string buffer.
+     *
+     * @param buffer - image data buffer
+     * @param options - Optional loading parameters. A boolean is accepted for backwards compatibility and controls `premultiply_alpha`.
+     * @returns loaded image, or `nil` if loading fails
+     * @example
+     * ```ts
+     * // Load an image from an URL as a buffer and create a texture resource from it:
+     * const imgurl = "http://www.site.com/image.png";
+     * http.request(imgurl, "GET", (self, id, response) => {
+     *   const img =
+     *     response.response !== undefined
+     *       ? image.load_buffer(response.response, { flip_vertically: true })
+     *       : undefined;
+     *   // the engine registers a texture format only when the driver supports it
+     *   const format = graphics.TEXTURE_FORMAT_RGBA;
+     *   if (img !== undefined && format !== undefined) {
+     *     const tparams = {
+     *       width: img.width,
+     *       height: img.height,
+     *       type: graphics.TEXTURE_TYPE_2D,
+     *       format,
+     *     };
+     *
+     *     const my_texture_id = resource.create_texture("/my_custom_texture.texturec", tparams, img.buffer);
+     *     // Apply the texture to a model
+     *     go.set("/go1#model", "texture0", my_texture_id);
+     *   }
+     * });
+     * ```
+     */
+    function load_buffer(buffer: string): image.load_buffer_result | undefined;
     /**
      * Load image (PNG or JPEG) from a string buffer.
      *
@@ -174,7 +226,7 @@ declare global {
      * });
      * ```
      */
-    function load_buffer(buffer: string, options?: boolean | image.load_options): image.load_buffer_result | undefined;
+    function load_buffer(buffer: string, options: boolean | image.load_options): image.load_buffer_result | undefined;
   }
 }
 

package/generated/versions/defold-1.13.2/index.d.ts

@@ -58,6 +58,8 @@ import "../../../src/scene-addresses";
 import "../../../src/go-overloads";
 import "../../../src/component-properties";
 import "../../../src/render-overloads";
+import "../../../src/gui-overloads";
+import "../../../src/gui-texture-removal";
 import "../../../src/vmath-overloads";
 import "../../../src/sys-overloads";
 

package/generated/versions/defold-1.13.2/liveupdate.d.ts

@@ -6,7 +6,7 @@ declare global {
    * Functions and constants to access resources.
    */
   namespace liveupdate {
-    type LIVEUPDATE = typeof liveupdate.LIVEUPDATE_BUNDLED_RESOURCE_MISMATCH | typeof liveupdate.LIVEUPDATE_ENGINE_VERSION_MISMATCH | typeof liveupdate.LIVEUPDATE_FORMAT_ERROR | typeof liveupdate.LIVEUPDATE_INVAL | typeof liveupdate.LIVEUPDATE_INVALID_HEADER | typeof liveupdate.LIVEUPDATE_INVALID_RESOURCE | typeof liveupdate.LIVEUPDATE_IO_ERROR | typeof liveupdate.LIVEUPDATE_MEM_ERROR | typeof liveupdate.LIVEUPDATE_OK | typeof liveupdate.LIVEUPDATE_SCHEME_MISMATCH | typeof liveupdate.LIVEUPDATE_SIGNATURE_MISMATCH | typeof liveupdate.LIVEUPDATE_UNKNOWN | typeof liveupdate.LIVEUPDATE_VERSION_MISMATCH;
+    type LIVEUPDATE = typeof liveupdate.LIVEUPDATE_BUNDLED_RESOURCE_MISMATCH | typeof liveupdate.LIVEUPDATE_ENGINE_VERSION_MISMATCH | typeof liveupdate.LIVEUPDATE_FORMAT_ERROR | typeof liveupdate.LIVEUPDATE_INVAL | typeof liveupdate.LIVEUPDATE_INVALID_HEADER | typeof liveupdate.LIVEUPDATE_INVALID_RESOURCE | typeof liveupdate.LIVEUPDATE_IO_ERROR | typeof liveupdate.LIVEUPDATE_MEM_ERROR | typeof liveupdate.LIVEUPDATE_OK | typeof liveupdate.LIVEUPDATE_SCHEME_MISMATCH | typeof liveupdate.LIVEUPDATE_SIGNATURE_MISMATCH | typeof liveupdate.LIVEUPDATE_UNKNOWN | typeof liveupdate.LIVEUPDATE_VERSION_MISMATCH | typeof liveupdate.LIVEUPDATE_NOT_INITIALIZED;
     /**
      * Mismatch between between expected bundled resources and actual bundled resources. The manifest expects a resource to be in the bundle, but it was not found in the bundle. This is typically the case when a non-excluded resource was modified between publishing the bundle and publishing the manifest.
      */
@@ -39,6 +39,10 @@ declare global {
      * Memory wasn't allocated
      */
     const LIVEUPDATE_MEM_ERROR: number & { readonly __brand: "liveupdate.LIVEUPDATE_MEM_ERROR" };
+    /**
+     * Live update is not initialized. `liveupdate.add_mount` and `liveupdate.remove_mount` return it while live update is disabled.
+     */
+    const LIVEUPDATE_NOT_INITIALIZED: number & { readonly __brand: "liveupdate.LIVEUPDATE_NOT_INITIALIZED" };
     /**
      * Operation completed successfully.
      */

package/generated/versions/defold-1.13.2/material.d.ts

@@ -78,7 +78,7 @@ declare global {
       /**
        * Sampler texture type.
        */
-      type: graphics.TEXTURE_TYPE;
+      type: graphics.TEXTURE_TYPE | 6 | 7 | 8 | 9 | 10;
       /**
        * Horizontal wrap mode.
        */
@@ -348,7 +348,7 @@ declare global {
      * Returns a table of all the textures from the material.
      *
      * @param path - The path to the resource
-     * @returns material texture information
+     * @returns material texture information. Keyed by sampler slot from 1; a slot with no texture has no entry, so iterate with `for (const [slot, info] of textures)`.
      * @example
      * ```ts
      * // Get the textures from a material specified as a resource property
@@ -363,7 +363,7 @@ declare global {
      * });
      * ```
      */
-    function get_textures(path: Hash | string): material.texture_info[];
+    function get_textures(path: Hash | string): LuaMap<number, material.texture_info>;
     /**
      * Returns a table of all the vertex attributes in the material. This function will return all the vertex attributes
      * that are used in the vertex shader of the material.

package/generated/versions/defold-1.13.2/particlefx.d.ts

@@ -128,7 +128,26 @@ declare global {
      * });
      * ```
      */
-    function stop(url: string | Hash | Url, options?: particlefx.stop_options): void;
+    function stop(url: string | Hash | Url): void;
+    /**
+     * Stops a particle FX component from playing.
+     * Stopping a particle FX does not remove already spawned particles.
+     * Which particle FX to stop is identified by the URL.
+     *
+     * @param url - the particle fx that should stop playing
+     * @param options - options used when stopping the particle fx
+     * @example
+     * ```ts
+     * // How to stop a particle fx when a game object is deleted and immediately also
+     * // clear any spawned particles:
+     * export default defineScript({
+     *   final(self) {
+     *     particlefx.stop("#particlefx", { clear: true });
+     *   },
+     * });
+     * ```
+     */
+    function stop(url: string | Hash | Url, options: particlefx.stop_options): void;
     interface properties {
       /**
        * The animation used during rendering by an emitter in a particle FX component.

package/generated/versions/defold-1.13.2/physics.d.ts

@@ -435,7 +435,51 @@ declare global {
      * });
      * ```
      */
-    function raycast_async(from: Vector3, to: Vector3, groups: Hash[], request_id?: number): void;
+    function raycast_async(from: Vector3, to: Vector3, groups: Hash[]): void;
+    /**
+     * Ray casts are used to test for intersections against collision objects in the physics world.
+     * Collision objects of types kinematic, dynamic and static are tested against. Trigger objects
+     * do not intersect with ray casts.
+     * Which collision objects to hit is filtered by their collision groups and can be configured
+     * through `groups`.
+     * The actual ray cast will be performed during the physics-update.
+     *
+     * - If an object is hit, the result will be reported via a ray_cast_response message.
+     * - If there is no object hit, the result will be reported via a ray_cast_missed message.
+     *
+     * NOTE: Ray casts will ignore collision objects that contain the starting point of the ray. This is a limitation in Box2D.
+     *
+     * @param from - the world position of the start of the ray
+     * @param to - the world position of the end of the ray
+     * @param groups - a lua table containing the hashed groups for which to test collisions against
+     * @param request_id - a number in range [0,255]. It will be sent back in the response for identification, 0 by default
+     * @example
+     * ```ts
+     * // How to perform a ray cast asynchronously:
+     * export default defineScript({
+     *   init() {
+     *     return { my_groups: [hash("my_group1"), hash("my_group2")] };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // request ray cast
+     *     const my_start = go.get_world_position();
+     *     const my_end = vmath.vector3(my_start.x, my_start.y - 100, my_start.z);
+     *     physics.raycast_async(my_start, my_end, self.my_groups);
+     *   },
+     *
+     *   on_message(self, message_id, message, sender) {
+     *     // check for the response
+     *     if (message_id === hash("ray_cast_response")) {
+     *       // act on the hit
+     *     } else if (message_id === hash("ray_cast_missed")) {
+     *       // act on the miss
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    function raycast_async(from: Vector3, to: Vector3, groups: Hash[], request_id: number): void;
     /**
      * Only one physics world event listener can be set at a time.
      *

package/generated/versions/defold-1.13.2/render.d.ts

@@ -59,7 +59,7 @@ declare global {
        */
       sort_order?: render.SORT;
     }
-    type render_predicate = number;
+    type render_predicate = Opaque<"render_predicate">;
     type render_target = Opaque<"render_target">;
     /**
      * Render-target attachment parameters
@@ -114,6 +114,7 @@ declare global {
     }
     type texture = Opaque<"texture">;
     type ClearBufferKey = typeof graphics.BUFFER_TYPE_COLOR0_BIT | typeof graphics.BUFFER_TYPE_DEPTH_BIT | typeof graphics.BUFFER_TYPE_STENCIL_BIT;
+    type RenderTargetTextureType = typeof graphics.TEXTURE_TYPE_2D | typeof graphics.TEXTURE_TYPE_CUBE_MAP;
     type RenderTargetParams = render.render_target_params;
     type CONTEXT_EVENT = typeof render.CONTEXT_EVENT_CONTEXT_LOST | typeof render.CONTEXT_EVENT_CONTEXT_RESTORED;
     type FRUSTUM_PLANES = typeof render.FRUSTUM_PLANES_ALL | typeof render.FRUSTUM_PLANES_SIDES;
@@ -291,7 +292,7 @@ declare global {
      * });
      * ```
      */
-    function disable_state(state: graphics.STATE): void;
+    function disable_state(state: graphics.State): void;
     /**
      * Disables a texture that has previourly been enabled.
      *
@@ -326,7 +327,7 @@ declare global {
      * });
      * ```
      */
-    function disable_texture(binding: Opaque<"texture"> | string | Hash | number): void;
+    function disable_texture(binding: string | Hash | number): void;
     /**
      * Dispatches the currently enabled compute program. The dispatch call takes three arguments x,y,z which constitutes
      * the 'global working group' of the compute dispatch. Together with the 'local working group' specified in the compute shader
@@ -423,7 +424,56 @@ declare global {
      * }
      * ```
      */
-    function draw(predicate: Opaque<"render_predicate">, options?: render.draw_options): void;
+    function draw(predicate: Opaque<"render_predicate">): void;
+    /**
+     * Draws all objects that match a specified predicate. An optional constant buffer can be
+     * provided to override the default constants. If no constants buffer is provided, a default
+     * system constants buffer is used containing constants as defined in materials and set through
+     * go.set (or particlefx.set_constant) on visual components.
+     *
+     * @param predicate - predicate to draw for
+     * @param options - optional draw options
+     * @example
+     * ```ts
+     * export default defineRenderScript({
+     *   init() {
+     *     // define a predicate matching anything with material tag "my_tag"
+     *     return { my_pred: render.predicate([hash("my_tag")]) };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // draw everything in the my_pred predicate
+     *     render.draw(self.my_pred);
+     *   },
+     * });
+     * ```
+     * @example
+     * Draw predicate with constants:
+     * ```ts
+     * function draw_tinted(self: { my_pred: Opaque<"render_predicate"> }) {
+     *   const constants = render.constant_buffer();
+     *   constants.tint = vmath.vector4(1, 1, 1, 1);
+     *   render.draw(self.my_pred, { constants });
+     * }
+     * ```
+     * @example
+     * Draw with predicate and frustum culling (without near+far planes):
+     * ```ts
+     * function draw_culled(self: { my_pred: Opaque<"render_predicate">; proj: Matrix4; view: Matrix4 }) {
+     *   const frustum = self.proj.mul(self.view);
+     *   render.draw(self.my_pred, { frustum });
+     * }
+     * ```
+     * @example
+     * Draw with predicate and frustum culling (with near+far planes):
+     * ```ts
+     * function draw_culled(self: { my_pred: Opaque<"render_predicate">; proj: Matrix4; view: Matrix4 }) {
+     *   const frustum = self.proj.mul(self.view);
+     *   render.draw(self.my_pred, { frustum, frustum_planes: render.FRUSTUM_PLANES_ALL });
+     * }
+     * ```
+     */
+    function draw(predicate: Opaque<"render_predicate">, options: render.draw_options): void;
     /**
      * Draws all 3d debug graphics such as lines drawn with "draw_line" messages and physics visualization.
      *
@@ -490,7 +540,7 @@ declare global {
      * });
      * ```
      */
-    function enable_state(state: graphics.STATE): void;
+    function enable_state(state: graphics.State): void;
     /**
      * Sets the specified texture handle for a render target attachment or a regular texture
      * that should be used for rendering. The texture can be bound to either a texture unit
@@ -787,7 +837,7 @@ declare global {
      * render.set_blend_func_separate(graphics.BLEND_FACTOR_SRC_ALPHA, graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA, graphics.BLEND_FACTOR_ONE, graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA);
      * ```
      */
-    function set_blend_func_separate(source_factor_color: number, destination_factor_color: number, source_factor_alpha: number, destination_factor_alpha: number): void;
+    function set_blend_func_separate(source_factor_color: graphics.BlendFactor, destination_factor_color: graphics.BlendFactor, source_factor_alpha: graphics.BlendFactor, destination_factor_alpha: graphics.BlendFactor): void;
     /**
      * Sets the current render camera to be used for rendering. If a render camera
      * has been set by the render script, the renderer will be using its projection and view matrix
@@ -1033,7 +1083,73 @@ declare global {
      * });
      * ```
      */
-    function set_render_target(render_target?: Opaque<"render_target"> | string | Hash | typeof render.RENDER_TARGET_DEFAULT, options?: render.set_render_target_options): void;
+    function set_render_target(render_target?: Opaque<"render_target"> | string | Hash | typeof render.RENDER_TARGET_DEFAULT): void;
+    /**
+     * Sets a render target. Subsequent draw operations will be to the
+     * render target until it is replaced by a subsequent call to set_render_target.
+     * This function supports render targets created by a render script, or a render target resource.
+     *
+     * @param render_target - render target to set. Omit it, pass `nil`, or use render.RENDER_TARGET_DEFAULT to set the default render target
+     * @param options - optional render-target activation options
+     * @example
+     * How to set a render target and draw to it and then switch back to the default render target
+     * The render target defines the depth/stencil buffers as transient, when set_render_target is called the next time the buffers may be invalidated and allow for optimisations depending on driver support
+     * ```ts
+     * // How to set a render target and draw to it and then switch back to the default render target
+     * // The render target defines the depth/stencil buffers as transient, when set_render_target is called the next time the buffers may be invalidated and allow for optimisations depending on driver support
+     * export default defineRenderScript({
+     *   init() {
+     *     // the engine registers a texture format only when the driver supports it
+     *     const format = graphics.TEXTURE_FORMAT_RGBA;
+     *     if (format === undefined) return undefined;
+     *     const color_params = {
+     *       format,
+     *       width: render.get_window_width(),
+     *       height: render.get_window_height(),
+     *     };
+     *     return {
+     *       my_render_target: render.render_target({ [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params }),
+     *       my_pred: render.predicate([hash("my_tag")]),
+     *     };
+     *   },
+     *
+     *   update(self, dt) {
+     *     if (self === undefined) return;
+     *     // set render target so all drawing is done to it
+     *     render.set_render_target(self.my_render_target, {
+     *       transient: [graphics.BUFFER_TYPE_DEPTH_BIT, graphics.BUFFER_TYPE_STENCIL_BIT],
+     *     });
+     *
+     *     // draw a predicate to the render target
+     *     render.draw(self.my_pred);
+     *
+     *     // set default render target. This also invalidates the depth and stencil buffers of the current target (self.my_render_target)
+     *     //  which can be an optimisation on some hardware
+     *     render.set_render_target(render.RENDER_TARGET_DEFAULT);
+     *   },
+     * });
+     * ```
+     * @example
+     * ```ts
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_pred: render.predicate([hash("my_tag")]) };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // set render target by a render target resource identifier
+     *     render.set_render_target("my_rt_resource");
+     *
+     *     // draw a predicate to the render target
+     *     render.draw(self.my_pred);
+     *
+     *     // reset the render target to the default backbuffer
+     *     render.set_render_target(render.RENDER_TARGET_DEFAULT);
+     *   },
+     * });
+     * ```
+     */
+    function set_render_target(render_target: Opaque<"render_target"> | string | Hash | typeof render.RENDER_TARGET_DEFAULT | undefined, options: render.set_render_target_options): void;
     /**
      * Sets the render target size for a render target created from
      * either a render script, or from a render target resource.

package/generated/versions/defold-1.13.2/resource.d.ts

@@ -130,7 +130,7 @@ declare global {
       /**
        * Buffer to bind to the resource.
        */
-      buffer: Opaque<"buffer">;
+      buffer: Opaque<"buffer"> & { length: LuaLengthMethod<number> };
       /**
        * Whether the resource takes ownership of the buffer. The default is true.
        */
@@ -708,7 +708,7 @@ declare global {
      * });
      * ```
      */
-    function create_sound_data(path: string, options: resource.sound_data_options): Hash;
+    function create_sound_data(path: string, options: resource.sound_data_options & ({ partial?: false } | ({ partial: true } & Required<Pick<resource.sound_data_options, "filesize">>))): Hash;
     /**
      * Creates a new texture resource that can be used in the same way as any texture created during build time.
      * The path used for creating the texture must be unique, trying to create a resource at a path that is already
@@ -836,7 +836,7 @@ declare global {
      * }
      * ```
      */
-    function create_texture(path: string, table: resource.texture_creation_params, buffer?: Opaque<"buffer">): Hash;
+    function create_texture(path: string, table: resource.texture_creation_params, buffer?: Opaque<"buffer"> & { length: LuaLengthMethod<number> }): Hash;
     /**
      * Creates a new texture resource that can be used in the same way as any texture created during build time.
      * The path used for creating the texture must be unique, trying to create a resource at a path that is already
@@ -955,7 +955,7 @@ declare global {
      * });
      * ```
      */
-    function create_texture_async(path: string, table: resource.texture_creation_params, buffer: Opaque<"buffer"> | undefined, callback: (self: unknown, request_id: number, result: resource.texture_creation_result) => void): LuaMultiReturn<[Hash, number]>;
+    function create_texture_async(path: string, table: resource.texture_creation_params, buffer: Opaque<"buffer"> & { length: LuaLengthMethod<number> } | undefined, callback: (self: unknown, request_id: number, result: resource.texture_creation_result) => void): LuaMultiReturn<[Hash, number]>;
     /**
      * Constructor-like function with two purposes:
      *
@@ -1024,7 +1024,7 @@ declare global {
      * });
      * ```
      */
-    function get_buffer(path: Hash | string): Opaque<"buffer">;
+    function get_buffer(path: Hash | string): Opaque<"buffer"> & { length: LuaLengthMethod<number> };
     /**
      * Gets render target info from a render target resource path or a render target handle
      *
@@ -1080,7 +1080,28 @@ declare global {
      * });
      * ```
      */
-    function get_text_metrics(url: Hash | string, text: string, options?: resource.text_metrics_options): resource.text_metrics;
+    function get_text_metrics(url: Hash | string, text: string): resource.text_metrics;
+    /**
+     * Gets the text metrics from a font. Rich text markup is measured using its
+     * visible text and font sizes. If markup cannot be parsed, the text is measured literally.
+     * Inline sprites reserve their specified dimensions, or one em by default.
+     *
+     * @param url - the font to get the (unscaled) metrics from
+     * @param text - text to measure
+     * @param options - optional text-metric options
+     * @returns measured text metrics
+     * @example
+     * ```ts
+     * export default defineScript({
+     *   init() {
+     *     const font = go.get<label.properties>()("#label", "font");
+     *     const metrics = resource.get_text_metrics(font, "The quick brown fox\n jumps over the lazy dog");
+     *     pprint(metrics);
+     *   },
+     * });
+     * ```
+     */
+    function get_text_metrics(url: Hash | string, text: string, options: resource.text_metrics_options): resource.text_metrics;
     /**
      * Gets texture info from a texture resource path or a texture handle
      *
@@ -1155,7 +1176,7 @@ declare global {
      * // custom_resources = resources/,assets/level_data.json
      * ```
      */
-    function load(path: string): Opaque<"buffer">;
+    function load(path: string): Opaque<"buffer"> & { length: LuaLengthMethod<number> };
     /**
      * Constructor-like function with two purposes:
      *
@@ -1242,7 +1263,7 @@ declare global {
      * resource.set(go.get<sprite.properties>()("#sprite", "texture0"), buffer);
      * ```
      */
-    function set(path: string | Hash, buffer: Opaque<"buffer">): void;
+    function set(path: string | Hash, buffer: Opaque<"buffer"> & { length: LuaLengthMethod<number> }): void;
     /**
      * Sets the data for a specific atlas resource. Setting new atlas data is specified by passing in
      * a texture path for the backing texture of the atlas, a list of geometries and a list of animations
@@ -1371,7 +1392,7 @@ declare global {
      * });
      * ```
      */
-    function set_buffer(path: Hash | string, buffer: Opaque<"buffer">, table?: resource.buffer_update_options): void;
+    function set_buffer(path: Hash | string, buffer: Opaque<"buffer"> & { length: LuaLengthMethod<number> }, table?: resource.buffer_update_options): void;
     /**
      * Update internal sound resource (wavc/oggc/opusc) with new data
      *
@@ -1571,7 +1592,7 @@ declare global {
      * }
      * ```
      */
-    function set_texture(path: Hash | string, table: resource.texture_update_params, buffer: Opaque<"buffer">): void;
+    function set_texture(path: Hash | string, table: resource.texture_update_params, buffer: Opaque<"buffer"> & { length: LuaLengthMethod<number> }): void;
     /**
      * Constructor-like function with two purposes:
      *

package/generated/versions/defold-1.13.2/sprite.d.ts

@@ -66,7 +66,55 @@ declare global {
      * });
      * ```
      */
-    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;
+    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): void;
+    /**
+     * 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`
+     * script_instance The current script instance.
+     * `message_id`
+     * hash The name of the completion message, `"animation_done"`.
+     * `message`
+     * message.sprite.animation_done Information about the completion.
+     * `sender`
+     * url The invoker of the callback: the sprite component.
+     * @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");
+     *
+     * 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
+     * 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: Hash, message: { current_tile: number; id: Hash }, sender: Url) => void) | undefined, 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.