@defold-typescript/types 0.40.0 → 0.42.0

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

@@ -10,7 +10,6 @@ declare global {
      * Constructor-like function with two purposes:
      *
      * - Load the specified resource as part of loading the script
-     *
      * - Return a hash to the run-time version of the resource
      *
      * This function can only be called within go.property function calls.
@@ -51,7 +50,6 @@ declare global {
      * Constructor-like function with two purposes:
      *
      * - Load the specified resource as part of loading the script
-     *
      * - Return a hash to the run-time version of the resource
      *
      * This function can only be called within go.property function calls.
@@ -150,18 +148,23 @@ declare global {
      *
      * - `indices`
      * table a list of the indices of the geometry in the form {i0, i1, i2, ..., in}. Each tripe in the list represents a triangle.
+     *
+     * **⚠️ `frame_start` is 1-based; passed to Defold unchanged.** **⚠️ `frame_end` is 1-based; passed to Defold unchanged.** **⚠️ `frame_start` is 1-based; passed to Defold unchanged.** **⚠️ `frame_end` is 1-based; passed to Defold unchanged.** **⚠️ `frames` is 1-based; passed to Defold unchanged.** **0️⃣ `indices` is 0-based; passed to Defold unchanged.**
      * @returns Returns the atlas resource path
      * @example
      * ```ts
      * // Create a backing texture and an atlas
      * export default defineScript({
      *   init() {
+     *     // the engine registers a texture format only when the driver supports it
+     *     const format = graphics.TEXTURE_FORMAT_RGBA;
+     *     if (format === undefined) return;
      *     // create an empty texture
      *     const tparams = {
      *       width: 128,
      *       height: 128,
      *       type: graphics.TEXTURE_TYPE_2D,
-     *       format: graphics.TEXTURE_FORMAT_RGBA,
+     *       format,
      *     };
      *     const my_texture_id = resource.create_texture("/my_texture.texturec", tparams);
      *
@@ -192,7 +195,7 @@ declare global {
      *           indices: [0, 1, 2, 0, 2, 3],
      *         },
      *       ],
-     *     };
+     *     } satisfies Parameters<typeof resource.create_atlas>[1];
      *     const my_atlas_id = resource.create_atlas("/my_atlas.texturesetc", aparams);
      *
      *     // assign the atlas to the 'sprite' component on the same go
@@ -201,7 +204,7 @@ declare global {
      * });
      * ```
      */
-    function create_atlas(path: string, table: { texture?: string | Hash; animations?: { id?: string; width?: number; height?: number; frame_start?: number; frame_end?: number; playback?: go.Playback; fps?: number; flip_vertical?: boolean; flip_horizontal?: boolean }[]; geometries?: { id?: string; width?: number; height?: number; pivot_x?: number; pivot_y?: number; rotated?: boolean }[]; vertices?: number[]; uvs?: number[]; indices?: number[] }): Hash;
+    function create_atlas(path: string, table: { texture: string | Hash; animations: [{ id: string; width: number; height: number; playback?: go.Playback; fps?: number; flip_vertical?: boolean; flip_horizontal?: boolean } & ({ frames: [number, ...number[]] } | { frame_start: number; frame_end: number }), ...({ id: string; width: number; height: number; playback?: go.Playback; fps?: number; flip_vertical?: boolean; flip_horizontal?: boolean } & ({ frames: [number, ...number[]] } | { frame_start: number; frame_end: number }))[]]; geometries: [{ id?: string; width?: number; height?: number; pivot_x?: number; pivot_y?: number; rotated?: boolean; vertices: number[]; uvs: number[]; indices: number[] }, ...{ id?: string; width?: number; height?: number; pivot_x?: number; pivot_y?: number; rotated?: boolean; vertices: number[]; uvs: number[]; indices: number[] }[]]; vertices?: number[]; uvs?: number[]; indices?: number[] }): Hash;
     /**
      * This function creates a new buffer resource that can be used in the same way as any buffer created during build time.
      * The function requires a valid buffer created from either buffer.create or another pre-existing buffer resource.
@@ -274,7 +277,7 @@ declare global {
      * });
      * ```
      */
-    function create_buffer(path: string, table?: { buffer?: Opaque<"buffer">; transfer_ownership?: boolean }): Hash;
+    function create_buffer(path: string, table: { buffer: Opaque<"buffer">; transfer_ownership?: boolean }): Hash;
     /**
      * Creates a sound data resource
      * Supported formats are .oggc, .opusc and .wavc
@@ -307,7 +310,7 @@ declare global {
      * });
      * ```
      */
-    function create_sound_data(path: string, options?: { data?: string; filesize?: number; partial?: boolean }): Hash;
+    function create_sound_data(path: string, options: { data: string | Opaque<"buffer">; filesize?: number; partial?: boolean }): 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
@@ -323,13 +326,9 @@ declare global {
      * number The texture type. Supported values:
      *
      * - `graphics.TEXTURE_TYPE_2D`
-     *
      * - `graphics.TEXTURE_TYPE_IMAGE_2D`
-     *
      * - `graphics.TEXTURE_TYPE_3D`
-     *
      * - `graphics.TEXTURE_TYPE_IMAGE_3D`
-     *
      * - `graphics.TEXTURE_TYPE_CUBE_MAP`
      *
      * `width`
@@ -342,68 +341,46 @@ declare global {
      * number The texture format, note that some of these formats might not be supported by the running device. Supported values:
      *
      * - `graphics.TEXTURE_FORMAT_LUMINANCE`
-     *
      * - `graphics.TEXTURE_FORMAT_RGB`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA`
      *
      * These constants might not be available on the device:
      *
      * - `graphics.TEXTURE_FORMAT_RGB_PVRTC_2BPPV1`
-     *
      * - `graphics.TEXTURE_FORMAT_RGB_PVRTC_4BPPV1`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA_PVRTC_2BPPV1`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA_PVRTC_4BPPV1`
-     *
      * - `graphics.TEXTURE_FORMAT_RGB_ETC1`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA_ETC2`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA_ASTC_4X4`
-     *
      * - `graphics.TEXTURE_FORMAT_RGB_BC1`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA_BC3`
-     *
      * - `graphics.TEXTURE_FORMAT_R_BC4`
-     *
      * - `graphics.TEXTURE_FORMAT_RG_BC5`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA_BC7`
-     *
      * - `graphics.TEXTURE_FORMAT_RGB16F`
-     *
      * - `graphics.TEXTURE_FORMAT_RGB32F`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA16F`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA32F`
-     *
      * - `graphics.TEXTURE_FORMAT_R16F`
-     *
      * - `graphics.TEXTURE_FORMAT_RG16F`
-     *
      * - `graphics.TEXTURE_FORMAT_R32F`
-     *
      * - `graphics.TEXTURE_FORMAT_RG32F`
      *
      * You can test if the device supports these values by checking if a specific enum is nil or not:
      *
-     * `if graphics.TEXTURE_FORMAT_RGBA16F ~= nil then
-     * -- it is safe to use this format
-     * end
-     * `
+     * ```ts
+     * if (graphics.TEXTURE_FORMAT_RGBA16F !== undefined) {
+     *   // it is safe to use this format
+     * }
+     * ```
      *
      * `flags`
      * number Texture creation flags that can be used to dictate how the texture is created. The default value is graphics.TEXTURE_USAGE_FLAG_SAMPLE, which means that the texture can be sampled from a shader.
      * These flags may or may not be supported on the running device and/or the underlying graphics API and is simply used internally as a 'hint' when creating the texture. There is no guarantee that any of these will have any effect. Supported values:
      *
      * - `graphics.TEXTURE_USAGE_FLAG_SAMPLE` - The texture can be sampled from a shader (default)
-     *
      * - `graphics.TEXTURE_USAGE_FLAG_MEMORYLESS` - The texture can be used as a memoryless texture, i.e only transient memory for the texture is used during rendering
-     *
      * - `graphics.TEXTURE_USAGE_FLAG_STORAGE` - The texture can be used as a storage texture, which is required for a shader to write to the texture
      *
      * `max_mipmaps`
@@ -413,15 +390,14 @@ declare global {
      * Creating an empty texture with no buffer data is not supported as a core feature. Defaults to graphics.COMPRESSION_TYPE_DEFAULT, i.e no compression. Supported values:
      *
      * - `COMPRESSION_TYPE_DEFAULT`
-     *
      * - `COMPRESSION_TYPE_BASIS_UASTC`
      * @param buffer - optional buffer of precreated pixel data
      * @returns The path to the resource.
      * 3D Textures are currently only supported on OpenGL and Vulkan adapters. To check if your device supports 3D textures, use:
-     * ```lua
-     * if graphics.TEXTURE_TYPE_3D ~= nil then
-     * -- Device and graphics adapter support 3D textures
-     * end
+     * ```ts
+     * if (graphics.TEXTURE_TYPE_3D !== undefined) {
+     *   // Device and graphics adapter support 3D textures
+     * }
      * ```
      * @example
      * How to create an 128x128 RGBA texture resource and assign it to a model
@@ -429,11 +405,14 @@ declare global {
      * // How to create an 128x128 RGBA texture resource and assign it to a model
      * export default defineScript({
      *   init() {
+     *     // the engine registers a texture format only when the driver supports it
+     *     const format = graphics.TEXTURE_FORMAT_RGBA;
+     *     if (format === undefined) return;
      *     const tparams = {
      *       width: 128,
      *       height: 128,
      *       type: graphics.TEXTURE_TYPE_2D,
-     *       format: graphics.TEXTURE_FORMAT_RGBA,
+     *       format,
      *     };
      *     const my_texture_id = resource.create_texture("/my_custom_texture.texturec", tparams);
      *     go.set("#model", "texture0", my_texture_id);
@@ -446,6 +425,9 @@ declare global {
      * // How to create an 128x128 floating point texture (RGBA32F) resource from a buffer object
      * export default defineScript({
      *   init() {
+     *     // the engine registers a texture format only when the driver supports it
+     *     const format = graphics.TEXTURE_FORMAT_RGBA32F;
+     *     if (format === undefined) return;
      *     // Create a new buffer with 4 components and FLOAT32 type
      *     const tbuffer = buffer.create(128 * 128, [{ name: hash("rgba"), type: buffer.VALUE_TYPE_FLOAT32, count: 4 }]);
      *     const tstream = buffer.get_stream(tbuffer, hash("rgba"));
@@ -466,7 +448,7 @@ declare global {
      *       width: 128,
      *       height: 128,
      *       type: graphics.TEXTURE_TYPE_2D,
-     *       format: graphics.TEXTURE_FORMAT_RGBA32F,
+     *       format,
      *     };
      *
      *     // Note that we pass the buffer as the last argument here!
@@ -483,12 +465,16 @@ declare global {
      * // How to create a 32x32x32 floating point 3D texture that can be used to generate volumetric data in a compute shader
      * export default defineScript({
      *   init() {
+     *     // the engine registers a texture type or format only when the driver supports it
+     *     const type = graphics.TEXTURE_TYPE_IMAGE_3D;
+     *     const format = graphics.TEXTURE_FORMAT_RGBA32F;
+     *     if (type === undefined || format === undefined) return;
      *     const t_volume = resource.create_texture("/my_backing_texture.texturec", {
-     *       type: graphics.TEXTURE_TYPE_IMAGE_3D,
+     *       type,
      *       width: 32,
      *       height: 32,
      *       depth: 32,
-     *       format: graphics.TEXTURE_FORMAT_RGBA32F,
+     *       format,
      *       flags: graphics.TEXTURE_USAGE_FLAG_STORAGE + graphics.TEXTURE_USAGE_FLAG_SAMPLE,
      *     });
      *
@@ -501,16 +487,20 @@ declare global {
      * How to create 512x512 texture array with 5 pages.
      * ```ts
      * // How to create 512x512 texture array with 5 pages.
-     * const new_tex = resource.create_texture("/runtime/example_array.texturec", {
-     *   type: graphics.TEXTURE_TYPE_2D_ARRAY,
-     *   width: 512,
-     *   height: 512,
-     *   page_count: 5,
-     *   format: graphics.TEXTURE_FORMAT_RGB,
-     * });
+     * // the engine registers a texture format only when the driver supports it
+     * const format = graphics.TEXTURE_FORMAT_RGB;
+     * if (format !== undefined) {
+     *   const new_tex = resource.create_texture("/runtime/example_array.texturec", {
+     *     type: graphics.TEXTURE_TYPE_2D_ARRAY,
+     *     width: 512,
+     *     height: 512,
+     *     page_count: 5,
+     *     format,
+     *   });
+     * }
      * ```
      */
-    function create_texture(path: string, table: { type?: number; width?: number; height?: number; depth?: number; format?: number; flags?: number; max_mipmaps?: number; compression_type?: number; page_count?: number }, buffer?: Opaque<"buffer">): Hash;
+    function create_texture(path: string, table: { type: number; width: number; height: number; depth?: number; format: number; flags?: number; max_mipmaps?: number; compression_type?: number; page_count?: number }, buffer?: Opaque<"buffer">): 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
@@ -529,13 +519,9 @@ declare global {
      * number The texture type. Supported values:
      *
      * - `graphics.TEXTURE_TYPE_2D`
-     *
      * - `graphics.TEXTURE_TYPE_IMAGE_2D`
-     *
      * - `graphics.TEXTURE_TYPE_3D`
-     *
      * - `graphics.TEXTURE_TYPE_IMAGE_3D`
-     *
      * - `graphics.TEXTURE_TYPE_CUBE_MAP`
      *
      * `width`
@@ -548,67 +534,45 @@ declare global {
      * number The texture format, note that some of these formats might not be supported by the running device. Supported values:
      *
      * - `graphics.TEXTURE_FORMAT_LUMINANCE`
-     *
      * - `graphics.TEXTURE_FORMAT_RGB`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA`
      *
      * These constants might not be available on the device:
      *
      * - `graphics.TEXTURE_FORMAT_RGB_PVRTC_2BPPV1`
-     *
      * - `graphics.TEXTURE_FORMAT_RGB_PVRTC_4BPPV1`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA_PVRTC_2BPPV1`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA_PVRTC_4BPPV1`
-     *
      * - `graphics.TEXTURE_FORMAT_RGB_ETC1`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA_ETC2`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA_ASTC_4X4`
-     *
      * - `graphics.TEXTURE_FORMAT_RGB_BC1`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA_BC3`
-     *
      * - `graphics.TEXTURE_FORMAT_R_BC4`
-     *
      * - `graphics.TEXTURE_FORMAT_RG_BC5`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA_BC7`
-     *
      * - `graphics.TEXTURE_FORMAT_RGB16F`
-     *
      * - `graphics.TEXTURE_FORMAT_RGB32F`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA16F`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA32F`
-     *
      * - `graphics.TEXTURE_FORMAT_R16F`
-     *
      * - `graphics.TEXTURE_FORMAT_RG16F`
-     *
      * - `graphics.TEXTURE_FORMAT_R32F`
-     *
      * - `graphics.TEXTURE_FORMAT_RG32F`
      *
      * You can test if the device supports these values by checking if a specific enum is nil or not:
      *
-     * `if graphics.TEXTURE_FORMAT_RGBA16F ~= nil then
-     * -- it is safe to use this format
-     * end
-     * `
+     * ```ts
+     * if (graphics.TEXTURE_FORMAT_RGBA16F !== undefined) {
+     *   // it is safe to use this format
+     * }
+     * ```
      *
      * `flags`
      * number Texture creation flags that can be used to dictate how the texture is created. Supported values:
      *
      * - `graphics.TEXTURE_USAGE_FLAG_SAMPLE` - The texture can be sampled from a shader (default)
-     *
      * - `graphics.TEXTURE_USAGE_FLAG_MEMORYLESS` - The texture can be used as a memoryless texture, i.e only transient memory for the texture is used during rendering
-     *
      * - `graphics.TEXTURE_USAGE_FLAG_STORAGE` - The texture can be used as a storage texture, which is required for a shader to write to the texture
      *
      * `max_mipmaps`
@@ -618,7 +582,6 @@ declare global {
      * Creating an empty texture with no buffer data is not supported as a core feature. Defaults to graphics.COMPRESSION_TYPE_DEFAULT, i.e no compression. Supported values:
      *
      * - `COMPRESSION_TYPE_DEFAULT`
-     *
      * - `COMPRESSION_TYPE_BASIS_UASTC`
      * @param buffer - optional buffer of precreated pixel data
      * @param callback - callback function when texture is created (self, request_id, resource)
@@ -667,17 +630,20 @@ declare global {
      * });
      * ```
      * @example
-     * Create a texture resource asyncronously without a callback
+     * Create a texture resource asynchronously with a callback that does nothing
      * ```ts
-     * // Create a texture resource asyncronously without a callback
+     * // Create a texture resource asyncronously without handling its completion
      * export default defineScript({
      *   init() {
+     *     // the engine registers a texture format only when the driver supports it
+     *     const format = graphics.TEXTURE_FORMAT_RGBA;
+     *     if (format === undefined) return;
      *     // Create a texture resource async
      *     const tparams = {
      *       width: 128,
      *       height: 128,
      *       type: graphics.TEXTURE_TYPE_2D,
-     *       format: graphics.TEXTURE_FORMAT_RGBA,
+     *       format,
      *     };
      *
      *     // Create a new buffer with 4 components
@@ -695,7 +661,8 @@ declare global {
      *       }
      *     }
      *     // create the texture
-     *     const [tpath, request_id] = resource.create_texture_async("/my_texture.texturec", tparams, tbuffer);
+     *     // the binding requires a callback function, so pass one that does nothing
+     *     const [tpath, request_id] = resource.create_texture_async("/my_texture.texturec", tparams, tbuffer, () => {});
      *     // at this point you can use the resource as-is, but note that the texture will be a blank 1x1 texture
      *     // that will be removed once the new texture has been updated
      *     go.set("#model", "texture0", tpath);
@@ -703,12 +670,11 @@ declare global {
      * });
      * ```
      */
-    function create_texture_async(path: string | Hash, table: { type?: number; width?: number; height?: number; depth?: number; format?: number; flags?: number; max_mipmaps?: number; compression_type?: number }, buffer?: Opaque<"buffer">, callback?: (...args: unknown[]) => unknown): LuaMultiReturn<[Hash, number]>;
+    function create_texture_async(path: string, table: { type: number; width: number; height: number; depth?: number; format: number; flags?: number; max_mipmaps?: number; compression_type?: number }, buffer: Opaque<"buffer"> | undefined, callback: (...args: unknown[]) => unknown): LuaMultiReturn<[Hash, number]>;
     /**
      * Constructor-like function with two purposes:
      *
      * - Load the specified resource as part of loading the script
-     *
      * - Return a hash to the run-time version of the resource
      *
      * This function can only be called within go.property function calls.
@@ -752,14 +718,14 @@ declare global {
      * @returns A table with the following entries:
      *
      * - texture
-     *
      * - geometries
-     *
      * - animations
      *
      * Each animation entry also contains a `frames` table with indices into
      * `geometries`, preserving the frame-to-geometry mapping used by the atlas.
      * See resource.set_atlas for a detailed description of each field
+     *
+     * **⚠️ `frames` is 1-based; passed to Defold unchanged.** **0️⃣ `indices` is 0-based; passed to Defold unchanged.**
      */
     function get_atlas(path: Hash | string): { texture: string | Hash; animations: { id: string; width: number; height: number; frame_start: number; frame_end: number; playback: go.Playback; fps: number; flip_vertical: boolean; flip_horizontal: boolean }[]; geometries: { vertices: number[]; uvs: number[]; indices: number[] }[] };
     /**
@@ -806,26 +772,18 @@ declare global {
      * number The texture type. Supported values:
      *
      * - `graphics.TEXTURE_TYPE_2D`
-     *
      * - `graphics.TEXTURE_TYPE_CUBE_MAP`
-     *
      * - `graphics.TEXTURE_TYPE_2D_ARRAY`
      *
      * `buffer_type`
      * number The attachment buffer type. Supported values:
      *
      * - `resource.BUFFER_TYPE_COLOR0`
-     *
      * - `resource.BUFFER_TYPE_COLOR1`
-     *
      * - `resource.BUFFER_TYPE_COLOR2`
-     *
      * - `resource.BUFFER_TYPE_COLOR3`
-     *
      * - `resource.BUFFER_TYPE_DEPTH`
-     *
      * - `resource.BUFFER_TYPE_STENCIL`
-     *
      * - `texture`
      * hash The hashed path to the attachment texture resource. This field is only available if the render target passed in is a resource.
      * @example
@@ -876,11 +834,8 @@ declare global {
      * @returns a table with the following fields:
      *
      * - width
-     *
      * - height
-     *
      * - max_ascent
-     *
      * - max_descent
      * @example
      * ```ts
@@ -893,7 +848,7 @@ declare global {
      * });
      * ```
      */
-    function get_text_metrics(url: Hash, text: string, options?: { width?: number; leading?: number; tracking?: number; line_break?: boolean }): { width: number; height: number; max_ascent: number; max_descent: number };
+    function get_text_metrics(url: Hash | string, text: string, options?: { width?: number; leading?: number; tracking?: number; line_break?: boolean }): { width: number; height: number; max_ascent: number; max_descent: number };
     /**
      * Gets texture info from a texture resource path or a texture handle
      *
@@ -918,15 +873,10 @@ declare global {
      * number The texture type. Supported values:
      *
      * - `graphics.TEXTURE_TYPE_2D`
-     *
      * - `graphics.TEXTURE_TYPE_2D_ARRAY`
-     *
      * - `graphics.TEXTURE_TYPE_IMAGE_2D`
-     *
      * - `graphics.TEXTURE_TYPE_3D`
-     *
      * - `graphics.TEXTURE_TYPE_IMAGE_3D`
-     *
      * - `graphics.TEXTURE_TYPE_CUBE_MAP`
      * @example
      * Create a new texture and get the metadata from it
@@ -934,12 +884,15 @@ declare global {
      * // Create a new texture and get the metadata from it
      * export default defineScript({
      *   init() {
+     *     // the engine registers a texture format only when the driver supports it
+     *     const format = graphics.TEXTURE_FORMAT_RGBA;
+     *     if (format === undefined) return;
      *     // create an empty texture
      *     const tparams = {
      *       width: 128,
      *       height: 128,
      *       type: graphics.TEXTURE_TYPE_2D,
-     *       format: graphics.TEXTURE_FORMAT_RGBA,
+     *       format,
      *     };
      *
      *     const my_texture_path = resource.create_texture("/my_texture.texturec", tparams);
@@ -983,9 +936,11 @@ declare global {
      * ```ts
      * // read custom resource data into buffer
      * const buffer = resource.load("/resources/datafile");
-     *
-     * // In order for the engine to include custom resources in the build process, you
-     * // need to specify them in the "game.project" settings file:
+     * ```
+     * @example
+     * In order for the engine to include custom resources in the build process, you need
+     * to specify them in the "game.project" settings file:
+     * ```ts
      * // [project]
      * // title = My project
      * // version = 0.1
@@ -997,7 +952,6 @@ declare global {
      * Constructor-like function with two purposes:
      *
      * - Load the specified resource as part of loading the script
-     *
      * - Return a hash to the run-time version of the resource
      *
      * This function can only be called within go.property function calls.
@@ -1045,7 +999,6 @@ declare global {
      * Constructor-like function with two purposes:
      *
      * - Load the specified resource as part of loading the script
-     *
      * - Return a hash to the run-time version of the resource
      *
      * This function can only be called within go.property function calls.
@@ -1142,6 +1095,8 @@ declare global {
      *
      * - `indices`
      * table a list of the indices of the geometry in the form {i0, i1, i2, ..., in}. Each tripe in the list represents a triangle.
+     *
+     * **⚠️ `frame_start` is 1-based; passed to Defold unchanged.** **⚠️ `frame_end` is 1-based; passed to Defold unchanged.** **⚠️ `frame_start` is 1-based; passed to Defold unchanged.** **⚠️ `frame_end` is 1-based; passed to Defold unchanged.** **⚠️ `frames` is 1-based; passed to Defold unchanged.** **0️⃣ `indices` is 0-based; passed to Defold unchanged.**
      * @example
      * Add a new animation to an existing atlas
      * ```ts
@@ -1160,8 +1115,22 @@ declare global {
      *       flip_vertical: false,
      *       flip_horizontal: false,
      *     };
-     *     data.animations.push(my_animation);
-     *     resource.set_atlas("/main/my_atlas.a.texturesetc", data);
+     *     // set_atlas takes each animation's frames as a non-empty list
+     *     const animations = data.animations.flatMap((animation) => {
+     *       // an animation described by frame_start/frame_end passes through as-is
+     *       if (!("frames" in animation)) return [animation];
+     *       const [first, ...rest] = (animation.frames as number[] | undefined) ?? [];
+     *       return first === undefined ? [] : [{ ...animation, frames: [first, ...rest] as [number, ...number[]] }];
+     *     });
+     *     // set_atlas needs at least one animation and one geometry
+     *     const [first_geometry, ...geometries] = data.geometries;
+     *     if (first_geometry !== undefined) {
+     *       resource.set_atlas("/main/my_atlas.a.texturesetc", {
+     *         ...data,
+     *         animations: [my_animation, ...animations],
+     *         geometries: [first_geometry, ...geometries],
+     *       });
+     *     }
      *   },
      * });
      * ```
@@ -1188,13 +1157,13 @@ declare global {
      *           indices: [0, 1, 2, 0, 2, 3],
      *         },
      *       ],
-     *     };
+     *     } satisfies Parameters<typeof resource.set_atlas>[1];
      *     resource.set_atlas("/main/test.a.texturesetc", params);
      *   },
      * });
      * ```
      */
-    function set_atlas(path: Hash | string, table: { texture?: string | Hash; animations?: { id?: string; width?: number; height?: number; frame_start?: number; frame_end?: number; playback?: go.Playback; fps?: number; flip_vertical?: boolean; flip_horizontal?: boolean }[]; geometries?: { vertices?: number[]; uvs?: number[]; indices?: number[] }[]; vertices?: number[]; uvs?: number[]; indices?: number[] }): void;
+    function set_atlas(path: Hash | string, table: { texture: string | Hash; animations: [{ id: string; width: number; height: number; playback?: go.Playback; fps?: number; flip_vertical?: boolean; flip_horizontal?: boolean } & ({ frames: [number, ...number[]] } | { frame_start: number; frame_end: number }), ...({ id: string; width: number; height: number; playback?: go.Playback; fps?: number; flip_vertical?: boolean; flip_horizontal?: boolean } & ({ frames: [number, ...number[]] } | { frame_start: number; frame_end: number }))[]]; geometries: [{ vertices: number[]; uvs: number[]; indices: number[] }, ...{ vertices: number[]; uvs: number[]; indices: number[] }[]]; vertices?: number[]; uvs?: number[]; indices?: number[] }): void;
     /**
      * Sets the buffer of a resource. By default, setting the resource buffer will either copy the data from the incoming buffer object
      * to the buffer stored in the destination resource, or make a new buffer object if the sizes between the source buffer and the destination buffer
@@ -1262,13 +1231,9 @@ declare global {
      * number The texture type. Supported values:
      *
      * - `graphics.TEXTURE_TYPE_2D`
-     *
      * - `graphics.TEXTURE_TYPE_IMAGE_2D`
-     *
      * - `graphics.TEXTURE_TYPE_3D`
-     *
      * - `graphics.TEXTURE_TYPE_IMAGE_3D`
-     *
      * - `graphics.TEXTURE_TYPE_CUBE_MAP`
      *
      * `width`
@@ -1279,9 +1244,7 @@ declare global {
      * number The texture format, note that some of these formats are platform specific. Supported values:
      *
      * - `graphics.TEXTURE_FORMAT_LUMINANCE`
-     *
      * - `graphics.TEXTURE_FORMAT_RGB`
-     *
      * - `graphics.TEXTURE_FORMAT_RGBA`
      *
      * These constants might not be available on the device:
@@ -1307,10 +1270,11 @@ declare global {
      * - `graphics.TEXTURE_FORMAT_RG32F`
      * You can test if the device supports these values by checking if a specific enum is nil or not:
      *
-     * `if graphics.TEXTURE_FORMAT_RGBA16F ~= nil then
-     * -- it is safe to use this format
-     * end
-     * `
+     * ```ts
+     * if (graphics.TEXTURE_FORMAT_RGBA16F !== undefined) {
+     *   // it is safe to use this format
+     * }
+     * ```
      *
      * `x`
      * number optional x offset of the texture (in pixels)
@@ -1326,15 +1290,16 @@ declare global {
      * number optional specify the compression type for the data in the buffer object that holds the texture data. Defaults to graphics.COMPRESSION_TYPE_DEFAULT, i.e no compression. Supported values:
      *
      * - `COMPRESSION_TYPE_DEFAULT`
-     *
      * - `COMPRESSION_TYPE_BASIS_UASTC`
+     *
+     * **0️⃣ `page` is 0-based; passed to Defold unchanged.** **0️⃣ `mipmap` is 0-based; passed to Defold unchanged.**
      * @param buffer - The buffer of precreated pixel data
      * To update a cube map texture you need to pass in six times the amount of data via the buffer, since a cube map has six sides!
      * 3D Textures are currently only supported on OpenGL and Vulkan adapters. To check if your device supports 3D textures, use:
-     * ```lua
-     * if graphics.TEXTURE_TYPE_3D ~= nil then
-     * -- Device and graphics adapter support 3D textures
-     * end
+     * ```ts
+     * if (graphics.TEXTURE_TYPE_3D !== undefined) {
+     *   // Device and graphics adapter support 3D textures
+     * }
      * ```
      * @example
      * How to set all pixels of an atlas
@@ -1356,9 +1321,13 @@ declare global {
      *       }
      *     }
      *
-     *     const resource_path = go.get<model.properties>()("#model", "texture0");
-     *     const args = { width, height, type: graphics.TEXTURE_TYPE_2D, format: graphics.TEXTURE_FORMAT_RGB, num_mip_maps: 1 };
-     *     resource.set_texture(resource_path, args, buf);
+     *     // the engine registers a texture format only when the driver supports it
+     *     const format = graphics.TEXTURE_FORMAT_RGB;
+     *     if (format !== undefined) {
+     *       const resource_path = go.get<model.properties>()("#model", "texture0");
+     *       const args = { width, height, type: graphics.TEXTURE_TYPE_2D, format, num_mip_maps: 1 };
+     *       resource.set_texture(resource_path, args, buf);
+     *     }
      *     return { buffer: buf, stream };
      *   },
      * });
@@ -1385,9 +1354,13 @@ declare global {
      *       }
      *     }
      *
-     *     const resource_path = go.get<model.properties>()("#model", "texture0");
-     *     const args = { width, height, x, y, type: graphics.TEXTURE_TYPE_2D, format: graphics.TEXTURE_FORMAT_RGB, num_mip_maps: 1 };
-     *     resource.set_texture(resource_path, args, buf);
+     *     // the engine registers a texture format only when the driver supports it
+     *     const format = graphics.TEXTURE_FORMAT_RGB;
+     *     if (format !== undefined) {
+     *       const resource_path = go.get<model.properties>()("#model", "texture0");
+     *       const args = { width, height, x, y, type: graphics.TEXTURE_TYPE_2D, format, num_mip_maps: 1 };
+     *       resource.set_texture(resource_path, args, buf);
+     *     }
      *     return { buffer: buf, stream };
      *   },
      * });
@@ -1402,13 +1375,16 @@ declare global {
      *   properties: { my_buffer: resource.buffer("/my_default_buffer.buffer") },
      *
      *   init(self) {
+     *     // the engine registers a texture format only when the driver supports it
+     *     const format = graphics.TEXTURE_FORMAT_RGB;
+     *     if (format === undefined) return;
      *     const resource_path = go.get<model.properties>()("#model", "texture0");
      *     // the "my_buffer" resource is expected to hold 128 * 128 * 3 bytes!
      *     const args = {
      *       width: 128,
      *       height: 128,
      *       type: graphics.TEXTURE_TYPE_2D,
-     *       format: graphics.TEXTURE_FORMAT_RGB,
+     *       format,
      *     };
      *     // Note that the extra resource.get_buffer call is a requirement here
      *     // since the "self.my_buffer" is just pointing to a buffer resource path
@@ -1461,7 +1437,9 @@ declare global {
      * // Update texture 2nd array page with loaded texture from png
      * const tex_path = "/bundle_resources/page_02.png";
      * const [data] = sys.load_resource(tex_path);
-     * if (data !== undefined) {
+     * // the engine registers a texture format only when the driver supports it
+     * const format = graphics.TEXTURE_FORMAT_RGB;
+     * if (data !== undefined && format !== undefined) {
      *   const buf = image.load_buffer(data);
      *   if (buf !== undefined) {
      *     // new_tex is the resource handle of a texture created via resource.create_texture
@@ -1470,7 +1448,7 @@ declare global {
      *       width: buf.width,
      *       height: buf.height,
      *       page_count: 2,
-     *       format: graphics.TEXTURE_FORMAT_RGB,
+     *       format,
      *     });
      *     resource.set_texture(
      *       new_tex,
@@ -1479,7 +1457,7 @@ declare global {
      *         width: buf.width,
      *         height: buf.height,
      *         page: 1,
-     *         format: graphics.TEXTURE_FORMAT_RGB,
+     *         format,
      *       },
      *       buf.buffer,
      *     );
@@ -1488,12 +1466,11 @@ declare global {
      * }
      * ```
      */
-    function set_texture(path: Hash | string, table: { type?: number; width?: number; height?: number; format?: number; x?: number; y?: number; z?: number; page?: number; mipmap?: number; compression_type?: number }, buffer: Opaque<"buffer">): void;
+    function set_texture(path: Hash | string, table: { type: number; width: number; height: number; format: number; x?: number; y?: number; z?: number; page?: number; mipmap?: number; compression_type?: number }, buffer: Opaque<"buffer">): void;
     /**
      * Constructor-like function with two purposes:
      *
      * - Load the specified resource as part of loading the script
-     *
      * - Return a hash to the run-time version of the resource
      *
      * This function can only be called within go.property function calls.
@@ -1519,7 +1496,6 @@ declare global {
      * Constructor-like function with two purposes:
      *
      * - Load the specified resource as part of loading the script
-     *
      * - Return a hash to the run-time version of the resource
      *
      * This function can only be called within go.property function calls.