@defold-typescript/types 0.5.4 → 0.6.0

package/src/emit-dts.ts

@@ -13,6 +13,8 @@ import {
   htmlToDocText,
   renderDocComment,
 } from "./doc-comment";
+import type { TranslationStore } from "./example-store";
+import { hashExampleSource, lookupTranslation } from "./example-store";
 
 export interface EmitOptions {
   mapType?: (defoldType: string) => string;
@@ -21,6 +23,12 @@ export interface EmitOptions {
   // brands to the same FQN-keyed type its owning module's `const` emits,
   // instead of widening to `unknown`.
   knownConstantFqns?: ReadonlySet<string>;
+  // Hand-authored TypeScript `@example` translations keyed by element FQN.
+  // Defaults to an empty store (every example stays on its Lua fallback,
+  // byte-identical output); the build layer (`regen`) passes the loaded
+  // `examples/translations.json`. Loading lives in `scripts/example-store-io.ts`
+  // so this module stays node-free for downstream consumers.
+  translations?: TranslationStore;
 }
 
 export const TS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
@@ -74,8 +82,11 @@ export const TS_RESERVED_NAMES = new Set([
   "extends",
 ]);
 
-// Element names whose `table` slot is a genuinely-arbitrary lua table by design
-// — the serialization/JSON passthrough functions. Their emitted
+// Element names whose `table` slot is a genuinely-arbitrary lua table by design.
+// Two kinds: the serialization/JSON passthrough functions (Defold-internal — the
+// engine round-trips an arbitrary lua value), and the platform/OS-sourced opaque
+// blobs (external — the shape is set by the host OS or invoking app, not by
+// Defold, so there is no documented field list). Their emitted
 // `Record<string | number, unknown>` is the faithful "any lua table" type, not a
 // `recordTables` fidelity loss, so the audit consults this set to avoid counting
 // them. A new ref-doc function with an opaque table must be added here
@@ -87,6 +98,9 @@ export const ARBITRARY_TABLE_SLOTS = new Set([
   "sys.load",
   "sys.serialize",
   "sys.deserialize",
+  "iac.set_listener",
+  "push.get_scheduled",
+  "push.get_all_scheduled",
 ]);
 
 // Element names whose `table` slot is a prose-only `a table mapping X to Y`
@@ -123,6 +137,157 @@ export const HOMOGENEOUS_ARRAY_SLOTS: ReadonlyMap<string, string | readonly stri
   ["sound.get_groups", "hash"],
   ["iap.list", "string"],
   ["go.delete", ["string", "hash", "url"]],
+  // push.register's `notifications` is a prose-only array of push.NOTIFICATION_*
+  // bitmask constants (the ref example sums NOTIFICATION_BADGE/SOUND/ALERT). The
+  // vendored push_doc.json fixture declares no NOTIFICATION_* constant elements, so
+  // no brand exists to reference; `number` is the faithful element token for these
+  // numeric constants, mirroring the vmath.vector/buffer.* number entries.
+  ["push.register", "number"],
+]);
+
+// A `mapping` curation whose value is itself a single-level mapping, emitted
+// `LuaMap<Kouter, LuaMap<Kinner, Vinner>>` — the nested-row-map shape
+// (`tilemap.get_tiles` → `tiles[row][col]`).
+export type NestedMapping = { key: string; value: string };
+
+export type TableSlotCuration =
+  | { kind: "mapping"; key: string; value: string | readonly TableField[] | NestedMapping }
+  | { kind: "array"; element: string | readonly string[] }
+  | { kind: "object"; fields: readonly TableField[] }
+  | { kind: "array-object"; fields: readonly TableField[] };
+
+const SOCKET_HANDLE_TOKENS = ["client", "master", "unconnected"] as const;
+
+export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new Map([
+  ["collectionfactory.create:return:ids", { kind: "mapping", key: "hash", value: "hash" }],
+  // iap.finish and iap.acknowledge take the same Defold IAP transaction object —
+  // the table handed to the iap.set_listener callback. The ref-doc fixture
+  // describes it in prose only (no field list), so the shape is curated from the
+  // Defold iap reference. As a param-side object curation every field emits `?`,
+  // which is faithful: original_trans/signature/user_id are platform-specific.
+  [
+    "iap.finish:param:transaction",
+    {
+      kind: "object",
+      fields: [
+        { name: "ident", types: ["string"] },
+        { name: "state", types: ["number"] },
+        { name: "trans_ident", types: ["string"] },
+        { name: "date", types: ["string"] },
+        { name: "original_trans", types: ["string"] },
+        { name: "receipt", types: ["string"] },
+        { name: "signature", types: ["string"] },
+        { name: "user_id", types: ["string"] },
+      ],
+    },
+  ],
+  [
+    "iap.acknowledge:param:transaction",
+    {
+      kind: "object",
+      fields: [
+        { name: "ident", types: ["string"] },
+        { name: "state", types: ["number"] },
+        { name: "trans_ident", types: ["string"] },
+        { name: "date", types: ["string"] },
+        { name: "original_trans", types: ["string"] },
+        { name: "receipt", types: ["string"] },
+        { name: "signature", types: ["string"] },
+        { name: "user_id", types: ["string"] },
+      ],
+    },
+  ],
+  // iap.buy's `options` is documented in the fixture as prose only ("optional
+  // parameters as properties"), so the field set is curated from the Defold iap
+  // reference: a Facebook-only custom `request_id` and a Google-Play-only
+  // subscription-offer `token`. Both are platform-specific, hence param-side
+  // optional fields.
+  [
+    "iap.buy:param:options",
+    {
+      kind: "object",
+      fields: [
+        { name: "request_id", types: ["string"] },
+        { name: "token", types: ["string"] },
+      ],
+    },
+  ],
+  [
+    "liveupdate.get_mounts:return:mounts",
+    {
+      kind: "array-object",
+      fields: [
+        { name: "name", types: ["string"] },
+        { name: "uri", types: ["string"] },
+        { name: "priority", types: ["number"] },
+      ],
+    },
+  ],
+  [
+    "model.get_aabb:return:aabb",
+    {
+      kind: "object",
+      fields: [
+        { name: "min", types: ["vector3"] },
+        { name: "max", types: ["vector3"] },
+      ],
+    },
+  ],
+  [
+    "model.get_mesh_aabb:return:aabb",
+    {
+      kind: "mapping",
+      key: "hash",
+      value: [
+        { name: "min", types: ["vector3"] },
+        { name: "max", types: ["vector3"] },
+      ],
+    },
+  ],
+  ["physics.raycast:param:groups", { kind: "array", element: "hash" }],
+  ["physics.raycast_async:param:groups", { kind: "array", element: "hash" }],
+  // push.schedule's `notification_settings` is documented in the fixture as prose
+  // only ("Table with notification and platform specific fields"), so the field
+  // set is curated from the Defold push reference: an iOS `action`, an iOS
+  // `badge_count`, and an Android `priority`. Each is platform-specific, hence
+  // param-side optional fields.
+  [
+    "push.schedule:param:notification_settings",
+    {
+      kind: "object",
+      fields: [
+        { name: "action", types: ["string"] },
+        { name: "badge_count", types: ["number"] },
+        { name: "priority", types: ["number"] },
+      ],
+    },
+  ],
+  ["socket.select:param:recvt", { kind: "array", element: SOCKET_HANDLE_TOKENS }],
+  ["socket.select:param:sendt", { kind: "array", element: SOCKET_HANDLE_TOKENS }],
+  ["socket.select:return:sockets_r", { kind: "array", element: SOCKET_HANDLE_TOKENS }],
+  ["socket.select:return:sockets_w", { kind: "array", element: SOCKET_HANDLE_TOKENS }],
+  [
+    "tilemap.get_tile_info:return:tile_info",
+    {
+      kind: "object",
+      fields: [
+        { name: "index", types: ["number"] },
+        { name: "h_flip", types: ["boolean"] },
+        { name: "v_flip", types: ["boolean"] },
+        { name: "rotate_90", types: ["boolean"] },
+      ],
+    },
+  ],
+  // tilemap.get_tiles returns a sparse table of rows iterated `tiles[row][col]`,
+  // the keys being tile positions offset by tilemap.get_bounds() (not a dense
+  // 0..n run). The faithful shape is the nested LuaMap idiom
+  // `LuaMap<number, LuaMap<number, number>>` — the keys are plain `number` tile
+  // positions, not a branded `Hash`, and a non-string-keyed Lua table is `LuaMap`,
+  // never a `Record` (which would imply a dense index object).
+  [
+    "tilemap.get_tiles:return:tiles",
+    { kind: "mapping", key: "number", value: { key: "number", value: "number" } },
+  ],
 ]);
 
 /**
@@ -427,6 +592,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
 
   const constantFqns = new Set(module.constants.map((c) => c.name));
   const knownConstantFqns = options?.knownConstantFqns;
+  const translations = options?.translations ?? {};
   const baseMapType = options?.mapType ?? defaultMapType;
   const mapType = (token: string): string =>
     constantFqns.has(token) || knownConstantFqns?.has(token)
@@ -473,6 +639,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
   const decl = hasAliases ? "export " : "";
 
   const lines: string[] = [];
+  for (const docLine of namespaceDocLines(module)) lines.push(docLine);
   lines.push(`declare namespace ${module.namespace} {`);
 
   for (const t of typedefs) {
@@ -502,7 +669,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
   for (const fn of functions) {
     const reserved = TS_RESERVED_NAMES.has(fn.name);
     const emitName = aliasName(fn.name, aliases);
-    for (const docLine of functionDocLines(fn.original)) lines.push(docLine);
+    for (const docLine of functionDocLines(fn.original, translations)) lines.push(docLine);
     const line = emitFunction(fn, emitName, mapType, resolver);
     lines.push(`${INDENT}${reserved ? "" : decl}${line}`);
   }
@@ -614,18 +781,23 @@ function emitFunction(
 // fallback applies to non-identifier names, matching `emitParameter`) so the tag
 // resolves on hover; a single documented return becomes `@returns`. Returns `[]`
 // for a fully-undocumented function, leaving its emission byte-identical.
-function functionDocLines(fn: ApiFunction): string[] {
+function functionDocLines(fn: ApiFunction, translations: TranslationStore): string[] {
   const params = fn.parameters.map((p, index) => ({
     name: TS_IDENTIFIER.test(p.name) ? p.name : `arg${index}`,
     doc: htmlToDocText(p.doc),
   }));
   const onlyReturn = fn.returnValues.length === 1 ? fn.returnValues[0] : undefined;
-  const example = htmlToCodeText(fn.examples ?? "");
+  const lua = htmlToCodeText(fn.examples ?? "");
+  // A hand-authored TS translation pinned to this exact Lua flips the fence to
+  // ```ts; any hash mismatch (or absent translation) keeps the Lua fallback.
+  const ts = lua === "" ? null : lookupTranslation(translations, fn.name, hashExampleSource(lua));
+  const exampleParts: Pick<DocCommentParts, "example" | "exampleLang"> =
+    ts !== null ? { example: ts, exampleLang: "ts" } : lua !== "" ? { example: lua } : {};
   const parts: DocCommentParts = {
     summary: htmlToDocText(summaryFor(fn.brief, fn.description)),
     params,
     ...(onlyReturn ? { returns: htmlToDocText(onlyReturn.doc) } : {}),
-    ...(example !== "" ? { example } : {}),
+    ...exampleParts,
   };
   return indentDocLines(parts, INDENT);
 }
@@ -639,6 +811,15 @@ function summaryDocLines(brief: string, description: string, indent: string): st
   return indentDocLines({ summary: htmlToDocText(summaryFor(brief, description)) }, indent);
 }
 
+function namespaceDocLines(module: ApiModule): string[] {
+  const official = summaryFor(module.brief, module.description).trim();
+  const summary =
+    official.length > 0
+      ? htmlToDocText(official)
+      : `(synthesized)\nDefold \`${module.namespace}\` API namespace.`;
+  return indentDocLines({ summary }, "");
+}
+
 function indentDocLines(parts: DocCommentParts, indent: string): string[] {
   return renderDocComment(parts).map((line) => `${indent}${line}`);
 }
@@ -646,7 +827,7 @@ function indentDocLines(parts: DocCommentParts, indent: string): string[] {
 // Prefer the full `description`; fall back to the one-line `brief` when prose is
 // absent. Shared by every documented member kind so the summary source is
 // consistent across functions, constants, variables, and properties.
-function summaryFor(brief: string, description: string): string {
+export function summaryFor(brief: string, description: string): string {
   return description.trim() !== "" ? description : brief;
 }
 
@@ -676,7 +857,7 @@ function emitParameter(
   const concrete = p.types.filter((t) => t !== "nil");
   const ts =
     concrete.length > 0
-      ? mapSlotUnion(concrete, p.doc, mapType, true, resolver, elementName)
+      ? mapSlotUnion(concrete, p.doc, mapType, true, resolver, elementName, "param", p.name)
       : "unknown";
   return `${name}${optional ? "?" : ""}: ${ts}`;
 }
@@ -694,7 +875,7 @@ function emitReturn(
     // typescript-to-lua erases to `local a, b = fn()`.
     const slots = returnValues.map((rv) =>
       rv.types.length > 0
-        ? mapSlotUnion(rv.types, rv.doc, mapType, false, resolver, elementName)
+        ? mapSlotUnion(rv.types, rv.doc, mapType, false, resolver, elementName, "return", rv.name)
         : "unknown",
     );
     return { type: `LuaMultiReturn<[${slots.join(", ")}]>`, trailing: "" };
@@ -703,7 +884,16 @@ function emitReturn(
   if (!first) return { type: "void", trailing: "" };
   const ts =
     first.types.length > 0
-      ? mapSlotUnion(first.types, first.doc, mapType, false, resolver, elementName)
+      ? mapSlotUnion(
+          first.types,
+          first.doc,
+          mapType,
+          false,
+          resolver,
+          elementName,
+          "return",
+          first.name,
+        )
       : "unknown";
   return { type: ts, trailing: "" };
 }
@@ -728,22 +918,38 @@ function mapSlotUnion(
   optionalFields: boolean,
   resolver: TableDocResolver,
   elementName: string,
+  slotKind?: "param" | "return",
+  slotName?: string,
 ): string {
   const mapped: string[] = [];
   const seen = new Set<string>();
   for (const token of types) {
     let ts: string;
     if (token === "table") {
-      const mapping = MAPPING_TABLE_SLOTS.get(elementName);
-      const element = HOMOGENEOUS_ARRAY_SLOTS.get(elementName);
+      const curation =
+        slotKind !== undefined && slotName !== undefined
+          ? TABLE_SLOT_CURATIONS.get(tableSlotKey(elementName, slotKind, slotName))
+          : undefined;
+      const mapping =
+        curation?.kind === "mapping" ? curation : MAPPING_TABLE_SLOTS.get(elementName);
+      const element =
+        curation?.kind === "array" ? curation.element : HOMOGENEOUS_ARRAY_SLOTS.get(elementName);
       if (mapping !== undefined) {
-        ts = `LuaMap<${mapType(mapping.key)}, ${mapType(mapping.value)}>`;
+        let value: string;
+        if (typeof mapping.value === "string") {
+          value = mapType(mapping.value);
+        } else if (Array.isArray(mapping.value)) {
+          value = inlineTableType(mapping.value, mapType, optionalFields);
+        } else {
+          const nested = mapping.value as NestedMapping;
+          value = `LuaMap<${mapType(nested.key)}, ${mapType(nested.value)}>`;
+        }
+        ts = `LuaMap<${mapType(mapping.key)}, ${value}>`;
       } else if (element !== undefined) {
-        const tokens = typeof element === "string" ? [element] : element;
-        ts =
-          tokens.length > 1
-            ? `(${unionFromTokens(tokens, mapType)})[]`
-            : `${mapType(tokens[0] as string)}[]`;
+        ts = arrayTypeFromTokens(element, mapType);
+      } else if (curation?.kind === "object" || curation?.kind === "array-object") {
+        const object = inlineTableType(curation.fields, mapType, optionalFields);
+        ts = curation.kind === "array-object" ? `${object}[]` : object;
       } else {
         const fields = parseTableFields(doc, resolver);
         if (fields !== null) {
@@ -763,6 +969,20 @@ function mapSlotUnion(
   return mapped.join(" | ");
 }
 
+function tableSlotKey(elementName: string, slotKind: "param" | "return", slotName: string): string {
+  return `${elementName}:${slotKind}:${slotName}`;
+}
+
+function arrayTypeFromTokens(
+  element: string | readonly string[],
+  mapType: (t: string) => string,
+): string {
+  const tokens = typeof element === "string" ? [element] : element;
+  return tokens.length > 1
+    ? `(${unionFromTokens(tokens, mapType)})[]`
+    : `${mapType(tokens[0] as string)}[]`;
+}
+
 export function inlineTableType(
   fields: readonly TableField[],
   mapType: (t: string) => string,

package/src/engine-globals.d.ts

@@ -1,7 +1,9 @@
+/** @noSelfInFile */
 import type * as Core from "./core-types";
 
 declare global {
   type Hash = Core.Hash;
+  function hash(s: string): Core.Hash;
   type Opaque<Name extends string> = Core.Opaque<Name>;
   type Url = Core.Url;
   type Vector = Core.Vector;

package/src/example-store.ts

@@ -0,0 +1,44 @@
+// A hand-authored TypeScript translation of one element's ref-doc `@example`,
+// pinned by a hash of the exact source Lua it replaces. A ref-doc re-pin that
+// changes the source Lua flips the hash, so a stale translation stops matching
+// (drift guard) and the emit falls back to the Lua body.
+export interface Translation {
+  sourceHash: string;
+  ts: string;
+}
+
+export type TranslationStore = Record<string, Translation>;
+
+const FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const U64_MASK = 0xffffffffffffffffn;
+
+// A pure, dependency-free FNV-1a 64-bit hash over the source's UTF-16 code
+// units, returned as zero-padded hex. Deliberately node- and Bun-free: this
+// module is reachable from `index.ts` (via `emit-dts`), so a `node:crypto` or
+// ambient-`Bun` reference here would fail type-checking in every downstream
+// consumer that compiles the shipped `src/` graph.
+//
+// The input is the already-normalized post-`htmlToCodeText` string (per-line
+// trailing whitespace and surrounding blank lines stripped), so the hash is
+// independent of trailing whitespace in the original ref-doc HTML.
+export function hashExampleSource(source: string): string {
+  let hash = FNV_OFFSET_BASIS;
+  for (let i = 0; i < source.length; i++) {
+    hash = ((hash ^ BigInt(source.charCodeAt(i))) * FNV_PRIME) & U64_MASK;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+
+// Return the stored TypeScript body only when the FQN exists and its pinned
+// `sourceHash` matches the source we are about to emit; any mismatch returns
+// `null` so the caller keeps the Lua fallback.
+export function lookupTranslation(
+  store: TranslationStore,
+  fqn: string,
+  sourceHash: string,
+): string | null {
+  const entry = store[fqn];
+  if (!entry || entry.sourceHash !== sourceHash) return null;
+  return entry.ts;
+}

package/src/go-overloads.d.ts

@@ -1,6 +1,11 @@
 /** @noSelfInFile */
+
 import type { Hash, Opaque, Quaternion, Url, Vector3, Vector4 } from "./core-types";
 
+interface ScriptProperty<TValue> {
+  readonly __defoldScriptProperty: TValue;
+}
+
 declare global {
   namespace go {
     interface GoPropertyOptions {
@@ -9,6 +14,21 @@ declare global {
       keys?: Record<string | number, unknown>;
     }
 
+    /**
+     * gets a named property of the specified game object or component
+     *
+     * @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)
+     * @returns the value of the specified property
+     * @example
+     * ```ts
+     * const position = go.get("#sprite", "position");
+     * ```
+     */
     function get<K extends keyof go.properties>(
       url: string | Hash | Url,
       property: K,
@@ -19,6 +39,21 @@ declare global {
       property: string | Hash,
       options?: GoPropertyOptions,
     ): number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource">;
+    /**
+     * sets a named property of the specified game object or component, or a material constant
+     *
+     * @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 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)
+     * @example
+     * ```ts
+     * go.set("#sprite", "tint", vmath.vector4(1, 0, 0, 1));
+     * ```
+     */
     function set<K extends keyof go.properties>(
       url: string | Hash | Url,
       property: K,
@@ -31,5 +66,43 @@ declare global {
       value: number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource">,
       options?: GoPropertyOptions,
     ): void;
+    /**
+     * Registers a Defold editor script property (deprecated escape hatch).
+     *
+     * @deprecated Don't call `go.property` yourself. Declare the property in
+     * `defineScript({ properties })` — that is the only form that types it onto
+     * `self`; the transpiler emits the `go.property(...)` registration for you.
+     * A direct call still registers, but `self.<name>` stays untyped.
+     *
+     * @param name - editor property id to register.
+     * @param value - default value for the registered property.
+     * @returns a phantom descriptor used only for TypeScript self typing.
+     * @example
+     * ```ts
+     * // Declare it as a field — the key is the name, the value is the default:
+     * export default defineScript({
+     *   properties: { speed: 450 },
+     *   update(self) {
+     *     self.speed; // number
+     *   },
+     * });
+     * // The transpiler emits, at chunk scope:  go.property("speed", 450)
+     * ```
+     */
+    function property(name: string, value: number): ScriptProperty<number>;
+    /** @deprecated Declare booleans via the `defineScript({ properties })` field. */
+    function property(name: string, value: boolean): ScriptProperty<boolean>;
+    /** @deprecated Declare hashes via the `defineScript({ properties })` field. */
+    function property(name: string, value: Hash): ScriptProperty<Hash>;
+    /** @deprecated Declare URLs via the `defineScript({ properties })` field. */
+    function property(name: string, value: Url): ScriptProperty<Url>;
+    /** @deprecated Declare vector3s via the `defineScript({ properties })` field. */
+    function property(name: string, value: Vector3): ScriptProperty<Vector3>;
+    /** @deprecated Declare vector4s via the `defineScript({ properties })` field. */
+    function property(name: string, value: Vector4): ScriptProperty<Vector4>;
+    /** @deprecated Declare quaternions via the `defineScript({ properties })` field. */
+    function property(name: string, value: Quaternion): ScriptProperty<Quaternion>;
+    /** @deprecated Declare resources via the `defineScript({ properties })` field. */
+    function property(name: string, value: Opaque<"resource">): ScriptProperty<Opaque<"resource">>;
   }
 }

package/src/index.ts

@@ -17,11 +17,16 @@ export {
   defineRenderScript,
   defineScript,
   type GuiScriptHooks,
+  type GuiScriptHooksWithProperties,
   type InputAction,
   type InputTouch,
   type RenderScriptHooks,
+  type RenderScriptHooksWithProperties,
   SCRIPT_HOOK_NAMES,
   type ScriptHookName,
   type ScriptHooks,
+  type ScriptHooksWithProperties,
+  type ScriptProperties,
+  type ScriptProperty,
 } from "./lifecycle";
 export { type WrapOptions, wrapAsAmbientGlobal } from "./publish-dts";