@defold-typescript/types 0.23.0 → 0.25.0

package/src/scene-addresses.d.ts

@@ -0,0 +1,62 @@
+declare global {
+  /**
+   * Game-object addresses found in the project's scenes — `"/player"`,
+   * `"/level/enemy"`, and every other runtime path a `.collection` composes.
+   *
+   * @remarks
+   * The interface ships **empty** and is open: a generator augments it with one
+   * key per address it discovered, and editors then offer those keys as
+   * completions on every slot typed {@link SceneGameObjectAddress}. With no
+   * generator run the interface stays empty, which is exactly today's
+   * behavior — the alias is always widened, so nothing is ever rejected.
+   *
+   * @example
+   * ```ts
+   * declare global {
+   *   interface SceneGameObjectAddresses {
+   *     "/player": true;
+   *   }
+   * }
+   * ```
+   */
+  interface SceneGameObjectAddresses {}
+
+  /**
+   * Component addresses found in the project's scenes — `"#sprite"`,
+   * `"/player#collisionobject"`, and every other component a game object owns.
+   *
+   * @remarks
+   * Open and empty by default, exactly like {@link SceneGameObjectAddresses};
+   * a generator fills it and {@link SceneComponentAddress} reads it. Kept
+   * separate from the game-object interface so a slot that can only address a
+   * component never suggests a bare game-object path.
+   */
+  interface SceneComponentAddresses {}
+
+  /**
+   * A game-object address: the scene-derived ids as completions, plus every
+   * other string.
+   *
+   * @remarks
+   * The trailing `(string & {})` term is load-bearing. It keeps the alias
+   * assignable from — and to — an arbitrary `string`, so an address computed at
+   * runtime type-checks unchanged while the literal keys still surface as
+   * suggestions. A scene-derived type must never turn into a compile error.
+   */
+  type SceneGameObjectAddress = (keyof SceneGameObjectAddresses & string) | (string & {});
+
+  /**
+   * A component address: the scene-derived ids as completions, plus every other
+   * string. Never rejects, for the same reason as
+   * {@link SceneGameObjectAddress}.
+   */
+  type SceneComponentAddress = (keyof SceneComponentAddresses & string) | (string & {});
+
+  /**
+   * Either kind of address, for a slot that accepts a game object *or* one of
+   * its components — `msg.post`'s receiver, `go.get`'s url. Never rejects.
+   */
+  type SceneAddress = SceneGameObjectAddress | SceneComponentAddress;
+}
+
+export {};

package/src/script-api.ts

@@ -27,6 +27,17 @@ function stringOr(value: unknown, fallback: string): string {
   return typeof value === "string" ? value : fallback;
 }
 
+// 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.
+function splitTypeTokens(type: unknown): string[] {
+  if (typeof type !== "string") return [];
+  return type
+    .split("|")
+    .map((token) => token.trim())
+    .filter((token) => token.length > 0);
+}
+
 function mapParameters(raw: unknown): RefDocParameter[] {
   if (!Array.isArray(raw)) return [];
   const out: RefDocParameter[] = [];
@@ -36,11 +47,10 @@ function mapParameters(raw: unknown): RefDocParameter[] {
     // The script_api lists the implicit `self` the engine passes; the emitter
     // stamps @noSelfInFile, so generated signatures must not declare it.
     if (name === "self") continue;
-    const type = item.type;
     out.push({
       name,
       doc: stringOr(item.desc, ""),
-      types: typeof type === "string" ? [type] : [],
+      types: splitTypeTokens(item.type),
     });
   }
   return out;

package/src/url-parameters.ts

@@ -0,0 +1,174 @@
+import type { ApiModule } from "./api-doc";
+
+// How a parameter names something the project declares. `none` is the default
+// and the only non-affirmative value: a type shape is necessary but not
+// sufficient (`model.get_mesh_enabled#mesh_id` carries the address triple while
+// naming a mesh inside the model asset), so a slot is classified only
+// deliberately. The first three address the scene graph; `gui-node` names a node
+// inside the one `.gui` that owns the script, which is not an address at all;
+// `animation` names a block inside the atlas of a component a *sibling*
+// argument addresses, which is why it is the one class needing a companion;
+// `resource-path` names a project file outright, so it is scoped by the
+// extensions its entry declares rather than by anything in the scene graph;
+// `config-key` names a `<section>.<key>` entry in the project's own
+// `game.project`, so its universe is one file the project declares rather than
+// anything in the scene graph or on disk beside it; `action-id` names an action
+// the project's `.input_binding` files declare, and is the one class whose slot
+// is a parameter of a prefixless global rather than of a Defold module function
+// — `hash("jump")` — so it is scoped by the comparison the call sits in rather
+// than by a sibling argument.
+export type UrlParameterClass =
+  | "none"
+  | "game-object"
+  | "component"
+  | "either"
+  | "gui-node"
+  | "animation"
+  | "resource-path"
+  | "config-key"
+  | "action-id";
+
+export interface UrlParameterEntry {
+  fqn: string;
+  parameter: string;
+  class: UrlParameterClass;
+  // The parameter of the *same* function whose literal names the component the
+  // candidates are scoped to. Required for `animation` and absent otherwise —
+  // enforced by the drift guard rather than the type, because a per-class entry
+  // shape would fan the table's one interface out into a union for a single
+  // optional field.
+  addressParameter?: string;
+  // The file extensions this slot's literal may name, each written with its
+  // leading dot. Required for `resource-path` and absent otherwise — enforced by
+  // the drift guard for the same reason `addressParameter` is. Recorded per
+  // entry rather than per class because the six constructors sharing the class
+  // each accept a different one.
+  resourceExtensions?: readonly string[];
+  // The parameter this slot's *call* must be compared against for the class to
+  // apply — `action_id` for `hash("…")`, whose bare global would otherwise match
+  // every hashed name a project writes. Required for `action-id` and absent
+  // otherwise, enforced by the drift guard for the same reason `addressParameter`
+  // is. Unlike `addressParameter` this names a parameter of the surrounding
+  // *hook*, not of the classified function.
+  comparedParameter?: string;
+  // `"generated"` for a slot the emitter derives from the ref-doc, otherwise a
+  // package-relative path to the hand-authored `.d.ts` that declares it,
+  // resolved against the `packages/types` package root. Not repo-relative: the
+  // table ships inside `@defold-typescript/types`, so a published consumer has
+  // no repo root to resolve a `packages/types/` prefix against.
+  source: string;
+  // A verbatim phrase from the ref-doc `doc` the classification was judged from;
+  // required whenever `source` is `"generated"`, absent for hand-authored slots
+  // that have no ref-doc prose to pin against.
+  evidence?: string;
+}
+
+export type UrlParameterTable = UrlParameterEntry[];
+
+export interface UrlParameterSource {
+  module: ApiModule;
+  skipFunctions?: readonly string[];
+}
+
+export interface UrlParameterSlot {
+  fqn: string;
+  parameter: string;
+  module: string;
+  doc: string;
+  types: readonly string[];
+  // The declaring function's ref-doc examples, verbatim. The parameter prose
+  // alone cannot refute a `resource-path` extension — every one of the six reads
+  // "optional resource path string to the resource" — so the example is the only
+  // place the claim is checkable.
+  examples: string;
+}
+
+const ADDRESS_TYPES = ["string", "hash", "url"] as const;
+
+// The type shape a class needs its slot to carry. A classification is a judgment
+// about prose, but it is still refutable by the signature: nothing that cannot
+// hold a `url` can be an address, and nothing that cannot hold a `string` can
+// name a node.
+export const REQUIRED_TYPES: Record<Exclude<UrlParameterClass, "none">, readonly string[]> = {
+  "game-object": ADDRESS_TYPES,
+  component: ADDRESS_TYPES,
+  either: ADDRESS_TYPES,
+  "gui-node": ["string", "hash"],
+  animation: ["string", "hash"],
+  "resource-path": ["string"],
+  "config-key": ["string"],
+  "action-id": ["string"],
+};
+
+function bareName(fqn: string): string {
+  const lastDot = fqn.lastIndexOf(".");
+  return lastDot === -1 ? fqn : fqn.slice(lastDot + 1);
+}
+
+function carriesAll(types: readonly string[], required: readonly string[]): boolean {
+  const lowered = new Set(types.map((token) => token.toLowerCase()));
+  return required.every((token) => lowered.has(token));
+}
+
+function carriesAddressTriple(types: readonly string[]): boolean {
+  return carriesAll(types, ADDRESS_TYPES);
+}
+
+// Whether a slot declaring `types` could carry `parameterClass`. A superset is
+// fine — the shape is a floor, not an equality — and `none` is always satisfied
+// because it asserts nothing.
+export function parameterTypesSatisfyClass(
+  types: readonly string[],
+  parameterClass: UrlParameterClass,
+): boolean {
+  if (parameterClass === "none") return true;
+  return carriesAll(types, REQUIRED_TYPES[parameterClass]);
+}
+
+// The generated surface's whole parameter universe. Functions named in a
+// module's `skipFunctions` contribute nothing: the emitter suppresses them in
+// favour of hand-authored overloads, so counting them here would conflate the
+// two surfaces.
+export function collectParameterSlots(sources: readonly UrlParameterSource[]): UrlParameterSlot[] {
+  const slots: UrlParameterSlot[] = [];
+  for (const { module, skipFunctions } of sources) {
+    const skipped = new Set(skipFunctions ?? []);
+    for (const fn of module.functions) {
+      if (skipped.has(bareName(fn.name))) continue;
+      for (const parameter of fn.parameters) {
+        slots.push({
+          fqn: fn.name,
+          parameter: parameter.name,
+          module: module.namespace,
+          doc: parameter.doc,
+          types: parameter.types,
+          examples: fn.examples ?? "",
+        });
+      }
+    }
+  }
+  return slots;
+}
+
+// The address-triple subset of the above — the universe a classification survey
+// of `msg.post`-shaped slots walks.
+export function collectUrlParameterSlots(
+  sources: readonly UrlParameterSource[],
+): UrlParameterSlot[] {
+  return collectParameterSlots(sources).filter((slot) => carriesAddressTriple(slot.types));
+}
+
+// Pure lookup, dependency-free like `signature-store.ts`: this module is
+// reachable from `index.ts`, so a `node:fs`/ambient-`Bun` reference here would
+// fail type-checking in every downstream consumer that compiles the shipped
+// `src/` graph.
+export function classifyUrlParameter(
+  table: UrlParameterTable,
+  fqn: string,
+  parameter: string,
+): UrlParameterClass {
+  for (const entry of table) {
+    if (entry.fqn === fqn && entry.parameter === parameter) return entry.class;
+  }
+  return "none";
+}

package/url-parameters.json

@@ -0,0 +1,285 @@
+[
+  {
+    "fqn": "go.get_position",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to get the position for"
+  },
+  {
+    "fqn": "go.get_rotation",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to get the rotation for"
+  },
+  {
+    "fqn": "go.get_scale",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to get the scale for"
+  },
+  {
+    "fqn": "go.get_scale_uniform",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to get the uniform scale for"
+  },
+  {
+    "fqn": "go.set_position",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to set the position for"
+  },
+  {
+    "fqn": "go.set_rotation",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to get the rotation for"
+  },
+  {
+    "fqn": "go.set_scale",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to get the scale for"
+  },
+  {
+    "fqn": "go.set_scale_xy",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to get the scale for"
+  },
+  {
+    "fqn": "go.set_parent",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to set parent for"
+  },
+  {
+    "fqn": "go.set_parent",
+    "parameter": "parent_id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the new parent game object"
+  },
+  {
+    "fqn": "go.get_parent",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to get parent for"
+  },
+  {
+    "fqn": "go.get_world_position",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to get the world position for"
+  },
+  {
+    "fqn": "go.get_world_rotation",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to get the world rotation for"
+  },
+  {
+    "fqn": "go.get_world_scale",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to get the world scale for"
+  },
+  {
+    "fqn": "go.get_world_scale_uniform",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to get the world scale for"
+  },
+  {
+    "fqn": "go.get_world_transform",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to get the world transform for"
+  },
+  {
+    "fqn": "go.update_world_transform",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id of the game object instance to update"
+  },
+  {
+    "fqn": "go.delete",
+    "parameter": "id",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "id or table of id's of the instance(s) to delete"
+  },
+  {
+    "fqn": "go.exists",
+    "parameter": "url",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "url of the game object to check"
+  },
+  {
+    "fqn": "go.world_to_local_position",
+    "parameter": "url",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "url of the game object which coordinate system convert to"
+  },
+  {
+    "fqn": "go.world_to_local_transform",
+    "parameter": "url",
+    "class": "game-object",
+    "source": "generated",
+    "evidence": "url of the game object which coordinate system convert to"
+  },
+  {
+    "fqn": "go.animate",
+    "parameter": "url",
+    "class": "either",
+    "source": "generated",
+    "evidence": "url of the game object or component having the property"
+  },
+  {
+    "fqn": "go.cancel_animations",
+    "parameter": "url",
+    "class": "either",
+    "source": "generated",
+    "evidence": "url of the game object or component"
+  },
+  {
+    "fqn": "go.get",
+    "parameter": "url",
+    "class": "either",
+    "source": "src/go-overloads.d.ts"
+  },
+  {
+    "fqn": "go.set",
+    "parameter": "url",
+    "class": "either",
+    "source": "src/go-overloads.d.ts"
+  },
+  {
+    "fqn": "msg.post",
+    "parameter": "receiver",
+    "class": "either",
+    "source": "src/msg-overloads.d.ts"
+  },
+  {
+    "fqn": "msg.url",
+    "parameter": "urlstring",
+    "class": "either",
+    "source": "src/msg-overloads.d.ts"
+  },
+  {
+    "fqn": "gui.get_node",
+    "parameter": "id",
+    "class": "gui-node",
+    "source": "generated",
+    "evidence": "id of the node to retrieve"
+  },
+  {
+    "fqn": "sprite.play_flipbook",
+    "parameter": "id",
+    "class": "animation",
+    "addressParameter": "url",
+    "source": "generated",
+    "evidence": "hashed id of the animation to play"
+  },
+  {
+    "fqn": "resource.atlas",
+    "parameter": "path",
+    "class": "resource-path",
+    "resourceExtensions": [".atlas"],
+    "source": "generated",
+    "evidence": "optional resource path string to the resource"
+  },
+  {
+    "fqn": "resource.buffer",
+    "parameter": "path",
+    "class": "resource-path",
+    "resourceExtensions": [".buffer"],
+    "source": "generated",
+    "evidence": "optional resource path string to the resource"
+  },
+  {
+    "fqn": "resource.font",
+    "parameter": "path",
+    "class": "resource-path",
+    "resourceExtensions": [".font"],
+    "source": "generated",
+    "evidence": "optional resource path string to the resource"
+  },
+  {
+    "fqn": "resource.material",
+    "parameter": "path",
+    "class": "resource-path",
+    "resourceExtensions": [".material"],
+    "source": "generated",
+    "evidence": "optional resource path string to the resource"
+  },
+  {
+    "fqn": "resource.texture",
+    "parameter": "path",
+    "class": "resource-path",
+    "resourceExtensions": [".png"],
+    "source": "generated",
+    "evidence": "optional resource path string to the resource"
+  },
+  {
+    "fqn": "resource.tile_source",
+    "parameter": "path",
+    "class": "resource-path",
+    "resourceExtensions": [".tilesource"],
+    "source": "generated",
+    "evidence": "optional resource path string to the resource"
+  },
+  {
+    "fqn": "sys.get_config_boolean",
+    "parameter": "key",
+    "class": "config-key",
+    "source": "generated",
+    "evidence": "The syntax is SECTION.KEY"
+  },
+  {
+    "fqn": "sys.get_config_int",
+    "parameter": "key",
+    "class": "config-key",
+    "source": "generated",
+    "evidence": "The syntax is SECTION.KEY"
+  },
+  {
+    "fqn": "sys.get_config_number",
+    "parameter": "key",
+    "class": "config-key",
+    "source": "generated",
+    "evidence": "The syntax is SECTION.KEY"
+  },
+  {
+    "fqn": "sys.get_config_string",
+    "parameter": "key",
+    "class": "config-key",
+    "source": "generated",
+    "evidence": "The syntax is SECTION.KEY"
+  },
+  {
+    "fqn": "hash",
+    "parameter": "s",
+    "class": "action-id",
+    "comparedParameter": "action_id",
+    "source": "src/engine-globals.d.ts"
+  }
+]