@defold-typescript/transpiler 0.45.0 → 0.46.0

package/dist/hsm/async.ts

@@ -1,8 +1,20 @@
 import type { EventObject, TaskStart } from "./index";
 
-/** @noSelf */
+/**
+ * The second argument of a `sequence` function: a wait that leaving the state cancels, and a flag
+ * that tells the state was left.
+ * @noSelf
+ */
 export interface SequenceSignal {
+  /**
+   * Turns `true` once the state is left. Check it after awaiting anything other than `wait`: such
+   * a promise can still resolve after the state is left, and the code after it then runs.
+   */
   readonly aborted: boolean;
+  /**
+   * Resolves after `seconds`, counted by `timer.delay` rather than by `update(dt)`. A wait still
+   * pending when the state is left never resolves, so the code after it does not run.
+   */
   readonly wait: (seconds: number) => Promise<void>;
 }
 
@@ -32,6 +44,12 @@ function rethrow(reason: unknown): void {
 
 // The sequence plugs into the state's task, so its cleanup cancels the pending
 // waits on every way out of the state; a wait left pending is never resolved.
+/**
+ * Turns an `async` function into a state's `task`. The function gets the context and a
+ * `SequenceSignal`, and the event it returns is sent to the machine; one returned after the state
+ * is left is ignored. An error thrown inside it leaves the machine where it is and is raised
+ * again from a timer callback, so it shows in the engine console.
+ */
 export function sequence<Ctx, E extends EventObject>(
   // biome-ignore lint/suspicious/noConfusingVoidType: `void` lets a sequence end without returning an event.
   run: (ctx: Ctx, signal: SequenceSignal) => Promise<NoInfer<E> | void>,

package/dist/hsm/debug.ts

@@ -1,7 +1,15 @@
 import type { EventObject, MachineInstance } from "./index";
 
-/** @noSelf */
+/**
+ * Returned by `inspect`. Keep it on `self` and call its `draw` from `update`.
+ * @noSelf
+ */
 export interface MachineInspector {
+  /**
+   * Draws the label and the active leaves as debug text, 40 units above `target`'s world
+   * position. Each call also advances the frame number the console lines show. In a release
+   * build it does nothing.
+   */
   readonly draw: (target: Hash | Url | string) => void;
 }
 
@@ -86,6 +94,12 @@ function shownLeaves(leaves: readonly string[]): string {
   return leaves.length === 0 ? "(stopped)" : shownList(leaves, raw);
 }
 
+/**
+ * Prints one line when it is called, then one line for each move `instance` makes, each starting
+ * with `hsm` and the label. Call it once after `start`. A label another `inspect` call already
+ * used gets an ordinal, such as `enemy#2`. In a release build it registers nothing and returns an
+ * inspector whose `draw` does nothing, so the calls can stay in shipped code.
+ */
 export function inspect<Ctx, E extends EventObject, P extends string>(
   instance: MachineInstance<Ctx, E, P>,
   label: string,

package/dist/hsm/defold.ts

@@ -1,9 +1,27 @@
+/**
+ * The event `messageEvents` builds from the Defold message `K`, for a machine's event union. It
+ * holds the message id as `type`, the payload fields declared through `BuiltinMessages` and
+ * `CustomMessages`, and the `sender`.
+ */
 export type MessageEvent<K extends MessageId> = K extends MessageId
-  ? { readonly type: K; readonly sender: Url } & Omit<MessagePayload<K>, "type" | "sender">
+  ? {
+      /** The message id. A payload field named `type` never overrides it. */
+      readonly type: K;
+      /** The URL the message came from. A payload field named `sender` never overrides it. */
+      readonly sender: Url;
+    } & Omit<MessagePayload<K>, "type" | "sender">
   : never;
 
-/** @noSelf */
+/**
+ * Returned by `messageEvents`. Build it once at module scope: it hashes the ids when it is
+ * created.
+ * @noSelf
+ */
 export interface MessageEventMapper<K extends MessageId> {
+  /**
+   * Turns the parameters of `on_message` into the event for that message, a new table on each
+   * call. Returns `undefined` for a message id that `messageEvents` was not given.
+   */
   readonly toEvent: (
     message_id: Hash,
     message: Record<string | number, unknown>,
@@ -11,6 +29,11 @@ export interface MessageEventMapper<K extends MessageId> {
   ) => MessageEvent<K> | undefined;
 }
 
+/**
+ * Builds a mapper that turns the Defold messages listed in `ids` into typed machine events of
+ * the shape `{ type: id, ...payload, sender }`. Call it once at module scope: the ids are hashed
+ * here.
+ */
 export function messageEvents<const K extends MessageId>(ids: readonly K[]): MessageEventMapper<K> {
   const hashes: Hash[] = [];
   for (let i = 0; i < ids.length; i++) {

package/dist/hsm/index.ts

@@ -1,10 +1,25 @@
+/**
+ * An event a machine handles: an object with a string `type`, plus any payload fields. A
+ * machine's event type is a union of these.
+ */
 export interface EventObject {
+  /** Names the event. A state's `on` takes these values as its keys. */
   readonly type: string;
 }
 
+/**
+ * What made a move happen: `event` for a sent event, `after` for a timer, `update` for a path an
+ * `update` hook returned, `always` for an `always` rule, `stop` for `stop()`, and `reload` for a
+ * hot reload that changed the current state.
+ */
 export type MoveCause = "event" | "after" | "update" | "stop" | "reload" | "always";
 
-/** @noSelf */
+/**
+ * A listener given to `onMove`. It gets the leaf left, the leaf entered (`undefined` after
+ * `stop()`), the cause, and the event, which is `undefined` unless the cause is `event`. It runs
+ * after the move's `enter` hooks.
+ * @noSelf
+ */
 export type MoveListener<E extends EventObject, P extends string = string> = (
   from: P,
   to: P | undefined,
@@ -12,14 +27,41 @@ export type MoveListener<E extends EventObject, P extends string = string> = (
   event: E | undefined,
 ) => void;
 
-/** @noSelf */
+/**
+ * One running machine, returned by `start`. `P` is the union of the machine's state paths; the
+ * `machine` a hook, a `run` or a `task` receives uses plain `string` paths instead.
+ * @noSelf
+ */
 export interface MachineInstance<Ctx, E extends EventObject, P extends string = string> {
+  /** The context passed to `start`. */
   readonly ctx: Ctx;
+  /**
+   * The full path of the deepest active state, or `undefined` once stopped. In a parallel state
+   * it is the first region's leaf.
+   */
   readonly path: P | undefined;
+  /**
+   * The full path of every active leaf, in region order: one path without parallel states, empty
+   * once stopped. It is the same array on every read, updated in place.
+   */
   readonly leaves: readonly P[];
+  /** Whether the state at the full path `path` is active. Ancestors of the current state count. */
   readonly matches: (path: P) => boolean;
+  /**
+   * Handles `event`, or queues it when called during a step. An event no active state handles is
+   * dropped, and once the machine is stopped the call does nothing.
+   */
   readonly send: (event: E) => void;
+  /**
+   * Advances the machine by `dt` seconds: runs the `update` hooks, then the `after` timers if no
+   * hook moved it. A machine whose `update` is not called is frozen in time, and once the machine
+   * is stopped the call does nothing.
+   */
   readonly update: (dt: number) => void;
+  /**
+   * Exits every active state, deepest first, and sets `path` to `undefined`. Called during a
+   * step, it lets that step finish and drops the queued events.
+   */
   readonly stop: () => void;
   /**
    * Adds a listener called after each move completes, with the leaf left, the leaf entered and
@@ -30,6 +72,10 @@ export interface MachineInstance<Ctx, E extends EventObject, P extends string =
   readonly onMove: (listener: MoveListener<E, P>) => () => void;
 }
 
+/**
+ * A function a rule's `run` calls during the move, after the `exit` hooks and before the `enter`
+ * hooks. Its `event` is the variant the `on` key names.
+ */
 export type MoveAction<Ctx, E extends EventObject, V extends E = E> = (
   ctx: Ctx,
   event: V,
@@ -45,7 +91,11 @@ interface RuleList<Rule> {
   readonly length: number;
 }
 
-/** @noSelf */
+/**
+ * The object form of a rule under `on`: a `to`, a `when` and a `run`, each optional. A rule with
+ * no `to` runs its `run` and nothing else: no state exits or enters.
+ * @noSelf
+ */
 export interface TransitionConfig<
   Ctx,
   E extends EventObject,
@@ -79,6 +129,10 @@ export interface TransitionConfig<
   readonly reenter?: never;
 }
 
+/**
+ * What an `on` key maps to: a target path, a `TransitionConfig`, or a non-empty list of them
+ * tried in order. The first rule with no `when`, or whose `when` returns `true`, is taken.
+ */
 export type TransitionSpec<
   Ctx,
   E extends EventObject,
@@ -86,8 +140,16 @@ export type TransitionSpec<
   To extends string = string,
 > = To | TransitionConfig<Ctx, E, V, To> | RuleList<TransitionConfig<Ctx, E, V, To>>;
 
-/** @noSelf */
+/**
+ * The object form of an `always` rule: a `to` and an optional `when`. It gets no event and has
+ * no `run`; side effects belong in the target's `enter`.
+ * @noSelf
+ */
 export interface AlwaysConfig<Ctx, To extends string = string> {
+  /**
+   * The full path of the state to move to. An `always` rule without one throws when the machine
+   * is defined.
+   */
   readonly to: To;
   /** Checked on every recheck, so it must have no side effects. */
   readonly when?: (ctx: Ctx) => boolean;
@@ -97,11 +159,19 @@ export interface AlwaysConfig<Ctx, To extends string = string> {
   readonly guard?: never;
 }
 
+/**
+ * What `always` takes: a target path, an `AlwaysConfig`, or a non-empty list of them. The first
+ * whose `when` is missing or passes is taken.
+ */
 export type AlwaysSpec<Ctx, To extends string = string> =
   | To
   | AlwaysConfig<Ctx, To>
   | RuleList<AlwaysConfig<Ctx, To>>;
 
+/**
+ * A state's rules by event `type`. Only the machine's event types are keys, and each rule's
+ * `when` and `run` see the event variant its key names.
+ */
 export type OnConfig<Ctx, E extends EventObject, To extends string = string> = {
   readonly [K in E["type"]]?: TransitionSpec<Ctx, E, Extract<E, { type: K }>, To>;
 };
@@ -116,6 +186,11 @@ export type StateHook<Ctx, E extends EventObject> = (
   machine: MachineInstance<Ctx, E>,
 ) => void;
 
+/**
+ * Runs on every `update(dt)` while the state is active, deepest state first. It returns a full
+ * path to move there, or `undefined` to pass. The first hook to return a path wins: the hooks
+ * above it and the `after` timers do not run on that call, and the move has no `run`.
+ */
 export type UpdateHook<Ctx, E extends EventObject, To extends string = string> = (
   ctx: Ctx,
   dt: number,
@@ -134,8 +209,17 @@ export type TaskStart<Ctx, E extends EventObject> = (
   // biome-ignore lint/suspicious/noConfusingVoidType: `void` keeps an expression-body task returning a void call (`=> go.animate(...)`) valid.
 ) => (() => void) | void;
 
-/** @noSelf */
+/**
+ * A machine definition, returned by the second `defineMachine` call. Its `start` creates the
+ * instances that run.
+ * @noSelf
+ */
 export interface Machine<Ctx, E extends EventObject, P extends string = string> {
+  /**
+   * Creates an instance with `ctx` as its context and enters the root's `initial` chain. Each
+   * call returns a separate instance, which has already handled the events its `enter` hooks
+   * sent.
+   */
   readonly start: (ctx: Ctx) => MachineInstance<Ctx, E, P>;
 }
 
@@ -173,6 +257,10 @@ type TreeOf<C> = C extends { readonly states: infer Children }
   ? { readonly [K in keyof Children]: TreeOf<Children[K]> }
   : unknown;
 
+/**
+ * The union of a config's state paths, each with its leading `/`. Paths are spelled out four
+ * levels deep; below that, any string under a fourth-level path is accepted.
+ */
 export type StatePath<C> = TreePath<TreeOf<C>>;
 
 // The levels of child states below a node. It counts tree levels, so above a parallel state
@@ -206,14 +294,41 @@ type AnyChild<Ctx, E extends EventObject, T, To extends string> = unknown extend
 // at the first such callback, before the states beside it are read.
 /** @noSelf */
 interface StateBase<Ctx, E extends EventObject, T, Self extends string, To extends string> {
+  /** Child states, by name. A name is non-empty and contains no `/`. */
   readonly states?: {
     readonly [K in keyof T]: StateNode<Ctx, E, T[K], `${Self}/${K & string}`, To>;
   } & NoInfer<AnyChild<Ctx, E, T, To>>;
+  /**
+   * Rules by event `type`, each a target path, a rule object or a list of them. An event starts
+   * at the deepest active state and moves up to the parent while no rule takes it.
+   */
   readonly on?: NoInfer<OnConfig<Ctx, E, To>>;
+  /**
+   * Targets by delay in seconds of game time. The delay is counted by `update(dt)` while the
+   * state is active, from zero on each entry. One `update` call fires at most one timer, and
+   * none when an `update` hook moved the machine.
+   */
   readonly after?: NoInfer<{ readonly [seconds: number]: To }>;
+  /**
+   * Targets taken right after any move that leaves this state active; the first whose `when` is
+   * missing or passes wins. It is checked after a move only: not after a rule with no `to`, and
+   * not on an `update` call that moves nothing.
+   */
   readonly always?: AlwaysSpec<Ctx, To>;
+  /**
+   * Runs each time the state is entered, outermost state first: on a move, at `start`, and when
+   * a hot reload adds the state. It gets no event.
+   */
   readonly enter?: StateHook<Ctx, E>;
+  /**
+   * Runs each time the state is left, deepest state first, including on `stop()`. A state a hot
+   * reload removes is dropped without it.
+   */
   readonly exit?: StateHook<Ctx, E>;
+  /**
+   * Runs on every `update(dt)` while the state is active. Return one of the machine's full paths
+   * to move there, or `undefined` to stay.
+   */
   readonly update?: NoInfer<UpdateHook<Ctx, E, To>>;
   /** Started on each entry; see `TaskStart`. */
   readonly task?: TaskStart<Ctx, E>;
@@ -224,14 +339,32 @@ interface StateBase<Ctx, E extends EventObject, T, Self extends string, To exten
 /** @noSelf */
 interface CompoundState<Ctx, E extends EventObject, T, Self extends string, To extends string>
   extends StateBase<Ctx, E, T, Self, To> {
+  /**
+   * `"parallel"` keeps every child active at once, each as a region with its own active state.
+   * Not allowed on the root.
+   */
   readonly type?: never;
+  /**
+   * The full path of the child entered with this state, such as `/on/bright` inside `on`.
+   * Required when `states` is set, unless the state is parallel.
+   */
   readonly initial?: NoInfer<unknown extends T ? string : `${Self}/${keyof T & string}`>;
+  /**
+   * Makes the state remember which child was active when it was last left, and enter it again
+   * instead of `initial`. The count is how many levels down to restore, and `"all"` restores
+   * every level below the state. The first entry uses `initial`, and a move that targets a state
+   * inside this one lands on that target.
+   */
   readonly restoreDepth?: NoInfer<TreeDepth<T, 4> | "all">;
 }
 
 /** @noSelf */
 interface ParallelState<Ctx, E extends EventObject, T, Self extends string, To extends string>
   extends StateBase<Ctx, E, T, Self, To> {
+  /**
+   * `"parallel"` keeps every child active at once, each as a region with its own active state.
+   * Not allowed on the root.
+   */
   readonly type: "parallel";
   readonly initial?: never;
   readonly restoreDepth?: never;
@@ -252,8 +385,17 @@ type RootState<Ctx, E extends EventObject, T> = CompoundState<
   readonly states: object;
 };
 
+/**
+ * The config of one state. Every field is optional. A state with child `states` is a compound
+ * state and needs an `initial`, unless its `type` is `"parallel"`; a state without children is a
+ * leaf.
+ */
 export type StateConfig<Ctx, E extends EventObject> = StateNode<Ctx, E, unknown, string, string>;
 
+/**
+ * The root config passed to `defineMachine`. It takes the fields of a state and requires
+ * `initial` and `states`. The root has no name and cannot be parallel.
+ */
 export type MachineConfig<Ctx, E extends EventObject> = CompoundState<
   Ctx,
   E,
@@ -1445,6 +1587,13 @@ function define<Ctx, E extends EventObject>(
 
 // Ctx and E are given explicitly and the config is inferred, so the config takes a second call.
 // A key makes a later definition under it (a hot-reloaded module re-running) rebind live instances.
+/**
+ * Defines a machine in two calls: `defineMachine<Ctx, E>()` fixes the context and event types and
+ * takes an optional hot-reload key, and the second call takes the config. The config is checked
+ * when that call runs, and a mistake throws, naming the state path. With a key, a later
+ * definition under it puts its states into the machine already built, so every running instance
+ * sees the edit; without one, each call builds a separate machine.
+ */
 export function defineMachine<Ctx, E extends EventObject>(
   key?: string,
 ): <T>(config: RootState<Ctx, E, T>) => Machine<Ctx, E, TreePath<T>> {

package/dist/index.js

@@ -3150,6 +3150,14 @@ function resolvedRequirePaths(sourceFile, checker) {
   }
   return paths;
 }
+var NO_RESOLUTION_MARKER = "@NoResolution:";
+function companionRequirePath(argument, paths) {
+  const resolved = paths.get(argument);
+  if (resolved !== undefined) {
+    return resolved;
+  }
+  return argument.startsWith(NO_RESOLUTION_MARKER) ? argument.slice(NO_RESOLUTION_MARKER.length) : argument;
+}
 function resolveMovedRequires(statements, paths) {
   for (const statement of statements) {
     forEachLuaNode(statement, (node) => {
@@ -3163,10 +3171,7 @@ function resolveMovedRequires(statements, paths) {
       if (argument === undefined || !isStringLiteral7(argument)) {
         return;
       }
-      const resolved = paths.get(argument.value);
-      if (resolved !== undefined) {
-        argument.value = resolved;
-      }
+      argument.value = companionRequirePath(argument.value, paths);
     });
   }
 }
@@ -3186,8 +3191,8 @@ function withResolvedRequire(statement, paths) {
   if (argument === undefined || !isStringLiteral7(argument)) {
     return statement;
   }
-  const resolved = paths.get(argument.value);
-  if (resolved === undefined) {
+  const resolved = companionRequirePath(argument.value, paths);
+  if (resolved === argument.value) {
     return statement;
   }
   return createVariableDeclarationStatement3(createIdentifier4(name.text), createCallExpression4(createIdentifier4("require"), [createStringLiteral3(resolved)]));
@@ -3655,7 +3660,7 @@ function collectOutputs(transpiledFiles, diagnostics, userKeys, emittedCompanion
     ...hsm !== undefined ? { hsmModules: hsm } : {}
   };
 }
-function transpileVirtual(files, companionEmit) {
+function transpileVirtual(files, companionEmit, overrides = {}) {
   return tstl2.transpileVirtualProject({ ...AMBIENT_FILES, ...files }, {
     luaTarget: tstl2.LuaTarget.Lua51,
     sourceMap: true,
@@ -3672,7 +3677,8 @@ function transpileVirtual(files, companionEmit) {
       { plugin: hsmLoweringPlugin },
       { plugin: typeApplicationErasurePlugin },
       { plugin: companionEmit.plugin }
-    ]
+    ],
+    ...overrides
   });
 }
 function transpileProject(input) {
@@ -3697,7 +3703,7 @@ function compileHsmModules() {
     nameByKey.set(key, name);
     files[key] = readFileSync(path3.join(sourceDir, `${name}.ts`), "utf8");
   }
-  const result = transpileVirtual(files, createCompanionEmitPlugin());
+  const result = transpileVirtual(files, createCompanionEmitPlugin(), { removeComments: true });
   const problems = result.diagnostics.map((d) => `${d.file?.fileName ?? "(project)"}: ${flattenDiagnosticMessage(d.messageText)}`);
   const lua = {};
   for (const file of result.transpiledFiles) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/transpiler",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "TypeScript-to-Lua build pipeline tuned for Defold's runtime.",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@defold-typescript/types": "0.45.0",
+    "@defold-typescript/types": "0.46.0",
     "@typescript-to-lua/language-extensions": "1.19.0",
     "typescript": "6.0.2",
     "typescript-to-lua": "^1.36.0"

package/src/companion-emit.ts

@@ -290,6 +290,27 @@ function resolvedRequirePaths(
   return paths;
 }
 
+/**
+ * The prefix a lowering puts on the require of a runtime module with no source in
+ * the program (`hsm`, the timers), which TSTL's resolver strips from the script.
+ */
+const NO_RESOLUTION_MARKER = "@NoResolution:";
+
+/**
+ * How the companion spells the require the Lua AST spells `argument`: a project
+ * source by its resolved path, and a marked runtime module without the marker.
+ * Left on, the marker is a path Defold cannot load and Windows cannot even name.
+ */
+function companionRequirePath(argument: string, paths: ReadonlyMap<string, string>): string {
+  const resolved = paths.get(argument);
+  if (resolved !== undefined) {
+    return resolved;
+  }
+  return argument.startsWith(NO_RESOLUTION_MARKER)
+    ? argument.slice(NO_RESOLUTION_MARKER.length)
+    : argument;
+}
+
 /**
  * Rewrites every `require` a moved statement carries, at whatever depth — a
  * re-export's is nested in the `do … end` block TSTL emits for it.
@@ -313,10 +334,7 @@ function resolveMovedRequires(
       if (argument === undefined || !isStringLiteral(argument)) {
         return;
       }
-      const resolved = paths.get(argument.value);
-      if (resolved !== undefined) {
-        argument.value = resolved;
-      }
+      argument.value = companionRequirePath(argument.value, paths);
     });
   }
 }
@@ -339,8 +357,8 @@ function withResolvedRequire(statement: Statement, paths: ReadonlyMap<string, st
   if (argument === undefined || !isStringLiteral(argument)) {
     return statement;
   }
-  const resolved = paths.get(argument.value);
-  if (resolved === undefined) {
+  const resolved = companionRequirePath(argument.value, paths);
+  if (resolved === argument.value) {
     return statement;
   }
   return createVariableDeclarationStatement(

package/src/transpile.ts

@@ -327,6 +327,7 @@ export function collectOutputs(
 function transpileVirtual(
   files: Readonly<Record<string, string>>,
   companionEmit: ReturnType<typeof createCompanionEmitPlugin>,
+  overrides: Pick<tstl.CompilerOptions, "removeComments"> = {},
 ): tstl.TranspileVirtualProjectResult {
   return tstl.transpileVirtualProject(
     { ...AMBIENT_FILES, ...files },
@@ -354,6 +355,7 @@ function transpileVirtual(
         { plugin: typeApplicationErasurePlugin },
         { plugin: companionEmit.plugin },
       ],
+      ...overrides,
     },
   );
 }
@@ -398,7 +400,9 @@ export function compileHsmModules(): Readonly<Record<string, string>> {
     nameByKey.set(key, name);
     files[key] = readFileSync(path.join(sourceDir, `${name}.ts`), "utf8");
   }
-  const result = transpileVirtual(files, createCompanionEmitPlugin());
+  // The source's doc comments are for the editor, which reads the declarations; the Lua a
+  // project gets carries none of them.
+  const result = transpileVirtual(files, createCompanionEmitPlugin(), { removeComments: true });
 
   const problems = result.diagnostics.map(
     (d) => `${d.file?.fileName ?? "(project)"}: ${flattenDiagnosticMessage(d.messageText)}`,