@defold-typescript/types 0.38.0 → 0.40.0

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

@@ -14,9 +14,10 @@ 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">;
+    type constant_buffer = Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | 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;
     const FRUSTUM_PLANES_ALL: number & { readonly __brand: "render.FRUSTUM_PLANES_ALL" };
     const FRUSTUM_PLANES_SIDES: number & { readonly __brand: "render.FRUSTUM_PLANES_SIDES" };
     const RENDER_TARGET_DEFAULT: number & { readonly __brand: "render.RENDER_TARGET_DEFAULT" };
@@ -52,7 +53,7 @@ declare global {
      * render.clear(buffers);
      * ```
      */
-    function clear(buffers: LuaMap<number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR0_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_DEPTH_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_STENCIL_BIT" }, number | Vector4>): void;
+    function clear(buffers: LuaMap<render.ClearBufferKey, number | Vector4>): void;
     /**
      * Constant buffers are used to set shader program variables and are optionally passed to the `render.draw()` function.
      * The buffer's constant elements can be indexed like an ordinary Lua table, but you can't iterate over them with pairs() or ipairs().
@@ -60,33 +61,41 @@ declare global {
      * @returns new constant buffer
      * @example
      * ```ts
-     * // Set a "tint" constant in a constant buffer in the render script:
-     * const constants = render.constant_buffer();
-     * constants.tint = vmath.vector4(1, 1, 1, 1);
-     *
-     * // Then use the constant buffer when drawing a predicate:
-     * render.draw(self.my_pred, { constants });
-     *
-     * // The constant buffer also supports array values by specifying constants in an array:
-     * const constants2 = render.constant_buffer();
-     * constants2.light_colors = [];
-     * constants2.light_colors[0] = vmath.vector4(1, 0, 0, 1);
-     * constants2.light_colors[1] = vmath.vector4(0, 1, 0, 1);
-     * constants2.light_colors[2] = vmath.vector4(0, 0, 1, 1);
-     *
-     * // You can also create the array by passing the vectors directly:
-     * const constants3 = render.constant_buffer();
-     * constants3.light_colors = [
-     *   vmath.vector4(1, 0, 0, 1),
-     *   vmath.vector4(0, 1, 0, 1),
-     *   vmath.vector4(0, 0, 1, 1),
-     * ];
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_pred: render.predicate([hash("my_tag")]) };
+     *   },
      *
-     * // Add more constants to the array
-     * constants3.light_colors[3] = vmath.vector4(1, 1, 1, 1);
+     *   update(self, dt) {
+     *     // Set a "tint" constant in a constant buffer in the render script:
+     *     const constants = render.constant_buffer();
+     *     constants.tint = vmath.vector4(1, 1, 1, 1);
+     *
+     *     // Then use the constant buffer when drawing a predicate:
+     *     render.draw(self.my_pred, { constants });
+     *
+     *     // The constant buffer also supports array values by specifying constants in an array:
+     *     const constants2 = render.constant_buffer();
+     *     constants2.light_colors = [];
+     *     constants2.light_colors[0] = vmath.vector4(1, 0, 0, 1);
+     *     constants2.light_colors[1] = vmath.vector4(0, 1, 0, 1);
+     *     constants2.light_colors[2] = vmath.vector4(0, 0, 1, 1);
+     *
+     *     // You can also create the array by passing the vectors directly:
+     *     const constants3 = render.constant_buffer();
+     *     constants3.light_colors = [
+     *       vmath.vector4(1, 0, 0, 1),
+     *       vmath.vector4(0, 1, 0, 1),
+     *       vmath.vector4(0, 0, 1, 1),
+     *     ];
+     *
+     *     // Add more constants to the array
+     *     constants3.light_colors[3] = vmath.vector4(1, 1, 1, 1);
+     *   },
+     * });
      * ```
      */
-    function constant_buffer(): Opaque<"constant_buffer">;
+    function constant_buffer(): Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | Matrix4[] };
     /**
      * Deletes a render target created by a render script.
      * You cannot delete a render target resource.
@@ -94,8 +103,16 @@ declare global {
      * @param render_target - render target to delete
      * @example
      * ```ts
-     * // How to delete a render target:
-     * render.delete_render_target(self.my_render_target);
+     * export default defineRenderScript({
+     *   init() {
+     *     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);
+     *   },
+     * });
      * ```
      */
     function delete_render_target(render_target: Opaque<"render_target">): void;
@@ -106,10 +123,18 @@ declare global {
      *
      * @example
      * ```ts
-     * // Enable material named "glow", then draw my_pred with it.
-     * render.enable_material("glow");
-     * render.draw(self.my_pred);
-     * render.disable_material();
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_pred: render.predicate([hash("my_tag")]) };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // Enable material named "glow", then draw my_pred with it.
+     *     render.enable_material("glow");
+     *     render.draw(self.my_pred);
+     *     render.disable_material();
+     *   },
+     * });
      * ```
      */
     function disable_material(): void;
@@ -131,19 +156,39 @@ declare global {
      * - `graphics.STATE_POLYGON_OFFSET_FILL`
      * @example
      * ```ts
-     * // Disable face culling when drawing the tile predicate:
-     * render.disable_state(graphics.STATE_CULL_FACE);
-     * render.draw(self.tile_pred);
+     * export default defineRenderScript({
+     *   init() {
+     *     return { tile_pred: render.predicate([hash("tile")]) };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // Disable face culling when drawing the tile predicate:
+     *     render.disable_state(graphics.STATE_CULL_FACE);
+     *     render.draw(self.tile_pred);
+     *   },
+     * });
      * ```
      */
-    function disable_state(state: number & { readonly __brand: "graphics.STATE_DEPTH_TEST" } | number & { readonly __brand: "graphics.STATE_STENCIL_TEST" } | number & { readonly __brand: "graphics.STATE_BLEND" } | number & { readonly __brand: "graphics.STATE_ALPHA_TEST" } | number & { readonly __brand: "graphics.STATE_CULL_FACE" } | number & { readonly __brand: "graphics.STATE_POLYGON_OFFSET_FILL" }): void;
+    function disable_state(state: graphics.State): void;
     /**
      * Disables a texture that has previourly been enabled.
      *
      * @param binding - texture binding, either by texture unit, string or hash that should be disabled
      * @example
      * ```ts
-     * export default defineScript({
+     * export default defineRenderScript({
+     *   init() {
+     *     const color_params = {
+     *       format: graphics.TEXTURE_FORMAT_RGBA,
+     *       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) {
      *     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
@@ -155,7 +200,7 @@ declare global {
      * });
      * ```
      */
-    function disable_texture(binding: Opaque<"texture"> | string | Hash): void;
+    function disable_texture(binding: Opaque<"texture"> | 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
@@ -172,7 +217,7 @@ declare global {
      * constant_buffer optional constants to use while rendering
      * @example
      * ```ts
-     * export default defineScript({
+     * export default defineRenderScript({
      *   init() {
      *     const color_params = {
      *       format: graphics.TEXTURE_FORMAT_RGBA,
@@ -180,6 +225,7 @@ declare global {
      *       height: render.get_window_height(),
      *     };
      *     return {
+     *       backing_texture: resource.get_texture_info("/main/backing.texturec").handle,
      *       scene_rt: render.render_target({ [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params }),
      *     };
      *   },
@@ -199,7 +245,7 @@ declare global {
      * render.dispatch_compute(32, 32, 32, { constants });
      * ```
      */
-    function dispatch_compute(x: number, y: number, z: number, options?: { constants?: Opaque<"constant_buffer"> }): void;
+    function dispatch_compute(x: number, y: number, z: number, options?: { constants?: Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | 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
@@ -224,33 +270,37 @@ declare global {
      * int How to sort draw order for world-ordered entries. Default uses the renderer's preferred world sorting (back-to-front).
      * @example
      * ```ts
-     * export default defineScript({
+     * export default defineRenderScript({
      *   init() {
-     *     // define a predicate matching anything with material tag "my_tag"
-     *     return { my_pred: render.predicate([hash("my_tag")]) };
+     *     return {
+     *       // define a predicate matching anything with material tag "my_tag"
+     *       my_pred: render.predicate([hash("my_tag")]),
+     *       proj: vmath.matrix4_perspective(math.rad(45), render.get_window_width() / render.get_window_height(), 0.1, 1000),
+     *       view: vmath.matrix4_look_at(vmath.vector3(0, 0, 10), vmath.vector3(0, 0, 0), vmath.vector3(0, 1, 0)),
+     *     };
      *   },
      *
      *   update(self, dt) {
      *     // draw everything in the my_pred predicate
      *     render.draw(self.my_pred);
-     *   },
-     * });
      *
-     * // Draw predicate with constants:
-     * const constants = render.constant_buffer();
-     * constants.tint = vmath.vector4(1, 1, 1, 1);
-     * render.draw(self.my_pred, { constants });
+     *     // Draw predicate with constants:
+     *     const constants = render.constant_buffer();
+     *     constants.tint = vmath.vector4(1, 1, 1, 1);
+     *     render.draw(self.my_pred, { constants });
      *
-     * // Draw with predicate and frustum culling (without near+far planes):
-     * const frustum = self.proj.mul(self.view);
-     * render.draw(self.my_pred, { frustum });
+     *     // Draw with predicate and frustum culling (without near+far planes):
+     *     const frustum = self.proj.mul(self.view);
+     *     render.draw(self.my_pred, { frustum });
      *
-     * // Draw with predicate and frustum culling (with near+far planes):
-     * const frustum2 = self.proj.mul(self.view);
-     * render.draw(self.my_pred, { frustum: frustum2, frustum_planes: render.FRUSTUM_PLANES_ALL });
+     *     // Draw with predicate and frustum culling (with near+far planes):
+     *     const frustum2 = self.proj.mul(self.view);
+     *     render.draw(self.my_pred, { frustum: frustum2, frustum_planes: render.FRUSTUM_PLANES_ALL });
+     *   },
+     * });
      * ```
      */
-    function draw(predicate: number, options?: { frustum?: Matrix4; frustum_planes?: number; constants?: Opaque<"constant_buffer">; sort_order?: number }): void;
+    function draw(predicate: number, options?: { frustum?: Matrix4; frustum_planes?: number; constants?: Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | Matrix4[] }; sort_order?: number }): void;
     /**
      * Draws all 3d debug graphics such as lines drawn with "draw_line" messages and physics visualization.
      *
@@ -266,7 +316,7 @@ declare global {
      * - render.FRUSTUM_PLANES_ALL : All sides of the frustum.
      * @example
      * ```ts
-     * export default defineScript({
+     * export default defineRenderScript({
      *   update(self, dt) {
      *     // draw debug visualization
      *     render.draw_debug3d();
@@ -284,10 +334,18 @@ declare global {
      * @param material_id - material id to enable
      * @example
      * ```ts
-     * // Enable material named "glow", then draw my_pred with it.
-     * render.enable_material("glow");
-     * render.draw(self.my_pred);
-     * render.disable_material();
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_pred: render.predicate([hash("my_tag")]) };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // Enable material named "glow", then draw my_pred with it.
+     *     render.enable_material("glow");
+     *     render.draw(self.my_pred);
+     *     render.disable_material();
+     *   },
+     * });
      * ```
      */
     function enable_material(material_id: string | Hash): void;
@@ -309,13 +367,21 @@ declare global {
      * - `graphics.STATE_POLYGON_OFFSET_FILL`
      * @example
      * ```ts
-     * // Enable stencil test when drawing the gui predicate, then disable it:
-     * render.enable_state(graphics.STATE_STENCIL_TEST);
-     * render.draw(self.gui_pred);
-     * render.disable_state(graphics.STATE_STENCIL_TEST);
+     * export default defineRenderScript({
+     *   init() {
+     *     return { gui_pred: render.predicate([hash("gui")]) };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // Enable stencil test when drawing the gui predicate, then disable it:
+     *     render.enable_state(graphics.STATE_STENCIL_TEST);
+     *     render.draw(self.gui_pred);
+     *     render.disable_state(graphics.STATE_STENCIL_TEST);
+     *   },
+     * });
      * ```
      */
-    function enable_state(state: number & { readonly __brand: "graphics.STATE_DEPTH_TEST" } | number & { readonly __brand: "graphics.STATE_STENCIL_TEST" } | number & { readonly __brand: "graphics.STATE_BLEND" } | number & { readonly __brand: "graphics.STATE_ALPHA_TEST" } | number & { readonly __brand: "graphics.STATE_CULL_FACE" } | number & { readonly __brand: "graphics.STATE_POLYGON_OFFSET_FILL" }): 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
@@ -353,7 +419,19 @@ declare global {
      * - `graphics.BUFFER_TYPE_COLOR3_BIT`
      * @example
      * ```ts
-     * export default defineScript({
+     * export default defineRenderScript({
+     *   init() {
+     *     const color_params = {
+     *       format: graphics.TEXTURE_FORMAT_RGBA,
+     *       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) {
      *     // enable target so all drawing is done to it
      *     render.set_render_target(self.my_render_target);
@@ -370,9 +448,15 @@ declare global {
      *     render.draw(self.my_pred);
      *   },
      * });
-     *
+     * ```
+     * @example
+     * ```ts
      * // Or enable a render target by resource id:
-     * export default defineScript({
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_pred: render.predicate([hash("my_tag")]) };
+     *   },
+     *
      *   update(self, dt) {
      *     render.set_render_target("my_rt_resource");
      *     render.draw(self.my_pred);
@@ -384,9 +468,15 @@ declare global {
      *     render.draw(self.my_pred);
      *   },
      * });
-     *
+     * ```
+     * @example
+     * ```ts
      * // Or bind a texture handle directly:
-     * export default defineScript({
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_texture_handle: resource.get_texture_info("/main/my_texture.texturec").handle };
+     *   },
+     *
      *   update(self, dt) {
      *     // bind a texture to the texture unit 0
      *     render.enable_texture(0, self.my_texture_handle);
@@ -396,7 +486,7 @@ declare global {
      * });
      * ```
      */
-    function enable_texture(binding: number | string | Hash, handle_or_name: Opaque<"texture"> | string | Hash, buffer_type?: number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR0_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR1_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR2_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR3_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_DEPTH_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_STENCIL_BIT" }): void;
+    function enable_texture(binding: number | string | Hash, handle_or_name: Opaque<"texture"> | string | Hash | Opaque<"render_target"> | number, buffer_type?: graphics.BufferType): void;
     /**
      * Returns the logical window height that is set in the "game.project" settings.
      * Note that the actual window pixel size can change, either by device constraints
@@ -424,13 +514,35 @@ declare global {
      * @returns the height of the render target buffer texture
      * @example
      * ```ts
-     * // 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
-     * const w = render.get_render_target_height("my_rt_resource", graphics.BUFFER_TYPE_COLOR0_BIT);
+     * export default defineRenderScript({
+     *   init() {
+     *     // render target buffer parameters
+     *     const color_params = {
+     *       format: graphics.TEXTURE_FORMAT_RGBA,
+     *       width: render.get_window_width(),
+     *       height: render.get_window_height(),
+     *       min_filter: graphics.TEXTURE_FILTER_LINEAR,
+     *       mag_filter: graphics.TEXTURE_FILTER_LINEAR,
+     *       u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
+     *       v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
+     *     };
+     *     return {
+     *       target_right: render.render_target("right", {
+     *         [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params,
+     *       }),
+     *     };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // 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
+     *     const w = render.get_render_target_height("my_rt_resource", graphics.BUFFER_TYPE_COLOR0_BIT);
+     *   },
+     * });
      * ```
      */
-    function get_render_target_height(render_target: Opaque<"render_target">, buffer_type: number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR0_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR1_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR2_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR3_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_DEPTH_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_STENCIL_BIT" }): number;
+    function get_render_target_height(render_target: Opaque<"render_target"> | string | Hash, buffer_type: graphics.BufferType): number;
     /**
      * Returns the specified buffer width from a render target.
      *
@@ -447,13 +559,35 @@ declare global {
      * @returns the width of the render target buffer texture
      * @example
      * ```ts
-     * // 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
-     * const w2 = render.get_render_target_width("my_rt_resource", graphics.BUFFER_TYPE_COLOR0_BIT);
+     * export default defineRenderScript({
+     *   init() {
+     *     // render target buffer parameters
+     *     const color_params = {
+     *       format: graphics.TEXTURE_FORMAT_RGBA,
+     *       width: render.get_window_width(),
+     *       height: render.get_window_height(),
+     *       min_filter: graphics.TEXTURE_FILTER_LINEAR,
+     *       mag_filter: graphics.TEXTURE_FILTER_LINEAR,
+     *       u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
+     *       v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
+     *     };
+     *     return {
+     *       target_right: render.render_target("right", {
+     *         [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params,
+     *       }),
+     *     };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // 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
+     *     const w2 = render.get_render_target_width("my_rt_resource", graphics.BUFFER_TYPE_COLOR0_BIT);
+     *   },
+     * });
      * ```
      */
-    function get_render_target_width(render_target: Opaque<"render_target">, buffer_type: number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR0_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR1_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR2_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR3_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_DEPTH_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_STENCIL_BIT" }): number;
+    function get_render_target_width(render_target: Opaque<"render_target"> | string | Hash, buffer_type: graphics.BufferType): number;
     /**
      * Returns the logical window width that is set in the "game.project" settings.
      * Note that the actual window pixel size can change, either by device constraints
@@ -613,20 +747,28 @@ declare global {
      * boolean If true, the renderer will use the cameras view-projection matrix for frustum culling (default: false)
      * @example
      * ```ts
-     * // Set the current camera to be used for rendering
-     * render.set_camera("main:/my_go#camera");
-     * render.draw(self.my_pred);
-     * render.set_camera(undefined);
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_pred: render.predicate([hash("my_tag")]) };
+     *   },
      *
-     * // Use the camera frustum for frustum culling together with a specific frustum plane option for the draw command
-     * // The camera frustum will take precedence over the frustum plane option in render.draw
-     * render.set_camera("main:/my_go#camera", { use_frustum: true });
-     * // However, we can still customize the frustum planes regardless of the camera option!
-     * render.draw(self.my_pred, { frustum_planes: render.FRUSTUM_PLANES_ALL });
-     * render.set_camera();
+     *   update(self, dt) {
+     *     // Set the current camera to be used for rendering
+     *     render.set_camera("main:/my_go#camera");
+     *     render.draw(self.my_pred);
+     *     render.set_camera(undefined);
+     *
+     *     // Use the camera frustum for frustum culling together with a specific frustum plane option for the draw command
+     *     // The camera frustum will take precedence over the frustum plane option in render.draw
+     *     render.set_camera("main:/my_go#camera", { use_frustum: true });
+     *     // However, we can still customize the frustum planes regardless of the camera option!
+     *     render.draw(self.my_pred, { frustum_planes: render.FRUSTUM_PLANES_ALL });
+     *     render.set_camera();
+     *   },
+     * });
      * ```
      */
-    function set_camera(camera?: Url | number, options?: { use_frustum?: boolean }): void;
+    function set_camera(camera?: Url | number | string, options?: { use_frustum?: boolean }): void;
     /**
      * Specifies whether the individual color components in the frame buffer is enabled for writing (`true`) or disabled (`false`). For example, if `blue` is `false`, nothing is written to the blue component of any pixel in any of the color buffers, regardless of the drawing operation attempted. Note that writing are either enabled or disabled for entire color components, not the individual bits of a component.
      * The component masks are all initially `true`.
@@ -650,11 +792,19 @@ declare global {
      * @param compute - compute id to use, or nil to disable
      * @example
      * ```ts
-     * // Enable compute program named "fractals", then dispatch it.
-     * render.set_compute("fractals");
-     * render.enable_texture(0, self.backing_texture);
-     * render.dispatch_compute(128, 128, 1);
-     * render.set_compute();
+     * export default defineRenderScript({
+     *   init() {
+     *     return { backing_texture: "my_texture_resource" };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // Enable compute program named "fractals", then dispatch it.
+     *     render.set_compute("fractals");
+     *     render.enable_texture(0, self.backing_texture);
+     *     render.dispatch_compute(128, 128, 1);
+     *     render.set_compute();
+     *   },
+     * });
      * ```
      */
     function set_compute(compute?: string | Hash): void;
@@ -744,7 +894,7 @@ declare global {
      * ```ts
      * // Set listener and handle render context events.
      * // custom.render_script
-     * export default defineScript({
+     * export default defineRenderScript({
      *   init() {
      *     render.set_listener((self, event_type) => {
      *       if (event_type === render.CONTEXT_EVENT_CONTEXT_LOST) {
@@ -768,7 +918,7 @@ declare global {
      * offset for each polygon. The initial value is `0`.
      * `units` is multiplied by an implementation-specific value to create a
      * constant depth offset. The initial value is `0`.
-     * The value of the offset is computed as `factor` &times; `DZ` + `r` &times; `units`
+     * The value of the offset is computed as `factor` × `DZ` + `r` × `units`
      * `DZ` is a measurement of the depth slope of the polygon which is the change in z (depth)
      * values divided by the change in either x or y coordinates, as you traverse a polygon.
      * The depth values are in window coordinates, clamped to the range [0, 1].
@@ -817,10 +967,24 @@ declare global {
      *
      * - `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 defineScript({
+     * export default defineRenderScript({
+     *   init() {
+     *     const color_params = {
+     *       format: graphics.TEXTURE_FORMAT_RGBA,
+     *       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) {
      *     // set render target so all drawing is done to it
      *     render.set_render_target(self.my_render_target, {
@@ -835,9 +999,15 @@ declare global {
      *     render.set_render_target(render.RENDER_TARGET_DEFAULT);
      *   },
      * });
-     *
+     * ```
+     * @example
+     * ```ts
      * // Or set the render target by a render target resource identifier:
-     * export default defineScript({
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_pred: render.predicate([hash("my_tag")]) };
+     *   },
+     *
      *   update(self, dt) {
      *     render.set_render_target("my_rt_resource");
      *
@@ -850,7 +1020,7 @@ declare global {
      * });
      * ```
      */
-    function set_render_target(render_target: Opaque<"render_target">, options?: { transient?: Record<string | number, unknown> }): void;
+    function set_render_target(render_target: Opaque<"render_target"> | string | Hash | typeof render.RENDER_TARGET_DEFAULT, 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.
@@ -860,12 +1030,20 @@ declare global {
      * @param height - new render target height
      * @example
      * ```ts
-     * // Resize render targets to the current window size:
-     * render.set_render_target_size(self.my_render_target, render.get_window_width(), render.get_window_height());
-     * render.set_render_target_size("my_rt_resource", render.get_window_width(), render.get_window_height());
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_render_target: render.render_target("my_target", {}) };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // Resize render targets to the current window size:
+     *     render.set_render_target_size(self.my_render_target, render.get_window_width(), render.get_window_height());
+     *     render.set_render_target_size("my_rt_resource", render.get_window_width(), render.get_window_height());
+     *   },
+     * });
      * ```
      */
-    function set_render_target_size(render_target: Opaque<"render_target">, width: number, height: number): void;
+    function set_render_target_size(render_target: Opaque<"render_target"> | string | Hash, width: number, height: number): void;
     /**
      * Stenciling is similar to depth-buffering as it enables and disables drawing on a
      * per-pixel basis. First, GL drawing primitives are drawn into the stencil planes.
@@ -976,7 +1154,7 @@ declare global {
      * ```ts
      * // How to set the view and projection matrices according to
      * // the values supplied by a camera.
-     * export default defineScript({
+     * export default defineRenderScript({
      *   init() {
      *     return {
      *       view: vmath.matrix4(),
@@ -991,7 +1169,11 @@ declare global {
      *   },
      *
      *   on_message(self, message_id, message) {
-     *     if (message_id === hash("set_view_projection")) {
+     *     if (
+     *       message_id === hash("set_view_projection") &&
+     *       types.is_matrix4(message.view) &&
+     *       types.is_matrix4(message.projection)
+     *     ) {
      *       // camera view and projection arrives here.
      *       self.view = message.view;
      *       self.projection = message.projection;