@defold-typescript/transpiler 0.50.1 → 0.52.0

package/dist/lifecycle-erasure.d.ts

@@ -3,6 +3,7 @@ import { type Plugin } from "typescript-to-lua";
 export declare const FACTORY_MODULE = "@defold-typescript/types";
 export declare const FACTORY_NAMES: Set<string>;
 export declare function resolvesToFactoryExport(callee: ts.Expression, checker: ts.TypeChecker): boolean;
+export declare const RESOURCE_PROPERTY_MARKERS: ReadonlySet<string>;
 export interface PropertyMember {
     readonly name: string;
     readonly initializer: ts.Expression;

package/dist/physics-event-guard-lowering.d.ts

@@ -0,0 +1,2 @@
+import { type Plugin } from "typescript-to-lua";
+export declare const physicsEventGuardLoweringPlugin: Plugin;

package/dist/transpile.d.ts

@@ -22,6 +22,7 @@ export interface TranspileProjectResult {
     readonly lualib?: string;
     readonly timersRuntime?: string;
     readonly hsmModules?: Readonly<Record<string, string>>;
+    readonly hsmSourceMaps?: Readonly<Record<string, string>>;
 }
 export declare const AMBIENT_FILES: Readonly<Record<string, string>>;
 interface CollectableFile {
@@ -42,5 +43,7 @@ export declare function transpileProject(input: TranspileProjectInput): Transpil
  * lualib bundle.
  */
 export declare function compileHsmModules(): Readonly<Record<string, string>>;
+/** The source map of every module `compileHsmModules` returns, under the same keys. */
+export declare function compileHsmSourceMaps(): Readonly<Record<string, string>>;
 export declare function transpile(source: string): TranspileResult;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/transpiler",
-  "version": "0.50.1",
+  "version": "0.52.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.50.1",
+    "@defold-typescript/types": "0.52.0",
     "@typescript-to-lua/language-extensions": "1.19.0",
     "typescript": "6.0.2",
     "typescript-to-lua": "^1.36.0"

package/src/hsm-builtin.ts

@@ -7,8 +7,8 @@ import { scanEmittedRequires } from "./lua-require-scan";
 
 // `@defold-typescript/types/hsm` is the `index` module; every other module is a
 // subpath of it. Each lowers to a require of `defold_typescript_hsm.<module>`,
-// which the CLI writes under the output root the way it writes the timers
-// runtime.
+// which the CLI respells to the module's place in its runtime folder, the way it
+// handles the timers runtime.
 export const HSM_MODULE_SPECIFIER = "@defold-typescript/types/hsm";
 export const HSM_REQUIRE_ROOT = "defold_typescript_hsm";
 

package/src/index.ts

@@ -46,6 +46,7 @@ export {
   readGameProjectDependencies,
   readLibrarySceneDocuments,
 } from "./library-dependencies";
+export { scanEmittedRequires } from "./lua-require-scan";
 export { findMainEntryFactoryImports } from "./main-entry-factory-imports";
 export type { BuildConfig, ScriptKind, SourceOutputKind } from "./output-paths";
 export {

package/src/lifecycle-erasure.ts

@@ -35,22 +35,29 @@ const FACTORY_SPECIFIERS = new Set([
   `${FACTORY_MODULE}/render-script`,
 ]);
 
-export function resolvesToFactoryExport(callee: ts.Expression, checker: ts.TypeChecker): boolean {
+// The lifecycle factory a callee resolves to, aliases followed, or `undefined`
+// when it is not one of this package's factory exports.
+function factoryExportName(callee: ts.Expression, checker: ts.TypeChecker): string | undefined {
   let symbol = checker.getSymbolAtLocation(callee);
   if (symbol === undefined) {
-    return false;
+    return undefined;
   }
   if (symbol.flags & ts.SymbolFlags.Alias) {
     symbol = checker.getAliasedSymbol(symbol);
   }
-  if (!FACTORY_NAMES.has(symbol.getName())) {
-    return false;
+  const name = symbol.getName();
+  if (!FACTORY_NAMES.has(name)) {
+    return undefined;
   }
   const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
   if (declaration === undefined) {
-    return false;
+    return undefined;
   }
-  return declaration.getSourceFile().fileName.includes(FACTORY_MODULE);
+  return declaration.getSourceFile().fileName.includes(FACTORY_MODULE) ? name : undefined;
+}
+
+export function resolvesToFactoryExport(callee: ts.Expression, checker: ts.TypeChecker): boolean {
+  return factoryExportName(callee, checker) !== undefined;
 }
 
 function isThisParameter(param: ts.ParameterDeclaration): boolean {
@@ -208,6 +215,20 @@ function emitInitMerge(
   return [builderDecl, createAssignmentStatement(createIdentifier("init"), initFn, property)];
 }
 
+// Build-time markers, never engine functions: bob reads `resource.<kind>("path")`
+// only as a `go.property` default (`LuaScanner.java:923-933` at defold
+// `a81dbb04`), and the engine's `resource` table registers none of them
+// (`script_resource.cpp:3447-3463` in 1.14.0). Called anywhere else, each is nil.
+export const RESOURCE_PROPERTY_MARKERS: ReadonlySet<string> = new Set([
+  "resource.atlas",
+  "resource.buffer",
+  "resource.font",
+  "resource.material",
+  "resource.render_target",
+  "resource.texture",
+  "resource.tile_source",
+]);
+
 export interface PropertyMember {
   readonly name: string;
   readonly initializer: ts.Expression;
@@ -275,14 +296,171 @@ function emitPropertyRegistrations(
   );
 }
 
+// Defold builds `go.property` only in `.script` files, so a GUI or render
+// script's `properties` block has nothing it could lower to.
+function scriptOnlyProperties(
+  property: ts.ObjectLiteralElementLike,
+  factory: string,
+): ts.Diagnostic {
+  const file = property.getSourceFile();
+  const start = property.getStart(file);
+  return {
+    file,
+    start,
+    length: property.getEnd() - start,
+    category: ts.DiagnosticCategory.Error,
+    code: 0,
+    messageText: `\`${factory}\` cannot declare \`properties\`: Defold builds \`go.property\` only in \`.script\` files. Declare the property in a \`defineScript\` and send its value with \`msg.post\`.`,
+  };
+}
+
+// The outermost expression that only wraps `node` in parentheses or a type-only
+// form, so `(resource.atlas("/a.atlas") as Hash)` sits where the bare call would.
+function outermostWrapper(node: ts.Expression): ts.Expression {
+  let current = node;
+  while (
+    ts.isParenthesizedExpression(current.parent) ||
+    ts.isAsExpression(current.parent) ||
+    ts.isSatisfiesExpression(current.parent) ||
+    ts.isNonNullExpression(current.parent) ||
+    ts.isTypeAssertionExpression(current.parent)
+  ) {
+    current = current.parent;
+  }
+  return current;
+}
+
+// The inverse of `outermostWrapper`: the expression a run of parentheses and
+// type-only forms wraps, which TSTL emits in place of the whole run.
+function innermostExpression(node: ts.Expression): ts.Expression {
+  let current = node;
+  while (
+    ts.isParenthesizedExpression(current) ||
+    ts.isAsExpression(current) ||
+    ts.isSatisfiesExpression(current) ||
+    ts.isNonNullExpression(current) ||
+    ts.isTypeAssertionExpression(current)
+  ) {
+    current = current.expression;
+  }
+  return current;
+}
+
+// Keyed by the declaration's fully qualified name: only a symbol declared in an
+// ambient `declare global` block carries the `global.` prefix, so a project's
+// own `resource` never matches.
+function globalName(symbol: ts.Symbol | undefined, checker: ts.TypeChecker): string | undefined {
+  if (symbol === undefined) {
+    return undefined;
+  }
+  const fqn = checker.getFullyQualifiedName(symbol);
+  return fqn.startsWith("global.") ? fqn.slice("global.".length) : undefined;
+}
+
+function calledGlobal(call: ts.CallExpression, checker: ts.TypeChecker): string | undefined {
+  const declaration = checker.getResolvedSignature(call)?.declaration;
+  if (
+    declaration === undefined ||
+    !ts.isFunctionDeclaration(declaration) ||
+    declaration.name === undefined
+  ) {
+    return undefined;
+  }
+  return globalName(checker.getSymbolAtLocation(declaration.name), checker);
+}
+
+// A `properties` default of a factory call, or the default argument of a
+// direct `go.property` call: the two places bob reads a marker.
+function isPropertyDefault(call: ts.CallExpression, checker: ts.TypeChecker): boolean {
+  const value = outermostWrapper(call);
+  const parent = value.parent;
+  if (ts.isCallExpression(parent)) {
+    return parent.arguments[1] === value && calledGlobal(parent, checker) === "go.property";
+  }
+  const properties = parent?.parent?.parent;
+  if (
+    properties === undefined ||
+    !ts.isPropertyAssignment(properties) ||
+    !isPropertiesHook(properties)
+  ) {
+    return false;
+  }
+  const hooks = properties.parent;
+  return (
+    ts.isObjectLiteralExpression(hooks) &&
+    factoryHooks(hooks.parent as ts.Expression, checker) === hooks &&
+    propertyMembers(properties).some((member) => member.initializer === value)
+  );
+}
+
+function misplacedMarker(node: ts.Expression, marker: string): ts.Diagnostic {
+  const file = node.getSourceFile();
+  const start = node.getStart(file);
+  return {
+    file,
+    start,
+    length: node.getEnd() - start,
+    category: ts.DiagnosticCategory.Error,
+    code: 0,
+    messageText: `\`${marker}\` is a build-time marker: Defold's build reads it only in a \`go.property\` default, and the engine binds no such function. Use it as a \`defineScript\` \`properties\` default.`,
+  };
+}
+
+// Bob reads a default as a marker only when the emitted text is
+// `resource.<kind>("<path>")` or `resource.<kind>()`: the object token must be
+// `resource` with a dot `NAME` key, and the first argument a string literal or
+// absent (`LuaScanner.java:801-822`, `:923-933` and `:493-510` at defold
+// `a81dbb04`). The receiver test is textual like bob's; the marker resolution
+// has already excluded a project's own `resource`.
+function readsAsMarker(call: ts.CallExpression): boolean {
+  const callee = innermostExpression(call.expression);
+  if (ts.isOptionalChain(call) || ts.isOptionalChain(callee)) {
+    return false;
+  }
+  if (
+    !ts.isPropertyAccessExpression(callee) &&
+    !(
+      ts.isElementAccessExpression(callee) &&
+      ts.isStringLiteralLike(innermostExpression(callee.argumentExpression))
+    )
+  ) {
+    return false;
+  }
+  const receiver = innermostExpression(callee.expression);
+  if (!ts.isIdentifier(receiver) || receiver.text !== "resource") {
+    return false;
+  }
+  const [path] = call.arguments;
+  return path === undefined || ts.isStringLiteralLike(innermostExpression(path));
+}
+
+function unreadableMarker(node: ts.CallExpression, marker: string): ts.Diagnostic {
+  const file = node.getSourceFile();
+  const start = node.getStart(file);
+  return {
+    file,
+    start,
+    length: node.getEnd() - start,
+    category: ts.DiagnosticCategory.Error,
+    code: 0,
+    messageText: `\`${marker}\` in a property default must be written \`${marker}("<path>")\`, with a string literal path: Defold's build reads no other form.`,
+  };
+}
+
+function isCallee(node: ts.Expression): boolean {
+  const callee = outermostWrapper(node);
+  return ts.isCallExpression(callee.parent) && callee.parent.expression === callee;
+}
+
 function eraseFactoryCall(
   expression: ts.Expression,
   context: TransformationContext,
 ): Statement[] | undefined {
   const hooks = factoryHooks(expression, context.checker);
-  if (hooks === undefined) {
+  if (hooks === undefined || !ts.isCallExpression(expression)) {
     return undefined;
   }
+  const factory = factoryExportName(expression.expression, context.checker);
   const registrations: Statement[] = [];
   const statements: Statement[] = [];
   for (const property of hooks.properties) {
@@ -291,7 +469,11 @@ function eraseFactoryCall(
       continue;
     }
     if (name === "properties") {
-      registrations.push(...emitPropertyRegistrations(property, context));
+      if (factory === "defineScript") {
+        registrations.push(...emitPropertyRegistrations(property, context));
+      } else if (factory !== undefined && propertyMembers(property).length > 0) {
+        context.diagnostics.push(scriptOnlyProperties(property, factory));
+      }
       continue;
     }
     const fn = hookFunction(property);
@@ -374,5 +556,48 @@ export const lifecycleErasurePlugin: Plugin = {
     },
     [ts.SyntaxKind.ImportDeclaration]: (node, context) =>
       isFactoryOnlyImport(node) ? [] : context.superTransformStatements(node),
+    // TSTL's optional-chain lowering also visits nodes it synthesizes, which have
+    // no parent and no source span; only parsed nodes are checked.
+    [ts.SyntaxKind.CallExpression]: (node, context) => {
+      const marker = node.parent === undefined ? undefined : calledGlobal(node, context.checker);
+      if (marker !== undefined && RESOURCE_PROPERTY_MARKERS.has(marker)) {
+        if (!isPropertyDefault(node, context.checker)) {
+          context.diagnostics.push(misplacedMarker(node, marker));
+        } else if (!readsAsMarker(node)) {
+          context.diagnostics.push(unreadableMarker(node, marker));
+        }
+      }
+      return context.superTransformExpression(node);
+    },
+    [ts.SyntaxKind.PropertyAccessExpression]: (node, context) => {
+      if (node.parent !== undefined && !isCallee(node)) {
+        const marker = globalName(context.checker.getSymbolAtLocation(node.name), context.checker);
+        if (marker !== undefined && RESOURCE_PROPERTY_MARKERS.has(marker)) {
+          context.diagnostics.push(misplacedMarker(node, marker));
+        }
+      }
+      return context.superTransformExpression(node);
+    },
+    [ts.SyntaxKind.ElementAccessExpression]: (node, context) => {
+      if (node.parent !== undefined && !isCallee(node)) {
+        // The checker resolves a string key only when it is the direct argument,
+        // so a wrapped key is looked up by name on the receiver's type, as the
+        // checker does for a direct one.
+        const key = innermostExpression(node.argumentExpression);
+        const marker = ts.isStringLiteralLike(key)
+          ? globalName(
+              context.checker.getPropertyOfType(
+                context.checker.getTypeAtLocation(node.expression),
+                key.text,
+              ),
+              context.checker,
+            )
+          : undefined;
+        if (marker !== undefined && RESOURCE_PROPERTY_MARKERS.has(marker)) {
+          context.diagnostics.push(misplacedMarker(node, marker));
+        }
+      }
+      return context.superTransformExpression(node);
+    },
   },
 };

package/src/physics-event-guard-lowering.ts

@@ -0,0 +1,56 @@
+import * as ts from "typescript";
+import {
+  createBinaryExpression,
+  createCallExpression,
+  createIdentifier,
+  createStringLiteral,
+  createTableIndexExpression,
+  type Expression,
+  type Plugin,
+  SyntaxKind,
+} from "typescript-to-lua";
+
+const GUARD_MODULE = "@defold-typescript/types";
+const GUARD_NAME = "isPhysicsEvent";
+
+function resolvesToGuardExport(callee: ts.Expression, checker: ts.TypeChecker): boolean {
+  let symbol = checker.getSymbolAtLocation(callee);
+  if (symbol === undefined) {
+    return false;
+  }
+  if (symbol.flags & ts.SymbolFlags.Alias) {
+    symbol = checker.getAliasedSymbol(symbol);
+  }
+  if (symbol.getName() !== GUARD_NAME) {
+    return false;
+  }
+  const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+  if (declaration === undefined) {
+    return false;
+  }
+  return declaration.getSourceFile().fileName.includes(GUARD_MODULE);
+}
+
+export const physicsEventGuardLoweringPlugin: Plugin = {
+  visitors: {
+    [ts.SyntaxKind.CallExpression]: (node, context): Expression => {
+      const [eventArg, nameArg] = node.arguments;
+      if (
+        node.arguments.length === 2 &&
+        eventArg !== undefined &&
+        nameArg !== undefined &&
+        resolvesToGuardExport(node.expression, context.checker)
+      ) {
+        const event = context.transformExpression(eventArg);
+        const name = context.transformExpression(nameArg);
+        return createBinaryExpression(
+          createTableIndexExpression(event, createStringLiteral("type")),
+          createCallExpression(createIdentifier("hash"), [name]),
+          SyntaxKind.EqualityOperator,
+          node,
+        );
+      }
+      return context.superTransformExpression(node);
+    },
+  },
+};

package/src/program-diagnostics.ts

@@ -3,6 +3,7 @@ import * as tstl from "typescript-to-lua";
 import { lifecycleErasurePlugin } from "./lifecycle-erasure";
 import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
 import { messageGuardLoweringPlugin } from "./message-guard-lowering";
+import { physicsEventGuardLoweringPlugin } from "./physics-event-guard-lowering";
 import { timersLoweringPlugin } from "./timers-lowering";
 import { typeApplicationErasurePlugin } from "./type-application-erasure";
 import { windowEventGuardLoweringPlugin } from "./window-event-guard-lowering";
@@ -13,6 +14,7 @@ const LUA_PLUGINS: tstl.Plugin[] = [
   lifecycleErasurePlugin,
   messageGuardLoweringPlugin,
   windowEventGuardLoweringPlugin,
+  physicsEventGuardLoweringPlugin,
   messageDispatchLoweringPlugin,
   timersLoweringPlugin,
   typeApplicationErasurePlugin,

package/src/session.ts

@@ -9,6 +9,7 @@ import { hsmLoweringPlugin } from "./hsm-builtin";
 import { lifecycleErasurePlugin } from "./lifecycle-erasure";
 import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
 import { messageGuardLoweringPlugin } from "./message-guard-lowering";
+import { physicsEventGuardLoweringPlugin } from "./physics-event-guard-lowering";
 import { timersLoweringPlugin } from "./timers-lowering";
 import { AMBIENT_FILES, collectOutputs, type TranspileProjectResult } from "./transpile";
 import { typeApplicationErasurePlugin } from "./type-application-erasure";
@@ -50,6 +51,7 @@ function compilerOptions(companionEmit: CompanionEmitter): tstl.CompilerOptions
       { plugin: editorScriptErasurePlugin },
       { plugin: messageGuardLoweringPlugin },
       { plugin: windowEventGuardLoweringPlugin },
+      { plugin: physicsEventGuardLoweringPlugin },
       { plugin: messageDispatchLoweringPlugin },
       { plugin: timersLoweringPlugin },
       { plugin: hsmLoweringPlugin },

package/src/timers-runtime.ts

@@ -1,7 +1,7 @@
 // The importable polyfill specifier (matched by the type checker and the
 // lowering pass) and the flat Lua require name the import is rewritten to. The
-// CLI writes the runtime to `<require name>.lua` at the output root, mirroring
-// `lualib_bundle`, so `require("defold_typescript_timers")` resolves in Defold.
+// CLI writes the runtime into its runtime folder beside `lualib_bundle` and
+// respells every `require("defold_typescript_timers")` to that path.
 export const TIMERS_MODULE_SPECIFIER = "@defold-typescript/types/timers";
 export const TIMERS_REQUIRE_NAME = "defold_typescript_timers";
 

package/src/transpile.ts

@@ -21,6 +21,7 @@ import { lifecycleErasurePlugin } from "./lifecycle-erasure";
 import { scanEmittedRequires } from "./lua-require-scan";
 import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
 import { messageGuardLoweringPlugin } from "./message-guard-lowering";
+import { physicsEventGuardLoweringPlugin } from "./physics-event-guard-lowering";
 import { importsTimersModule, timersLoweringPlugin } from "./timers-lowering";
 import { TIMERS_RUNTIME } from "./timers-runtime";
 import { typeApplicationErasurePlugin } from "./type-application-erasure";
@@ -62,23 +63,27 @@ export interface TranspileProjectResult {
   // TSTL synthesizes this bundle (no user source) whenever a lualib feature is
   // registered — either by a user source using one (`Object.keys`, spread,
   // `__TS__TypeOf`, ...) or by the timers import lowering, whose generated
-  // runtime requires the bundle. The emitted `require("lualib_bundle")` only
-  // resolves in Defold if the CLI writes it to the output root. Absent when
+  // runtime requires the bundle. The emitted `require("lualib_bundle")` is an
+  // internal name the CLI respells to where it writes the bundle. Absent when
   // neither trigger fires.
   readonly lualib?: string;
   // Hand-authored runtime Lua for the `@defold-typescript/types/timers`
   // polyfills (`setTimeout`/`wait`/...). Unlike `defineScript`, the import is
-  // not erased — it lowers to `require("defold_typescript_timers")`, so the CLI
-  // must write this to the output root. Present only when a user file imports
-  // the module (pay-for-use).
+  // not erased — it lowers to `require("defold_typescript_timers")`, an
+  // internal name the CLI respells to where it writes this. Present only when
+  // a user file imports the module (pay-for-use).
   readonly timersRuntime?: string;
   // The compiled `hsm` modules the program requires, keyed by module name
   // (`index`, `defold`, ...). An hsm import lowers to
-  // `require("defold_typescript_hsm.<module>")`, so the CLI must write each one
-  // under the output root. Present only when some chunk requires one
-  // (pay-for-use); never carries a source map, since the `.ts` it would point
-  // at is not in the user's project.
+  // `require("defold_typescript_hsm.<module>")`, an internal name the CLI
+  // respells to where it writes each one. Present only when some chunk requires one
+  // (pay-for-use).
   readonly hsmModules?: Readonly<Record<string, string>>;
+  // The source map of each module in `hsmModules`, under the same keys. Its
+  // `sources` names `<module>.ts` with an empty `sourceRoot`: only the CLI knows
+  // where the module is written and where the hsm source sits, so it sets the
+  // root that joins them.
+  readonly hsmSourceMaps?: Readonly<Record<string, string>>;
 }
 
 function flattenDiagnosticMessage(
@@ -312,6 +317,7 @@ export function collectOutputs(
   }
 
   const hsm = hsmClosure([...Object.values(lua), ...Object.values(companions)], compileHsmModules);
+  const hsmSourceMaps = hsm === undefined ? undefined : selectHsmSourceMaps(Object.keys(hsm));
 
   return {
     lua,
@@ -321,9 +327,22 @@ export function collectOutputs(
     ...(lualib !== undefined ? { lualib } : {}),
     ...(timersImported ? { timersRuntime: TIMERS_RUNTIME } : {}),
     ...(hsm !== undefined ? { hsmModules: hsm } : {}),
+    ...(hsmSourceMaps !== undefined ? { hsmSourceMaps } : {}),
   };
 }
 
+function selectHsmSourceMaps(names: readonly string[]): Record<string, string> {
+  const maps = compileHsmSourceMaps();
+  const selected: Record<string, string> = {};
+  for (const name of names) {
+    const map = maps[name];
+    if (map !== undefined) {
+      selected[name] = map;
+    }
+  }
+  return selected;
+}
+
 function transpileVirtual(
   files: Readonly<Record<string, string>>,
   companionEmit: ReturnType<typeof createCompanionEmitPlugin>,
@@ -356,6 +375,7 @@ function transpileVirtual(
         { plugin: editorScriptErasurePlugin },
         { plugin: messageGuardLoweringPlugin },
         { plugin: windowEventGuardLoweringPlugin },
+        { plugin: physicsEventGuardLoweringPlugin },
         { plugin: messageDispatchLoweringPlugin },
         { plugin: timersLoweringPlugin },
         { plugin: hsmLoweringPlugin },
@@ -380,7 +400,12 @@ export function transpileProject(input: TranspileProjectInput): TranspileProject
   );
 }
 
-let compiledHsm: Readonly<Record<string, string>> | undefined;
+interface CompiledHsm {
+  readonly lua: Readonly<Record<string, string>>;
+  readonly sourceMaps: Readonly<Record<string, string>>;
+}
+
+let compiledHsm: CompiledHsm | undefined;
 
 function requiresLualib(lua: string): boolean {
   return scanEmittedRequires(lua).some(({ path: requirePath }) => requirePath === "lualib_bundle");
@@ -396,6 +421,15 @@ function requiresLualib(lua: string): boolean {
  * lualib bundle.
  */
 export function compileHsmModules(): Readonly<Record<string, string>> {
+  return compileHsm().lua;
+}
+
+/** The source map of every module `compileHsmModules` returns, under the same keys. */
+export function compileHsmSourceMaps(): Readonly<Record<string, string>> {
+  return compileHsm().sourceMaps;
+}
+
+function compileHsm(): CompiledHsm {
   if (compiledHsm !== undefined) {
     return compiledHsm;
   }
@@ -415,6 +449,7 @@ export function compileHsmModules(): Readonly<Record<string, string>> {
     (d) => `${d.file?.fileName ?? "(project)"}: ${flattenDiagnosticMessage(d.messageText)}`,
   );
   const lua: Record<string, string> = {};
+  const sourceMaps: Record<string, string> = {};
   for (const file of result.transpiledFiles) {
     if (isLualibBundle(file)) {
       continue;
@@ -428,14 +463,17 @@ export function compileHsmModules(): Readonly<Record<string, string>> {
       problems.push(`the compiled ${name} module requires lualib_bundle`);
     }
     lua[name] = file.lua;
+    if (typeof file.luaSourceMap === "string") {
+      sourceMaps[name] = file.luaSourceMap;
+    }
   }
   if (problems.length > 0) {
     throw new Error(
       `@defold-typescript/transpiler: the hsm library does not compile:\n  ${problems.join("\n  ")}`,
     );
   }
-  compiledHsm = lua;
-  return lua;
+  compiledHsm = { lua, sourceMaps };
+  return compiledHsm;
 }
 
 export function transpile(source: string): TranspileResult {