@defold-typescript/types 0.38.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/example-store.ts

@@ -51,3 +51,29 @@ export function lookupTranslation(
   const match = entries.find((entry) => entry.sourceHash === sourceHash);
   return match ? match.ts : null;
 }
+
+/**
+ * The stored bodies for a blob's segment hashes, in the order given, or `null`
+ * the moment one of them does not resolve.
+ *
+ * All-or-nothing on purpose: an element whose blob carries several examples is
+ * emitted as several `@example` blocks only when every one of them has an
+ * authored body. A partial resolve would document some of the element's
+ * examples and silently drop the rest, so the caller falls back to the
+ * whole-blob body instead. An empty hash list is a miss for the same reason —
+ * it would otherwise report success while documenting nothing.
+ */
+export function lookupExampleTranslations(
+  store: TranslationStore,
+  fqn: string,
+  sourceHashes: readonly string[],
+): string[] | null {
+  if (sourceHashes.length === 0) return null;
+  const bodies: string[] = [];
+  for (const sourceHash of sourceHashes) {
+    const ts = lookupTranslation(store, fqn, sourceHash);
+    if (ts === null) return null;
+    bodies.push(ts);
+  }
+  return bodies;
+}

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

@@ -35,10 +35,14 @@ export {
 } from "./core-types";
 export {
   type DocCommentParts,
+  type ExampleSegment,
+  type ExampleSegmentation,
   examplesHtmlToMarkdown,
   htmlToCodeText,
   htmlToDocText,
   renderDocComment,
+  segmentExampleRegions,
+  splitExampleSources,
 } from "./doc-comment";
 export {
   defineEditorScript,
@@ -49,6 +53,10 @@ export {
   type EmitOptions,
   emitDeclarations,
   emitSymbolSignatures,
+  firstSlotAlternativeOf,
+  PARAM_DOC_REWRITES,
+  type ParamDocRewrite,
+  rewriteParamDoc,
   type SlotTypes,
   type SymbolSignature,
   TS_IDENTIFIER,
@@ -56,6 +64,7 @@ export {
 } from "./emit-dts";
 export {
   hashExampleSource,
+  lookupExampleTranslations,
   lookupTranslation,
   type Translation,
   type TranslationStore,

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

@@ -4,23 +4,6 @@ import type { Opaque } from "./core-types";
 
 declare global {
   namespace render {
-    /**
-     * The buffer keys `render.clear` accepts: the three `graphics.BUFFER_TYPE_*`
-     * constants the reference names. Declare the clear table with this alias —
-     * `LuaMap`'s iterator makes its key parameter invariant, so a
-     * `LuaMap<number, ...>` is not assignable however its entries were set.
-     *
-     * @example
-     * ```ts
-     * const buffers = new LuaMap<render.ClearBufferKey, number | Vector4>();
-     * buffers.set(graphics.BUFFER_TYPE_COLOR0_BIT, vmath.vector4(0, 0, 0, 0));
-     * render.clear(buffers);
-     * ```
-     */
-    type ClearBufferKey =
-      | typeof graphics.BUFFER_TYPE_COLOR0_BIT
-      | typeof graphics.BUFFER_TYPE_DEPTH_BIT
-      | typeof graphics.BUFFER_TYPE_STENCIL_BIT;
     /**
      * Creates a new render target according to the supplied specification table.
      * The parameter table is keyed by buffer type, with one parameter table per
@@ -42,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("|")