@defold-typescript/types 0.50.1 → 0.52.0

package/generated/versions/defold-1.12.4/http.d.ts

@@ -1,5 +1,5 @@
 /** @noSelfInFile */
-import type { Hash } from "../../../src/core-types";
+import type { Hash, Url } from "../../../src/core-types";
 
 declare global {
   /**
@@ -31,6 +31,8 @@ declare global {
      * - number `range_start`: the start offset into the requested file
      * - number `range_end`: the end offset into the requested file (inclusive)
      * - number `document_size`: the full size of the requested file
+     *
+     * With `report_progress` set, the callback also receives progress events carrying `bytes_sent`, `bytes_received`, `bytes_total` and `url` but no `status`; `response.bytes_received !== undefined` marks a progress event, since a final response never carries it.
      * @param headers - optional table with custom headers
      * @param post_data - optional data to send
      * @param options - optional table with request parameters. Supported entries:
@@ -70,7 +72,7 @@ declare global {
      * });
      * ```
      */
-    function request(url: string, method: string, callback: (self: unknown, id: Hash, response: { status: number; response?: string; headers?: LuaMap<string, string>; path?: string; error?: string; bytes_received?: number; bytes_total?: number; range_start?: number; range_end?: number; document_size?: number }) => void, headers?: LuaMap<string, string> | Record<string, string>, post_data?: string, options?: { timeout?: number; path?: string; ignore_cache?: boolean; chunked_transfer?: boolean; report_progress?: boolean }): void;
+    function request(url: string, method: string, callback: (self: unknown, id: Hash, response: { status: number; url: string; response?: string; headers?: LuaMap<string, string>; path?: string; error?: string; bytes_sent?: number; bytes_received?: number; bytes_total?: number; range_start?: number; range_end?: number; document_size?: number }, sender: Url) => void, headers?: LuaMap<string, string> | Record<string, string>, post_data?: string, options?: { timeout?: number; path?: string; ignore_cache?: boolean; chunked_transfer?: boolean; report_progress?: boolean }): void;
   }
 }
 

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

@@ -44,7 +44,7 @@ declare global {
      * }
      * ```
      */
-    function get_astc_header(buffer: string): { width: number; height: number; depth: number; block_size_x: number; block_size_y: number; block_size_z: number } | undefined;
+    function get_astc_header(buffer: string): { width: number; height: number; depth: number; block_size_x: number; block_size_y: number; block_size_z: number };
     /**
      * Load image (PNG or JPEG) from buffer.
      *
@@ -77,7 +77,87 @@ declare global {
      * });
      * ```
      */
-    function load(buffer: string, options?: { premultiply_alpha?: boolean; flip_vertically?: boolean }): { width: number; height: number; type: Opaque<"constant">; buffer: string } | undefined;
+    function load(buffer: string): { width: number; height: number; type: Opaque<"constant">; buffer: string } | undefined;
+    /**
+     * Load image (PNG or JPEG) from buffer.
+     *
+     * @param buffer - image data buffer
+     * @param options - An optional table containing parameters for loading the image. Supported entries:
+     *
+     * `premultiply_alpha`
+     * boolean True if alpha should be premultiplied into the color components. Defaults to `false`.
+     * `flip_vertically`
+     * boolean True if the image contents should be flipped vertically. Defaults to `false`.
+     * @returns object or `nil` if loading fails. The object is a table with the following fields:
+     *
+     * - number `width`: image width
+     * - number `height`: image height
+     * - constant `type`: image type
+     *   - `image.TYPE_RGB`
+     *   - `image.TYPE_RGBA`
+     *   - `image.TYPE_LUMINANCE`
+     *   - `image.TYPE_LUMINANCE_ALPHA`
+     * - string `buffer`: the raw image data
+     * @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: { premultiply_alpha?: boolean; flip_vertically?: boolean }): { width: number; height: number; type: Opaque<"constant">; buffer: string } | undefined;
+    /**
+     * Load image (PNG or JPEG) from a string buffer.
+     *
+     * @param buffer - image data buffer
+     * @param options - An optional table containing parameters for loading the image. Supported entries:
+     *
+     * `premultiply_alpha`
+     * boolean True if alpha should be premultiplied into the color components. Defaults to `false`.
+     * `flip_vertically`
+     * boolean True if the image contents should be flipped vertically. Defaults to `false`.
+     * @returns object or `nil` if loading fails. The object is a table with the following fields:
+     *
+     * - number `width`: image width
+     * - number `height`: image height
+     * - constant `type`: image type
+     *   - `image.TYPE_RGB`
+     *   - `image.TYPE_RGBA`
+     *   - `image.TYPE_LUMINANCE`
+     *   - `image.TYPE_LUMINANCE_ALPHA`
+     * - buffer `buffer`: the script buffer that holds the decompressed image data. See buffer.create how to use the buffer.
+     * @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): { width: number; height: number; type: Opaque<"constant">; buffer: Opaque<"buffer"> & { length: LuaLengthMethod<number> } } | undefined;
     /**
      * Load image (PNG or JPEG) from a string buffer.
      *
@@ -124,7 +204,7 @@ declare global {
      * });
      * ```
      */
-    function load_buffer(buffer: string, options?: { premultiply_alpha?: boolean; flip_vertically?: boolean }): { width: number; height: number; type: Opaque<"constant">; buffer: Opaque<"buffer"> } | undefined;
+    function load_buffer(buffer: string, options: { premultiply_alpha?: boolean; flip_vertically?: boolean }): { width: number; height: number; type: Opaque<"constant">; buffer: Opaque<"buffer"> & { length: LuaLengthMethod<number> } } | undefined;
   }
 }
 

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

@@ -40,10 +40,12 @@ import "../../../src/engine-globals";
 import "../../../src/msg-overloads";
 import "../../../src/message-guard";
 import "../../../src/window-event-guard";
+import "../../../src/physics-event-guard";
 import "../../../src/scene-addresses";
 import "../../../src/go-overloads";
 import "../../../src/component-properties";
 import "../../../src/render-overloads";
+import "../../../src/gui-overloads";
 import "../../../src/vmath-overloads";
 import "../../../src/sys-overloads";
 

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

@@ -36,6 +36,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" };
     /**
      * LIVEUPDATE_OK
      */

package/generated/versions/defold-1.12.4/model.d.ts

@@ -136,10 +136,9 @@ declare global {
      * // How to play the "jump" animation followed by the "run" animation:
      * const url = msg.url("#model");
      *
-     * function anim_done(self: unknown, message_id: unknown, message: unknown, sender: unknown) {
+     * function anim_done(self: unknown, message_id: Hash, message: { animation_id: Hash }) {
      *   if (message_id === hash("model_animation_done")) {
-     *     const { animation_id } = message as { animation_id: Hash };
-     *     if (animation_id === hash("jump")) {
+     *     if (message.animation_id === hash("jump")) {
      *       // open animation done, chain with "run"
      *       const properties = { blend_duration: 0.2 };
      *       model.play_anim(url, "run", go.PLAYBACK_LOOP_FORWARD, properties, anim_done);
@@ -156,7 +155,7 @@ declare global {
      * });
      * ```
      */
-    function play_anim(url: string | Hash | Url, anim_id: string | Hash, playback: go.Playback, play_properties?: { blend_duration?: number; offset?: number; playback_rate?: number }, complete_function?: (self: unknown, message_id: unknown, message: unknown, sender: unknown) => void): void;
+    function play_anim(url: string | Hash | Url, anim_id: string | Hash, playback: go.Playback, play_properties?: { blend_duration?: number; offset?: number; playback_rate?: number }, complete_function?: (self: unknown, message_id: Hash, message: BuiltinMessages["model_animation_done"]) => void): void;
     /**
      * Enable or disable visibility of a mesh
      *
@@ -178,7 +177,7 @@ declare global {
       /**
        * The current animation set on the component. The type of the property is hash.
        */
-      animation: Hash;
+      readonly animation: Hash;
       /**
        * The normalized animation cursor. The type of the property is number.
        * Please note that model events may not fire as expected when the cursor is manipulated directly.

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

@@ -134,7 +134,28 @@ declare global {
      * });
      * ```
      */
-    function stop(url: string | Hash | Url, options?: { clear?: boolean }): 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 when stopping the particle fx. Supported options:
+     *
+     * - boolean `clear`: instantly clear spawned particles
+     * @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: { clear?: boolean }): void;
     interface properties {
       /**
        * The animation used during rendering by an emitter in a particle FX component.

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

@@ -202,7 +202,7 @@ declare global {
      * @returns It returns a list. If missed it returns `nil`. See ray_cast_response for details on the returned values.
      * @example
      * ```ts
-     * function handle_result(hit: { fraction: number; position: Vector3; normal: Vector3; id: Hash; group: Hash; request_id: number }) {
+     * function handle_result(hit: { fraction: number; position: Vector3; normal: Vector3; id: Hash; group: Hash }) {
      *   // act on the hit (see 'ray_cast_response')
      * }
      *
@@ -227,7 +227,7 @@ declare global {
      * });
      * ```
      */
-    function raycast(from: Vector3, to: Vector3, groups: Hash[], options?: { all?: boolean }): { fraction: number; position: Vector3; normal: Vector3; id: Hash; group: Hash; request_id: number }[] | undefined;
+    function raycast(from: Vector3, to: Vector3, groups: Hash[], options?: { all?: boolean }): Omit<BuiltinMessages["ray_cast_response"], "request_id">[] | Omit<BuiltinMessages["ray_cast_response"], "request_id"> | undefined;
     /**
      * 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
@@ -271,7 +271,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.12.4/render.d.ts

@@ -14,10 +14,12 @@ declare global {
    * require features not in OpenGL ES 2.0, but those will not work cross platform.
    */
   namespace render {
-    type constant_buffer = Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | Matrix4[] };
+    type constant_buffer = Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | ConstantArray<Vector4> | ConstantArray<Matrix4> };
     type render_target = Opaque<"render_target">;
     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 = Record<string | number, unknown>;
     /**
      * The rendering context was lost. Rendering is paused and all graphics resources become invalid. Passed to the `render.set_listener` callback.
      */
@@ -112,7 +114,7 @@ declare global {
      * constants.light_colors[3] = vmath.vector4(1, 1, 1, 1);
      * ```
      */
-    function constant_buffer(): Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | Matrix4[] };
+    function constant_buffer(): Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | ConstantArray<Vector4> | ConstantArray<Matrix4> };
     /**
      * Deletes a render target created by a render script.
      * You cannot delete a render target resource.
@@ -125,9 +127,12 @@ declare global {
      *     return { my_render_target: render.render_target("my_target", {}) };
      *   },
      *
-     *   final(self) {
-     *     // How to delete a render target:
-     *     render.delete_render_target(self.my_render_target);
+     *   // A render script has no final hook, so free the target on a message.
+     *   on_message(self, message_id) {
+     *     if (message_id === hash("release_target")) {
+     *       // How to delete a render target:
+     *       render.delete_render_target(self.my_render_target);
+     *     }
      *   },
      * });
      * ```
@@ -190,8 +195,11 @@ declare global {
      * ```ts
      * 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: graphics.TEXTURE_FORMAT_RGBA,
+     *       format,
      *       width: render.get_window_width(),
      *       height: render.get_window_height(),
      *     };
@@ -202,6 +210,7 @@ declare global {
      *   },
      *
      *   update(self, dt) {
+     *     if (self === undefined) return;
      *     render.enable_texture(0, self.my_render_target, graphics.BUFFER_TYPE_COLOR0_BIT);
      *     // draw a predicate with the render target available as texture 0 in the predicate
      *     // material shader.
@@ -212,7 +221,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
@@ -231,8 +240,11 @@ declare global {
      * ```ts
      * 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: graphics.TEXTURE_FORMAT_RGBA,
+     *       format,
      *       width: render.get_window_width(),
      *       height: render.get_window_height(),
      *     };
@@ -243,6 +255,7 @@ declare global {
      *   },
      *
      *   update(self, dt) {
+     *     if (self === undefined) return;
      *     render.set_compute("bloom");
      *     render.enable_texture(0, self.backing_texture);
      *     render.enable_texture(1, self.scene_rt);
@@ -259,7 +272,7 @@ declare global {
      * render.dispatch_compute(32, 32, 32, { constants });
      * ```
      */
-    function dispatch_compute(x: number, y: number, z: number, options?: { constants?: Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | Matrix4[] } }): void;
+    function dispatch_compute(x: number, y: number, z: number, options?: { constants?: Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | ConstantArray<Vector4> | ConstantArray<Matrix4> } }): 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
@@ -321,7 +334,7 @@ declare global {
      * }
      * ```
      */
-    function draw(predicate: Opaque<"render_predicate">, options?: { frustum?: Matrix4; frustum_planes?: number; constants?: Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | Matrix4[] }; sort_order?: number }): void;
+    function draw(predicate: Opaque<"render_predicate">, options?: { frustum?: Matrix4; frustum_planes?: number; constants?: Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | ConstantArray<Vector4> | ConstantArray<Matrix4> }; sort_order?: number }): void;
     /**
      * Draws all 3d debug graphics such as lines drawn with "draw_line" messages and physics visualization.
      *
@@ -432,8 +445,11 @@ declare global {
      * ```ts
      * 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: graphics.TEXTURE_FORMAT_RGBA,
+     *       format,
      *       width: render.get_window_width(),
      *       height: render.get_window_height(),
      *     };
@@ -444,6 +460,7 @@ declare global {
      *   },
      *
      *   update(self, dt) {
+     *     if (self === undefined) return;
      *     // enable target so all drawing is done to it
      *     render.set_render_target(self.my_render_target);
      *
@@ -524,8 +541,11 @@ declare global {
      * ```ts
      * 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: graphics.TEXTURE_FORMAT_RGBA,
+     *       format,
      *       width: render.get_window_width(),
      *       height: render.get_window_height(),
      *     };
@@ -537,6 +557,7 @@ declare global {
      *   },
      *
      *   update(self, dt) {
+     *     if (self === undefined) return;
      *     // get the height of the render target color buffer
      *     const h = render.get_render_target_height(self.target_right, graphics.BUFFER_TYPE_COLOR0_BIT);
      *     // get the height of a render target resource
@@ -561,8 +582,11 @@ declare global {
      * ```ts
      * 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: graphics.TEXTURE_FORMAT_RGBA,
+     *       format,
      *       width: render.get_window_width(),
      *       height: render.get_window_height(),
      *     };
@@ -574,6 +598,7 @@ declare global {
      *   },
      *
      *   update(self, dt) {
+     *     if (self === undefined) return;
      *     // get the width of the render target color buffer
      *     const w = render.get_render_target_width(self.target_right, graphics.BUFFER_TYPE_COLOR0_BIT);
      *     // get the width of a render target resource
@@ -953,8 +978,86 @@ declare global {
      * // 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): 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. render.RENDER_TARGET_DEFAULT to set the default render target
+     * @param options - optional table with behaviour parameters
+     *
+     * `transient`
+     * table Transient frame buffer types are only valid while the render target is active, i.e becomes undefined when a new target is set by a subsequent call to set_render_target.
+     * Default is all non-transient. Be aware that some hardware uses a combined depth stencil buffer and when this is the case both are considered non-transient if exclusively selected!
+     * A buffer type defined that doesn't exist in the render target is silently ignored.
+     *
+     * - `graphics.BUFFER_TYPE_COLOR0_BIT`
+     * - `graphics.BUFFER_TYPE_DEPTH_BIT`
+     * - `graphics.BUFFER_TYPE_STENCIL_BIT`
+     * @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: graphics.TEXTURE_FORMAT_RGBA,
+     *       format,
      *       width: render.get_window_width(),
      *       height: render.get_window_height(),
      *     };
@@ -965,6 +1068,7 @@ declare global {
      *   },
      *
      *   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],
@@ -999,7 +1103,7 @@ declare global {
      * });
      * ```
      */
-    function set_render_target(render_target?: Opaque<"render_target"> | string | Hash | typeof render.RENDER_TARGET_DEFAULT, options?: { transient?: graphics.BufferType[] }): void;
+    function set_render_target(render_target: Opaque<"render_target"> | string | Hash | typeof render.RENDER_TARGET_DEFAULT | undefined, options: { transient?: graphics.BufferType[] }): void;
     /**
      * Sets the render target size for a render target created from
      * either a render script, or from a render target resource.