@defold-typescript/transpiler 0.29.0 → 0.31.0

package/src/component-animation-index.ts

@@ -0,0 +1,399 @@
+import {
+  animationSetEntries,
+  normalizeDocumentKey,
+  readAnimationSources,
+  resourceKey,
+} from "./animation-sources";
+import { parseSceneTextFormat, type SceneMessage, SceneTextFormatError } from "./scene-text-format";
+
+// The animation ids each script may play, keyed first by the project-relative
+// resource path of the `.script` that owns them and then by the id of the
+// component they belong to, plus an honest record of every link that could not
+// be settled. A missing key means nothing may be offered for it; an empty set
+// means the component resolved and declares no animation.
+export interface ComponentAnimationIndex {
+  readonly byScriptResource: ReadonlyMap<string, ReadonlyMap<string, ReadonlySet<string>>>;
+  // The display path of the document declaring each animation id — an atlas or
+  // tile source for a sprite, and for a model the animation set that *lists the
+  // entry* producing the id rather than the root the `.model` points at — under
+  // the same two keys plus the id itself. Its per-component key set is exactly
+  // that component's id set in `byScriptResource`, so the two can never
+  // disagree about which ids a component declares.
+  readonly sourceByScriptResource: ReadonlyMap<
+    string,
+    ReadonlyMap<string, ReadonlyMap<string, string>>
+  >;
+  readonly unresolved: readonly string[];
+}
+
+const SCRIPT_SUFFIX = ".script";
+const SPRITE_SUFFIX = ".sprite";
+const MODEL_SUFFIX = ".model";
+const ANIMATION_SET_SUFFIX = ".animationset";
+
+// The only mesh containers `AnimationSetBuilder` accepts. Anything else in an
+// entry is a build error, so it may contribute no id.
+const MESH_SUFFIXES = [".gltf", ".glb"];
+
+function firstField(message: SceneMessage, name: string): string | undefined {
+  return (message.fields.get(name) ?? [])[0];
+}
+
+function childrenOf(message: SceneMessage, name: string): readonly SceneMessage[] {
+  return message.messages.get(name) ?? [];
+}
+
+// The id an animation-set entry contributes, before its prefix: the entry's
+// filename with its extension dropped. The names inside the mesh container are
+// never read — for a set the editor stamps the owning name on every animation
+// the file holds, so the path is the whole answer.
+function basename(resource: string): string {
+  const file = resource.slice(resource.lastIndexOf("/") + 1);
+  const dot = file.lastIndexOf(".");
+  return dot === -1 ? file : file.slice(0, dot);
+}
+
+// Which kind of document a component reads its ids from. The two resolve
+// differently — a tile source declares ids outright, an animation set names
+// files whose basenames are the ids — while sharing one key space, because
+// component ids are unique within a game object.
+type AnimationSourceKind = "sprite" | "model";
+
+interface AnimationSource {
+  readonly kind: AnimationSourceKind;
+  readonly path: string;
+}
+
+interface AssetIndex {
+  readonly animationsByTileSet: Map<string, Set<string>>;
+  readonly tileSetBySprite: Map<string, string>;
+  readonly modelDocuments: Set<string>;
+  readonly animationSourceByModel: Map<string, string>;
+  readonly entriesByAnimationSet: Map<string, readonly string[]>;
+}
+
+function readAssets(assets: ReadonlyMap<string, string>, unresolved: string[]): AssetIndex {
+  const animationsByTileSet = readAnimationSources(assets, unresolved);
+  const tileSetBySprite = new Map<string, string>();
+  const modelDocuments = new Set<string>();
+  const animationSourceByModel = new Map<string, string>();
+  const entriesByAnimationSet = new Map<string, readonly string[]>();
+
+  for (const [path, text] of assets) {
+    const displayPath = normalizeDocumentKey(path);
+    const isSprite = displayPath.endsWith(SPRITE_SUFFIX);
+    const isModel = displayPath.endsWith(MODEL_SUFFIX);
+    const isAnimationSet = displayPath.endsWith(ANIMATION_SET_SUFFIX);
+    if (!isSprite && !isModel && !isAnimationSet) continue;
+    let document: SceneMessage;
+    try {
+      document = parseSceneTextFormat(text);
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError)) throw error;
+      unresolved.push(`${displayPath}: could not be parsed (${error.message})`);
+      continue;
+    }
+    if (isSprite) {
+      const tileSet = firstField(document, "tile_set");
+      if (tileSet !== undefined) tileSetBySprite.set(displayPath, resourceKey(tileSet));
+      continue;
+    }
+    if (isModel) {
+      modelDocuments.add(displayPath);
+      const animations = firstField(document, "animations");
+      if (animations !== undefined) animationSourceByModel.set(displayPath, animations);
+      continue;
+    }
+    entriesByAnimationSet.set(displayPath, animationSetEntries(document));
+  }
+
+  return {
+    animationsByTileSet,
+    tileSetBySprite,
+    modelDocuments,
+    animationSourceByModel,
+    entriesByAnimationSet,
+  };
+}
+
+// The ids one animation set contributes, each mapped to the display path of the
+// set that lists the entry producing it, or `undefined` when the chain itself
+// could not be read. An entry in an unsupported format is refused on its own
+// and the rest of the set still stands, because that entry is a build error the
+// author sees; a missing document or a cycle breaks the chain instead, and a
+// partial answer from a chain that is not understood is exactly the wrong guess
+// this index refuses to make.
+function resolveAnimationSet(input: {
+  path: string;
+  prefix: string;
+  stack: Set<string>;
+  assets: AssetIndex;
+  unresolved: string[];
+}): Map<string, string> | undefined {
+  const { path, prefix, stack, assets, unresolved } = input;
+  const entries = assets.entriesByAnimationSet.get(path);
+  if (entries === undefined) return undefined;
+
+  // Branch-local, not global: a set reached from two different entries is
+  // reached twice legitimately, and only a set re-entered while still being
+  // read is a cycle.
+  stack.add(path);
+  try {
+    const ids = new Map<string, string>();
+    for (const entry of entries) {
+      const key = resourceKey(entry);
+      if (MESH_SUFFIXES.some((suffix) => key.endsWith(suffix))) {
+        ids.set(prefix + basename(key), path);
+        continue;
+      }
+      if (!key.endsWith(ANIMATION_SET_SUFFIX)) {
+        unresolved.push(
+          `${path}: the entry ${entry} is not a .gltf, .glb or .animationset, so it declares no animation id`,
+        );
+        continue;
+      }
+      if (!assets.entriesByAnimationSet.has(key)) {
+        unresolved.push(
+          `${path}: the entry ${entry} is not among the project's animation set documents`,
+        );
+        return undefined;
+      }
+      if (stack.has(key)) {
+        unresolved.push(
+          `${path}: the entry ${entry} re-enters an animation set already being read, so the chain is cyclic`,
+        );
+        return undefined;
+      }
+      const nested = resolveAnimationSet({
+        path: key,
+        prefix: `${prefix + basename(key)}/`,
+        stack,
+        assets,
+        unresolved,
+      });
+      if (nested === undefined) return undefined;
+      for (const [id, declaring] of nested) if (!ids.has(id)) ids.set(id, declaring);
+    }
+    return ids;
+  } finally {
+    stack.delete(path);
+  }
+}
+
+// The animation-declaring components of one game object, as
+// `id -> source document`. An embedded component carries its own payload; a
+// referenced one names a document that carries it instead. A `.model` naming a
+// mesh source directly is refused here rather than resolved: the editor and the
+// build pipeline disagree about which ids such a model can play, so no id is
+// established and the model is named in `unresolved`.
+function componentAnimationSources(
+  object: SceneMessage,
+  displayPath: string,
+  assets: AssetIndex,
+  unresolved: string[],
+): Map<string, AnimationSource> {
+  const sources = new Map<string, AnimationSource>();
+
+  function claimModel(id: string, animations: string): void {
+    if (!animations.endsWith(ANIMATION_SET_SUFFIX)) {
+      unresolved.push(
+        `${displayPath}: the model component "${id}" names ${animations} rather than an animation set, so none of its animation ids are established`,
+      );
+      return;
+    }
+    sources.set(id, { kind: "model", path: resourceKey(animations) });
+  }
+
+  for (const embedded of childrenOf(object, "embedded_components")) {
+    const type = firstField(embedded, "type");
+    if (type !== "sprite" && type !== "model") continue;
+    const id = firstField(embedded, "id");
+    const payload = firstField(embedded, "data");
+    if (id === undefined || payload === undefined) continue;
+    let document: SceneMessage;
+    try {
+      document = parseSceneTextFormat(payload);
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError)) throw error;
+      unresolved.push(
+        `${displayPath}: the embedded ${type} "${id}" could not be read (${error.message})`,
+      );
+      continue;
+    }
+    if (type === "sprite") {
+      const tileSet = firstField(document, "tile_set");
+      if (tileSet !== undefined) sources.set(id, { kind: "sprite", path: resourceKey(tileSet) });
+      continue;
+    }
+    const animations = firstField(document, "animations");
+    if (animations !== undefined) claimModel(id, animations);
+  }
+
+  for (const referenced of childrenOf(object, "components")) {
+    const component = firstField(referenced, "component");
+    const id = firstField(referenced, "id");
+    if (id === undefined || component === undefined) continue;
+    if (component.endsWith(SPRITE_SUFFIX)) {
+      const tileSet = assets.tileSetBySprite.get(resourceKey(component));
+      if (tileSet === undefined) {
+        unresolved.push(
+          `${displayPath}: the sprite component "${id}" names ${component}, which is not among the project's sprite documents`,
+        );
+        continue;
+      }
+      sources.set(id, { kind: "sprite", path: tileSet });
+      continue;
+    }
+    if (!component.endsWith(MODEL_SUFFIX)) continue;
+    const resource = resourceKey(component);
+    if (!assets.modelDocuments.has(resource)) {
+      unresolved.push(
+        `${displayPath}: the model component "${id}" names ${component}, which is not among the project's model documents`,
+      );
+      continue;
+    }
+    // A model that declares no animations at all is a legitimate authoring
+    // state, not a broken link: it resolves to nothing and says nothing.
+    const animations = assets.animationSourceByModel.get(resource);
+    if (animations !== undefined) claimModel(id, animations);
+  }
+
+  return sources;
+}
+
+function scriptResourcesOf(object: SceneMessage): string[] {
+  const resources: string[] = [];
+  for (const component of childrenOf(object, "components")) {
+    const resource = firstField(component, "component");
+    if (resource === undefined || !resource.endsWith(SCRIPT_SUFFIX)) continue;
+    const key = resourceKey(resource);
+    if (key !== SCRIPT_SUFFIX.slice(1)) resources.push(key);
+  }
+  return resources;
+}
+
+function isGameObject(message: SceneMessage): boolean {
+  return message.messages.has("components") || message.messages.has("embedded_components");
+}
+
+export function buildComponentAnimationIndex(input: {
+  scenes: ReadonlyMap<string, string>;
+  assets: ReadonlyMap<string, string>;
+}): ComponentAnimationIndex {
+  const unresolved: string[] = [];
+  const assets = readAssets(input.assets, unresolved);
+  const byScriptResource = new Map<string, ReadonlyMap<string, ReadonlySet<string>>>();
+  const sourceByScriptResource = new Map<
+    string,
+    ReadonlyMap<string, ReadonlyMap<string, string>>
+  >();
+  const claimedBy = new Map<string, string>();
+
+  // A `.go` document is a game object at its root; a `.collection` carries one
+  // inside each `embedded_instances` `data:` payload, decoded exactly one level
+  // at a time. No `instances { prototype: }` edge is followed: the referenced
+  // `.go` is its own document and already claims its own script.
+  function walk(message: SceneMessage, blockName: string, displayPath: string): void {
+    if (isGameObject(message)) {
+      claim(message, displayPath);
+    }
+    if (blockName === "embedded_instances") {
+      for (const payload of message.fields.get("data") ?? []) {
+        try {
+          walk(parseSceneTextFormat(payload), "", displayPath);
+        } catch (error) {
+          if (!(error instanceof SceneTextFormatError)) throw error;
+          unresolved.push(
+            `${displayPath}: an embedded game object could not be read (${error.message})`,
+          );
+        }
+      }
+    }
+    for (const [name, nested] of message.messages) {
+      for (const child of nested) {
+        walk(child, name, displayPath);
+      }
+    }
+  }
+
+  function idsOf(
+    id: string,
+    source: AnimationSource,
+    displayPath: string,
+  ): Map<string, string> | undefined {
+    if (source.kind === "sprite") {
+      const declared = assets.animationsByTileSet.get(source.path);
+      if (declared !== undefined) return new Map([...declared].map((name) => [name, source.path]));
+      unresolved.push(
+        `${displayPath}: the sprite component "${id}" names the tile source /${source.path}, which is not among the project's asset documents`,
+      );
+      return undefined;
+    }
+    const resolved = resolveAnimationSet({
+      path: source.path,
+      prefix: "",
+      stack: new Set(),
+      assets,
+      unresolved,
+    });
+    if (resolved !== undefined) return resolved;
+    if (!assets.entriesByAnimationSet.has(source.path)) {
+      unresolved.push(
+        `${displayPath}: the model component "${id}" names the animation set /${source.path}, which is not among the project's asset documents`,
+      );
+    }
+    return undefined;
+  }
+
+  function claim(object: SceneMessage, displayPath: string): void {
+    const scripts = scriptResourcesOf(object);
+    if (scripts.length === 0) return;
+
+    const sources = componentAnimationSources(object, displayPath, assets, unresolved);
+    const animations = new Map<string, ReadonlySet<string>>();
+    const declaringSources = new Map<string, ReadonlyMap<string, string>>();
+    for (const [id, source] of sources) {
+      const resolved = idsOf(id, source, displayPath);
+      if (resolved === undefined) continue;
+      animations.set(id, new Set(resolved.keys()));
+      declaringSources.set(id, resolved);
+    }
+
+    for (const key of scripts) {
+      const owner = claimedBy.get(key);
+      if (owner !== undefined) {
+        byScriptResource.delete(key);
+        sourceByScriptResource.delete(key);
+        unresolved.push(
+          `${key}: claimed by both ${owner} and ${displayPath}, so its component animations are ambiguous`,
+        );
+        continue;
+      }
+      claimedBy.set(key, displayPath);
+      byScriptResource.set(key, animations);
+      sourceByScriptResource.set(key, declaringSources);
+    }
+  }
+
+  for (const [path, text] of input.scenes) {
+    const displayPath = normalizeDocumentKey(path);
+    try {
+      walk(parseSceneTextFormat(text), "", displayPath);
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError)) throw error;
+      unresolved.push(`${displayPath}: could not be parsed (${error.message})`);
+    }
+  }
+
+  return { byScriptResource, sourceByScriptResource, unresolved };
+}
+
+// The component id a same-object `"#id"` address names, or `undefined` for
+// every other form. A path form names a component on a *different* game
+// object, so its id must never be resolved against this script's own.
+export function componentIdOfSameObjectAddress(address: string): string | undefined {
+  if (!address.startsWith("#")) return undefined;
+  const id = address.slice(1);
+  if (id === "" || id.includes("/") || id.includes("#")) return undefined;
+  return id;
+}

package/src/config-key-index.ts

@@ -4,8 +4,9 @@
 //
 // Deliberately a line reader rather than a parse of the scene text format:
 // `game.project` is a flat INI the editor writes, the same shape
-// `readExtensionDependencies` already walks. A key may carry a `#`
-// (`dependencies#0`), which is part of its name here and never a fragment.
+// `readGameProjectDependencies` (library-dependencies.ts) already walks. A key
+// may carry a `#` (`dependencies#0`), which is part of its name here and never a
+// fragment.
 
 function sectionNameOf(line: string): string | undefined {
   const match = line.trim().match(/^\[(.+)\]$/);
@@ -32,3 +33,28 @@ export function buildConfigKeyIndex(gameProjectText: string): ReadonlySet<string
   }
   return keys;
 }
+
+// One declared value, read the same way `buildConfigKeyIndex` reads the whole
+// file. The section is matched in full rather than as a prefix, so a
+// `main_collection_backup` beside `main_collection` answers neither.
+export function readGameProjectSetting(
+  gameProjectText: string,
+  section: string,
+  key: string,
+): string | undefined {
+  let current: string | undefined;
+  for (const line of gameProjectText.split("\n")) {
+    const header = sectionNameOf(line);
+    if (header !== undefined) {
+      current = header;
+      continue;
+    }
+    if (current !== section) continue;
+    const separator = line.indexOf("=");
+    if (separator === -1) continue;
+    if (line.slice(0, separator).trim() !== key) continue;
+    const value = line.slice(separator + 1).trim();
+    if (value !== "") return value;
+  }
+  return undefined;
+}

package/src/gui-flipbook-index.ts

@@ -0,0 +1,91 @@
+import { normalizeDocumentKey, readAnimationSources, resourceKey } from "./animation-sources";
+import { parseSceneTextFormat, type SceneMessage, SceneTextFormatError } from "./scene-text-format";
+
+// The flipbook animation ids each gui script may play, keyed by the
+// project-relative resource path of the `.gui_script` that owns them, and then
+// by animation id — whose value is the display path of every named texture
+// declaring it, so a completion reads the keys and a provenance panel reads the
+// value. A missing key means nothing may be offered for it; an empty map means
+// the scene resolved and its textures declare no animation.
+export interface GuiFlipbookIndex {
+  readonly byScriptResource: ReadonlyMap<string, ReadonlyMap<string, ReadonlySet<string>>>;
+  readonly unresolved: readonly string[];
+}
+
+// The scope is the `.gui` scene naming this script, never the node the call
+// addresses: `gui.set_texture` retargets a node at runtime, so scoping to a
+// node's authored texture would reject calls that are valid. The scene's
+// `textures` blocks are the honest universe.
+const SCRIPT_SUFFIX = ".gui_script";
+
+function scriptKeyOf(script: string): string | undefined {
+  if (!script.endsWith(SCRIPT_SUFFIX)) return undefined;
+  const key = resourceKey(script);
+  return key === SCRIPT_SUFFIX ? undefined : key;
+}
+
+export function buildGuiFlipbookIndex(input: {
+  scenes: ReadonlyMap<string, string>;
+  assets: ReadonlyMap<string, string>;
+}): GuiFlipbookIndex {
+  const unresolved: string[] = [];
+  const animationsBySource = readAnimationSources(input.assets, unresolved);
+  const byScriptResource = new Map<string, ReadonlyMap<string, ReadonlySet<string>>>();
+  const claimedBy = new Map<string, string>();
+
+  for (const [path, text] of input.scenes) {
+    const displayPath = normalizeDocumentKey(path);
+    let document: SceneMessage;
+    try {
+      document = parseSceneTextFormat(text);
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError)) throw error;
+      unresolved.push(`${displayPath}: could not be parsed (${error.message})`);
+      continue;
+    }
+
+    const [script] = document.fields.get("script") ?? [];
+    if (script === undefined) continue;
+    const key = scriptKeyOf(script);
+    if (key === undefined) continue;
+
+    const owner = claimedBy.get(key);
+    if (owner !== undefined) {
+      byScriptResource.delete(key);
+      unresolved.push(
+        `${key}: claimed by both ${owner} and ${displayPath}, so its flipbook animations are ambiguous`,
+      );
+      continue;
+    }
+    claimedBy.set(key, displayPath);
+
+    // Top-level `textures` only, for the reason `buildGuiNodeIndex` reads only
+    // top-level `nodes`: a `layouts` or `templates` block repeats an authored
+    // surface under an override rather than naming a source of its own.
+    const declaredBy = new Map<string, Set<string>>();
+    for (const message of document.messages.get("textures") ?? []) {
+      for (const texture of message.fields.get("texture") ?? []) {
+        if (texture === "") continue;
+        const source = resourceKey(texture);
+        const ids = animationsBySource.get(source);
+        if (ids === undefined) {
+          unresolved.push(
+            `${displayPath}: the texture ${texture} is not among the project's asset documents`,
+          );
+          continue;
+        }
+        for (const id of ids) {
+          const declarers = declaredBy.get(id);
+          if (declarers) {
+            declarers.add(source);
+          } else {
+            declaredBy.set(id, new Set([source]));
+          }
+        }
+      }
+    }
+    byScriptResource.set(key, declaredBy);
+  }
+
+  return { byScriptResource, unresolved };
+}

package/src/gui-node-index.ts

@@ -1,4 +1,4 @@
-import { parseSceneTextFormat, SceneTextFormatError } from "./scene-text-format";
+import { parseSceneTextFormat, type SceneMessage, SceneTextFormatError } from "./scene-text-format";
 
 // The node ids each script may address, keyed by the project-relative resource
 // path of the `.gui_script` that owns them, plus an honest record of every scene
@@ -25,6 +25,46 @@ function scriptKeyOf(script: string): string | undefined {
   return key === SCRIPT_SUFFIX ? undefined : key;
 }
 
+/**
+ * The gui-script resource one already-parsed `.gui` names, keyed the way this
+ * index keys it. Exported so the naming-context resolver reaches a gui script
+ * through the same rule rather than a second reader — the aggregation on top
+ * differs on purpose (this index refuses a resource two scenes claim, while two
+ * scenes driving one gui script really is two naming contexts), but the key
+ * shape has one owner.
+ */
+export function guiScriptResourceOf(document: SceneMessage): string | undefined {
+  const [script] = document.fields.get("script") ?? [];
+  return script === undefined ? undefined : scriptKeyOf(script);
+}
+
+/**
+ * Every `.gui` document's display path mapped to the gui-script resource it
+ * names, skipping a `.gui` that names none and one this parser cannot read.
+ *
+ * The map `buildScriptNamingContexts` consumes, built once here so the editor
+ * plugin and the CLI reach a gui script through one reader. Unlike
+ * `buildGuiNodeIndex` it records no ambiguity: two `.gui` scenes driving one gui
+ * script really are two naming contexts, while they would make that script's
+ * node ids unanswerable.
+ */
+export function guiScriptResourcesOf(
+  documents: ReadonlyMap<string, string>,
+): ReadonlyMap<string, string> {
+  const scripts = new Map<string, string>();
+  for (const [displayPath, text] of documents) {
+    let resource: string | undefined;
+    try {
+      resource = guiScriptResourceOf(parseSceneTextFormat(text));
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError)) throw error;
+      continue;
+    }
+    if (resource !== undefined) scripts.set(displayPath, resource);
+  }
+  return scripts;
+}
+
 export function buildGuiNodeIndex(documents: ReadonlyMap<string, string>): GuiNodeIndex {
   const byScriptResource = new Map<string, ReadonlySet<string>>();
   const claimedBy = new Map<string, string>();
@@ -40,9 +80,7 @@ export function buildGuiNodeIndex(documents: ReadonlyMap<string, string>): GuiNo
       continue;
     }
 
-    const [script] = document.fields.get("script") ?? [];
-    if (script === undefined) continue;
-    const key = scriptKeyOf(script);
+    const key = guiScriptResourceOf(document);
     if (key === undefined) continue;
 
     const owner = claimedBy.get(key);