@defold-typescript/types 0.51.0 → 0.53.0

package/src/gui-overloads.d.ts

@@ -0,0 +1,489 @@
+/** @noSelfInFile */
+
+import type {
+  Hash,
+  Matrix4,
+  Opaque,
+  Quaternion,
+  Url,
+  Vector,
+  Vector3,
+  Vector4,
+} from "./core-types";
+
+// The property name a `gui.PROP_*` constant equals: its brand suffix, lowercased.
+type PropName<P> = P extends { readonly __brand: `gui.PROP_${infer S}` } ? Lowercase<S> : never;
+
+// gui.cpp g_Properties: these four have no `.x`..`.w` sub-keys.
+type ScalarName = "inner_radius" | "fill_angle" | "leading" | "tracking";
+
+type VectorName = Exclude<PropName<gui.Prop>, ScalarName>;
+
+type NodePropertyName<K> = K extends keyof gui.NodeProperties
+  ? K
+  : Extract<PropName<K>, keyof gui.NodeProperties>;
+
+// gui_script.cpp:LuaSet: `rotation` takes only a quat, every other vector a
+// vector4 or a vector3, and a sub-key or scalar a number.
+type NodePropertyWrite<N extends keyof gui.NodeProperties> = N extends "rotation"
+  ? Quaternion
+  : gui.NodeProperties[N] extends number
+    ? number
+    : Vector4 | Vector3;
+
+declare global {
+  namespace gui {
+    /**
+     * The GUI node properties and the type each one reads as. A vector
+     * property reads as a vmath.vector4 and `rotation` as a vmath.quat; their
+     * `.x`..`.w` sub-keys and the four scalar properties read as a number.
+     */
+    type NodeProperties = {
+      [K in
+        | VectorName
+        | `${VectorName}.${"x" | "y" | "z" | "w"}`
+        | ScalarName]: K extends "rotation" ? Quaternion : K extends VectorName ? Vector4 : number;
+    };
+
+    interface PropertyOptions {
+      /** **⚠️ 1-based index into an array property; passed to Defold unchanged.** */
+      index?: number;
+      key?: string | Hash;
+      keys?: (Hash | string)[];
+    }
+
+    /**
+     * Instead of using specific getters such as gui.get_position or gui.get_scale,
+     * you can use gui.get instead and supply the property as a string or a
+     * `gui.PROP_*` constant. Only these node properties are supported:
+     *
+     * - `"position"`
+     * - `"rotation"`
+     * - `"euler"`
+     * - `"scale"`
+     * - `"color"`
+     * - `"outline"`
+     * - `"shadow"`
+     * - `"size"`
+     * - `"fill_angle"` (pie)
+     * - `"inner_radius"` (pie)
+     * - `"leading"` (text)
+     * - `"tracking"` (text)
+     * - `"slice9"` (slice9)
+     *
+     * Each property but the four scalars (`fill_angle`, `inner_radius`, `leading`
+     * and `tracking`) also exposes its components as `"<name>.x"` to `"<name>.w"`.
+     * Getting `"rotation"` returns a vmath.quat, another vector property a
+     * vmath.vector4, and a component or a scalar property a single number. To get
+     * a material constant, pass its name as a hash.
+     *
+     * @param node - node to get the property for
+     * @param property - the property to retrieve; each `gui.PROP_*` constant equals its corresponding property name string
+     * @returns the property value
+     * @example
+     * ```ts
+     * // Get properties on existing nodes:
+     * const node = gui.get_node("my_box_node");
+     * const node_position = gui.get(node, "position");
+     * ```
+     */
+    function get<K extends keyof gui.NodeProperties | gui.Prop>(
+      node: Opaque<"node">,
+      property: K,
+    ): gui.NodeProperties[NodePropertyName<K>];
+    /**
+     * Gets a material constant of a node, or any property named by a hash. Pass
+     * the constant's name as a hash, such as `hash("tint")`. Reading an array
+     * constant without `index` returns every element in a table.
+     *
+     * @param node - node to get the property for
+     * @param property - the property to retrieve, as a hash
+     * @param options - optional options table (only applicable for material constants)
+     * - `index` integer index into array property (1 based)
+     *
+     * **⚠️ `index` is 1-based; passed to Defold unchanged.**
+     * @returns the property value
+     * @example
+     * ```ts
+     * const node = gui.get_node("my_box_node");
+     * const tint = gui.get(node, hash("tint"));
+     * const second = gui.get(node, hash("tint_array"), { index: 2 });
+     * ```
+     */
+    function get(
+      node: Opaque<"node">,
+      property: Hash,
+    ): number | Vector4 | Quaternion | Matrix4 | number[] | Vector4[] | Matrix4[];
+    /**
+     * Gets a material constant of a node, or any property named by a hash. Pass
+     * the constant's name as a hash, such as `hash("tint")`. Reading an array
+     * constant without `index` returns every element in a table.
+     *
+     * @param node - node to get the property for
+     * @param property - the property to retrieve, as a hash
+     * @param options - optional options table (only applicable for material constants)
+     * - `index` integer index into array property (1 based)
+     *
+     * **⚠️ `index` is 1-based; passed to Defold unchanged.**
+     * @returns the property value
+     * @example
+     * ```ts
+     * const node = gui.get_node("my_box_node");
+     * const tint = gui.get(node, hash("tint"));
+     * const second = gui.get(node, hash("tint_array"), { index: 2 });
+     * ```
+     */
+    function get(
+      node: Opaque<"node">,
+      property: Hash,
+      options: gui.PropertyOptions,
+    ): number | Vector4 | Quaternion | Matrix4 | number[] | Vector4[] | Matrix4[];
+    /**
+     * Instead of using specific setters such as gui.set_position or gui.set_scale,
+     * you can use gui.set instead and supply the property as a string or a
+     * `gui.PROP_*` constant. Only the node properties gui.get lists are supported.
+     *
+     * The value depends on the property name. Setting `"rotation"` takes a
+     * vmath.quat, which differs from gui.set_rotation; to set the rotation in
+     * degrees, set `"euler"` instead. The rotation and euler properties are
+     * linked, so changing one changes the other. Every other vector property
+     * takes a vmath.vector4 or a vmath.vector3, and a component such as
+     * `"position.x"` or one of the four scalar properties takes a single number.
+     *
+     * @param node - node to set the property for
+     * @param property - the property to set; each `gui.PROP_*` constant equals its corresponding property name string
+     * @param value - the value to set
+     * @example
+     * Updates the position property on an existing node:
+     * ```ts
+     * const node = gui.get_node("my_box_node");
+     * const node_position = gui.get(node, "position");
+     * gui.set(node, "position.x", node_position.x + 128);
+     * ```
+     * @example
+     * Updates the rotation property on an existing node:
+     * ```ts
+     * const node = gui.get_node("my_box_node");
+     * gui.set(node, "rotation", vmath.quat_rotation_z(math.rad(45)));
+     * // this is equivalent to:
+     * gui.set(node, "euler.z", 45);
+     * // or using the entire vector:
+     * gui.set(node, "euler", vmath.vector3(0, 0, 45));
+     * // or using the set_rotation
+     * gui.set_rotation(node, vmath.vector3(0, 0, 45));
+     * ```
+     */
+    function set<K extends keyof gui.NodeProperties | gui.Prop>(
+      node: Opaque<"node">,
+      property: K,
+      value: NodePropertyWrite<NodePropertyName<K>>,
+    ): void;
+    /**
+     * Sets a material constant of a node, or any property named by a hash. If a
+     * material specifies a constant called `tint` in the .material file, set it
+     * with `gui.set(node, hash("tint"), vmath.vector4(1, 0, 0, 1))`, or pass a
+     * vmath.matrix4 if the constant is a matrix. To set one element of an array
+     * constant, pass an options table with `index` set.
+     *
+     * @param node - node to set the property for
+     * @param property - the property to set, as a hash
+     * @param value - the value to set
+     * @param options - optional material-constant options. **⚠️ `index` is 1-based; passed to Defold unchanged.**
+     * @example
+     * Sets various material constants for a node:
+     * ```ts
+     * const node = gui.get_node("my_box_node");
+     * gui.set(node, hash("tint"), vmath.vector4(1, 0, 0, 1));
+     * // matrix4 is also supported
+     * gui.set(node, hash("light_matrix"), vmath.matrix4());
+     * // update a constant in an array at position 4. the array is specified in the shader as:
+     * // uniform vec4 tint_array[4]; // lua is 1 based, shader is 0 based
+     * gui.set(node, hash("tint_array"), vmath.vector4(1, 0, 0, 1), { index: 4 });
+     * // update a matrix constant in an array at position 4. the array is specified in the shader as:
+     * // uniform mat4 light_matrix_array[4];
+     * gui.set(node, hash("light_matrix_array"), vmath.matrix4(), { index: 4 });
+     * // update a sub-element in a constant
+     * gui.set(node, hash("tint.x"), 1);
+     * // update a sub-element in an array constant at position 4
+     * gui.set(node, hash("tint_array.x"), 1, { index: 4 });
+     * ```
+     */
+    function set(
+      node: Opaque<"node">,
+      property: Hash,
+      value: number | Vector4 | Vector3 | Quaternion | Matrix4 | Hash,
+    ): void;
+    /**
+     * Sets a material constant of a node, or any property named by a hash. If a
+     * material specifies a constant called `tint` in the .material file, set it
+     * with `gui.set(node, hash("tint"), vmath.vector4(1, 0, 0, 1))`, or pass a
+     * vmath.matrix4 if the constant is a matrix. To set one element of an array
+     * constant, pass an options table with `index` set.
+     *
+     * @param node - node to set the property for
+     * @param property - the property to set, as a hash
+     * @param value - the value to set
+     * @param options - optional material-constant options. **⚠️ `index` is 1-based; passed to Defold unchanged.**
+     * @example
+     * Sets various material constants for a node:
+     * ```ts
+     * const node = gui.get_node("my_box_node");
+     * gui.set(node, hash("tint"), vmath.vector4(1, 0, 0, 1));
+     * // matrix4 is also supported
+     * gui.set(node, hash("light_matrix"), vmath.matrix4());
+     * // update a constant in an array at position 4. the array is specified in the shader as:
+     * // uniform vec4 tint_array[4]; // lua is 1 based, shader is 0 based
+     * gui.set(node, hash("tint_array"), vmath.vector4(1, 0, 0, 1), { index: 4 });
+     * // update a matrix constant in an array at position 4. the array is specified in the shader as:
+     * // uniform mat4 light_matrix_array[4];
+     * gui.set(node, hash("light_matrix_array"), vmath.matrix4(), { index: 4 });
+     * // update a sub-element in a constant
+     * gui.set(node, hash("tint.x"), 1);
+     * // update a sub-element in an array constant at position 4
+     * gui.set(node, hash("tint_array.x"), 1, { index: 4 });
+     * ```
+     */
+    function set(
+      node: Opaque<"node">,
+      property: Hash,
+      value: number | Vector4 | Vector3 | Quaternion | Matrix4 | Hash,
+      options: gui.PropertyOptions,
+    ): void;
+    /**
+     * Sets a resource property of the gui component itself, addressed with
+     * `msg.url()`: `"material"`, or the `"materials"`, `"fonts"` or `"textures"`
+     * entry named by the `key` option. A property a native extension registers is
+     * named by a hash.
+     *
+     * @param url - msg.url() to the gui itself
+     * @param property - the property to set
+     * @param value - the resource to set
+     * @param options - options table; `key` names the entry to set
+     * @example
+     * Set a named property
+     * ```ts
+     * export default defineGuiScript({
+     *   on_message(self, message_id, message) {
+     *     if (message_id === hash("set_font") && types.is_hash(message.font)) {
+     *       gui.set(msg.url(), "fonts", message.font, { key: "my_font_name" });
+     *       gui.set_font(gui.get_node("text"), "my_font_name");
+     *     } else if (message_id === hash("set_texture") && types.is_hash(message.texture)) {
+     *       gui.set(msg.url(), "textures", message.texture, { key: "my_texture" });
+     *       gui.set_texture(gui.get_node("box"), "my_texture");
+     *       gui.play_flipbook(gui.get_node("box"), "logo_256");
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    function set(
+      url: Url,
+      property: "material" | "materials" | "fonts" | "textures" | Hash,
+      value: Hash,
+    ): void;
+    /**
+     * Sets a resource property of the gui component itself, addressed with
+     * `msg.url()`: `"material"`, or the `"materials"`, `"fonts"` or `"textures"`
+     * entry named by the `key` option. A property a native extension registers is
+     * named by a hash.
+     *
+     * @param url - msg.url() to the gui itself
+     * @param property - the property to set
+     * @param value - the resource to set
+     * @param options - options table; `key` names the entry to set
+     * @example
+     * Set a named property
+     * ```ts
+     * export default defineGuiScript({
+     *   on_message(self, message_id, message) {
+     *     if (message_id === hash("set_font") && types.is_hash(message.font)) {
+     *       gui.set(msg.url(), "fonts", message.font, { key: "my_font_name" });
+     *       gui.set_font(gui.get_node("text"), "my_font_name");
+     *     } else if (message_id === hash("set_texture") && types.is_hash(message.texture)) {
+     *       gui.set(msg.url(), "textures", message.texture, { key: "my_texture" });
+     *       gui.set_texture(gui.get_node("box"), "my_texture");
+     *       gui.play_flipbook(gui.get_node("box"), "logo_256");
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    function set(
+      url: Url,
+      property: "material" | "materials" | "fonts" | "textures" | Hash,
+      value: Hash,
+      options: gui.PropertyOptions,
+    ): void;
+    /**
+     * This starts an animation of a node property according to the specified parameters.
+     * If the node property is already being animated, that animation will be canceled and
+     * replaced by the new one. Note however that several different node properties
+     * can be animated simultaneously. Use `gui.cancel_animations` to stop the animation
+     * before it has completed.
+     * Only the node properties gui.get lists can be animated; a material constant
+     * cannot. Composite properties of type vector3, vector4 or quaternion
+     * also expose their sub-components (x, y, z and w).
+     * You can address the components individually by suffixing the name with a dot '.'
+     * and the name of the component.
+     * For instance, `"position.x"` (the position x coordinate) or `"color.w"`
+     * (the color alpha value).
+     * 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 below for more information.
+     *
+     * @param node - node to animate
+     * @param property - property to animate; each `gui.PROP_*` constant equals its corresponding property name string
+     * @param to - target property value
+     * @param easing - easing to use during animation.
+     * Either specify one of the `gui.EASING_*` constants or provide a
+     * vector with a custom curve. See the animation guide for more information.
+     * @param duration - duration of the animation in seconds.
+     * @param delay - delay before the animation starts in seconds.
+     * @param complete_function - function to call when the
+     * animation has completed
+     * @param playback - playback mode
+     * @example
+     * How to start a simple color animation, where the node fades in to white during 0.5 seconds:
+     * ```ts
+     * // How to start a simple color animation, where the node fades in to white during 0.5 seconds:
+     * const node = gui.get_node("my_node");
+     * gui.set_color(node, vmath.vector4(0, 0, 0, 0)); // node is fully transparent
+     * gui.animate(node, gui.PROP_COLOR, vmath.vector4(1, 1, 1, 1), gui.EASING_INOUTQUAD, 0.5); // start animation
+     * ```
+     * @example
+     * How to start a sequenced animation where the node fades in to white during 0.5 seconds, stays visible for 2 seconds and then fades out:
+     * ```ts
+     * // How to start a sequenced animation where the node fades in to white during 0.5
+     * // seconds, stays visible for 2 seconds and then fades out:
+     * function on_animation_done(self: unknown, node: Opaque<"node">) {
+     *   // fade out node, but wait 2 seconds before the animation starts
+     *   gui.animate(node, gui.PROP_COLOR, vmath.vector4(0, 0, 0, 0), gui.EASING_OUTQUAD, 0.5, 2.0);
+     * }
+     *
+     * export default defineGuiScript({
+     *   init(self) {
+     *     // fetch the node we want to animate
+     *     const my_node = gui.get_node("my_node");
+     *     // node is initially set to fully transparent
+     *     gui.set_color(my_node, vmath.vector4(0, 0, 0, 0));
+     *     // animate the node immediately and call on_animation_done when the animation has completed
+     *     gui.animate(my_node, gui.PROP_COLOR, vmath.vector4(1, 1, 1, 1), gui.EASING_INOUTQUAD, 0.5, 0.0, on_animation_done);
+     *   },
+     * });
+     * ```
+     * @example
+     * How to animate a node's y position using a crazy custom easing curve:
+     * ```ts
+     * // How to animate a node's y position using a crazy custom easing curve:
+     * export default defineGuiScript({
+     *   init(self) {
+     *     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);
+     *     const node = gui.get_node("box");
+     *     gui.animate(node, "position.y", 100, vec, 4.0, 0, undefined, gui.PLAYBACK_LOOP_PINGPONG);
+     *   },
+     * });
+     * ```
+     */
+    function animate(
+      node: Opaque<"node">,
+      property: keyof gui.NodeProperties | gui.Prop | Hash,
+      to: number | Vector3 | Vector4 | Quaternion,
+      easing: gui.Easing | Vector,
+      duration: number,
+    ): void;
+    /**
+     * This starts an animation of a node property according to the specified parameters.
+     * If the node property is already being animated, that animation will be canceled and
+     * replaced by the new one. Note however that several different node properties
+     * can be animated simultaneously. Use `gui.cancel_animations` to stop the animation
+     * before it has completed.
+     * Only the node properties gui.get lists can be animated; a material constant
+     * cannot. Composite properties of type vector3, vector4 or quaternion
+     * also expose their sub-components (x, y, z and w).
+     * You can address the components individually by suffixing the name with a dot '.'
+     * and the name of the component.
+     * For instance, `"position.x"` (the position x coordinate) or `"color.w"`
+     * (the color alpha value).
+     * 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 below for more information.
+     *
+     * @param node - node to animate
+     * @param property - property to animate; each `gui.PROP_*` constant equals its corresponding property name string
+     * @param to - target property value
+     * @param easing - easing to use during animation.
+     * Either specify one of the `gui.EASING_*` constants or provide a
+     * vector with a custom curve. See the animation guide for more information.
+     * @param duration - duration of the animation in seconds.
+     * @param delay - delay before the animation starts in seconds.
+     * @param complete_function - function to call when the
+     * animation has completed
+     * @param playback - playback mode
+     * @example
+     * How to start a simple color animation, where the node fades in to white during 0.5 seconds:
+     * ```ts
+     * // How to start a simple color animation, where the node fades in to white during 0.5 seconds:
+     * const node = gui.get_node("my_node");
+     * gui.set_color(node, vmath.vector4(0, 0, 0, 0)); // node is fully transparent
+     * gui.animate(node, gui.PROP_COLOR, vmath.vector4(1, 1, 1, 1), gui.EASING_INOUTQUAD, 0.5); // start animation
+     * ```
+     * @example
+     * How to start a sequenced animation where the node fades in to white during 0.5 seconds, stays visible for 2 seconds and then fades out:
+     * ```ts
+     * // How to start a sequenced animation where the node fades in to white during 0.5
+     * // seconds, stays visible for 2 seconds and then fades out:
+     * function on_animation_done(self: unknown, node: Opaque<"node">) {
+     *   // fade out node, but wait 2 seconds before the animation starts
+     *   gui.animate(node, gui.PROP_COLOR, vmath.vector4(0, 0, 0, 0), gui.EASING_OUTQUAD, 0.5, 2.0);
+     * }
+     *
+     * export default defineGuiScript({
+     *   init(self) {
+     *     // fetch the node we want to animate
+     *     const my_node = gui.get_node("my_node");
+     *     // node is initially set to fully transparent
+     *     gui.set_color(my_node, vmath.vector4(0, 0, 0, 0));
+     *     // animate the node immediately and call on_animation_done when the animation has completed
+     *     gui.animate(my_node, gui.PROP_COLOR, vmath.vector4(1, 1, 1, 1), gui.EASING_INOUTQUAD, 0.5, 0.0, on_animation_done);
+     *   },
+     * });
+     * ```
+     * @example
+     * How to animate a node's y position using a crazy custom easing curve:
+     * ```ts
+     * // How to animate a node's y position using a crazy custom easing curve:
+     * export default defineGuiScript({
+     *   init(self) {
+     *     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);
+     *     const node = gui.get_node("box");
+     *     gui.animate(node, "position.y", 100, vec, 4.0, 0, undefined, gui.PLAYBACK_LOOP_PINGPONG);
+     *   },
+     * });
+     * ```
+     */
+    function animate(
+      node: Opaque<"node">,
+      property: keyof gui.NodeProperties | gui.Prop | Hash,
+      to: number | Vector3 | Vector4 | Quaternion,
+      easing: gui.Easing | Vector,
+      duration: number,
+      delay: number,
+      complete_function?: (self: unknown, node: Opaque<"node">) => void,
+      playback?: gui.Playback,
+    ): void;
+  }
+}

package/src/gui-texture-removal.d.ts

@@ -0,0 +1,41 @@
+/** @noSelfInFile */
+
+import type { Hash, Url } from "./core-types";
+
+// The nil branch of gui_script.cpp:LuaSet exists from Defold 1.13.1, so this
+// arm rides only the surfaces whose import gate (`regen.ts`) admits it.
+declare global {
+  namespace gui {
+    /**
+     * Removes the runtime texture mapping the `key` option names from the gui
+     * component itself. Needs Defold 1.13.1 or later.
+     *
+     * @param url - msg.url() to the gui itself
+     * @param property - the textures property
+     * @param value - nil, to remove the mapping
+     * @param options - options table; `key` names the texture to remove
+     * @example
+     * Remove a named runtime texture resource mapping:
+     * ```ts
+     * const atlas_params = {
+     *   texture: "/runtime.texturec",
+     *   animations: [{ id: "runtime", width: 1, height: 1, frames: [1] }],
+     *   geometries: [{ vertices: [0, 0, 0, 1, 1, 1, 1, 0], uvs: [0, 0, 0, 1, 1, 1, 1, 0], indices: [0, 1, 2, 0, 2, 3] }],
+     * } satisfies Parameters<typeof resource.create_atlas>[1];
+     * const atlas_id = resource.create_atlas("/runtime.texturesetc", atlas_params);
+     * gui.set(msg.url(), "textures", atlas_id, { key: "runtime_texture" });
+     * gui.set_texture(gui.get_node("box"), "runtime_texture");
+     *
+     * // Later, remove the GUI mapping before releasing the atlas resource.
+     * gui.set(msg.url(), "textures", undefined, { key: "runtime_texture" });
+     * resource.release(atlas_id);
+     * ```
+     */
+    function set(
+      url: Url,
+      property: "textures",
+      value: undefined,
+      options: { key: string | Hash },
+    ): void;
+  }
+}

package/src/index.ts

@@ -67,6 +67,7 @@ export {
   TS_IDENTIFIER,
   TS_RESERVED_NAMES,
 } from "./emit-dts";
+export { ENGINE_TYPE_NAME_OVERRIDES, engineTypeName } from "./engine-type-name";
 export {
   hashExampleSource,
   lookupExampleSegments,
@@ -136,6 +137,8 @@ export {
   lookupSignature,
   type SignatureOverride,
   type SignatureStore,
+  signatureArmsFor,
+  signatureStoreFor,
 } from "./signature-store";
 export {
   classifyUrlParameter,

package/src/lifecycle.ts

@@ -1,6 +1,6 @@
 import type { Hash, Url } from "./core-types";
 
-// Fields and docs follow the go ref-doc's `on_input.touch` STRUCT, whose keys are
+// Fields and docs follow the go ref-doc's `on_input.touch` STRUCT (`go.on_input.Touch`), whose keys are
 // the ones comp_script.cpp pushes; lifecycle-member-docs drift-guards the docs
 // against it, and a ref-doc re-pin is reconciled by hand.
 export interface InputTouch {
@@ -54,7 +54,7 @@ export interface InputTouch {
   screen_dy: number;
 }
 
-// Fields and docs follow the go ref-doc's `on_input.action` STRUCT, whose keys are
+// Fields and docs follow the go ref-doc's `on_input.action` STRUCT (`go.on_input.Action`), whose keys are
 // the ones comp_script.cpp pushes; lifecycle-member-docs drift-guards the docs
 // against it, and a ref-doc re-pin is reconciled by hand.
 export interface InputAction {
@@ -370,7 +370,10 @@ export type RenderScriptHooks<TSelf, TInitState = TSelf> = Omit<
 // the property channel (raw default values), `TSelf` the merged `self` the
 // callbacks see (`NoInfer`-wrapped inside the hook set), and `TInitState` what
 // `init` returns. `ScriptHooks` itself stays callback-only so the
-// `SCRIPT_HOOK_NAMES` drift pin remains valid.
+// `SCRIPT_HOOK_NAMES` drift pin remains valid. Only `defineScript` takes
+// `properties`: the GUI and render variants keep the same three type parameters
+// but type the field `undefined`, because Defold builds `go.property` only in
+// `.script` files.
 //
 // `init` is overridden to receive `self: NoInfer<TProps>` — Defold applies the
 // declared property values to `self` before `init` runs, so init-time setup can
@@ -402,17 +405,20 @@ export type GuiScriptHooksWithProperties<TProps, TSelf, TInitState> = Omit<
   "init"
 > & {
   /**
-   * Receives `self` pre-populated with the declared `properties` before the
-   * engine runs init, so init-time setup can read those default values. The
-   * returned object still seeds the inferred script state.
+   * Receives `self` typed by the first type argument, which stays empty unless
+   * given explicitly, since a GUI script declares no properties. The
+   * returned object seeds the inferred script state.
    */
   init?(self: NoInfer<TProps>): TInitState;
   /**
-   * Value-keyed editor properties: each key is a property name and its value
-   * the default, so the value's type threads onto `self` alongside init's
-   * returned state.
+   * Not available: Defold builds `go.property` only in `.script` files, so a
+   * GUI script cannot declare properties. Declare the property on a game
+   * object's {@link defineScript} and `msg.post` its value to the GUI
+   * script from that script's `init`; `go.get` does not work for this from a
+   * GUI script, since the engine's `go.get` accepts only a game-object
+   * script instance.
    */
-  properties?: TProps;
+  properties?: undefined;
 };
 
 export type RenderScriptHooksWithProperties<TProps, TSelf, TInitState> = Omit<
@@ -420,17 +426,20 @@ export type RenderScriptHooksWithProperties<TProps, TSelf, TInitState> = Omit<
   "init"
 > & {
   /**
-   * Receives `self` pre-populated with the declared `properties` before the
-   * engine runs init, so init-time setup can read those default values. The
-   * returned object still seeds the inferred script state.
+   * Receives `self` typed by the first type argument, which stays empty unless
+   * given explicitly, since a render script declares no properties. The
+   * returned object seeds the inferred script state.
    */
   init?(self: NoInfer<TProps>): TInitState;
   /**
-   * Value-keyed editor properties: each key is a property name and its value
-   * the default, so the value's type threads onto `self` alongside init's
-   * returned state.
+   * Not available: Defold builds `go.property` only in `.script` files, so a
+   * render script cannot declare properties. Declare the property on a game
+   * object's {@link defineScript} and `msg.post` its value to the render
+   * script from that script's `init`; `go.get` does not work for this from a
+   * render script, since the engine's `go.get` accepts only a game-object
+   * script instance.
    */
-  properties?: TProps;
+  properties?: undefined;
 };
 
 // The script-local message map an `onMessage` dispatcher carries, lifted onto
@@ -502,9 +511,9 @@ export function defineScript<
 /**
  * Type a `.gui_script` component's hook table. Like {@link defineScript} it is
  * an identity function at runtime, infers `TSelf` from `init`'s return by
- * default, accepts the same value-keyed `properties` field as
- * {@link defineScript}, and is erased by the transpiler's `lifecycle-erasure`
- * pass into the flat Defold chunk shape.
+ * default, and is erased by the transpiler's `lifecycle-erasure` pass into the
+ * flat Defold chunk shape. The `properties` field is {@link defineScript}-only:
+ * Defold builds `go.property` only in `.script` files.
  *
  * `GuiScriptHooks` is `Omit<ScriptHooks, "fixed_update" | "late_update">` — gui
  * scripts are not driven by the fixed-timestep or late-update passes. It accepts
@@ -543,9 +552,9 @@ export function defineGuiScript<
 /**
  * Type a `.render_script` component's hook table. Like {@link defineScript} it
  * is an identity function at runtime, infers `TSelf` from `init`'s return by
- * default, accepts the same value-keyed `properties` field as
- * {@link defineScript}, and is erased by the transpiler's `lifecycle-erasure`
- * pass into the flat Defold chunk shape.
+ * default, and is erased by the transpiler's `lifecycle-erasure` pass into the
+ * flat Defold chunk shape. The `properties` field is {@link defineScript}-only:
+ * Defold builds `go.property` only in `.script` files.
  *
  * `RenderScriptHooks` is `Omit<ScriptHooks, "on_input" | "final" |
  * "fixed_update" | "late_update">` — the engine calls only four render-script