@defold-typescript/types 0.50.1 → 0.52.0

package/src/lifecycle.ts

@@ -7,51 +7,51 @@ export interface InputTouch {
   /**
    * Identifier for the touch during its lifetime.
    */
-  id?: number;
+  id: number;
   /**
    * Whether the finger was pressed this frame.
    */
-  pressed?: boolean;
+  pressed: boolean;
   /**
    * Whether the finger was released this frame.
    */
-  released?: boolean;
+  released: boolean;
   /**
    * Number of taps, such as one for a single tap and two for a double tap.
    */
-  tap_count?: number;
+  tap_count: number;
   /**
    * Touch x-coordinate.
    */
-  x?: number;
+  x: number;
   /**
    * Touch y-coordinate.
    */
-  y?: number;
+  y: number;
   /**
    * Change in the touch x-coordinate.
    */
-  dx?: number;
+  dx: number;
   /**
    * Change in the touch y-coordinate.
    */
-  dy?: number;
+  dy: number;
   /**
    * Touch x-coordinate in screen space.
    */
-  screen_x?: number;
+  screen_x: number;
   /**
    * Touch y-coordinate in screen space.
    */
-  screen_y?: number;
+  screen_y: number;
   /**
    * Change in the touch x-coordinate in screen space.
    */
-  screen_dx?: number;
+  screen_dx: number;
   /**
    * Change in the touch y-coordinate in screen space.
    */
-  screen_dy?: number;
+  screen_dy: number;
 }
 
 // Fields and docs follow the go ref-doc's `on_input.action` STRUCT, whose keys are
@@ -363,14 +363,17 @@ export type GuiScriptHooks<TSelf, TInitState = TSelf> = Omit<
 
 export type RenderScriptHooks<TSelf, TInitState = TSelf> = Omit<
   ScriptHooks<TSelf, TInitState>,
-  "on_input"
+  "on_input" | "final" | "fixed_update" | "late_update"
 >;
 
 // The factory hook table plus the value-keyed `properties` field. `TProps` is
 // 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,13 +552,13 @@ 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">` — render scripts do not
- * receive input. It accepts the rest of the set, all optional: `init`,
- * `update`, `fixed_update`, `late_update`, `on_message`, `final`, `on_reload`.
+ * `RenderScriptHooks` is `Omit<ScriptHooks, "on_input" | "final" |
+ * "fixed_update" | "late_update">` — the engine calls only four render-script
+ * hooks, all optional: `init`, `update`, `on_message`, `on_reload`.
  *
  * Scaffold it with the `def-ts-defineRenderScript-inferred-self` / `def-ts-defineRenderScript-typed-self` VSCode snippets
  * from `defold-typescript init`.

package/src/luals-type-expr.ts

@@ -334,6 +334,11 @@ export function mapLualsExpression(
   return { ts: mapToken(token, walk), unknowns: walk.unknowns };
 }
 
+/** Whether a raw token is a typed LuaLS `fun(...)` expression rather than a bare `function(...)`. */
+export function isLualsFunctionToken(token: string): boolean {
+  return /^fun\s*\(/.test(token.trim());
+}
+
 /**
  * Map a `fun(...)` expression to a TypeScript **call signature** — the colon-return
  * form `(params): ret` an interface uses to become callable, not the `=>` arrow a
@@ -345,7 +350,7 @@ export function mapLualsCallSignatureExpression(
   position: LualsPosition = "output",
 ): LualsMapResult {
   const trimmed = token.trim();
-  if (!/^fun\s*\(/.test(trimmed)) {
+  if (!isLualsFunctionToken(trimmed)) {
     throw new Error(`mapLualsCallSignature: expected a "fun(...)" token, got "${token}".`);
   }
   const walk: Walk = { resolveLeaf, unknowns: [], position };

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/physics-event-guard.d.ts

@@ -0,0 +1,39 @@
+/** @noSelfInFile */
+import type { Hash } from "./core-types";
+
+// `physics.set_event_listener` sets `type` on every event to its message-name
+// hash (script_physics.cpp), but a `Hash` is an object type, not a unit type, so
+// an `event.type == hash("…")` check cannot narrow the event union. This guard
+// re-introduces the literal at the use site. The transpiler lowers the call to
+// `event.type == hash("…")` (physics-event-guard-lowering.ts), so this package
+// emits no runtime Lua. It names no `physics` type, so it compiles on a surface
+// whose reference declares no event union.
+type PhysicsEventName<E> = E extends { type: Hash<infer N> } ? N : never;
+
+declare global {
+  /**
+   * Type guard for a `physics.set_event_listener` callback: narrows one event
+   * to the member of the event union whose `type` is the hash of `name`. The
+   * engine sets `type` on every event, but a `Hash` cannot act as a union
+   * discriminant, so an `event.type == hash("collision_event")` check leaves the
+   * event unnarrowed — this guard re-introduces the literal.
+   *
+   * @param event - one entry of the `events` array the listener received.
+   * @param name - the event's message name (e.g. `"collision_event"`).
+   * @returns `true` when `event.type` is `hash(name)`, narrowing `event` to that event.
+   * @example
+   * ```ts
+   * physics.set_event_listener((self, events) => {
+   *   for (const event of events) {
+   *     if (isPhysicsEvent(event, "collision_event")) {
+   *       print(event.a.id, event.b.id);
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  function isPhysicsEvent<E extends { type: Hash }, K extends PhysicsEventName<E>>(
+    event: E,
+    name: K,
+  ): event is Extract<E, { type: Hash<K> }>;
+}

package/src/render-overloads.d.ts

@@ -12,7 +12,7 @@ declare global {
      * @param parameters - table of buffer parameters, see the description for available keys and values
      * @returns new render target
      */
-    function render_target(parameters: Record<string | number, unknown>): Opaque<"render_target">;
+    function render_target(parameters: render.RenderTargetParams): Opaque<"render_target">;
     /**
      * Creates a new named render target according to the supplied specification
      * table. The name is used by the profiler and by render target lookups.
@@ -23,7 +23,7 @@ declare global {
      */
     function render_target(
       name: string,
-      parameters: Record<string | number, unknown>,
+      parameters: render.RenderTargetParams,
     ): Opaque<"render_target">;
   }
 }

package/src/return-correction-provenance.ts

@@ -248,6 +248,10 @@ export interface ReturnTypeProvenance {
   readonly sightedIn: readonly string[];
   readonly neededBy: readonly string[];
   readonly resolvedIn: readonly string[];
+  // Targets whose vendored binding does not show a binding-pinned entry's pin,
+  // so the emitter leaves the entry off there. Never a resolution: upstream
+  // documented nothing, the engine source changed.
+  readonly unboundIn: readonly string[];
   readonly driftedIn: readonly string[];
   readonly typeDrift: readonly string[];
 }
@@ -255,14 +259,26 @@ export interface ReturnTypeProvenance {
 // Same ranking argument as `FIELD_VERDICT_RANK`: `emitReturn` applies the
 // correction to every declaration of the FQN in a target, so one drifted
 // declaration makes that target's emit wrong whatever its siblings say.
-type ReturnVerdict = "drift" | "needed" | "resolved";
+// Binding evidence is per target, so for a binding-pinned entry `unbound` never
+// meets another verdict in the same target.
+type ReturnVerdict = "drift" | "needed" | "unbound" | "resolved";
 
 const RETURN_VERDICT_RANK: Record<ReturnVerdict, number> = {
-  drift: 2,
-  needed: 1,
+  drift: 3,
+  needed: 2,
+  unbound: 1,
   resolved: 0,
 };
 
+// Whether the declared tokens already say what the correction does. Tokens can
+// state only the nil: a binding-pinned `ts` entry corrects what the binding sets
+// (a field it never pushes), so upstream fixing that shows as a retype, which is
+// drift, never as a resolution.
+function declaresCorrection(tokens: readonly string[], correction: ReturnTypeCorrection): boolean {
+  if (correction.nullable === undefined && correction.binding !== undefined) return false;
+  return correction.nullable === false ? !tokens.includes("nil") : tokens.includes("nil");
+}
+
 // The return-type class has the same two-sided evidence: the declared tokens
 // still say what the correction contradicts, and the slot prose still states the
 // contradiction. A target that fixes either half no longer needs the entry.
@@ -273,9 +289,16 @@ const RETURN_VERDICT_RANK: Record<ReturnVerdict, number> = {
 // return correction replaces the whole emitted type, so a base upstream no longer
 // declares means the correction now overwrites a type nobody verified — a
 // decision for a human, not a deletion and not a silent bank.
+//
+// A binding-pinned entry rests on the engine source rather than the prose, so
+// its prose is never searched. `bindingEvidence` maps each vendored target to
+// the keys whose pin holds there; a target absent from it shows no evidence.
+// A target without the entry's evidence is `unbound` before its tokens are
+// read, because the emitter leaves the entry off there.
 export function returnCorrectionProvenance(
   entries: readonly [string, ReturnTypeCorrection][],
   surfaces: readonly ProvenanceSurface[],
+  bindingEvidence: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
 ): ReturnTypeProvenance[] {
   return entries.map(([key, correction]) => {
     const namespace = namespaceOf(key);
@@ -291,7 +314,12 @@ export function returnCorrectionProvenance(
         const tokens = slot.types ?? [];
 
         let verdict: ReturnVerdict;
-        if (!pinMatches(tokens, pins)) {
+        if (
+          correction.binding !== undefined &&
+          bindingEvidence.get(surface.target)?.has(key) !== true
+        ) {
+          verdict = "unbound";
+        } else if (!pinMatches(tokens, pins)) {
           verdict = "drift";
           const messages = drift.get(surface.target) ?? new Set<string>();
           drift.set(surface.target, messages);
@@ -299,8 +327,9 @@ export function returnCorrectionProvenance(
             `${surface.target}: pinned ${pins.map((pin) => pin.join("|")).join(" or ")}, found ${tokens.join("|")}`,
           );
         } else if (
-          tokens.includes("nil") ||
-          !decodeSlotProse(slot.doc ?? "").includes(correction.reason)
+          declaresCorrection(tokens, correction) ||
+          (correction.binding === undefined &&
+            !decodeSlotProse(slot.doc ?? "").includes(correction.reason))
         ) {
           verdict = "resolved";
         } else {
@@ -323,6 +352,7 @@ export function returnCorrectionProvenance(
       sightedIn,
       neededBy: inBucket("needed"),
       resolvedIn: inBucket("resolved"),
+      unboundIn: inBucket("unbound"),
       driftedIn,
       typeDrift: driftedIn.flatMap((target) => [...(drift.get(target) ?? [])]).sort(),
     };

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.

package/src/window-event-guard.d.ts

@@ -4,7 +4,8 @@
 // params, and the `WINDOW_EVENT_*` constants are branded numbers — so TS can
 // neither correlate the two params nor use a branded number as a discriminant.
 // This guard re-introduces the discriminant at the use site, narrowing the
-// untyped `data` payload (only `WINDOW_EVENT_RESIZED` carries fields). It mirrors
+// untyped `data` payload (only `WINDOW_EVENT_RESIZED` carries fields; every
+// other event gets an empty table, script_window.cpp). It mirrors
 // `isMessage` for `on_message`; the transpiler lowers the call to a bare
 // `event == window.WINDOW_EVENT_*` (window-event-guard-lowering.ts), so this
 // package emits no runtime Lua. The event kinds are read off the loaded
@@ -14,7 +15,7 @@ type WindowEventKind = (typeof window)[Extract<keyof typeof window, `WINDOW_EVEN
 
 type WindowEventData<K extends WindowEventKind> = K extends typeof window.WINDOW_EVENT_RESIZED
   ? { width: number; height: number }
-  : undefined;
+  : Record<string, never>;
 
 declare global {
   /**
@@ -24,7 +25,8 @@ declare global {
    * params and the constants are branded numbers, so TS cannot auto-narrow `data`
    * from an `event === window.WINDOW_EVENT_RESIZED` check — this guard
    * re-introduces the discriminant. Only `WINDOW_EVENT_RESIZED` carries fields
-   * (`{ width, height }`); every other event narrows `data` to `undefined`.
+   * (`{ width, height }`); every other event receives an empty table, so `data`
+   * narrows to `Record<string, never>`.
    *
    * @param event - the event constant the callback received.
    * @param data - the untyped data payload the callback received.