@defold-typescript/transpiler 0.45.0 → 0.47.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,
@@ -723,6 +865,22 @@ interface Registered<Ctx, E extends EventObject> {
 
 const registered: { [key: string]: Registered<unknown, EventObject> } = {};
 
+// Adds the fields the root's privateCtx returns to ctx. With onlyMissing, a field ctx already
+// has keeps its value: a hot reload adds new private fields and leaves the old ones alone.
+function fillPrivate(
+  target: { [name: string]: unknown },
+  root: unknown,
+  onlyMissing: boolean,
+): void {
+  const factory = (root as Partial<PrivateCtxConfig<unknown, object>>).privateCtx;
+  const fields = (factory?.() || {}) as { [name: string]: unknown };
+  for (const name in fields) {
+    if (!onlyMissing || target[name] === undefined) {
+      target[name] = fields[name];
+    }
+  }
+}
+
 function createMachine<Ctx, E extends EventObject>(
   definition: Definition<Ctx, E>,
 ): Machine<Ctx, E> {
@@ -838,6 +996,7 @@ function createMachine<Ctx, E extends EventObject>(
       afterDelays = compiled.afterDelays;
       afterTargets = compiled.afterTargets;
       always = compiled.always;
+      fillPrivate(ctx as never, configs[ROOT], true);
       growSlots();
       const dropped: number[] = [];
       for (let i = 0; i < order.length; i++) {
@@ -1411,6 +1570,7 @@ function createMachine<Ctx, E extends EventObject>(
     }
 
     busy = true;
+    fillPrivate(ctx as never, configs[ROOT], false);
     enterState(ROOT);
     enterDefaults(ROOT, 0);
     refreshLeaves();
@@ -1445,8 +1605,126 @@ 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>> {
   return ((config: MachineConfig<Ctx, E>) => define(key, config)) as never;
 }
+
+/**
+ * The key a `definePrivateMachine` config adds to the root, beside `initial` and `states`.
+ * @noSelf
+ */
+export interface PrivateCtxConfig<Ctx, Priv> {
+  /**
+   * Builds the fields only the machine uses. It runs once per `start`, before the root's `enter`
+   * hook, so every instance gets fresh fields of its own; a value written straight into the
+   * config would be one array or table shared by every instance. It takes no arguments: to set
+   * a private field from a field of `Ctx`, do it in the root's `enter` hook.
+   *
+   * The fields are added to the object passed to `start`, which stays the instance's `ctx`, so
+   * restarting with `start(old.ctx)` keeps the public fields and builds the private ones fresh.
+   * A hot reload under the machine's key adds the fields a new factory introduces and leaves
+   * every field that already holds a value alone. A private field may not share a name with a
+   * field of `Ctx`.
+   *
+   * The fields are hidden from callers by type only. At run time `ctx` is one table, and hooks,
+   * `hsm-view` and a debugger see every field.
+   */
+  readonly privateCtx: () => Priv & { readonly [K in keyof Ctx & keyof Priv]: never };
+}
+
+/**
+ * Like `defineMachine`, for a machine that keeps fields of its own, such as a counter, a heat
+ * level or a list it builds up. The config's `privateCtx` returns those fields. Every hook,
+ * `when`, `run`, `task` and `update` sees them beside `Ctx`, while `start` takes only `Ctx` and
+ * the instance it returns shows only `Ctx` in its `ctx`. A machine without fields of its own
+ * uses `defineMachine`.
+ *
+ * There are two ways to type the fields.
+ *
+ * @example
+ * **Inferred.** For a few fields, write them inline and let TypeScript infer their types. Add
+ * `as` where the inferred type is wrong: an empty array is `never[]` until it reads
+ * `[] as Hash[]`, and a field holding one of several strings is any `string` until it reads
+ * `"cool" as "cool" | "hot"`.
+ *
+ * ```ts
+ * type TurretEvent = { type: "SPOTTED" } | { type: "LOST" };
+ *
+ * export const turret = definePrivateMachine<{ readonly fireRate: number }, TurretEvent>("turret")({
+ *   privateCtx: () => ({ heat: 0, targets: [] as Hash[] }),
+ *   initial: "/idle",
+ *   states: {
+ *     idle: { on: { SPOTTED: "/firing" } },
+ *     firing: {
+ *       enter: (ctx) => {
+ *         ctx.heat += 1 / ctx.fireRate;
+ *       },
+ *       on: { LOST: "/idle" },
+ *     },
+ *   },
+ * });
+ *
+ * const gun = turret.start({ fireRate: 2 }); // gun.ctx shows fireRate only
+ * ```
+ *
+ * @example
+ * **A named type.** For more fields, or when a helper outside the config needs the whole
+ * context, declare the fields as an interface and make it the factory's return type. The fields
+ * need no `as`, a misspelled or unknown field is a compile error, and the whole context is
+ * `TurretOptions & TurretPrivate`. `satisfies TurretPrivate` does not do this: it checks the
+ * object but keeps its narrow types, so an empty array stays `never[]`.
+ *
+ * ```ts
+ * interface TurretOptions {
+ *   readonly fireRate: number;
+ * }
+ *
+ * interface TurretPrivate {
+ *   heat: number;
+ *   mode: "cool" | "hot";
+ * }
+ *
+ * type TurretEvent = { type: "SPOTTED" } | { type: "LOST" };
+ *
+ * const overheated = (ctx: TurretOptions & TurretPrivate) => ctx.heat > ctx.fireRate;
+ *
+ * export const turret = definePrivateMachine<TurretOptions, TurretEvent>("turret")({
+ *   privateCtx: (): TurretPrivate => ({ heat: 0, mode: "cool" }),
+ *   initial: "/idle",
+ *   states: {
+ *     idle: { on: { SPOTTED: "/firing" } },
+ *     firing: {
+ *       enter: (ctx) => {
+ *         ctx.heat += 1 / ctx.fireRate;
+ *       },
+ *       always: { to: "/cooling", when: overheated },
+ *       on: { LOST: "/idle" },
+ *     },
+ *     cooling: {
+ *       enter: (ctx) => {
+ *         ctx.mode = "hot";
+ *       },
+ *       exit: (ctx) => {
+ *         ctx.heat = 0;
+ *         ctx.mode = "cool";
+ *       },
+ *       after: { 2: "/idle" },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export const definePrivateMachine: <Ctx, E extends EventObject>(
+  key?: string,
+) => <T, Priv extends object>(
+  config: RootState<Ctx & Priv, E, T> & PrivateCtxConfig<Ctx, Priv>,
+) => Machine<Ctx, E, TreePath<T>> = defineMachine as never;

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,12 +3660,13 @@ 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,
     lib: ["lib.es2022.d.ts"],
     skipLibCheck: true,
+    resolvePackageJsonImports: false,
     noImplicitSelf: true,
     luaPlugins: [
       { plugin: lifecycleErasurePlugin },
@@ -3672,7 +3678,8 @@ function transpileVirtual(files, companionEmit) {
       { plugin: hsmLoweringPlugin },
       { plugin: typeApplicationErasurePlugin },
       { plugin: companionEmit.plugin }
-    ]
+    ],
+    ...overrides
   });
 }
 function transpileProject(input) {
@@ -3697,7 +3704,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) {
@@ -3739,6 +3746,7 @@ function compilerOptions(companionEmit) {
     sourceMap: true,
     lib: ["lib.es2022.d.ts"],
     skipLibCheck: true,
+    resolvePackageJsonImports: false,
     noImplicitSelf: true,
     luaPlugins: [
       { plugin: lifecycleErasurePlugin },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/transpiler",
-  "version": "0.45.0",
+  "version": "0.47.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.47.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/session.ts

@@ -35,6 +35,13 @@ function compilerOptions(companionEmit: CompanionEmitter): tstl.CompilerOptions
     // Don't cross-check the seeded ambient .d.ts surface against itself; only user
     // files matter (mirrors transpileProject and the editor's skipLibCheck).
     skipLibCheck: true,
+    // TypeScript turns this on under its default `bundler` resolution. With it on,
+    // an error that has to name a module-declared type the file does not import
+    // (`Url`, `Hash`, `Vector3`) throws inside the checker, which builds a module
+    // specifier from an undefined base path and the virtual host's empty current
+    // directory. The virtual host reads every `package.json` as empty, so no `#`
+    // import resolves with the option on or off.
+    resolvePackageJsonImports: false,
     // Defold scripts are not OO: free helper functions never receive a context,
     // so suppress TSTL's implicit `self` parameter and the `_G` call-site filler.
     noImplicitSelf: true,

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 },
@@ -340,6 +341,13 @@ function transpileVirtual(
       // Don't cross-check the seeded ambient .d.ts surface against itself; we only
       // care about diagnostics on user files (mirrors the editor's skipLibCheck).
       skipLibCheck: true,
+      // TypeScript turns this on under its default `bundler` resolution. With it on,
+      // an error that has to name a module-declared type the file does not import
+      // (`Url`, `Hash`, `Vector3`) throws inside the checker, which builds a module
+      // specifier from an undefined base path and the virtual host's empty current
+      // directory. The virtual host reads every `package.json` as empty, so no `#`
+      // import resolves with the option on or off.
+      resolvePackageJsonImports: false,
       // Defold scripts are not OO: free helper functions never receive a context,
       // so suppress TSTL's implicit `self` parameter and the `_G` call-site filler.
       noImplicitSelf: true,
@@ -354,6 +362,7 @@ function transpileVirtual(
         { plugin: typeApplicationErasurePlugin },
         { plugin: companionEmit.plugin },
       ],
+      ...overrides,
     },
   );
 }
@@ -398,7 +407,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)}`,