@defold-typescript/transpiler 0.24.0 → 0.25.0

package/src/scene-object-path-index.ts

@@ -0,0 +1,148 @@
+import { parseSceneTextFormat, type SceneMessage, SceneTextFormatError } from "./scene-text-format";
+
+// Every game-object path the project declares, `/`-prefixed and composed the way
+// Defold composes them, plus an honest record of everything the walk could not
+// settle. Shaped like `SceneComponentIndex`: a non-empty `incomplete` means the
+// universe is not provably whole, so no consumer may conclude a path is absent.
+export interface SceneObjectPathIndex {
+  readonly paths: ReadonlySet<string>;
+  // The documents declaring each path's *leaf* segment, sorted — the files an
+  // author would open to rename that object. A composed address is attributed to
+  // the collection that names the object, never to the ones that prefixed it.
+  readonly declaredIn: ReadonlyMap<string, readonly string[]>;
+  readonly incomplete: readonly string[];
+}
+
+// The two blocks whose `id` is a leaf segment. `collection_instances` is handled
+// apart, because its id is a namespace rather than an object.
+const LEAF_BLOCKS = ["instances", "embedded_instances"];
+
+// Resource paths inside a scene are project-absolute; documents are keyed by
+// project-relative display path, the same convention `resourceKey` follows in
+// `sprite-animation-index.ts`.
+function resourceKey(resource: string): string {
+  return resource.startsWith("/") ? resource.slice(1) : resource;
+}
+
+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) ?? [];
+}
+
+// Build the game-object path universe from already-read scene sources: keys are
+// display paths, values are file text. Pure the same way `buildSceneComponentIndex`
+// is — the filesystem walk belongs to the caller.
+//
+// A `children:` edge is deliberately not a path segment. Defold ids are unique
+// inside one collection and a child object is still addressed `/child`, so
+// parenting is a transform relation; nesting comes from a collection instanced
+// inside another.
+export function buildSceneObjectPathIndex(
+  documents: ReadonlyMap<string, string>,
+): SceneObjectPathIndex {
+  const incomplete: string[] = [];
+
+  if (documents.size === 0) {
+    incomplete.push("no scene sources were read, so no game-object path can be proven absent");
+    return { paths: new Set(), declaredIn: new Map(), incomplete };
+  }
+
+  const parsed = new Map<string, SceneMessage>();
+  for (const [displayPath, text] of documents) {
+    try {
+      parsed.set(displayPath, parseSceneTextFormat(text));
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError)) throw error;
+      incomplete.push(`${displayPath}: could not be parsed (${error.message})`);
+    }
+  }
+
+  // A collection another document instances is not a world of its own: at
+  // runtime its objects only exist under that instance's id, so contributing its
+  // own unprefixed paths as well would offer addresses that resolve to nothing.
+  const instanced = new Set<string>();
+  for (const document of parsed.values()) {
+    for (const block of childrenOf(document, "collection_instances")) {
+      const collection = firstField(block, "collection");
+      if (collection !== undefined) instanced.add(resourceKey(collection));
+    }
+  }
+
+  // Memo keyed by display path, so a collection instanced twice is read once;
+  // `inProgress` is the cycle guard, without which two collections instancing
+  // each other would recur until the stack ran out. Each entry maps a composed
+  // path to the document that declared its leaf, so the attribution is carried
+  // by the same walk that builds the path rather than recovered afterwards.
+  const composed = new Map<string, ReadonlyMap<string, string>>();
+  const inProgress = new Set<string>();
+
+  function pathsOf(displayPath: string): ReadonlyMap<string, string> {
+    const done = composed.get(displayPath);
+    if (done !== undefined) return done;
+    if (inProgress.has(displayPath)) {
+      incomplete.push(
+        `${displayPath}: is instanced inside itself through a cycle of collection references, so its paths cannot be composed`,
+      );
+      return new Map();
+    }
+    const document = parsed.get(displayPath);
+    if (document === undefined) return new Map();
+
+    inProgress.add(displayPath);
+    const paths = new Map<string, string>();
+
+    for (const blockName of LEAF_BLOCKS) {
+      for (const block of childrenOf(document, blockName)) {
+        const id = firstField(block, "id");
+        if (id !== undefined && id !== "") paths.set(`/${id}`, displayPath);
+      }
+    }
+
+    for (const block of childrenOf(document, "collection_instances")) {
+      const id = firstField(block, "id");
+      const collection = firstField(block, "collection");
+      if (id === undefined || id === "" || collection === undefined) continue;
+      const key = resourceKey(collection);
+      if (!parsed.has(key)) {
+        incomplete.push(
+          `${displayPath}: the collection instance "${id}" names ${collection}, which is not among the project's readable scene documents`,
+        );
+        continue;
+      }
+      for (const [nested, declarer] of pathsOf(key)) {
+        paths.set(`/${id}${nested}`, declarer);
+      }
+    }
+
+    inProgress.delete(displayPath);
+    composed.set(displayPath, paths);
+    return paths;
+  }
+
+  // Composed for every document, contributed from the un-instanced ones alone: a
+  // cycle or a dangling reference reached only from inside an instanced
+  // collection is still a gap the caller has to hear about.
+  const paths = new Set<string>();
+  const declaredIn = new Map<string, string[]>();
+  for (const displayPath of parsed.keys()) {
+    const own = pathsOf(displayPath);
+    if (instanced.has(displayPath)) continue;
+    for (const [path, declarer] of own) {
+      paths.add(path);
+      const declarers = declaredIn.get(path);
+      if (declarers === undefined) {
+        declaredIn.set(path, [declarer]);
+      } else if (!declarers.includes(declarer)) {
+        // Two roots instancing one collection under the same id compose the same
+        // address from the same leaf, which is one declaring file and not two.
+        declarers.push(declarer);
+      }
+    }
+  }
+  for (const declarers of declaredIn.values()) declarers.sort();
+
+  return { paths, declaredIn, incomplete };
+}

package/src/scene-text-format.ts

@@ -0,0 +1,171 @@
+// Defold's `.go`/`.collection` sources are protobuf text format. A message is a
+// tree of `key: <scalar>` and `key { … }` entries where any key may repeat, so
+// scalars and sub-messages are kept in separate multi-value maps — the format
+// never uses one name as both.
+export interface SceneMessage {
+  readonly fields: ReadonlyMap<string, readonly string[]>;
+  readonly messages: ReadonlyMap<string, readonly SceneMessage[]>;
+}
+
+export class SceneTextFormatError extends Error {
+  readonly line: number;
+
+  constructor(message: string, line: number) {
+    super(`${message} (line ${line})`);
+    this.name = "SceneTextFormatError";
+    this.line = line;
+  }
+}
+
+const IDENTIFIER_PART = /[A-Za-z0-9_]/;
+
+function append<T>(target: Map<string, T[]>, key: string, value: T): void {
+  const existing = target.get(key);
+  if (existing === undefined) {
+    target.set(key, [value]);
+    return;
+  }
+  existing.push(value);
+}
+
+// Parses one document. Nothing here knows that `data:` holds a payload: an
+// embedded `.go` is reached by the caller re-invoking this function on the
+// decoded value, which keeps exactly one decode pass per nesting level. A
+// greedy unescape would resolve the deeper level's `\\\"` too and leave the
+// payload unparseable.
+export function parseSceneTextFormat(text: string): SceneMessage {
+  let pos = 0;
+  let line = 1;
+
+  function fail(message: string, at: number): never {
+    throw new SceneTextFormatError(message, at);
+  }
+
+  function advance(): string {
+    const ch = text.charAt(pos);
+    pos += 1;
+    if (ch === "\n") line += 1;
+    return ch;
+  }
+
+  function skipWhitespace(): void {
+    while (pos < text.length) {
+      const ch = text.charAt(pos);
+      if (ch !== " " && ch !== "\t" && ch !== "\r" && ch !== "\n") return;
+      advance();
+    }
+  }
+
+  function skipInlineWhitespace(): void {
+    while (pos < text.length) {
+      const ch = text.charAt(pos);
+      if (ch !== " " && ch !== "\t") return;
+      pos += 1;
+    }
+  }
+
+  function readIdentifier(at: number): string {
+    const start = pos;
+    while (pos < text.length && IDENTIFIER_PART.test(text.charAt(pos))) {
+      pos += 1;
+    }
+    if (pos === start) {
+      fail(`unexpected \`${text.charAt(start)}\``, at);
+    }
+    return text.slice(start, pos);
+  }
+
+  // One or more double-quoted literals, adjacent across whitespace and
+  // newlines, concatenated with no separator. `\"`, `\\`, `\n`, `\r` and `\t`
+  // resolve; every other backslash pair survives verbatim because it is the
+  // next level's escaping.
+  function readQuotedScalar(): string {
+    let value = "";
+    for (;;) {
+      const openedAt = line;
+      advance();
+      let closed = false;
+      while (pos < text.length) {
+        const ch = advance();
+        if (ch === "\\") {
+          if (pos >= text.length) break;
+          const escaped = advance();
+          if (escaped === '"') value += '"';
+          else if (escaped === "\\") value += "\\";
+          else if (escaped === "n") value += "\n";
+          else if (escaped === "r") value += "\r";
+          else if (escaped === "t") value += "\t";
+          else value += `\\${escaped}`;
+          continue;
+        }
+        if (ch === '"') {
+          closed = true;
+          break;
+        }
+        if (ch === "\n") break;
+        value += ch;
+      }
+      if (!closed) {
+        fail("unterminated string literal", openedAt);
+      }
+      const resumePos = pos;
+      const resumeLine = line;
+      skipWhitespace();
+      if (text.charAt(pos) === '"') {
+        continue;
+      }
+      pos = resumePos;
+      line = resumeLine;
+      return value;
+    }
+  }
+
+  function readUnquotedScalar(): string {
+    const newline = text.indexOf("\n", pos);
+    const end = newline === -1 ? text.length : newline;
+    const raw = text.slice(pos, end);
+    pos = end;
+    return raw.trim();
+  }
+
+  function parseBody(nested: boolean, openedAt: number): SceneMessage {
+    const fields = new Map<string, string[]>();
+    const messages = new Map<string, SceneMessage[]>();
+    for (;;) {
+      skipWhitespace();
+      if (pos >= text.length) {
+        if (nested) {
+          fail("unclosed `{`", openedAt);
+        }
+        break;
+      }
+      if (text.charAt(pos) === "}") {
+        if (!nested) {
+          fail("unexpected `}`", line);
+        }
+        advance();
+        break;
+      }
+      const keyLine = line;
+      const key = readIdentifier(keyLine);
+      skipInlineWhitespace();
+      const delimiter = text.charAt(pos);
+      if (delimiter === "{") {
+        const braceLine = line;
+        advance();
+        append(messages, key, parseBody(true, braceLine));
+        continue;
+      }
+      if (delimiter === ":") {
+        advance();
+        skipInlineWhitespace();
+        append(fields, key, text.charAt(pos) === '"' ? readQuotedScalar() : readUnquotedScalar());
+        continue;
+      }
+      fail(`expected \`:\` or \`{\` after \`${key}\``, keyLine);
+    }
+    return { fields, messages };
+  }
+
+  return parseBody(false, 1);
+}

package/src/sprite-animation-index.ts

@@ -0,0 +1,241 @@
+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
+// sprite 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 SpriteAnimationIndex {
+  readonly byScriptResource: ReadonlyMap<string, ReadonlyMap<string, ReadonlySet<string>>>;
+  // The display path of the tile source each keyed component's ids were read
+  // from, under the same two keys. Present for exactly the components
+  // `byScriptResource` keys, so the two can never disagree about a resource.
+  readonly tileSetByScriptResource: ReadonlyMap<string, ReadonlyMap<string, string>>;
+  readonly unresolved: readonly string[];
+}
+
+// Resource paths inside a scene are project-absolute; the index is keyed the
+// way `buildGuiNodeIndex` keys its own, with the leading `/` dropped, so a
+// caller maps the file it holds forward through the build's output-path math
+// and looks the result up here.
+function resourceKey(resource: string): string {
+  return resource.startsWith("/") ? resource.slice(1) : resource;
+}
+
+// The keys a caller supplies name files on the host, so they may arrive with
+// native separators; the resource paths they are matched against come out of
+// scene content and are always `/`-separated. Normalizing here enforces that
+// contract at the boundary instead of leaving it to whichever caller happens
+// to build the maps.
+function normalizeDocumentKey(path: string): string {
+  return path.replaceAll("\\", "/");
+}
+
+const SCRIPT_SUFFIX = ".script";
+const SPRITE_SUFFIX = ".sprite";
+
+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) ?? [];
+}
+
+// Only `animations { id: … }` counts. Defold may also expose a bare
+// `images { image: … }` entry as a one-frame animation named after the file,
+// which is unverified here — and a wrong suggestion in this slot is a runtime
+// crash rather than a no-op.
+function declaredAnimations(document: SceneMessage): Set<string> {
+  const ids = new Set<string>();
+  for (const animation of childrenOf(document, "animations")) {
+    for (const id of animation.fields.get("id") ?? []) {
+      if (id !== "") ids.add(id);
+    }
+  }
+  return ids;
+}
+
+interface AssetIndex {
+  readonly animationsByTileSet: Map<string, Set<string>>;
+  readonly tileSetBySprite: Map<string, string>;
+}
+
+function readAssets(assets: ReadonlyMap<string, string>, unresolved: string[]): AssetIndex {
+  const animationsByTileSet = new Map<string, Set<string>>();
+  const tileSetBySprite = new Map<string, string>();
+
+  for (const [path, text] of assets) {
+    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;
+    }
+    if (displayPath.endsWith(SPRITE_SUFFIX)) {
+      const tileSet = firstField(document, "tile_set");
+      if (tileSet !== undefined) tileSetBySprite.set(displayPath, resourceKey(tileSet));
+      continue;
+    }
+    animationsByTileSet.set(displayPath, declaredAnimations(document));
+  }
+
+  return { animationsByTileSet, tileSetBySprite };
+}
+
+// The sprite components of one game object, as `id -> tile_set resource`. An
+// embedded sprite carries its own payload; a referenced one names a `.sprite`
+// document that carries it instead.
+function spriteTileSets(
+  object: SceneMessage,
+  displayPath: string,
+  assets: AssetIndex,
+  unresolved: string[],
+): Map<string, string> {
+  const tileSets = new Map<string, string>();
+
+  for (const embedded of childrenOf(object, "embedded_components")) {
+    if (firstField(embedded, "type") !== "sprite") continue;
+    const id = firstField(embedded, "id");
+    const payload = firstField(embedded, "data");
+    if (id === undefined || payload === undefined) continue;
+    try {
+      const tileSet = firstField(parseSceneTextFormat(payload), "tile_set");
+      if (tileSet !== undefined) tileSets.set(id, resourceKey(tileSet));
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError)) throw error;
+      unresolved.push(
+        `${displayPath}: the embedded sprite "${id}" could not be read (${error.message})`,
+      );
+    }
+  }
+
+  for (const referenced of childrenOf(object, "components")) {
+    const component = firstField(referenced, "component");
+    const id = firstField(referenced, "id");
+    if (id === undefined || component === undefined || !component.endsWith(SPRITE_SUFFIX)) continue;
+    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;
+    }
+    tileSets.set(id, tileSet);
+  }
+
+  return tileSets;
+}
+
+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 buildSpriteAnimationIndex(input: {
+  scenes: ReadonlyMap<string, string>;
+  assets: ReadonlyMap<string, string>;
+}): SpriteAnimationIndex {
+  const unresolved: string[] = [];
+  const assets = readAssets(input.assets, unresolved);
+  const byScriptResource = new Map<string, ReadonlyMap<string, ReadonlySet<string>>>();
+  const tileSetByScriptResource = new Map<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 claim(object: SceneMessage, displayPath: string): void {
+    const scripts = scriptResourcesOf(object);
+    if (scripts.length === 0) return;
+
+    const tileSets = spriteTileSets(object, displayPath, assets, unresolved);
+    const animations = new Map<string, ReadonlySet<string>>();
+    const declaringTileSets = new Map<string, string>();
+    for (const [id, tileSet] of tileSets) {
+      const declared = assets.animationsByTileSet.get(tileSet);
+      if (declared === undefined) {
+        unresolved.push(
+          `${displayPath}: the sprite component "${id}" names the tile source /${tileSet}, which is not among the project's asset documents`,
+        );
+        continue;
+      }
+      animations.set(id, declared);
+      declaringTileSets.set(id, tileSet);
+    }
+
+    for (const key of scripts) {
+      const owner = claimedBy.get(key);
+      if (owner !== undefined) {
+        byScriptResource.delete(key);
+        tileSetByScriptResource.delete(key);
+        unresolved.push(
+          `${key}: claimed by both ${owner} and ${displayPath}, so its sprite animations are ambiguous`,
+        );
+        continue;
+      }
+      claimedBy.set(key, displayPath);
+      byScriptResource.set(key, animations);
+      tileSetByScriptResource.set(key, declaringTileSets);
+    }
+  }
+
+  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, tileSetByScriptResource, 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/transpile.ts

@@ -158,6 +158,11 @@ function buildAmbientFiles(): Record<string, string> {
       'export { defineGuiScript } from "./src/lifecycle.js";\nexport type { ScriptProperties, ScriptProperty } from "./src/lifecycle.js";\n',
     "node_modules/@defold-typescript/types/render-script.d.ts":
       'export { defineRenderScript } from "./src/lifecycle.js";\nexport type { ScriptProperties, ScriptProperty } from "./src/lifecycle.js";\n',
+    "node_modules/@defold-typescript/types/editor-script.d.ts": [
+      'export { defineEditorCommand, defineEditorScript } from "./src/editor.js";',
+      'export type { EditorCommandQuery, EditorNode } from "./src/editor.js";',
+      "",
+    ].join("\n"),
   };
   // Seed the Lua 5.1 standard library (math/os/string/table/coroutine + base
   // globals) so user code can call e.g. `math.randomseed(os.time())`.