@defold-typescript/transpiler 0.5.2 → 0.5.3

package/dist/index.js

@@ -2,28 +2,143 @@
 import { readFileSync as readFileSync2 } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
 import * as path2 from "node:path";
-import * as ts2 from "typescript";
+import * as ts4 from "typescript";
 import * as tstl2 from "typescript-to-lua";
 
 // src/lifecycle-erasure.ts
-import * as ts from "typescript";
+import * as ts2 from "typescript";
 import {
   createAssignmentStatement,
+  createBinaryExpression as createBinaryExpression2,
+  createBlock as createBlock2,
+  createCallExpression as createCallExpression2,
+  createExpressionStatement,
+  createForInStatement,
+  createFunctionExpression as createFunctionExpression2,
+  createIdentifier as createIdentifier2,
+  createIfStatement as createIfStatement2,
+  createNilLiteral,
+  createReturnStatement,
+  createTableIndexExpression,
+  createVariableDeclarationStatement as createVariableDeclarationStatement2,
+  NodeFlags as NodeFlags2,
+  SyntaxKind as SyntaxKind4
+} from "typescript-to-lua";
+
+// src/message-dispatch-lowering.ts
+import * as ts from "typescript";
+import {
   createBinaryExpression,
   createBlock,
   createCallExpression,
-  createExpressionStatement,
-  createForInStatement,
   createFunctionExpression,
   createIdentifier,
   createIfStatement,
-  createNilLiteral,
-  createReturnStatement,
-  createTableIndexExpression,
+  createStringLiteral,
   createVariableDeclarationStatement,
   NodeFlags,
   SyntaxKind as SyntaxKind2
 } from "typescript-to-lua";
+var DISPATCH_MODULE = "@defold-typescript/types";
+var DISPATCH_NAME = "onMessage";
+var HANDLER_PARAM_TARGETS = ["self", "message", "sender"];
+function resolvesToDispatchExport(callee, checker) {
+  let symbol = checker.getSymbolAtLocation(callee);
+  if (symbol === undefined) {
+    return false;
+  }
+  if (symbol.flags & ts.SymbolFlags.Alias) {
+    symbol = checker.getAliasedSymbol(symbol);
+  }
+  if (symbol.getName() !== DISPATCH_NAME) {
+    return false;
+  }
+  const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+  if (declaration === undefined) {
+    return false;
+  }
+  return declaration.getSourceFile().fileName.includes(DISPATCH_MODULE);
+}
+function handlerName(property) {
+  const name = property.name;
+  if (name === undefined) {
+    return;
+  }
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) {
+    return name.text;
+  }
+  return;
+}
+function handlerFunction(property) {
+  if (ts.isMethodDeclaration(property) && property.body !== undefined) {
+    return property;
+  }
+  if (ts.isPropertyAssignment(property)) {
+    const initializer = property.initializer;
+    if (ts.isFunctionExpression(initializer) || ts.isArrowFunction(initializer)) {
+      return initializer;
+    }
+  }
+  return;
+}
+function isThisParameter(param) {
+  return ts.isIdentifier(param.name) && ts.identifierToKeywordKind(param.name) === ts.SyntaxKind.ThisKeyword;
+}
+function aliasStatements(fn) {
+  const params = fn.parameters.filter((param) => !isThisParameter(param));
+  const aliases = [];
+  params.forEach((param, index) => {
+    const engineName = HANDLER_PARAM_TARGETS[index];
+    if (engineName === undefined || !ts.isIdentifier(param.name)) {
+      return;
+    }
+    if (param.name.text !== engineName) {
+      aliases.push(createVariableDeclarationStatement(createIdentifier(param.name.text), createIdentifier(engineName)));
+    }
+  });
+  return aliases;
+}
+function handlerBody(fn, context) {
+  if (ts.isBlock(fn.body)) {
+    return context.transformStatements(fn.body.statements);
+  }
+  return context.transformStatements([ts.factory.createExpressionStatement(fn.body)]);
+}
+var messageDispatchLoweringPlugin = {
+  visitors: {
+    [ts.SyntaxKind.CallExpression]: (node, context) => {
+      const [handlersArg] = node.arguments;
+      if (node.arguments.length === 1 && handlersArg !== undefined && ts.isObjectLiteralExpression(handlersArg) && resolvesToDispatchExport(node.expression, context.checker)) {
+        let chain;
+        const properties = [...handlersArg.properties];
+        for (let i = properties.length - 1;i >= 0; i--) {
+          const property = properties[i];
+          if (property === undefined) {
+            continue;
+          }
+          const name = handlerName(property);
+          const fn = handlerFunction(property);
+          if (name === undefined || fn === undefined) {
+            continue;
+          }
+          const condition = createBinaryExpression(createIdentifier("message_id"), createCallExpression(createIdentifier("hash"), [createStringLiteral(name)]), SyntaxKind2.EqualityOperator);
+          const body = [...aliasStatements(fn), ...handlerBody(fn, context)];
+          chain = createIfStatement(condition, createBlock(body), chain);
+        }
+        const params = [
+          createIdentifier("self"),
+          createIdentifier("message_id"),
+          createIdentifier("message"),
+          createIdentifier("sender")
+        ];
+        return createFunctionExpression(createBlock(chain === undefined ? [] : [chain]), params, undefined, NodeFlags.Declaration, node);
+      }
+      return context.superTransformExpression(node);
+    }
+  }
+};
+
+// src/lifecycle-erasure.ts
 var FACTORY_MODULE = "@defold-typescript/types";
 var FACTORY_NAMES = new Set(["defineScript", "defineGuiScript", "defineRenderScript"]);
 function resolvesToFactoryExport(callee, checker) {
@@ -31,7 +146,7 @@ function resolvesToFactoryExport(callee, checker) {
   if (symbol === undefined) {
     return false;
   }
-  if (symbol.flags & ts.SymbolFlags.Alias) {
+  if (symbol.flags & ts2.SymbolFlags.Alias) {
     symbol = checker.getAliasedSymbol(symbol);
   }
   if (!FACTORY_NAMES.has(symbol.getName())) {
@@ -43,42 +158,52 @@ function resolvesToFactoryExport(callee, checker) {
   }
   return declaration.getSourceFile().fileName.includes(FACTORY_MODULE);
 }
-function isThisParameter(param) {
-  return ts.isIdentifier(param.name) && ts.identifierToKeywordKind(param.name) === ts.SyntaxKind.ThisKeyword;
+function isThisParameter2(param) {
+  return ts2.isIdentifier(param.name) && ts2.identifierToKeywordKind(param.name) === ts2.SyntaxKind.ThisKeyword;
 }
 function hookName(property) {
   const name = property.name;
   if (name === undefined) {
     return;
   }
-  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) {
+  if (ts2.isIdentifier(name) || ts2.isStringLiteral(name)) {
     return name.text;
   }
   return;
 }
 function hookFunction(property) {
-  if (ts.isMethodDeclaration(property) && property.body !== undefined) {
+  if (ts2.isMethodDeclaration(property) && property.body !== undefined) {
     return property;
   }
-  if (ts.isPropertyAssignment(property)) {
+  if (ts2.isPropertyAssignment(property)) {
     const initializer = property.initializer;
-    if (ts.isFunctionExpression(initializer) || ts.isArrowFunction(initializer)) {
+    if (ts2.isFunctionExpression(initializer) || ts2.isArrowFunction(initializer)) {
       return initializer;
     }
   }
   return;
 }
+function dispatcherInitializer(property, checker) {
+  if (!ts2.isPropertyAssignment(property)) {
+    return;
+  }
+  const initializer = property.initializer;
+  if (!ts2.isCallExpression(initializer)) {
+    return;
+  }
+  return resolvesToDispatchExport(initializer.expression, checker) ? initializer : undefined;
+}
 function transformHookBody(fn, context) {
-  if (ts.isBlock(fn.body)) {
+  if (ts2.isBlock(fn.body)) {
     return context.transformStatements(fn.body.statements);
   }
   return [createExpressionStatement(context.transformExpression(fn.body))];
 }
 function crossesFunctionBoundary(node) {
-  return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node);
+  return ts2.isFunctionDeclaration(node) || ts2.isFunctionExpression(node) || ts2.isArrowFunction(node) || ts2.isMethodDeclaration(node) || ts2.isGetAccessorDeclaration(node) || ts2.isSetAccessorDeclaration(node);
 }
 function initReturnsValue(fn) {
-  if (!ts.isBlock(fn.body)) {
+  if (!ts2.isBlock(fn.body)) {
     return true;
   }
   let found = false;
@@ -86,61 +211,68 @@ function initReturnsValue(fn) {
     if (found || crossesFunctionBoundary(node)) {
       return;
     }
-    if (ts.isReturnStatement(node) && node.expression !== undefined) {
+    if (ts2.isReturnStatement(node) && node.expression !== undefined) {
       found = true;
       return;
     }
-    ts.forEachChild(node, visit);
+    ts2.forEachChild(node, visit);
   };
-  ts.forEachChild(fn.body, visit);
+  ts2.forEachChild(fn.body, visit);
   return found;
 }
 function initBuilderBody(fn, context) {
-  if (ts.isBlock(fn.body)) {
+  if (ts2.isBlock(fn.body)) {
     return context.transformStatements(fn.body.statements);
   }
   return [createReturnStatement([context.transformExpression(fn.body)])];
 }
 function emitInitMerge(fn, context, property) {
-  const builder = createFunctionExpression(createBlock(initBuilderBody(fn, context)), [], undefined, NodeFlags.Declaration, fn);
-  const builderDecl = createVariableDeclarationStatement(createIdentifier("____init"), builder);
-  const stateDecl = createVariableDeclarationStatement(createIdentifier("____s"), createCallExpression(createIdentifier("____init"), []));
-  const mergeAssignment = createAssignmentStatement(createTableIndexExpression(createIdentifier("self"), createIdentifier("____k")), createIdentifier("____v"));
-  const forIn = createForInStatement(createBlock([mergeAssignment]), [createIdentifier("____k"), createIdentifier("____v")], [createCallExpression(createIdentifier("pairs"), [createIdentifier("____s")])]);
-  const guard = createIfStatement(createBinaryExpression(createIdentifier("____s"), createNilLiteral(), SyntaxKind2.InequalityOperator), createBlock([forIn]));
-  const initFn = createFunctionExpression(createBlock([stateDecl, guard]), [createIdentifier("self")], undefined, NodeFlags.Declaration, fn);
-  return [builderDecl, createAssignmentStatement(createIdentifier("init"), initFn, property)];
+  const builder = createFunctionExpression2(createBlock2(initBuilderBody(fn, context)), [], undefined, NodeFlags2.Declaration, fn);
+  const builderDecl = createVariableDeclarationStatement2(createIdentifier2("____init"), builder);
+  const stateDecl = createVariableDeclarationStatement2(createIdentifier2("____s"), createCallExpression2(createIdentifier2("____init"), []));
+  const mergeAssignment = createAssignmentStatement(createTableIndexExpression(createIdentifier2("self"), createIdentifier2("____k")), createIdentifier2("____v"));
+  const forIn = createForInStatement(createBlock2([mergeAssignment]), [createIdentifier2("____k"), createIdentifier2("____v")], [createCallExpression2(createIdentifier2("pairs"), [createIdentifier2("____s")])]);
+  const guard = createIfStatement2(createBinaryExpression2(createIdentifier2("____s"), createNilLiteral(), SyntaxKind4.InequalityOperator), createBlock2([forIn]));
+  const initFn = createFunctionExpression2(createBlock2([stateDecl, guard]), [createIdentifier2("self")], undefined, NodeFlags2.Declaration, fn);
+  return [builderDecl, createAssignmentStatement(createIdentifier2("init"), initFn, property)];
 }
 function eraseFactoryCall(expression, context) {
-  if (!ts.isCallExpression(expression)) {
+  if (!ts2.isCallExpression(expression)) {
     return;
   }
   if (!resolvesToFactoryExport(expression.expression, context.checker)) {
     return;
   }
   const hooks = expression.arguments[0];
-  if (hooks === undefined || !ts.isObjectLiteralExpression(hooks)) {
+  if (hooks === undefined || !ts2.isObjectLiteralExpression(hooks)) {
     return;
   }
   const statements = [];
   for (const property of hooks.properties) {
     const name = hookName(property);
+    if (name === undefined) {
+      continue;
+    }
     const fn = hookFunction(property);
-    if (name === undefined || fn === undefined) {
+    if (fn === undefined) {
+      const dispatch = dispatcherInitializer(property, context.checker);
+      if (dispatch !== undefined) {
+        statements.push(createAssignmentStatement(createIdentifier2(name), context.transformExpression(dispatch), property));
+      }
       continue;
     }
     if (name === "init" && initReturnsValue(fn)) {
       statements.push(...emitInitMerge(fn, context, property));
       continue;
     }
-    const params = fn.parameters.filter((param) => !isThisParameter(param) && ts.isIdentifier(param.name)).map((param) => context.transformExpression(param.name));
-    const fnExpression = createFunctionExpression(createBlock(transformHookBody(fn, context)), params, undefined, NodeFlags.Declaration, fn);
-    statements.push(createAssignmentStatement(createIdentifier(name), fnExpression, property));
+    const params = fn.parameters.filter((param) => !isThisParameter2(param) && ts2.isIdentifier(param.name)).map((param) => context.transformExpression(param.name));
+    const fnExpression = createFunctionExpression2(createBlock2(transformHookBody(fn, context)), params, undefined, NodeFlags2.Declaration, fn);
+    statements.push(createAssignmentStatement(createIdentifier2(name), fnExpression, property));
   }
   return statements;
 }
 function isFactoryOnlyImport(node) {
-  if (!ts.isStringLiteral(node.moduleSpecifier) || node.moduleSpecifier.text !== FACTORY_MODULE) {
+  if (!ts2.isStringLiteral(node.moduleSpecifier) || node.moduleSpecifier.text !== FACTORY_MODULE) {
     return false;
   }
   const clause = node.importClause;
@@ -148,15 +280,15 @@ function isFactoryOnlyImport(node) {
     return false;
   }
   const bindings = clause.namedBindings;
-  if (bindings === undefined || !ts.isNamedImports(bindings)) {
+  if (bindings === undefined || !ts2.isNamedImports(bindings)) {
     return false;
   }
   return bindings.elements.every((element) => FACTORY_NAMES.has((element.propertyName ?? element.name).text));
 }
 var lifecycleErasurePlugin = {
   visitors: {
-    [ts.SyntaxKind.ExpressionStatement]: (node, context) => eraseFactoryCall(node.expression, context) ?? context.superTransformStatements(node),
-    [ts.SyntaxKind.ExportAssignment]: (node, context) => {
+    [ts2.SyntaxKind.ExpressionStatement]: (node, context) => eraseFactoryCall(node.expression, context) ?? context.superTransformStatements(node),
+    [ts2.SyntaxKind.ExportAssignment]: (node, context) => {
       if (!node.isExportEquals) {
         const erased = eraseFactoryCall(node.expression, context);
         if (erased !== undefined) {
@@ -165,7 +297,48 @@ var lifecycleErasurePlugin = {
       }
       return context.superTransformStatements(node);
     },
-    [ts.SyntaxKind.ImportDeclaration]: (node, context) => isFactoryOnlyImport(node) ? [] : context.superTransformStatements(node)
+    [ts2.SyntaxKind.ImportDeclaration]: (node, context) => isFactoryOnlyImport(node) ? [] : context.superTransformStatements(node)
+  }
+};
+
+// src/message-guard-lowering.ts
+import * as ts3 from "typescript";
+import {
+  createBinaryExpression as createBinaryExpression3,
+  createCallExpression as createCallExpression3,
+  createIdentifier as createIdentifier3,
+  SyntaxKind as SyntaxKind6
+} from "typescript-to-lua";
+var GUARD_MODULE = "@defold-typescript/types";
+var GUARD_NAME = "isMessage";
+function resolvesToGuardExport(callee, checker) {
+  let symbol = checker.getSymbolAtLocation(callee);
+  if (symbol === undefined) {
+    return false;
+  }
+  if (symbol.flags & ts3.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);
+}
+var messageGuardLoweringPlugin = {
+  visitors: {
+    [ts3.SyntaxKind.CallExpression]: (node, context) => {
+      const [messageIdArg, , expectedArg] = node.arguments;
+      if (node.arguments.length === 3 && messageIdArg !== undefined && expectedArg !== undefined && resolvesToGuardExport(node.expression, context.checker)) {
+        const messageId = context.transformExpression(messageIdArg);
+        const expected = context.transformExpression(expectedArg);
+        return createBinaryExpression3(messageId, createCallExpression3(createIdentifier3("hash"), [expected]), SyntaxKind6.EqualityOperator, node);
+      }
+      return context.superTransformExpression(node);
+    }
   }
 };
 
@@ -191,6 +364,8 @@ function buildAmbientFiles() {
     "node_modules/@typescript-to-lua/language-extensions/index.d.ts": readFileSync(path.join(TSTL_LANG_EXT_ROOT, "index.d.ts"), "utf8"),
     "node_modules/@defold-typescript/types/src/core-types.ts": readAmbient("src/core-types.ts"),
     "node_modules/@defold-typescript/types/src/msg-overloads.d.ts": readAmbient("src/msg-overloads.d.ts"),
+    "node_modules/@defold-typescript/types/src/message-guard.d.ts": readAmbient("src/message-guard.d.ts"),
+    "node_modules/@defold-typescript/types/src/message-dispatch.d.ts": readAmbient("src/message-dispatch.d.ts"),
     "node_modules/@defold-typescript/types/src/lifecycle.ts": readAmbient("src/lifecycle.ts"),
     "node_modules/@defold-typescript/types/index.ts": [
       'export { defineGuiScript, defineRenderScript, defineScript } from "./src/lifecycle";',
@@ -241,7 +416,12 @@ function transpileProject(input) {
     luaTarget: tstl.LuaTarget.Lua54,
     sourceMap: true,
     skipLibCheck: true,
-    luaPlugins: [{ plugin: lifecycleErasurePlugin }]
+    noImplicitSelf: true,
+    luaPlugins: [
+      { plugin: lifecycleErasurePlugin },
+      { plugin: messageGuardLoweringPlugin },
+      { plugin: messageDispatchLoweringPlugin }
+    ]
   });
   return collectOutputs(result.transpiledFiles, result.diagnostics, userKeys);
 }
@@ -260,7 +440,12 @@ var COMPILER_OPTIONS = {
   luaTarget: tstl2.LuaTarget.Lua54,
   sourceMap: true,
   skipLibCheck: true,
-  luaPlugins: [{ plugin: lifecycleErasurePlugin }]
+  noImplicitSelf: true,
+  luaPlugins: [
+    { plugin: lifecycleErasurePlugin },
+    { plugin: messageGuardLoweringPlugin },
+    { plugin: messageDispatchLoweringPlugin }
+  ]
 };
 function normalizeSlashes(p) {
   return p.replace(/\\/g, "/");
@@ -300,7 +485,7 @@ function createTranspileSession() {
       if (cached) {
         return cached;
       }
-      const created = ts2.createSourceFile(fileName, content, ts2.ScriptTarget.Latest, false);
+      const created = ts4.createSourceFile(fileName, content, ts4.ScriptTarget.Latest, false);
       sourceFileCache.set(normalized, created);
       return created;
     }
@@ -319,7 +504,7 @@ function createTranspileSession() {
         return cached;
       }
       const fileContent = readFileSync2(filePath, "utf8");
-      const created = ts2.createSourceFile(filePath, fileContent, ts2.ScriptTarget.Latest, false);
+      const created = ts4.createSourceFile(filePath, fileContent, ts4.ScriptTarget.Latest, false);
       libCache.set(fileName, created);
       return created;
     }
@@ -332,10 +517,10 @@ function createTranspileSession() {
     return AMBIENT_FILES[normalized];
   }
   const host = {
-    fileExists: (fileName) => mergedContent(normalizeSlashes(fileName)) !== undefined || ts2.sys.fileExists(fileName),
+    fileExists: (fileName) => mergedContent(normalizeSlashes(fileName)) !== undefined || ts4.sys.fileExists(fileName),
     getCanonicalFileName: (fileName) => fileName,
     getCurrentDirectory: () => "",
-    getDefaultLibFileName: ts2.getDefaultLibFileName,
+    getDefaultLibFileName: ts4.getDefaultLibFileName,
     readFile: () => "",
     getNewLine: () => `
 `,
@@ -356,15 +541,15 @@ function createTranspileSession() {
     }
     const userKeys = new Set(userFiles.keys());
     const rootNames = [...Object.keys(AMBIENT_FILES).map(normalizeSlashes), ...userKeys];
-    program = ts2.createProgram(rootNames, COMPILER_OPTIONS, host, program);
-    const preEmitDiagnostics = ts2.getPreEmitDiagnostics(program);
+    program = ts4.createProgram(rootNames, COMPILER_OPTIONS, host, program);
+    const preEmitDiagnostics = ts4.getPreEmitDiagnostics(program);
     const collector = createOutputCollector();
     const { diagnostics: transpileDiagnostics } = new tstl2.Transpiler().emit({
       program,
       writeFile: collector.writeFile
     });
     const diagnostics = [
-      ...ts2.sortAndDeduplicateDiagnostics([...preEmitDiagnostics, ...transpileDiagnostics])
+      ...ts4.sortAndDeduplicateDiagnostics([...preEmitDiagnostics, ...transpileDiagnostics])
     ];
     return collectOutputs(collector.files, diagnostics, userKeys);
   }

package/dist/message-dispatch-lowering.d.ts

@@ -0,0 +1,4 @@
+import * as ts from "typescript";
+import { type Plugin } from "typescript-to-lua";
+export declare function resolvesToDispatchExport(callee: ts.Expression, checker: ts.TypeChecker): boolean;
+export declare const messageDispatchLoweringPlugin: Plugin;

package/dist/message-guard-lowering.d.ts

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

package/package.json

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

package/src/lifecycle-erasure.ts

@@ -20,6 +20,7 @@ import {
   SyntaxKind,
   type TransformationContext,
 } from "typescript-to-lua";
+import { resolvesToDispatchExport } from "./message-dispatch-lowering";
 
 const FACTORY_MODULE = "@defold-typescript/types";
 const FACTORY_NAMES = new Set(["defineScript", "defineGuiScript", "defineRenderScript"]);
@@ -77,6 +78,20 @@ function hookFunction(property: ts.ObjectLiteralElementLike): HookFunction | und
   return undefined;
 }
 
+function dispatcherInitializer(
+  property: ts.ObjectLiteralElementLike,
+  checker: ts.TypeChecker,
+): ts.CallExpression | undefined {
+  if (!ts.isPropertyAssignment(property)) {
+    return undefined;
+  }
+  const initializer = property.initializer;
+  if (!ts.isCallExpression(initializer)) {
+    return undefined;
+  }
+  return resolvesToDispatchExport(initializer.expression, checker) ? initializer : undefined;
+}
+
 function transformHookBody(fn: HookFunction, context: TransformationContext): Statement[] {
   if (ts.isBlock(fn.body)) {
     return context.transformStatements(fn.body.statements);
@@ -187,8 +202,24 @@ function eraseFactoryCall(
   const statements: Statement[] = [];
   for (const property of hooks.properties) {
     const name = hookName(property);
+    if (name === undefined) {
+      continue;
+    }
     const fn = hookFunction(property);
-    if (name === undefined || fn === undefined) {
+    if (fn === undefined) {
+      // A hook whose initializer is a recognized `onMessage({...})` call: let it
+      // route through the message-dispatch lowering, which yields the flat
+      // `function(self, message_id, message, sender)` chunk, then bind it.
+      const dispatch = dispatcherInitializer(property, context.checker);
+      if (dispatch !== undefined) {
+        statements.push(
+          createAssignmentStatement(
+            createIdentifier(name),
+            context.transformExpression(dispatch),
+            property,
+          ),
+        );
+      }
       continue;
     }
     if (name === "init" && initReturnsValue(fn)) {

package/src/message-dispatch-lowering.ts

@@ -0,0 +1,155 @@
+import * as ts from "typescript";
+import {
+  createBinaryExpression,
+  createBlock,
+  createCallExpression,
+  createFunctionExpression,
+  createIdentifier,
+  createIfStatement,
+  createStringLiteral,
+  createVariableDeclarationStatement,
+  type Expression,
+  type Identifier,
+  type IfStatement,
+  NodeFlags,
+  type Plugin,
+  type Statement,
+  SyntaxKind,
+  type TransformationContext,
+} from "typescript-to-lua";
+
+const DISPATCH_MODULE = "@defold-typescript/types";
+const DISPATCH_NAME = "onMessage";
+
+// The engine calls `on_message(self, message_id, message, sender)`; a handler's
+// own params (in order) alias onto these three value-bearing names.
+const HANDLER_PARAM_TARGETS = ["self", "message", "sender"] as const;
+
+export function resolvesToDispatchExport(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() !== DISPATCH_NAME) {
+    return false;
+  }
+  const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+  if (declaration === undefined) {
+    return false;
+  }
+  return declaration.getSourceFile().fileName.includes(DISPATCH_MODULE);
+}
+
+type HandlerFunction = (ts.MethodDeclaration | ts.FunctionExpression | ts.ArrowFunction) & {
+  body: ts.ConciseBody;
+};
+
+function handlerName(property: ts.ObjectLiteralElementLike): string | undefined {
+  const name = property.name;
+  if (name === undefined) {
+    return undefined;
+  }
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) {
+    return name.text;
+  }
+  return undefined;
+}
+
+function handlerFunction(property: ts.ObjectLiteralElementLike): HandlerFunction | undefined {
+  if (ts.isMethodDeclaration(property) && property.body !== undefined) {
+    return property as HandlerFunction;
+  }
+  if (ts.isPropertyAssignment(property)) {
+    const initializer = property.initializer;
+    if (ts.isFunctionExpression(initializer) || ts.isArrowFunction(initializer)) {
+      return initializer as HandlerFunction;
+    }
+  }
+  return undefined;
+}
+
+function isThisParameter(param: ts.ParameterDeclaration): boolean {
+  return (
+    ts.isIdentifier(param.name) &&
+    ts.identifierToKeywordKind(param.name) === ts.SyntaxKind.ThisKeyword
+  );
+}
+
+function aliasStatements(fn: HandlerFunction): Statement[] {
+  const params = fn.parameters.filter((param) => !isThisParameter(param));
+  const aliases: Statement[] = [];
+  params.forEach((param, index) => {
+    const engineName = HANDLER_PARAM_TARGETS[index];
+    if (engineName === undefined || !ts.isIdentifier(param.name)) {
+      return;
+    }
+    if (param.name.text !== engineName) {
+      aliases.push(
+        createVariableDeclarationStatement(
+          createIdentifier(param.name.text),
+          createIdentifier(engineName),
+        ),
+      );
+    }
+  });
+  return aliases;
+}
+
+function handlerBody(fn: HandlerFunction, context: TransformationContext): Statement[] {
+  if (ts.isBlock(fn.body)) {
+    return context.transformStatements(fn.body.statements);
+  }
+  return context.transformStatements([ts.factory.createExpressionStatement(fn.body)]);
+}
+
+export const messageDispatchLoweringPlugin: Plugin = {
+  visitors: {
+    [ts.SyntaxKind.CallExpression]: (node, context): Expression => {
+      const [handlersArg] = node.arguments;
+      if (
+        node.arguments.length === 1 &&
+        handlersArg !== undefined &&
+        ts.isObjectLiteralExpression(handlersArg) &&
+        resolvesToDispatchExport(node.expression, context.checker)
+      ) {
+        let chain: IfStatement | undefined;
+        const properties = [...handlersArg.properties];
+        for (let i = properties.length - 1; i >= 0; i--) {
+          const property = properties[i];
+          if (property === undefined) {
+            continue;
+          }
+          const name = handlerName(property);
+          const fn = handlerFunction(property);
+          if (name === undefined || fn === undefined) {
+            continue;
+          }
+          const condition = createBinaryExpression(
+            createIdentifier("message_id"),
+            createCallExpression(createIdentifier("hash"), [createStringLiteral(name)]),
+            SyntaxKind.EqualityOperator,
+          );
+          const body = [...aliasStatements(fn), ...handlerBody(fn, context)];
+          chain = createIfStatement(condition, createBlock(body), chain);
+        }
+        const params: Identifier[] = [
+          createIdentifier("self"),
+          createIdentifier("message_id"),
+          createIdentifier("message"),
+          createIdentifier("sender"),
+        ];
+        return createFunctionExpression(
+          createBlock(chain === undefined ? [] : [chain]),
+          params,
+          undefined,
+          NodeFlags.Declaration,
+          node,
+        );
+      }
+      return context.superTransformExpression(node);
+    },
+  },
+};

package/src/message-guard-lowering.ts

@@ -0,0 +1,54 @@
+import * as ts from "typescript";
+import {
+  createBinaryExpression,
+  createCallExpression,
+  createIdentifier,
+  type Expression,
+  type Plugin,
+  SyntaxKind,
+} from "typescript-to-lua";
+
+const GUARD_MODULE = "@defold-typescript/types";
+const GUARD_NAME = "isMessage";
+
+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 messageGuardLoweringPlugin: Plugin = {
+  visitors: {
+    [ts.SyntaxKind.CallExpression]: (node, context): Expression => {
+      const [messageIdArg, , expectedArg] = node.arguments;
+      if (
+        node.arguments.length === 3 &&
+        messageIdArg !== undefined &&
+        expectedArg !== undefined &&
+        resolvesToGuardExport(node.expression, context.checker)
+      ) {
+        const messageId = context.transformExpression(messageIdArg);
+        const expected = context.transformExpression(expectedArg);
+        return createBinaryExpression(
+          messageId,
+          createCallExpression(createIdentifier("hash"), [expected]),
+          SyntaxKind.EqualityOperator,
+          node,
+        );
+      }
+      return context.superTransformExpression(node);
+    },
+  },
+};

package/src/session.ts

@@ -4,6 +4,8 @@ import * as path from "node:path";
 import * as ts from "typescript";
 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 { AMBIENT_FILES, collectOutputs, type TranspileProjectResult } from "./transpile";
 
 export interface TranspileSession {
@@ -19,7 +21,14 @@ const COMPILER_OPTIONS: 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,
-  luaPlugins: [{ plugin: lifecycleErasurePlugin }],
+  // 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,
+  luaPlugins: [
+    { plugin: lifecycleErasurePlugin },
+    { plugin: messageGuardLoweringPlugin },
+    { plugin: messageDispatchLoweringPlugin },
+  ],
 };
 
 function normalizeSlashes(p: string): string {

package/src/transpile.ts

@@ -4,6 +4,8 @@ import * as path from "node:path";
 import type * as ts from "typescript";
 import * as tstl from "typescript-to-lua";
 import { lifecycleErasurePlugin } from "./lifecycle-erasure";
+import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
+import { messageGuardLoweringPlugin } from "./message-guard-lowering";
 
 export interface TranspileResult {
   readonly lua: string;
@@ -56,6 +58,11 @@ function buildAmbientFiles(): Record<string, string> {
     "node_modules/@defold-typescript/types/src/core-types.ts": readAmbient("src/core-types.ts"),
     "node_modules/@defold-typescript/types/src/msg-overloads.d.ts":
       readAmbient("src/msg-overloads.d.ts"),
+    "node_modules/@defold-typescript/types/src/message-guard.d.ts":
+      readAmbient("src/message-guard.d.ts"),
+    "node_modules/@defold-typescript/types/src/message-dispatch.d.ts": readAmbient(
+      "src/message-dispatch.d.ts",
+    ),
     "node_modules/@defold-typescript/types/src/lifecycle.ts": readAmbient("src/lifecycle.ts"),
     // Mirror the consumer-facing re-exports of the real package index so a user
     // file can `import { defineScript }` and `import type { Hash, Vector3 }`.
@@ -131,7 +138,14 @@ export function transpileProject(input: TranspileProjectInput): TranspileProject
     // 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,
-    luaPlugins: [{ plugin: lifecycleErasurePlugin }],
+    // 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,
+    luaPlugins: [
+      { plugin: lifecycleErasurePlugin },
+      { plugin: messageGuardLoweringPlugin },
+      { plugin: messageDispatchLoweringPlugin },
+    ],
   });
 
   return collectOutputs(result.transpiledFiles, result.diagnostics, userKeys);