@defold-typescript/types 0.44.1 → 0.46.0

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

@@ -108,7 +108,16 @@ declare global {
      * vmath.vector4 | vmath.matrix4 the value(s) of the constant. If the constant is an array, the value will be a table of vmath.vector4 or vmath.matrix4 if the type is `material.CONSTANT_TYPE_USER_MATRIX4`.
      * @example
      * ```ts
-     * const constants = material.get_constants(resource.material("/my_material.materialc"));
+     * // Get the shader constants from a material specified as a resource property
+     * export default defineScript({
+     *   // Never call `go.property` yourself: the transpiler emits the chunk-scope
+     *   // registration from this field, and only this field types the property onto `self`.
+     *   properties: { my_material: resource.material() },
+     *
+     *   init(self) {
+     *     const constants = material.get_constants(self.my_material);
+     *   },
+     * });
      * ```
      */
     function get_constants(path: Hash | string): { name: Hash; type: number; value: Vector4 | Matrix4 }[];
@@ -159,7 +168,16 @@ declare global {
      * number the max anisotropy of the texture sampler
      * @example
      * ```ts
-     * const samplers = material.get_samplers(resource.material("/my_material.materialc"));
+     * // Get the texture samplers from a material specified as a resource property
+     * export default defineScript({
+     *   // Never call `go.property` yourself: the transpiler emits the chunk-scope
+     *   // registration from this field, and only this field types the property onto `self`.
+     *   properties: { my_material: resource.material() },
+     *
+     *   init(self) {
+     *     const samplers = material.get_samplers(self.my_material);
+     *   },
+     * });
      * ```
      */
     function get_samplers(path: Hash | string): { name: Hash; u_wrap: number; v_wrap: number; min_filter: number; mag_filter: number; max_anisotropy: number }[];
@@ -201,7 +219,16 @@ declare global {
      * - `graphics.TEXTURE_USAGE_FLAG_COLOR`
      * @example
      * ```ts
-     * const textures = material.get_textures(resource.material("/my_material.materialc"));
+     * // Get the textures from a material specified as a resource property
+     * export default defineScript({
+     *   // Never call `go.property` yourself: the transpiler emits the chunk-scope
+     *   // registration from this field, and only this field types the property onto `self`.
+     *   properties: { my_material: resource.material() },
+     *
+     *   init(self) {
+     *     const textures = material.get_textures(self.my_material);
+     *   },
+     * });
      * ```
      */
     function get_textures(path: Hash | string): { path: Hash; handle: Hash; width: number; height: number; depth: number; mipmaps: number; type: number; flags: number }[];
@@ -253,7 +280,16 @@ declare global {
      * - `graphics.SEMANTIC_TYPE_MORPH_TARGET_WEIGHTS`
      * @example
      * ```ts
-     * const vertex_attributes = material.get_vertex_attributes(resource.material("/my_material.materialc"));
+     * // Get the vertex attributes from a material specified as a resource property
+     * export default defineScript({
+     *   // Never call `go.property` yourself: the transpiler emits the chunk-scope
+     *   // registration from this field, and only this field types the property onto `self`.
+     *   properties: { my_material: resource.material() },
+     *
+     *   init(self) {
+     *     const vertex_attributes = material.get_vertex_attributes(self.my_material);
+     *   },
+     * });
      * ```
      */
     function get_vertex_attributes(path: Hash | string): { name: Hash; value: Vector4 | Vector3 | Matrix4 | number | number[]; normalize: boolean; data_type: number; coordinate_space: number; semantic_type: number }[];
@@ -288,7 +324,27 @@ declare global {
      * vmath.vector4 | vmath.vector3 | vmath.matrix4 | number | table the value(s) of the constant. If the shader constant is an array, the amount of values to update depends on how many values that are passed in the 'value' field.
      * @example
      * ```ts
-     * material.set_constants(resource.material("/my_material.materialc"), { tint: { value: vmath.vector4(1, 0, 0, 1) } });
+     * // Set a shader constant in a material specified as a resource property
+     * export default defineScript({
+     *   // Never call `go.property` yourself: the transpiler emits the chunk-scope
+     *   // registration from this field, and only this field types the property onto `self`.
+     *   properties: { my_material: resource.material() },
+     *
+     *   init() {
+     *     return { my_view_proj: vmath.matrix4() };
+     *   },
+     *
+     *   update(self) {
+     *     // update the 'tint' constant
+     *     material.set_constants(self.my_material, {
+     *       tint: { value: vmath.vector4(1, 0, 0, 1) },
+     *     });
+     *     // change the type of the 'view_proj' constant to CONSTANT_TYPE_USER_MATRIX4 so the renderer can set our custom data
+     *     material.set_constants(self.my_material, {
+     *       view_proj: { value: self.my_view_proj, type: material.CONSTANT_TYPE_USER_MATRIX4 },
+     *     });
+     *   },
+     * });
      * ```
      */
     function set_constants(path: Hash | string, constants: Record<string, { type?: number; value?: Vector4 | Vector3 | Matrix4 | number | (Vector4 | Matrix4)[] }>): void;
@@ -337,7 +393,18 @@ declare global {
      * number the max anisotropy of the texture sampler
      * @example
      * ```ts
-     * material.set_samplers(resource.material("/my_material.materialc"), { texture_sampler: { u_wrap: graphics.TEXTURE_WRAP_REPEAT, v_wrap: graphics.TEXTURE_WRAP_MIRRORED_REPEAT } });
+     * // Configures a sampler in a material specified as a resource property
+     * export default defineScript({
+     *   // Never call `go.property` yourself: the transpiler emits the chunk-scope
+     *   // registration from this field, and only this field types the property onto `self`.
+     *   properties: { my_material: resource.material() },
+     *
+     *   init(self) {
+     *     material.set_samplers(self.my_material, {
+     *       texture_sampler: { u_wrap: graphics.TEXTURE_WRAP_REPEAT, v_wrap: graphics.TEXTURE_WRAP_MIRRORED_REPEAT },
+     *     });
+     *   },
+     * });
      * ```
      */
     function set_samplers(path: Hash | string, samplers: Record<string, { u_wrap?: number; v_wrap?: number; min_filter?: number; mag_filter?: number; max_anisotropy?: number }>): void;
@@ -348,7 +415,18 @@ declare global {
      * @param textures - A table keyed by sampler name with texture resources as values.
      * @example
      * ```ts
-     * material.set_textures(resource.material("/my_material.materialc"), { my_texture: resource.texture() });
+     * // Set a texture in a material from a resource
+     * export default defineScript({
+     *   // Never call `go.property` yourself: the transpiler emits the chunk-scope
+     *   // registrations from this field, and only this field types them onto `self`.
+     *   properties: { my_material: resource.material(), my_texture: resource.texture() },
+     *
+     *   init(self) {
+     *     material.set_textures(self.my_material, {
+     *       my_texture: self.my_texture,
+     *     });
+     *   },
+     * });
      * ```
      */
     function set_textures(path: Hash | string, textures: LuaMap<string, Hash> | Record<string, Hash>): void;
@@ -398,7 +476,19 @@ declare global {
      * - `graphics.SEMANTIC_TYPE_MORPH_TARGET_WEIGHTS`
      * @example
      * ```ts
-     * material.set_vertex_attributes(resource.material("/my_material.materialc"), { tint_attribute: { value: vmath.vector4(1, 0, 0, 1), semantic_type: graphics.SEMANTIC_TYPE_COLOR } });
+     * // Configures a vertex attribute in a material specified as a resource property
+     * export default defineScript({
+     *   // Never call `go.property` yourself: the transpiler emits the chunk-scope
+     *   // registration from this field, and only this field types the property onto `self`.
+     *   properties: { my_material: resource.material() },
+     *
+     *   init(self) {
+     *     material.set_vertex_attributes(self.my_material, {
+     *       tint_attribute: { value: vmath.vector4(1, 0, 0, 1), semantic_type: graphics.SEMANTIC_TYPE_COLOR },
+     *       weights: { value: vmath.vector4(0, 1, 0, 0), semantic_type: graphics.SEMANTIC_TYPE_NONE },
+     *     });
+     *   },
+     * });
      * ```
      */
     function set_vertex_attributes(path: Hash | string, attributes: Record<string, { value?: Vector4 | Vector3 | Matrix4 | number | number[]; normalize?: boolean; data_type?: number; coordinate_space?: number; semantic_type?: number }>): void;

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

@@ -33,10 +33,14 @@ declare global {
      * @returns array of weight values, or empty table if the model has no morph targets
      * @example
      * ```ts
-     * const weights = model.get_blend_weights("#model");
-     * weights[1] = 0.75;
-     * weights[2] = 0.25;
-     * model.set_blend_weights("#model", weights);
+     * const w = model.get_blend_weights("#model");
+     * w.forEach((weight, i) => {
+     *   print(i + 1, weight);
+     * });
+     * // change the data in the table and then set the weights again
+     * w[0] = 0.75;
+     * w[1] = 0.25;
+     * model.set_blend_weights("#model", w);
      * ```
      */
     function get_blend_weights(url: string | Hash | Url): number[];
@@ -197,8 +201,10 @@ declare global {
      * @param weights - array of weight values (1-based indices). Omit or pass `nil` to clear the override and return morphs to animation only
      * @example
      * ```ts
+     * // set the weights for the first 4 morph targets
      * model.set_blend_weights("#model", [0, 1, 0.5, 0]);
-     * model.set_blend_weights("#model");
+     * // clear the override, animation will continue if the weights are driven by an animation
+     * model.set_blend_weights("#model"); // clear script override
      * ```
      */
     function set_blend_weights(url: string | Hash | Url, weights?: number[]): void;

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

@@ -50,15 +50,13 @@ declare global {
      * // How to play a particle fx when a game object is created.
      * // The callback receives the hash of the path to the particlefx, the hash of the id
      * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.
-     * function emitter_state_change(self: unknown, id: unknown, emitter: unknown, state: unknown) {
-     *   if (emitter === hash("exhaust") && state === particlefx.EMITTER_STATE_POSTSPAWN) {
-     *     // exhaust is done spawning particles...
-     *   }
-     * }
-     *
      * export default defineScript({
      *   init(self) {
-     *     particlefx.play("#particlefx", emitter_state_change);
+     *     particlefx.play("#particlefx", (self, id, emitter, state) => {
+     *       if (emitter === hash("exhaust") && state === particlefx.EMITTER_STATE_POSTSPAWN) {
+     *         // exhaust is done spawning particles...
+     *       }
+     *     });
      *   },
      * });
      * ```

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

@@ -70,11 +70,16 @@ declare global {
      * @example
      * Then use the constant buffer when drawing a predicate:
      * ```ts
-     * function draw_tinted(self: { my_pred: Opaque<"render_predicate"> }) {
-     *   const constants = render.constant_buffer();
-     *   constants.tint = vmath.vector4(1, 1, 1, 1);
-     *   render.draw(self.my_pred, { constants });
-     * }
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_pred: render.predicate([hash("my_tag")]) };
+     *   },
+     *
+     *   update(self, dt) {
+     *     const constants = render.constant_buffer();
+     *     render.draw(self.my_pred, { constants });
+     *   },
+     * });
      * ```
      * @example
      * The constant buffer also supports array values by specifying constants in a table:
@@ -449,13 +454,13 @@ declare global {
      * ```
      * @example
      * ```ts
-     * // Or enable a render target by resource id:
      * export default defineRenderScript({
      *   init() {
      *     return { my_pred: render.predicate([hash("my_tag")]) };
      *   },
      *
      *   update(self, dt) {
+     *     // enable render target by resource id
      *     render.set_render_target("my_rt_resource");
      *     render.draw(self.my_pred);
      *     render.set_render_target(render.RENDER_TARGET_DEFAULT);
@@ -469,7 +474,6 @@ declare global {
      * ```
      * @example
      * ```ts
-     * // Or bind a texture handle directly:
      * export default defineRenderScript({
      *   init() {
      *     return { my_texture_handle: resource.get_texture_info("/main/my_texture.texturec").handle };
@@ -512,15 +516,10 @@ declare global {
      * ```ts
      * 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", {
@@ -554,15 +553,10 @@ declare global {
      * ```ts
      * 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", {
@@ -1003,13 +997,13 @@ declare global {
      * ```
      * @example
      * ```ts
-     * // Or set the render target by a render target resource identifier:
      * 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

package/generated/versions/defold-1.13.1/sys.d.ts

@@ -605,22 +605,20 @@ declare global {
      * string The stack traceback.
      * @example
      * ```ts
-     * // Install error handler that just prints the errors
-     * function my_error_handler(source: unknown, message: unknown, traceback: unknown) {
-     *   print(source); //> lua
-     *   print(message); //> main/my.script:10: attempt to perform arithmetic on a string value
-     *   print(traceback); //> stack traceback:
-     *   //>         main/test.script:10: in function 'boom'
-     *   //>         main/test.script:15: in function <main/my.script:13>
-     * }
-     *
      * function boom() {
      *   return 10 + "string";
      * }
      *
      * export default defineScript({
      *   init() {
-     *     sys.set_error_handler(my_error_handler);
+     *     // Install error handler that just prints the errors
+     *     sys.set_error_handler((source, message, traceback) => {
+     *       print(source); //> lua
+     *       print(message); //> main/my.script:10: attempt to perform arithmetic on a string value
+     *       print(traceback); //> stack traceback:
+     *       //>         main/test.script:10: in function 'boom'
+     *       //>         main/test.script:15: in function <main/my.script:13>
+     *     });
      *     boom();
      *   },
      * });

package/generated/versions/defold-1.13.1/window.d.ts

@@ -127,23 +127,21 @@ declare global {
      * - number `height`: The height of a resize event. nil otherwise.
      * @example
      * ```ts
-     * function window_callback(self: unknown, event: unknown, data: Record<string | number, unknown>) {
-     *   if (event === window.WINDOW_EVENT_FOCUS_LOST) {
-     *     print("window.WINDOW_EVENT_FOCUS_LOST");
-     *   } else if (event === window.WINDOW_EVENT_FOCUS_GAINED) {
-     *     print("window.WINDOW_EVENT_FOCUS_GAINED");
-     *   } else if (event === window.WINDOW_EVENT_ICONFIED) {
-     *     print("window.WINDOW_EVENT_ICONFIED");
-     *   } else if (event === window.WINDOW_EVENT_DEICONIFIED) {
-     *     print("window.WINDOW_EVENT_DEICONIFIED");
-     *   } else if (event === window.WINDOW_EVENT_RESIZED) {
-     *     print("Window resized: ", data.width, data.height);
-     *   }
-     * }
-     *
      * export default defineScript({
      *   init() {
-     *     window.set_listener(window_callback);
+     *     window.set_listener((self, event, data) => {
+     *       if (event === window.WINDOW_EVENT_FOCUS_LOST) {
+     *         print("window.WINDOW_EVENT_FOCUS_LOST");
+     *       } else if (event === window.WINDOW_EVENT_FOCUS_GAINED) {
+     *         print("window.WINDOW_EVENT_FOCUS_GAINED");
+     *       } else if (event === window.WINDOW_EVENT_ICONFIED) {
+     *         print("window.WINDOW_EVENT_ICONFIED");
+     *       } else if (event === window.WINDOW_EVENT_DEICONIFIED) {
+     *         print("window.WINDOW_EVENT_DEICONIFIED");
+     *       } else if (event === window.WINDOW_EVENT_RESIZED) {
+     *         print("Window resized: ", data.width, data.height);
+     *       }
+     *     });
      *   },
      * });
      * ```

package/generated/window.d.ts

@@ -142,23 +142,21 @@ declare global {
      * @param callback - A callback which receives info about window events. Pass an empty function or `nil` if you no longer wish to receive callbacks.
      * @example
      * ```ts
-     * function window_callback(self: unknown, event: unknown, data: Record<string | number, unknown>) {
-     *   if (event === window.WINDOW_EVENT_FOCUS_LOST) {
-     *     print("window.WINDOW_EVENT_FOCUS_LOST");
-     *   } else if (event === window.WINDOW_EVENT_FOCUS_GAINED) {
-     *     print("window.WINDOW_EVENT_FOCUS_GAINED");
-     *   } else if (event === window.WINDOW_EVENT_ICONIFIED) {
-     *     print("window.WINDOW_EVENT_ICONIFIED");
-     *   } else if (event === window.WINDOW_EVENT_DEICONIFIED) {
-     *     print("window.WINDOW_EVENT_DEICONIFIED");
-     *   } else if (event === window.WINDOW_EVENT_RESIZED) {
-     *     print("Window resized: ", data.width, data.height);
-     *   }
-     * }
-     *
      * export default defineScript({
      *   init() {
-     *     window.set_listener(window_callback);
+     *     window.set_listener((self, event, data) => {
+     *       if (event === window.WINDOW_EVENT_FOCUS_LOST) {
+     *         print("window.WINDOW_EVENT_FOCUS_LOST");
+     *       } else if (event === window.WINDOW_EVENT_FOCUS_GAINED) {
+     *         print("window.WINDOW_EVENT_FOCUS_GAINED");
+     *       } else if (event === window.WINDOW_EVENT_ICONIFIED) {
+     *         print("window.WINDOW_EVENT_ICONIFIED");
+     *       } else if (event === window.WINDOW_EVENT_DEICONIFIED) {
+     *         print("window.WINDOW_EVENT_DEICONIFIED");
+     *       } else if (event === window.WINDOW_EVENT_RESIZED) {
+     *         print("Window resized: ", data.width, data.height);
+     *       }
+     *     });
      *   },
      * });
      * ```

package/hsm/async.d.ts

@@ -1,8 +1,26 @@
 // Generated from packages/hsm/src/async.ts by `bun run --cwd packages/hsm declarations`; do not edit.
 import type { EventObject, TaskStart } from "./index";
-/** @noSelf */
+/**
+ * The second argument of a `sequence` function: a wait that leaving the state cancels, and a flag
+ * that tells the state was left.
+ * @noSelf
+ */
 export interface SequenceSignal {
+    /**
+     * Turns `true` once the state is left. Check it after awaiting anything other than `wait`: such
+     * a promise can still resolve after the state is left, and the code after it then runs.
+     */
     readonly aborted: boolean;
+    /**
+     * Resolves after `seconds`, counted by `timer.delay` rather than by `update(dt)`. A wait still
+     * pending when the state is left never resolves, so the code after it does not run.
+     */
     readonly wait: (seconds: number) => Promise<void>;
 }
+/**
+ * Turns an `async` function into a state's `task`. The function gets the context and a
+ * `SequenceSignal`, and the event it returns is sent to the machine; one returned after the state
+ * is left is ignored. An error thrown inside it leaves the machine where it is and is raised
+ * again from a timer callback, so it shows in the engine console.
+ */
 export declare function sequence<Ctx, E extends EventObject>(run: (ctx: Ctx, signal: SequenceSignal) => Promise<NoInfer<E> | void>): TaskStart<Ctx, E>;

package/hsm/debug.d.ts

@@ -1,7 +1,21 @@
 // Generated from packages/hsm/src/debug.ts by `bun run --cwd packages/hsm declarations`; do not edit.
 import type { EventObject, MachineInstance } from "./index";
-/** @noSelf */
+/**
+ * Returned by `inspect`. Keep it on `self` and call its `draw` from `update`.
+ * @noSelf
+ */
 export interface MachineInspector {
+    /**
+     * Draws the label and the active leaves as debug text, 40 units above `target`'s world
+     * position. Each call also advances the frame number the console lines show. In a release
+     * build it does nothing.
+     */
     readonly draw: (target: Hash | Url | string) => void;
 }
+/**
+ * Prints one line when it is called, then one line for each move `instance` makes, each starting
+ * with `hsm` and the label. Call it once after `start`. A label another `inspect` call already
+ * used gets an ordinal, such as `enemy#2`. In a release build it registers nothing and returns an
+ * inspector whose `draw` does nothing, so the calls can stay in shipped code.
+ */
 export declare function inspect<Ctx, E extends EventObject, P extends string>(instance: MachineInstance<Ctx, E, P>, label: string): MachineInspector;

package/hsm/defold.d.ts

@@ -1,10 +1,30 @@
 // Generated from packages/hsm/src/defold.ts by `bun run --cwd packages/hsm declarations`; do not edit.
+/**
+ * The event `messageEvents` builds from the Defold message `K`, for a machine's event union. It
+ * holds the message id as `type`, the payload fields declared through `BuiltinMessages` and
+ * `CustomMessages`, and the `sender`.
+ */
 export type MessageEvent<K extends MessageId> = K extends MessageId ? {
+    /** The message id. A payload field named `type` never overrides it. */
     readonly type: K;
+    /** The URL the message came from. A payload field named `sender` never overrides it. */
     readonly sender: Url;
 } & Omit<MessagePayload<K>, "type" | "sender"> : never;
-/** @noSelf */
+/**
+ * Returned by `messageEvents`. Build it once at module scope: it hashes the ids when it is
+ * created.
+ * @noSelf
+ */
 export interface MessageEventMapper<K extends MessageId> {
+    /**
+     * Turns the parameters of `on_message` into the event for that message, a new table on each
+     * call. Returns `undefined` for a message id that `messageEvents` was not given.
+     */
     readonly toEvent: (message_id: Hash, message: Record<string | number, unknown>, sender: Url) => MessageEvent<K> | undefined;
 }
+/**
+ * Builds a mapper that turns the Defold messages listed in `ids` into typed machine events of
+ * the shape `{ type: id, ...payload, sender }`. Call it once at module scope: the ids are hashed
+ * here.
+ */
 export declare function messageEvents<const K extends MessageId>(ids: readonly K[]): MessageEventMapper<K>;