@defold-typescript/types 0.51.0 → 0.52.0

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

@@ -1,5 +1,5 @@
 /** @noSelfInFile */
-import type { Hash, Matrix4, Opaque, Quaternion, Url, Vector, Vector3, Vector4 } from "../../../src/core-types";
+import type { Hash, Matrix4, Quaternion, Url, Vector, Vector3, Vector4 } from "../../../src/core-types";
 
 declare global {
   /**
@@ -259,7 +259,65 @@ declare global {
      * go.animate("go", "position.y", go.PLAYBACK_LOOP_PINGPONG, 100, vec, 2.0);
      * ```
      */
-    export function animate(url: SceneAddress | Hash | Url, property: string | Hash, playback: go.Playback, to: number | Vector3 | Vector4 | Quaternion, easing: Vector | go.Easing, duration: number, delay?: number, complete_function?: (self: unknown, url: unknown, property: unknown) => void): void;
+    export function animate(url: SceneAddress | Hash | Url, property: string | Hash, playback: go.Playback, to: number | Vector3 | Vector4 | Quaternion, easing: Vector | go.Easing, duration: number): void;
+    /**
+     * This is only supported for numerical properties. If the node property is already being
+     * animated, that animation will be canceled and replaced by the new one.
+     * If a `complete_function` (lua function) is specified, that function will be called when the animation has completed.
+     * By starting a new animation in that function, several animations can be sequenced together. See the examples for more information.
+     * If you call `go.animate()` from a game object's `final()` function,
+     * any passed `complete_function` will be ignored and never called upon animation completion.
+     * See the properties guide for which properties can be animated and the animation guide for how
+     * them.
+     *
+     * @param url - url of the game object or component having the property
+     * @param property - id of the property to animate
+     * @param playback - playback mode of the animation
+     *
+     * - `go.PLAYBACK_ONCE_FORWARD`
+     * - `go.PLAYBACK_ONCE_BACKWARD`
+     * - `go.PLAYBACK_ONCE_PINGPONG`
+     * - `go.PLAYBACK_LOOP_FORWARD`
+     * - `go.PLAYBACK_LOOP_BACKWARD`
+     * - `go.PLAYBACK_LOOP_PINGPONG`
+     * @param to - target property value
+     * @param easing - easing to use during animation. Either specify a constant, see the animation guide for a complete list, or a vmath.vector with a curve
+     * @param duration - duration of the animation in seconds
+     * @param delay - delay before the animation starts in seconds
+     * @param complete_function - optional function to call when the animation has completed
+     *
+     * `self`
+     *
+     * object The current object.
+     *
+     * `url`
+     *
+     * url The game object or component instance for which the property is animated.
+     *
+     * `property`
+     *
+     * hash The id of the animated property.
+     * @example
+     * Animate the position of a game object to x = 10 during 1 second, then y = 20 during 1 second:
+     * ```ts
+     * go.animate(go.get_id(), "position.x", go.PLAYBACK_ONCE_FORWARD, 10, go.EASING_LINEAR, 1, 0, () => {
+     *   go.animate(go.get_id(), "position.y", go.PLAYBACK_ONCE_FORWARD, 20, go.EASING_LINEAR, 1);
+     * });
+     * ```
+     * @example
+     * Animate the y position of a game object using a crazy custom easing curve:
+     * ```ts
+     * const values = [
+     *   0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1,
+     *   0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1,
+     *   0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1,
+     *   0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1,
+     * ];
+     * const vec = vmath.vector(values);
+     * go.animate("go", "position.y", go.PLAYBACK_LOOP_PINGPONG, 100, vec, 2.0);
+     * ```
+     */
+    export function animate(url: SceneAddress | Hash | Url, property: string | Hash, playback: go.Playback, to: number | Vector3 | Vector4 | Quaternion, easing: Vector | go.Easing, duration: number, delay: number, complete_function?: (self: unknown, url: unknown, property: unknown) => void): void;
     /**
      * By calling this function, all or specified stored property animations of the game object or component will be canceled.
      * See the properties guide for which properties can be animated and the animation guide for how to animate them.
@@ -318,7 +376,43 @@ declare global {
      * go.delete(ids, true);
      * ```
      */
-    function _delete(id?: SceneGameObjectAddress | Hash | Url | (SceneGameObjectAddress | Hash | Url)[] | boolean, recursive?: boolean): void;
+    function _delete(id?: SceneGameObjectAddress | Hash | Url | (SceneGameObjectAddress | Hash | Url)[] | LuaPairsIterable<AnyNotNil, SceneGameObjectAddress | Hash | Url> | boolean): void;
+    /**
+     * Delete one or more game objects identified by id. Deletion is asynchronous meaning that
+     * the game object(s) are scheduled for deletion which will happen at the end of the current
+     * frame. Note that game objects scheduled for deletion will be counted against
+     * `max_instances` in "game.project" until they are actually removed.
+     * Deleting a game object containing a particle FX component emitting particles will not immediately stop the particle FX from emitting particles. You need to manually stop the particle FX using `particlefx.stop()`.
+     * Deleting a game object containing a sound component that is playing will not immediately stop the sound from playing. You need to manually stop the sound using `sound.stop()`.
+     *
+     * @param id - optional id or table of id's of the instance(s) to delete, the instance of the calling script is deleted by default
+     * @param recursive - optional boolean, set to true to recursively delete child hiearchy in child to parent order
+     * @example
+     * This example demonstrates how to delete game objects
+     * ```ts
+     * // Delete the script's own game object.
+     * go.delete();
+     * // Delete a game object with the id "my_game_object".
+     * const id = go.get_id("my_game_object"); // retrieve the id of the game object to be deleted
+     * go.delete(id);
+     * // Delete a list of game objects.
+     * const ids = [hash("/my_object_1"), hash("/my_object_2"), hash("/my_object_3")];
+     * go.delete(ids);
+     * ```
+     * @example
+     * This example demonstrates how to delete a game objects and their children (child to parent order)
+     * ```ts
+     * // Delete the script's own game object and its children.
+     * go.delete(true);
+     * // Delete a game object with the id "my_game_object" and its children.
+     * const id = go.get_id("my_game_object"); // retrieve the id of the game object to be deleted
+     * go.delete(id, true);
+     * // Delete a list of game objects and their children.
+     * const ids = [hash("/my_object_1"), hash("/my_object_2"), hash("/my_object_3")];
+     * go.delete(ids, true);
+     * ```
+     */
+    function _delete(id: SceneGameObjectAddress | Hash | Url | (SceneGameObjectAddress | Hash | Url)[] | LuaPairsIterable<AnyNotNil, SceneGameObjectAddress | Hash | Url>, recursive: boolean): void;
     /**
      * This function can check for game objects in any collection by specifying
      * the collection name in the URL.
@@ -338,36 +432,29 @@ declare global {
      */
     export function exists(url: SceneGameObjectAddress | Hash | Url): boolean;
     /**
-     * This is a callback-function, which is called by the engine when a script component is finalized (destroyed). It can
-     * be used to e.g. take some last action, report the finalization to other game object instances, delete spawned objects
-     * or release user input focus (see release_input_focus).
+     * Returns or constructs an instance identifier. The instance id is a hash
+     * of the absolute path to the instance.
      *
-     * @param self - reference to the script state to be used for storing data
+     * - If `path` is specified, it can either be absolute or relative to the instance of the calling script.
+     * - If `path` is not specified, the id of the game object instance the script is attached to will be returned.
+     *
+     * @param path - path of the instance for which to return the id
+     * @returns instance id
      * @example
      * ```ts
-     * export default defineScript({
-     *   init() {
-     *     return { some_value: 0 };
-     *   },
+     * // For the instance with path /my_sub_collection/my_instance, the following calls
+     * // are equivalent:
+     * const id = go.get_id(); // no path, defaults to the instance containing the calling script
+     * print(id); // => hash: [/my_sub_collection/my_instance]
      *
-     *   final(self) {
-     *     // report finalization
-     *     msg.post("my_friend_instance", "im_dead", { my_stats: self.some_value });
-     *   },
-     * });
-     * ```
-     */
-    export function final(self: Opaque<"userdata">): void;
-    /**
-     * This is a callback-function, which is called by the engine at fixed intervals to update the state of a script
-     * component. The function will be called if 'Fixed Update Frequency' is enabled in the Engine section of game.project.
-     * It can for instance be used to update game logic with the physics simulation if using a fixed timestep for the
-     * physics (enabled by ticking 'Use Fixed Timestep' in the Physics section of game.project).
+     * const id2 = go.get_id("/my_sub_collection/my_instance"); // absolute path
+     * print(id2); // => hash: [/my_sub_collection/my_instance]
      *
-     * @param self - reference to the script state to be used for storing data
-     * @param dt - the time-step of the frame update
+     * const id3 = go.get_id("my_instance"); // relative path
+     * print(id3); // => hash: [/my_sub_collection/my_instance]
+     * ```
      */
-    export function fixed_update(self: Opaque<"userdata">, dt: number): void;
+    export function get_id(): Hash;
     /**
      * Returns or constructs an instance identifier. The instance id is a hash
      * of the absolute path to the instance.
@@ -391,7 +478,7 @@ declare global {
      * print(id3); // => hash: [/my_sub_collection/my_instance]
      * ```
      */
-    export function get_id(path?: string): Hash;
+    export function get_id(path: string): Hash;
     /**
      * Get the parent for a game object instance.
      *
@@ -574,298 +661,6 @@ declare global {
      * ```
      */
     export function get_world_transform(id?: SceneGameObjectAddress | Hash | Url): Matrix4;
-    /**
-     * This is a callback-function, which is called by the engine when a script component is initialized. It can be used
-     * to set the initial state of the script.
-     *
-     * @param self - reference to the script state to be used for storing data
-     * @example
-     * ```ts
-     * export default defineScript({
-     *   init() {
-     *     // set up useful data
-     *     return { my_value: 1 };
-     *   },
-     * });
-     * ```
-     */
-    export function init(self: Opaque<"userdata">): void;
-    /**
-     * This is a callback-function, which is called by the engine at the end of the frame to update the state of a script
-     * component. Use it to make final adjustments to the game object instance.
-     *
-     * @param self - reference to the script state to be used for storing data
-     * @param dt - the time-step of the frame update
-     */
-    export function late_update(self: Opaque<"userdata">, dt: number): void;
-    /**
-     * This is a callback-function, which is called by the engine when user input is sent to the game object instance of the script.
-     * It can be used to take action on the input, e.g. move the instance according to the input.
-     * For an instance to obtain user input, it must first acquire input focus
-     * through the message `acquire_input_focus`.
-     * Any instance that has obtained input will be put on top of an
-     * input stack. Input is sent to all listeners on the stack until the
-     * end of stack is reached, or a listener returns `true`
-     * to signal that it wants input to be consumed.
-     * See the documentation of acquire_input_focus for more
-     * information.
-     * The `action` parameter is a table containing data about the input mapped to the
-     * `action_id`.
-     * For mapped actions it specifies the value of the input and if it was just pressed or released.
-     * Actions are mapped to input in an input_binding-file.
-     * Mouse movement is specifically handled and uses `nil` as its `action_id`.
-     * The `action` only contains positional parameters in this case, such as x and y of the pointer.
-     * Here is a brief description of the available table fields:
-     *
-     * Field
-     * Description
-     *
-     * `value`
-     * The amount of input given by the user. This is usually 1 for buttons and 0-1 for analogue inputs. This is not present for mouse movement and text input.
-     *
-     * `pressed`
-     * If the input was pressed this frame. This is not present for mouse movement and text input.
-     *
-     * `released`
-     * If the input was released this frame. This is not present for mouse movement and text input.
-     *
-     * `repeated`
-     * If the input was repeated this frame. This is similar to how a key on a keyboard is repeated when you hold it down. This is not present for mouse movement and text input.
-     *
-     * `x`
-     * The x value of a pointer device, if present. This is not present for gamepad, key and text input.
-     *
-     * `y`
-     * The y value of a pointer device, if present. This is not present for gamepad, key and text input.
-     *
-     * `screen_x`
-     * The screen space x value of a pointer device, if present. This is not present for gamepad, key and text input.
-     *
-     * `screen_y`
-     * The screen space y value of a pointer device, if present. This is not present for gamepad, key and text input.
-     *
-     * `dx`
-     * The change in x value of a pointer device, if present. This is not present for gamepad, key and text input.
-     *
-     * `dy`
-     * The change in y value of a pointer device, if present. This is not present for gamepad, key and text input.
-     *
-     * `screen_dx`
-     * The change in screen space x value of a pointer device, if present. This is not present for gamepad, key and text input.
-     *
-     * `screen_dy`
-     * The change in screen space y value of a pointer device, if present. This is not present for gamepad, key and text input.
-     *
-     * `gamepad`
-     * The index of the gamepad device that provided the input. See table below about gamepad input.
-     *
-     * `touch`
-     * List of touch input, one element per finger, if present. See table below about touch input
-     *
-     * `text`
-     * Text input from a (virtual) keyboard or similar.
-     *
-     * `marked_text`
-     * Sequence of entered symbols while entering a symbol combination, for example Japanese Kana.
-     *
-     * Gamepad specific fields:
-     *
-     * Field
-     * Description
-     *
-     * `gamepad`
-     * The index of the gamepad device that provided the input.
-     *
-     * `userid`
-     * Id of the user associated with the controller. Usually only relevant on consoles.
-     *
-     * `gamepad_unknown`
-     * True if the inout originated from an unknown/unmapped gamepad.
-     *
-     * `gamepad_name`
-     * Name of the gamepad
-     *
-     * `gamepad_axis`
-     * List of gamepad axis values. For raw gamepad input only.
-     *
-     * `gamepadhats`
-     * List of gamepad hat values. For raw gamepad input only.
-     *
-     * `gamepad_buttons`
-     * List of gamepad button values. For raw gamepad input only.
-     *
-     * Touch input table:
-     *
-     * Field
-     * Description
-     *
-     * `id`
-     * A number identifying the touch input during its duration.
-     *
-     * `pressed`
-     * True if the finger was pressed this frame.
-     *
-     * `released`
-     * True if the finger was released this frame.
-     *
-     * `tap_count`
-     * Number of taps, one for single, two for double-tap, etc
-     *
-     * `x`
-     * The x touch location.
-     *
-     * `y`
-     * The y touch location.
-     *
-     * `dx`
-     * The change in x value.
-     *
-     * `dy`
-     * The change in y value.
-     *
-     * `acc_x`
-     * Accelerometer x value (if present).
-     *
-     * `acc_y`
-     * Accelerometer y value (if present).
-     *
-     * `acc_z`
-     * Accelerometer z value (if present).
-     *
-     * @param self - reference to the script state to be used for storing data
-     * @param action_id - id of the received input action, as mapped in the input_binding-file
-     * @param action - a table containing the input data, see above for a description. **0️⃣ `gamepad` is 0-based; passed to Defold unchanged.**
-     * @returns optional boolean to signal if the input should be consumed (not passed on to others) or not, default is false
-     * @example
-     * ```ts
-     * // This example demonstrates how a game object instance can be moved as a response to user input.
-     * export default defineScript({
-     *   init() {
-     *     // acquire input focus
-     *     msg.post(".", "acquire_input_focus");
-     *     return {
-     *       // maximum speed the instance can be moved
-     *       max_speed: 2,
-     *       // velocity of the instance, initially zero
-     *       velocity: vmath.vector3(),
-     *     };
-     *   },
-     *
-     *   update(self, dt) {
-     *     // move the instance
-     *     go.set_position(go.get_position().add(self.velocity.mul(dt)));
-     *   },
-     *
-     *   on_input(self, action_id, action) {
-     *     // check for movement input
-     *     if (action_id === hash("right")) {
-     *       if (action.released) {
-     *         // reset velocity if input was released
-     *         self.velocity = vmath.vector3();
-     *       } else {
-     *         // update velocity
-     *         self.velocity = vmath.vector3((action.value ?? 0) * self.max_speed, 0, 0);
-     *       }
-     *     }
-     *   },
-     * });
-     * ```
-     */
-    export function on_input(self: Opaque<"userdata">, action_id: Hash, action: { value?: number; pressed?: boolean; released?: boolean; repeated?: boolean; x?: number; y?: number; screen_x?: number; screen_y?: number; dx?: number; dy?: number; screen_dx?: number; screen_dy?: number; gamepad?: number; gamepad_axis?: Vector3; touch?: { id?: number; pressed?: boolean; released?: boolean; tap_count?: number; x?: number; y?: number; dx?: number; dy?: number; acc_x?: number; acc_y?: number; acc_z?: number }[]; text?: string }): boolean | undefined;
-    /**
-     * This is a callback-function, which is called by the engine whenever a message has been sent to the script component.
-     * It can be used to take action on the message, e.g. send a response back to the sender of the message.
-     * The `message` parameter is a table containing the message data. If the message is sent from the engine, the
-     * documentation of the message specifies which data is supplied.
-     *
-     * @param self - reference to the script state to be used for storing data
-     * @param message_id - id of the received message
-     * @param message - a table containing the message data
-     * @param sender - address of the sender
-     * @example
-     * This example demonstrates how a game object instance, called "a", can communicate with another instance, called "b". It
-     * is assumed that both script components of the instances has id "script".
-     * Script of instance "a":
-     * ```ts
-     * // This example demonstrates how a game object instance, called "a", can communicate with another instance, called "b". It
-     * // is assumed that both script components of the instances has id "script".
-     *
-     * // a.script — Script of instance "a":
-     * export default defineScript({
-     *   init() {
-     *     // let b know about some important data
-     *     msg.post("b#script", "my_data", { important_value: 1 });
-     *   },
-     * });
-     * ```
-     * @example
-     * Script of instance "b":
-     * ```ts
-     * // b.script — Script of instance "b":
-     * export default defineScript({
-     *   init() {
-     *     // store the url of instance "a" for later use, by specifying undefined as socket we
-     *     // automatically use our own socket
-     *     return { a_url: msg.url(undefined, go.get_id("a"), "script"), important_value: 0 };
-     *   },
-     *
-     *   on_message(self, message_id, message, sender) {
-     *     // check message and sender
-     *     if (message_id === hash("my_data") && sender === self.a_url && typeof message.important_value === "number") {
-     *       // use the data in some way
-     *       self.important_value = message.important_value;
-     *     }
-     *   },
-     * });
-     * ```
-     */
-    export function on_message(self: Opaque<"userdata">, message_id: Hash, message: Record<string | number, unknown>, sender: Url): void;
-    /**
-     * This is a callback-function, which is called by the engine when the script component is reloaded, e.g. from the editor.
-     * It can be used for live development, e.g. to tweak constants or set up the state properly for the instance.
-     *
-     * @param self - reference to the script state to be used for storing data
-     * @example
-     * ```ts
-     * // This example demonstrates how to tweak the speed of a game object instance that is moved on user input.
-     * export default defineScript({
-     *   init() {
-     *     // acquire input focus
-     *     msg.post(".", "acquire_input_focus");
-     *     return {
-     *       // maximum speed the instance can be moved, this value is tweaked in the on_reload function below
-     *       max_speed: 2,
-     *       // velocity of the instance, initially zero
-     *       velocity: vmath.vector3(),
-     *     };
-     *   },
-     *
-     *   update(self, dt) {
-     *     // move the instance
-     *     go.set_position(go.get_position().add(self.velocity.mul(dt)));
-     *   },
-     *
-     *   on_input(self, action_id, action) {
-     *     // check for movement input
-     *     if (action_id === hash("right")) {
-     *       if (action.released) {
-     *         // reset velocity if input was released
-     *         self.velocity = vmath.vector3();
-     *       } else {
-     *         // update velocity
-     *         self.velocity = vmath.vector3((action.value ?? 0) * self.max_speed, 0, 0);
-     *       }
-     *     }
-     *   },
-     *
-     *   on_reload(self) {
-     *     // edit this value and reload the script component
-     *     self.max_speed = 100;
-     *   },
-     * });
-     * ```
-     */
-    export function on_reload(self: Opaque<"userdata">): void;
     /**
      * Sets the parent for a game object instance. This means that the instance will exist in the geometrical space of its parent,
      * like a basic transformation hierarchy or scene graph. If no parent is specified, the instance will be detached from any parent and exist in world
@@ -978,29 +773,6 @@ declare global {
      * ```
      */
     export function set_scale_xy(scale: number | Vector3, id?: SceneGameObjectAddress | Hash | Url): void;
-    /**
-     * This is a callback-function, which is called by the engine every frame to update the state of a script component.
-     * It can be used to perform any kind of game related tasks, e.g. moving the game object instance.
-     *
-     * @param self - reference to the script state to be used for storing data
-     * @param dt - the time-step of the frame update
-     * @example
-     * ```ts
-     * // This example demonstrates how to move a game object instance through the script component:
-     * export default defineScript({
-     *   init() {
-     *     // set initial velocity to be 1 along world x-axis
-     *     return { my_velocity: vmath.vector3(1, 0, 0) };
-     *   },
-     *
-     *   update(self, dt) {
-     *     // move the game object instance
-     *     go.set_position(go.get_position().add(self.my_velocity.mul(dt)));
-     *   },
-     * });
-     * ```
-     */
-    export function update(self: Opaque<"userdata">, dt: number): void;
     /**
      * Recalculates and updates the cached world transform immediately for the target instance
      * and its ancestors (parent chain up to the collection root). Descendants (children) are

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

@@ -4,6 +4,7 @@ declare global {
    * Graphics functions and constants.
    */
   namespace graphics {
+    type BlendFactor = typeof graphics.BLEND_FACTOR_ZERO | typeof graphics.BLEND_FACTOR_ONE | typeof graphics.BLEND_FACTOR_SRC_COLOR | typeof graphics.BLEND_FACTOR_ONE_MINUS_SRC_COLOR | typeof graphics.BLEND_FACTOR_DST_COLOR | typeof graphics.BLEND_FACTOR_ONE_MINUS_DST_COLOR | typeof graphics.BLEND_FACTOR_SRC_ALPHA | typeof graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA | typeof graphics.BLEND_FACTOR_DST_ALPHA | typeof graphics.BLEND_FACTOR_ONE_MINUS_DST_ALPHA | typeof graphics.BLEND_FACTOR_SRC_ALPHA_SATURATE | typeof graphics.BLEND_FACTOR_CONSTANT_COLOR | typeof graphics.BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR | typeof graphics.BLEND_FACTOR_CONSTANT_ALPHA | typeof graphics.BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA;
     type BufferType = typeof graphics.BUFFER_TYPE_COLOR0_BIT | typeof graphics.BUFFER_TYPE_COLOR1_BIT | typeof graphics.BUFFER_TYPE_COLOR2_BIT | typeof graphics.BUFFER_TYPE_COLOR3_BIT | typeof graphics.BUFFER_TYPE_DEPTH_BIT | typeof graphics.BUFFER_TYPE_STENCIL_BIT;
     type State = typeof graphics.STATE_DEPTH_TEST | typeof graphics.STATE_STENCIL_TEST | typeof graphics.STATE_BLEND | typeof graphics.STATE_ALPHA_TEST | typeof graphics.STATE_CULL_FACE | typeof graphics.STATE_POLYGON_OFFSET_FILL;
     const BLEND_FACTOR_CONSTANT_ALPHA: number & { readonly __brand: "graphics.BLEND_FACTOR_CONSTANT_ALPHA" };