@defold-typescript/types 0.39.0 → 0.40.0

package/src/engine-globals.d.ts

@@ -12,8 +12,8 @@ declare global {
   function hash<S extends string>(s: S): Core.Hash<S>;
   /** Render a `Hash` handle as its hexadecimal string. */
   function hash_to_hex(h: Core.Hash): string;
-  /** Pretty-print any value to the console for debugging. */
-  function pprint(v: unknown): void;
+  /** Pretty-print any values to the console for debugging. */
+  function pprint(...args: unknown[]): void;
   /**
    * A typed handle to a resource the engine owns — a GUI node, a texture, a
    * render target, a physics body, a socket, and so on. You get one back from an

package/src/go-overloads.d.ts

@@ -9,9 +9,10 @@ interface ScriptProperty<TValue> {
 declare global {
   namespace go {
     interface GoPropertyOptions {
+      /** Zero-based element index into an array property; the transpiler emits Defold's 1-based index. */
       index?: number;
-      key?: Hash;
-      keys?: Record<string | number, unknown>;
+      key?: Hash | string;
+      keys?: (Hash | string)[];
     }
 
     /**
@@ -20,9 +21,9 @@ declare global {
      * @param url - url of the game object or component having the property
      * @param property - id of the property to retrieve
      * @param options - optional options table
-     * - index number index into array property (1 based)
-     * - key hash name of internal property
-     * - keys table array of internal component resources identified by key (e.g. a particle fx emitter, see examples below)
+     * - index number zero-based index into array property; the transpiler emits Defold's 1-based index
+     * - key hash or string name of internal property
+     * - keys array of hashes or strings identifying internal component resources (e.g. a particle fx emitter, see examples below)
      * @returns the value of the specified property
      * @example
      * ```ts
@@ -52,11 +53,11 @@ declare global {
      *
      * @param url - url of the game object or component having the property
      * @param property - id of the property to set
-     * @param value - the value to set
+     * @param value - the value to set, or an array of vector4 to set a material property array
      * @param options - optional options table
-     * - index integer index into array property (1 based)
-     * - key hash name of internal property
-     * - keys table array of internal component resources identified by key (e.g. a particle fx emitter, see examples below)
+     * - index integer zero-based index into array property; the transpiler emits Defold's 1-based index
+     * - key hash or string name of internal property
+     * - keys array of hashes or strings identifying internal component resources (e.g. a particle fx emitter, see examples below)
      * @example
      * ```ts
      * go.set("#sprite", "tint", vmath.vector4(1, 0, 0, 1));
@@ -80,7 +81,7 @@ declare global {
     function set(
       url: SceneAddress | Hash | Url,
       property: string | Hash,
-      value: number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion,
+      value: number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Vector4[],
       options?: GoPropertyOptions,
     ): void;
     /**

package/src/index.ts

@@ -53,6 +53,10 @@ export {
   type EmitOptions,
   emitDeclarations,
   emitSymbolSignatures,
+  firstSlotAlternativeOf,
+  PARAM_DOC_REWRITES,
+  type ParamDocRewrite,
+  rewriteParamDoc,
   type SlotTypes,
   type SymbolSignature,
   TS_IDENTIFIER,

package/src/param-correction-provenance.ts

@@ -0,0 +1,67 @@
+import { type ApiModule, parseDefoldApiDoc } from "./api-doc";
+import type { ParamTypeCorrection } from "./emit-dts";
+import type { ProvenanceSurface } from "./optional-correction-provenance";
+
+export interface ParamTypeProvenance {
+  readonly key: string;
+  readonly sightedIn: readonly string[];
+  readonly neededBy: readonly string[];
+  readonly resolvedIn: readonly string[];
+}
+
+const PARAM_SEPARATOR = ":param:";
+
+// `nil` is optionality, which `isDocOptional` owns; the correction replaces only
+// the concrete tokens, so only those are evidence.
+function baseTokens(tokens: readonly string[]): string {
+  return tokens.filter((token) => token !== "nil").join("|");
+}
+
+// A target needs a correction while any declaration of the slot there still
+// states the pinned tokens, so an overload that shows the defect keeps it alive.
+// Any other declared token set — fixed or retyped — no longer carries the
+// contradiction the entry records, and the entry goes once no target needs it.
+export function paramCorrectionProvenance(
+  entries: readonly [string, ParamTypeCorrection][],
+  surfaces: readonly ProvenanceSurface[],
+): ParamTypeProvenance[] {
+  const parsed = new Map<ProvenanceSurface, ApiModule>();
+  const parse = (surface: ProvenanceSurface): ApiModule => {
+    let module = parsed.get(surface);
+    if (!module) {
+      module = parseDefoldApiDoc(surface.doc);
+      parsed.set(surface, module);
+    }
+    return module;
+  };
+
+  return entries.map(([key, correction]) => {
+    const separator = key.lastIndexOf(PARAM_SEPARATOR);
+    if (separator < 0) throw new Error(`paramCorrectionProvenance: malformed key ${key}`);
+    const element = key.slice(0, separator);
+    const slot = key.slice(separator + PARAM_SEPARATOR.length);
+    const namespace = element.slice(0, element.lastIndexOf("."));
+    const pinned = baseTokens(correction.upstream);
+
+    const neededByTarget = new Map<string, boolean>();
+    for (const surface of surfaces) {
+      if (surface.namespace !== namespace) continue;
+      for (const fn of parse(surface).functions) {
+        if (fn.name !== element) continue;
+        for (const parameter of fn.parameters) {
+          if (parameter.name !== slot) continue;
+          const needed = neededByTarget.get(surface.target) ?? false;
+          neededByTarget.set(surface.target, needed || baseTokens(parameter.types) === pinned);
+        }
+      }
+    }
+
+    const sightedIn = [...neededByTarget.keys()].sort();
+    return {
+      key,
+      sightedIn,
+      neededBy: sightedIn.filter((target) => neededByTarget.get(target) === true),
+      resolvedIn: sightedIn.filter((target) => neededByTarget.get(target) === false),
+    };
+  });
+}

package/src/render-overloads.d.ts

@@ -25,5 +25,20 @@ declare global {
       name: string,
       parameters: Record<string | number, unknown>,
     ): Opaque<"render_target">;
+    /**
+     * The rendering context was lost. Rendering is paused and all graphics
+     * resources become invalid. Passed to the `render.set_listener` callback.
+     */
+    const CONTEXT_EVENT_CONTEXT_LOST: number & {
+      readonly __brand: "render.CONTEXT_EVENT_CONTEXT_LOST";
+    };
+    /**
+     * The rendering context was restored. Rendering is still paused and graphics
+     * resources are still invalid, but can be reloaded. Passed to the
+     * `render.set_listener` callback.
+     */
+    const CONTEXT_EVENT_CONTEXT_RESTORED: number & {
+      readonly __brand: "render.CONTEXT_EVENT_CONTEXT_RESTORED";
+    };
   }
 }

package/src/script-api.ts

@@ -49,8 +49,10 @@ function stringOr(value: unknown, fallback: string): string {
 
 // A `.script_api` `type:` may spell a union inline (`string | nil`), where the
 // core ref-doc format carries one token per alternative. Splitting here keeps the
-// downstream emitter and fidelity resolver working in single tokens.
+// downstream emitter and fidelity resolver working in single tokens. A `type:`
+// may also be a YAML list (`[table, string]`), one alternative per entry.
 function splitTypeTokens(type: unknown): string[] {
+  if (Array.isArray(type)) return type.flatMap(splitTypeTokens);
   if (typeof type !== "string") return [];
   return type
     .split("|")