@defold-typescript/types 0.4.3 → 0.5.0

package/generated/msg.d.ts

@@ -3,8 +3,64 @@ import type { Hash, Url } from "../src/core-types";
 
 declare global {
   namespace msg {
+    /**
+     * This is equivalent to `msg.url(nil)` or `msg.url("#")`, which creates an url to the current
+     * script component.
+     *
+     * @returns a new URL
+     * @example
+     * ```lua
+     * Create a new URL which will address the current script:
+     * local my_url = msg.url()
+     * print(my_url) --> url: [current_collection:/my_instance#my_component]
+     * ```
+     */
     function url(): Url;
+    /**
+     * The format of the string must be `[socket:][path][#fragment]`, which is similar to a HTTP URL.
+     * When addressing instances:
+     * - `socket` is the name of a valid world (a collection)
+     * - `path` is the id of the instance, which can either be relative the instance of the calling script or global
+     * - `fragment` would be the id of the desired component
+     * In addition, the following shorthands are available:
+     * - `"."` the current game object
+     * - `"#"` the current component
+     *
+     * @param urlstring - string to create the url from
+     * @returns a new URL
+     * @example
+     * ```lua
+     * local my_url = msg.url("#my_component")
+     * print(my_url) --> url: [current_collection:/my_instance#my_component]
+     *
+     * local my_url = msg.url("my_collection:/my_sub_collection/my_instance#my_component")
+     * print(my_url) --> url: [my_collection:/my_sub_collection/my_instance#my_component]
+     *
+     * local my_url = msg.url("my_socket:")
+     * print(my_url) --> url: [my_collection:]
+     * ```
+     */
     function url(urlstring: string): Url;
+    /**
+     * creates a new URL from separate arguments
+     *
+     * @param socket - socket of the URL
+     * @param path - path of the URL
+     * @param fragment - fragment of the URL
+     * @returns a new URL
+     * @example
+     * ```lua
+     * local my_socket = "main" -- specify by valid name
+     * local my_path = hash("/my_collection/my_gameobject") -- specify as string or hash
+     * local my_fragment = "component" -- specify as string or hash
+     * local my_url = msg.url(my_socket, my_path, my_fragment)
+     *
+     * print(my_url) --> url: [main:/my_collection/my_gameobject#component]
+     * print(my_url.socket) --> 786443 (internal numeric value)
+     * print(my_url.path) --> hash: [/my_collection/my_gameobject]
+     * print(my_url.fragment) --> hash: [component]
+     * ```
+     */
     function url(socket?: string | Hash, path?: string | Hash, fragment?: string | Hash): Url;
   }
 }

package/generated/particlefx.d.ts

@@ -3,17 +3,139 @@ import type { Hash, Url, Vector4 } from "../src/core-types";
 
 declare global {
   namespace particlefx {
+    /**
+     * The emitter is not spawning any particles, but has particles that are still alive.
+     */
     const EMITTER_STATE_POSTSPAWN: number & { readonly __brand: "particlefx.EMITTER_STATE_POSTSPAWN" };
+    /**
+     * The emitter will be in this state when it has been started but before spawning any particles. Normally the emitter is in this state for a short time, depending on if a start delay has been set for this emitter or not.
+     */
     const EMITTER_STATE_PRESPAWN: number & { readonly __brand: "particlefx.EMITTER_STATE_PRESPAWN" };
+    /**
+     * The emitter does not have any living particles and will not spawn any particles in this state.
+     */
     const EMITTER_STATE_SLEEPING: number & { readonly __brand: "particlefx.EMITTER_STATE_SLEEPING" };
+    /**
+     * The emitter is spawning particles.
+     */
     const EMITTER_STATE_SPAWNING: number & { readonly __brand: "particlefx.EMITTER_STATE_SPAWNING" };
+    /**
+     * Starts playing a particle FX component.
+     * Particle FX started this way need to be manually stopped through `particlefx.stop()`.
+     * Which particle FX to play is identified by the URL.
+     * A particle FX will continue to emit particles even if the game object the particle FX component belonged to is deleted. You can call `particlefx.stop()` to stop it from emitting more particles.
+     *
+     * @param url - the particle fx that should start playing.
+     * @param emitter_state_function - optional callback function that will be called when an emitter attached to this particlefx changes state.
+  `self`
+  object The current object
+  `id`
+  hash The id of the particle fx component
+  `emitter`
+  hash The id of the emitter
+  `state`
+  constant the new state of the emitter:
+  - `particlefx.EMITTER_STATE_SLEEPING`
+  - `particlefx.EMITTER_STATE_PRESPAWN`
+  - `particlefx.EMITTER_STATE_SPAWNING`
+  - `particlefx.EMITTER_STATE_POSTSPAWN`
+     * @example
+     * ```lua
+     * 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_.
+     * local function emitter_state_change(self, id, emitter, state)
+     *   if emitter == hash("exhaust") and state == particlefx.EMITTER_STATE_POSTSPAWN then
+     *     -- exhaust is done spawning particles...
+     *   end
+     * end
+     *
+     * function init(self)
+     *     particlefx.play("#particlefx", emitter_state_change)
+     * end
+     * ```
+     */
     function play(url: string | Hash | Url, emitter_state_function?: (self: unknown, id: unknown, emitter: unknown, state: unknown) => void): void;
+    /**
+     * Resets a shader constant for a particle FX component emitter.
+     * The constant must be defined in the material assigned to the emitter.
+     * Resetting a constant through this function implies that the value defined in the material will be used.
+     * Which particle FX to reset a constant for is identified by the URL.
+     *
+     * @param url - the particle FX that should have a constant reset
+     * @param emitter - the id of the emitter
+     * @param constant - the name of the constant
+     * @example
+     * ```lua
+     * The following examples assumes that the particle FX has id "particlefx", it
+     * contains an emitter with the id "emitter" and that the default-material in builtins is used, which defines the constant "tint".
+     * If you assign a custom material to the sprite, you can reset the constants defined there in the same manner.
+     * How to reset the tinting of particles from an emitter:
+     * function init(self)
+     *     particlefx.reset_constant("#particlefx", "emitter", "tint")
+     * end
+     * ```
+     */
     function reset_constant(url: string | Hash | Url, emitter: string | Hash, constant: string | Hash): void;
+    /**
+     * Sets a shader constant for a particle FX component emitter.
+     * The constant must be defined in the material assigned to the emitter.
+     * Setting a constant through this function will override the value set for that constant in the material.
+     * The value will be overridden until particlefx.reset_constant is called.
+     * Which particle FX to set a constant for is identified by the URL.
+     *
+     * @param url - the particle FX that should have a constant set
+     * @param emitter - the id of the emitter
+     * @param constant - the name of the constant
+     * @param value - the value of the constant
+     * @example
+     * ```lua
+     * The following examples assumes that the particle FX has id "particlefx", it
+     * contains an emitter with the id "emitter" and that the default-material in builtins is used, which defines the constant "tint".
+     * If you assign a custom material to the sprite, you can reset the constants defined there in the same manner.
+     * How to tint particles from an emitter red:
+     * function init(self)
+     *     particlefx.set_constant("#particlefx", "emitter", "tint", vmath.vector4(1, 0, 0, 1))
+     * end
+     * ```
+     */
     function set_constant(url: string | Hash | Url, emitter: string | Hash, constant: string | Hash, value: Vector4): void;
+    /**
+     * Stops a particle FX component from playing.
+     * Stopping a particle FX does not remove already spawned particles.
+     * Which particle FX to stop is identified by the URL.
+     *
+     * @param url - the particle fx that should stop playing
+     * @param options - Options when stopping the particle fx. Supported options:
+  - boolean `clear`: instantly clear spawned particles
+     * @example
+     * ```lua
+     * How to stop a particle fx when a game object is deleted and immediately also clear
+     * any spawned particles:
+     * function final(self)
+     *     particlefx.stop("#particlefx", { clear = true })
+     * end
+     * ```
+     */
     function stop(url: string | Hash | Url, options?: { clear?: boolean }): void;
     interface properties {
+      /**
+       * The animation used during rendering by an emitter in a particle FX component.
+       * The property type is a hash and refers to a valid animation in an atlas or a tile source resource.
+       * If the animation isn't found, and error will be thrown.
+       */
       animation: Hash;
+      /**
+       * The image used during rendering by an emitter in a particle FX component.
+       * The property type is a hash and refers to an image resource (atlas or tile source).
+       * Note: When setting the image, if the currently playing animation of the emitter
+       * isn't found in the new image, the animation will be set to the first animation found.
+       */
       image: Hash;
+      /**
+       * The material used during rendering by an emitter in a particle FX component.
+       * The property type is a hash and refers to a material resource.
+       */
       material: Hash;
     }
   }