@defold-typescript/types 0.51.0 → 0.52.0

package/generated/go.d.ts

@@ -276,7 +276,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: Url, property: Hash) => 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`
+     *
+     * script_instance The current script instance.
+     *
+     * `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: Url, property: Hash) => 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.
@@ -335,7 +393,43 @@ declare global {
      * go.delete(ids, true);
      * ```
      */
-    function _delete(id?: SceneGameObjectAddress | Hash | Url | (string | 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.
@@ -355,36 +449,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.
+     *
+     * - 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 self - script instance used for storing state
+     * @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: unknown): 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 - script instance used for storing state
-     * @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: unknown, 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.
@@ -408,7 +495,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.
      *
@@ -591,176 +678,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 - script instance used for storing state
-     * @example
-     * ```ts
-     * export default defineScript({
-     *   init() {
-     *     // set up useful data
-     *     return { my_value: 1 };
-     *   },
-     * });
-     * ```
-     */
-    export function init(self: unknown): 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 - script instance used for storing state
-     * @param dt - the time-step of the frame update
-     */
-    export function late_update(self: unknown, 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.
-     *
-     * @param self - script instance used for storing state
-     * @param action_id - id of the received input action, as mapped in the input_binding-file, or `nil` for mouse movement
-     * @param action - input data for the action. **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: unknown, action_id: Hash | undefined, action: go.on_input.action): 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 - script instance used for storing state
-     * @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: unknown, message_id: Hash, message: LuaMap<AnyNotNil, unknown> | Record<string, 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 - script instance used for storing state
-     * @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: unknown): 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
@@ -873,29 +790,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 - script instance used for storing state
-     * @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: unknown, 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/graphics.d.ts

@@ -114,6 +114,7 @@ declare global {
        */
       max_storage_buffers_per_stage: number;
     }
+    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;
     type BLEND_EQUATION = typeof graphics.BLEND_EQUATION_ADD | typeof graphics.BLEND_EQUATION_MAX | typeof graphics.BLEND_EQUATION_MIN | typeof graphics.BLEND_EQUATION_REVERSE_SUBTRACT | typeof graphics.BLEND_EQUATION_SUBTRACT;