@defold-typescript/types 0.51.0 → 0.52.0

package/src/lifecycle.ts

@@ -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

package/src/msg-overloads.d.ts

@@ -100,17 +100,24 @@ declare global {
      * Only the following arities are supported at runtime:
      *
      * - `msg.url()` — no-arg.
-     * - `msg.url("[socket:][path][#fragment]")` — one string, the full URL.
-     * - `msg.url(socket, path, fragment)` — three required args.
+     * - `msg.url(urlstring)` — one argument: a `"[socket:][path][#fragment]"`
+     *   string, a `Hash`, or a `Url`.
+     * - `msg.url(socket, path, fragment)` — three positions, each of which may
+     *   be `undefined` (Lua `nil`).
      *
      * The two-arg form `msg.url(socket, path)` is a runtime error.
      *
-     * `socket` may be `undefined` (Lua `nil`), which addresses the current
-     * game world, exactly as the runtime's own examples do.
+     * In the one-argument form, a `Hash` is a path in the current world with no
+     * fragment, and a `Url` is copied. `undefined` is equivalent to `msg.url()`
+     * — the URL of the current script.
      *
-     * The one-argument form's `urlstring` may likewise be `undefined` (Lua
-     * `nil`), which the ref-doc calls equivalent to `msg.url()` — the URL of the
-     * current script.
+     * In the three-argument form, an `undefined` `socket` addresses the current
+     * game world, exactly as the runtime's own examples do. An `undefined`
+     * `path` with an `undefined` socket is the current path. An `undefined`
+     * `fragment` is no fragment, unless `socket` and `path` are both
+     * `undefined`, which keeps the current fragment. A `socket` and `fragment`
+     * with an `undefined` `path` raise "Can't resolve id with specified socket
+     * and fragment."
      *
      * In the same world, address a sibling **relatively** — by bare id
      * (`msg.url("camera")`), absolute path (`msg.url("/camera")`), or
@@ -139,6 +146,9 @@ declare global {
      * // A component on a sibling.
      * const comp: Url = msg.url("camera#script");
      *
+     * // A hashed path in the current world.
+     * const door: Url = msg.url(hash("/door"));
+     *
      * // Crossing into a proxy-loaded world — `socket` is the world name.
      * const proxied: Url = msg.url(hash("level1"), hash("/door"), hash("script"));
      *
@@ -147,18 +157,20 @@ declare global {
      * ```
      */
     function url(): Url;
-    function url(urlstring: SceneAddress | undefined): Url;
+    function url(urlstring: SceneAddress | Hash | Url | undefined): Url;
     function url(
       socket: string | Hash | undefined,
-      path: string | Hash,
-      fragment: string | Hash,
+      path: string | Hash | undefined,
+      fragment: string | Hash | undefined,
     ): Url;
     function url<M extends object>(): ReceiverUrl<M>;
-    function url<M extends object>(urlstring: SceneAddress | undefined): ReceiverUrl<M>;
+    function url<M extends object>(
+      urlstring: SceneAddress | Hash | Url | undefined,
+    ): ReceiverUrl<M>;
     function url<M extends object>(
       socket: string | Hash | undefined,
-      path: string | Hash,
-      fragment: string | Hash,
+      path: string | Hash | undefined,
+      fragment: string | Hash | undefined,
     ): ReceiverUrl<M>;
   }
 }

package/src/signature-store.ts

@@ -9,6 +9,10 @@ export interface SignatureOverride {
   // than `signatures` keeps the ref-doc fixture description for those rows. Every
   // existing override omits `docs` and renders exactly as before.
   docs?: (string | null)[];
+  // Optional per-overload first release, parallel to `signatures`: entry `i` is
+  // the bare semver from which row `i` exists, or `null` for a row every target
+  // declares. An absent array means every row is ungated.
+  since?: (string | null)[];
 }
 
 // An FQN (`io.open`, `file:read`, …) maps to one override. An element with
@@ -23,3 +27,49 @@ export type SignatureStore = Record<string, SignatureOverride>;
 export function lookupSignature(store: SignatureStore, fqn: string): SignatureOverride | null {
   return store[fqn] ?? null;
 }
+
+function versionParts(version: string): number[] {
+  return version.split(".").map((part) => Number.parseInt(part, 10));
+}
+
+function versionAtLeast(version: string, since: string): boolean {
+  const [have, need] = [versionParts(version), versionParts(since)];
+  for (let index = 0; index < Math.max(have.length, need.length); index += 1) {
+    const diff = (have[index] ?? 0) - (need[index] ?? 0);
+    if (diff !== 0) return diff > 0;
+  }
+  return true;
+}
+
+// The override as a target at `version` declares it: only the rows whose `since`
+// is absent, `null`, or at most `version`, with `docs` and `since` kept parallel.
+export function signatureArmsFor(override: SignatureOverride, version: string): SignatureOverride {
+  const since = override.since;
+  if (since === undefined) return override;
+  const kept = override.signatures
+    .map((_, index) => index)
+    .filter((index) => {
+      const first = since[index];
+      return first == null || versionAtLeast(version, first);
+    });
+  if (kept.length === override.signatures.length) return override;
+  const docs = override.docs;
+  return {
+    signatures: kept.map((index) => override.signatures[index] as string),
+    ...(docs === undefined
+      ? {}
+      : { docs: kept.filter((index) => index < docs.length).map((index) => docs[index] ?? null) }),
+    since: kept.map((index) => since[index] ?? null),
+  };
+}
+
+// The store as one version declares it: each entry keeps only the arms whose
+// `since` the version meets, and an entry left with none is dropped.
+export function signatureStoreFor(store: SignatureStore, version: string): SignatureStore {
+  const scoped: SignatureStore = {};
+  for (const [fqn, override] of Object.entries(store)) {
+    const arms = signatureArmsFor(override, version);
+    if (arms.signatures.length > 0) scoped[fqn] = arms;
+  }
+  return scoped;
+}

package/src/timers.d.ts

@@ -3,7 +3,8 @@
 // as an isolated Lua chunk with no shared global scope and no JS event loop, so
 // these are named module exports (lowered to a `require`), not ambient globals:
 // pay-for-use and explicit. The transpiler emits the runtime and the CLI writes
-// it to the output root; the import lowers to `require("defold_typescript_timers")`.
+// it to `lib/defold_typescript/timers.lua` (moved by `runtime-dir`), respelling
+// the import's `require` to that path.
 declare module "@defold-typescript/types/timers" {
   /**
    * Run `callback` once after `delayMs` milliseconds, backed by Defold's

package/src/vmath-overloads.d.ts

@@ -85,6 +85,32 @@ declare global {
      * @returns multiplied vector
      */
     function mul_per_elem<T extends Vector3 | Vector4>(v1: T, v2: T): T;
+    /**
+     * The returned value is a scalar defined as:
+     * `P ⋅ Q = |P| |Q| cos θ`
+     * where θ is the angle between the vectors P and Q.
+     *
+     * - If the dot product is positive then the angle between the vectors is below 90 degrees.
+     * - If the dot product is zero the vectors are perpendicular (at right-angles to each other).
+     * - If the dot product is negative then the angle between the vectors is more than 90 degrees.
+     *
+     * Both vectors must have the same type: a vector3 paired with a vector4 raises.
+     *
+     * @param v1 - first vector
+     * @param v2 - second vector
+     * @returns dot product
+     * @example
+     * ```ts
+     * const vector1 = vmath.vector3(1, 0, 0);
+     * const vector2 = vmath.vector3(0, 1, 0);
+     *
+     * if (vmath.dot(vector1, vector2) === 0) {
+     *   // The two vectors are perpendicular (at right-angles to each other)
+     *   // ...
+     * }
+     * ```
+     */
+    function dot<T extends Vector3 | Vector4>(v1: T, v2: T): number;
     /**
      * Normalizes a vector, i.e. returns a new vector with the same
      * direction as the input vector, but with length 1.