@defold-typescript/cli 0.5.2 → 0.5.3

package/README.md

@@ -4,11 +4,16 @@ The end-user CLI for scaffolding and building [Defold](https://defold.com/)
 projects written in TypeScript, transpiled to Lua.
 
 ```sh
-bunx @defold-typescript/cli init    # add TypeScript to a Defold project, or scaffold a new one
-bunx @defold-typescript/cli build   # transpile src/ to Lua alongside your Defold sources
-bunx @defold-typescript/cli watch   # rebuild on change
+bunx @defold-typescript/cli@latest init   # add TypeScript to a Defold project, or scaffold a new one
+bun install                               # install the scaffolded devDependencies (types, biome)
+bunx @defold-typescript/cli build         # transpile src/ to Lua alongside your Defold sources
+bunx @defold-typescript/cli watch         # rebuild on change
 ```
 
+Scaffold with the `@latest` tag — `init` writes your `@defold-typescript/types`
+version pin, so a stale `bunx` cache would pin an older release. Run `bun install`
+once after `init` to put the scaffolded dev dependencies on disk.
+
 The package name is scoped (`@defold-typescript/cli`); `bunx defold-typescript`
 without the scope resolves a different, nonexistent package. Install it to get
 the shorter `defold-typescript` binary on your `PATH` and pin the version:

package/dist/bin.js

@@ -231,6 +231,169 @@ import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFi
 import * as path6 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
+// src/debug-launcher.ts
+var PLATFORM_TARGETS = {
+  darwin: { enginePlatform: "x86_64-darwin", buildFolder: "x86_64-osx", executable: "dmengine" },
+  linux: { enginePlatform: "x86_64-linux", buildFolder: "x86_64-linux", executable: "dmengine" },
+  win32: {
+    enginePlatform: "x86_64-win32",
+    buildFolder: "x86_64-win32",
+    executable: "dmengine.exe"
+  }
+};
+var ENGINE_INFO_URL = "https://d.defold.com/stable/info.json";
+var ENGINE_ARCHIVE_BASE = "https://d.defold.com/archive/stable";
+var DEBUG_LAUNCHER_REL = ".vscode/defold-debug.ts";
+function debugLaunchConfig() {
+  return {
+    name: "Defold: Debug (TypeScript)",
+    type: "lua-local",
+    request: "launch",
+    stopOnEntry: false,
+    verbose: false,
+    internalConsoleOptions: "openOnSessionStart",
+    program: { command: "bun" },
+    args: [DEBUG_LAUNCHER_REL]
+  };
+}
+var VSCODE_LAUNCH_CONTENT = {
+  version: "0.2.0",
+  configurations: [debugLaunchConfig()]
+};
+function renderDebugLauncher() {
+  const targets = JSON.stringify(PLATFORM_TARGETS, null, 2);
+  return `import { chmodSync, copyFileSync, existsSync, mkdirSync } from "node:fs";
+import * as path from "node:path";
+
+// Windows only: paths to OpenAL32.dll and wrap_oal.dll from your Defold SDK
+// (defoldsdk/ext/lib/x86_64-win32/). Leave empty on macOS/Linux.
+const WINDOWS_OPENAL32_PATH = "";
+const WINDOWS_WRAPOAL_PATH = "";
+
+interface EngineTarget {
+  enginePlatform: string;
+  buildFolder: string;
+  executable: string;
+}
+
+const PLATFORM_TARGETS: Record<string, EngineTarget> = ${targets};
+
+const ENGINE_INFO_URL = "${ENGINE_INFO_URL}";
+const ENGINE_ARCHIVE_BASE = "${ENGINE_ARCHIVE_BASE}";
+
+const target = PLATFORM_TARGETS[process.platform];
+if (!target) {
+  console.error(\`Unsupported platform: \${process.platform}\`);
+  process.exit(1);
+}
+
+const here = path.dirname(new URL(import.meta.url).pathname);
+const stockEnginePath = path.join(here, target.executable);
+
+if (!existsSync(stockEnginePath)) {
+  const info = (await (await fetch(ENGINE_INFO_URL)).json()) as { sha1: string };
+  const url = \`\${ENGINE_ARCHIVE_BASE}/\${info.sha1}/engine/\${target.enginePlatform}/\${target.executable}\`;
+  console.log(\`Fetching \${url}\`);
+  const res = await fetch(url);
+  if (!res.ok) {
+    console.error(\`Engine download failed: \${res.status} \${res.statusText}\`);
+    process.exit(1);
+  }
+  await Bun.write(stockEnginePath, res);
+}
+
+const buildFolder = path.join("build", target.buildFolder);
+const buildEnginePath = path.join(buildFolder, target.executable);
+let enginePath = existsSync(buildEnginePath) ? buildEnginePath : stockEnginePath;
+
+if (process.platform === "win32" && enginePath === buildEnginePath) {
+  for (const [src, name] of [
+    [WINDOWS_OPENAL32_PATH, "OpenAL32.dll"],
+    [WINDOWS_WRAPOAL_PATH, "wrap_oal.dll"],
+  ] as const) {
+    const dest = path.join(buildFolder, name);
+    if (src && !existsSync(dest)) {
+      copyFileSync(src, dest);
+    }
+  }
+}
+
+// macOS: a build engine launched in place attaches to the editor process; copy
+// it aside first so it runs standalone.
+if (process.platform === "darwin" && enginePath === buildEnginePath) {
+  const tempEngine = path.join(buildFolder, "temp", target.executable);
+  mkdirSync(path.dirname(tempEngine), { recursive: true });
+  copyFileSync(buildEnginePath, tempEngine);
+  enginePath = tempEngine;
+}
+
+if (process.platform !== "win32") {
+  chmodSync(enginePath, 0o755);
+}
+
+const projectc = path.join("build", "default", "game.projectc");
+console.log(\`Launching \${enginePath} \${projectc}\`);
+const proc = Bun.spawn([enginePath, projectc], {
+  stdio: ["inherit", "inherit", "inherit"],
+});
+process.exit(await proc.exited);
+`;
+}
+var DEBUG_LAUNCHER_SOURCE = renderDebugLauncher();
+
+// src/mise-scaffold.ts
+var MANAGED_MARKER = "# managed by @defold-typescript";
+var MISE_TASKS_TOML = `${MANAGED_MARKER}
+[tasks."defold-typescript:build"]
+description = "Build the TypeScript sources with the installed defold-typescript CLI"
+run = "bunx --no-install defold-typescript build"
+
+${MANAGED_MARKER}
+[tasks."defold-typescript:watch"]
+description = "Watch and rebuild the TypeScript sources with the installed defold-typescript CLI"
+run = "bunx --no-install defold-typescript watch"
+
+${MANAGED_MARKER}
+[tasks."defold-typescript:upgrade"]
+description = "Upgrade the defold-typescript CLI to its latest release and re-pin the types dependency"
+run = ["bunx @defold-typescript/cli@latest init --force", "bun install"]
+`;
+function stripManagedBlocks(text) {
+  const lines = text.split(`
+`);
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i] ?? "";
+    if (line.trim() === MANAGED_MARKER) {
+      i += 1;
+      while (i < lines.length && (lines[i] ?? "").trim() !== "") {
+        i += 1;
+      }
+      if (i < lines.length) {
+        i += 1;
+      }
+      continue;
+    }
+    out.push(line);
+    i += 1;
+  }
+  return out.join(`
+`);
+}
+function mergeMiseToml(existing) {
+  if (existing === undefined) {
+    return MISE_TASKS_TOML;
+  }
+  const userContent = stripManagedBlocks(existing).replace(/\s*$/, "");
+  if (userContent === "") {
+    return MISE_TASKS_TOML;
+  }
+  return `${userContent}
+
+${MISE_TASKS_TOML}`;
+}
+
 // src/script-kind.ts
 var DEFAULT_TYPES_ENTRYPOINT = "@defold-typescript/types";
 var KIND_BY_EXT = {
@@ -342,43 +505,64 @@ var BIOME_JSON_CONTENT = {
   }
 };
 var VSCODE_EXTENSIONS_CONTENT = {
-  recommendations: ["sumneko.lua", "astronachos.defold"],
+  recommendations: ["sumneko.lua", "astronachos.defold", "tomblind.local-lua-debugger-vscode"],
   unwantedRecommendations: ["johnnymorganz.luau-lsp"]
 };
 var VSCODE_SETTINGS_CONTENT = {
   "Lua.workspace.ignoreDir": ["src"]
 };
+var HOOK_COMMENTS = {
+  init: "Initialize the component and return its state.",
+  update: "Update the component every frame; `dt` is the time step.",
+  fixed_update: "Update at the fixed physics time step.",
+  late_update: "Update every frame after `update`.",
+  on_message: "Handle an incoming message.",
+  on_input: "Handle input once input focus is acquired.",
+  final: "Clean up when the component is deleted.",
+  on_reload: "React to a hot reload of this script."
+};
+var HOOK_SIGNATURES = {
+  init: "",
+  update: "self, dt",
+  fixed_update: "self, dt",
+  late_update: "self, dt",
+  on_message: "self, message_id, message, sender",
+  on_input: "self, action_id, action",
+  final: "self",
+  on_reload: "self"
+};
+var SNIPPET_HOOK_ORDER = Object.keys(HOOK_SIGNATURES);
+function hookLines(includeOnInput, startTabStop) {
+  const lines = [];
+  let tabStop = startTabStop;
+  for (const hook of SNIPPET_HOOK_ORDER) {
+    if (hook === "init") {
+      continue;
+    }
+    if (hook === "on_input" && !includeOnInput) {
+      continue;
+    }
+    lines.push(`  // ${HOOK_COMMENTS[hook]}`);
+    lines.push(`  ${hook}(${HOOK_SIGNATURES[hook]}) {$${tabStop}},`);
+    tabStop += 1;
+  }
+  return lines;
+}
 function inlineSnippetBody(factory, includeOnInput) {
-  const lines = [
+  return [
     `import { ${factory} } from "@defold-typescript/types";`,
     "",
     `export const script = ${factory}({`,
-    "  // Initialize the component and return its state.",
+    `  // ${HOOK_COMMENTS.init}`,
     "  init() {",
     "    return { $0 };",
     "  },",
-    "  // Update the component every frame; `dt` is the time step.",
-    "  update(self, dt) {$1},",
-    "  // Update at the fixed physics time step.",
-    "  fixed_update(self, dt) {$2},",
-    "  // Update every frame after `update`.",
-    "  late_update(self, dt) {$3},",
-    "  // Handle an incoming message.",
-    "  on_message(self, message_id, message, sender) {$4},"
+    ...hookLines(includeOnInput, 1),
+    "});"
   ];
-  if (includeOnInput) {
-    lines.push("  // Handle input once input focus is acquired.");
-    lines.push("  on_input(self, action_id, action) {$5},");
-  }
-  lines.push("  // Clean up when the component is deleted.");
-  lines.push("  final(self) {$6},");
-  lines.push("  // React to a hot reload of this script.");
-  lines.push("  on_reload(self) {$7},");
-  lines.push("});");
-  return lines;
 }
 function typedSnippetBody(factory, includeOnInput) {
-  const lines = [
+  return [
     `import { ${factory} } from "@defold-typescript/types";`,
     "",
     "type Self = {",
@@ -387,29 +571,13 @@ function typedSnippetBody(factory, includeOnInput) {
     "};",
     "",
     `export const script = ${factory}<Self>({`,
-    "  // Initialize the component and return its state.",
+    `  // ${HOOK_COMMENTS.init}`,
     "  init(): Self {",
     "    return { $0 };",
     "  },",
-    "  // Update the component every frame; `dt` is the time step.",
-    "  update(self, dt) {$2},",
-    "  // Update at the fixed physics time step.",
-    "  fixed_update(self, dt) {$3},",
-    "  // Update every frame after `update`.",
-    "  late_update(self, dt) {$4},",
-    "  // Handle an incoming message.",
-    "  on_message(self, message_id, message, sender) {$5},"
+    ...hookLines(includeOnInput, 2),
+    "});"
   ];
-  if (includeOnInput) {
-    lines.push("  // Handle input once input focus is acquired.");
-    lines.push("  on_input(self, action_id, action) {$6},");
-  }
-  lines.push("  // Clean up when the component is deleted.");
-  lines.push("  final(self) {$7},");
-  lines.push("  // React to a hot reload of this script.");
-  lines.push("  on_reload(self) {$8},");
-  lines.push("});");
-  return lines;
 }
 var VSCODE_SNIPPETS_CONTENT = {
   "Defold script (inferred self)": {
@@ -522,6 +690,12 @@ function writeBiome(cwd, written) {
   writeJson(biomePath, BIOME_JSON_CONTENT);
   written.push("biome.json");
 }
+function writeMiseTasks(cwd, written) {
+  const misePath = path6.join(cwd, "mise.toml");
+  const existing = existsSync2(misePath) ? readFileSync5(misePath, "utf8") : undefined;
+  writeFileSync2(misePath, mergeMiseToml(existing));
+  written.push("mise.toml");
+}
 function parseJsonc(text) {
   let out = "";
   let inString = false;
@@ -643,6 +817,39 @@ function writeVscodeSnippets(cwd, written) {
   writeJson(filePath, VSCODE_SNIPPETS_CONTENT);
   written.push(".vscode/defold-typescript.code-snippets");
 }
+function writeVscodeLaunch(cwd, written) {
+  const dir = path6.join(cwd, ".vscode");
+  const filePath = path6.join(dir, "launch.json");
+  const ours = debugLaunchConfig();
+  if (existsSync2(filePath)) {
+    const existing = readVscodeJson(filePath);
+    if (existing === null) {
+      return;
+    }
+    const configs = Array.isArray(existing.configurations) ? [...existing.configurations] : [];
+    const names = new Set(configs.map((c) => isJsonObject(c) ? c.name : undefined));
+    if (!names.has(ours.name)) {
+      configs.push(ours);
+    }
+    existing.configurations = configs;
+    existing.version ??= VSCODE_LAUNCH_CONTENT.version;
+    writeJson(filePath, existing);
+    return;
+  }
+  mkdirSync2(dir, { recursive: true });
+  writeJson(filePath, VSCODE_LAUNCH_CONTENT);
+  written.push(".vscode/launch.json");
+}
+function writeVscodeDebugLauncher(cwd, written) {
+  const dir = path6.join(cwd, ".vscode");
+  const filePath = path6.join(dir, "defold-debug.ts");
+  if (existsSync2(filePath)) {
+    return;
+  }
+  mkdirSync2(dir, { recursive: true });
+  writeFileSync2(filePath, DEBUG_LAUNCHER_SOURCE);
+  written.push(".vscode/defold-debug.ts");
+}
 function writeTsSurface(cwd, written, force = false) {
   mkdirSync2(path6.join(cwd, "src"), { recursive: true });
   writeFileSync2(path6.join(cwd, "src", "main.ts"), MAIN_TS_CONTENT);
@@ -684,9 +891,12 @@ function writeTsSurface(cwd, written, force = false) {
   writeGitignore(cwd);
   written.push(".gitignore");
   writeBiome(cwd, written);
+  writeMiseTasks(cwd, written);
   writeVscodeExtensions(cwd, written);
   writeVscodeSettings(cwd, written);
   writeVscodeSnippets(cwd, written);
+  writeVscodeLaunch(cwd, written);
+  writeVscodeDebugLauncher(cwd, written);
   return selectScriptKind(kinds);
 }
 function runNewProjectInit(cwd, force = false) {
@@ -769,7 +979,7 @@ function materializeApiSurface(opts) {
   const excluded = excludedModulesForKind(opts.scriptKind ?? null);
   const sources = listDts(sourceGeneratedDir).filter((file) => file !== "index.d.ts").filter((file) => !excluded.has(file.replace(/\.d\.ts$/, "")));
   const srcDir = path7.resolve(sourceGeneratedDir, "..", "src");
-  const overloads = ["msg-overloads.d.ts", "go-overloads.d.ts"].filter((file) => existsSync3(path7.join(srcDir, file)));
+  const overloads = ["msg-overloads.d.ts", "message-guard.d.ts", "go-overloads.d.ts"].filter((file) => existsSync3(path7.join(srcDir, file)));
   const coreTypesSrc = path7.join(srcDir, "core-types.ts");
   const includeCoreTypes = overloads.length > 0 && existsSync3(coreTypesSrc);
   const engineGlobalsSrc = path7.join(srcDir, "engine-globals.d.ts");
@@ -844,12 +1054,16 @@ function ensureMaterializedReference(cwd, materializedDir) {
   const tsconfigPath = path7.join(cwd, "tsconfig.json");
   if (existsSync3(tsconfigPath)) {
     const tsconfig = JSON.parse(readFileSync6(tsconfigPath, "utf8"));
-    tsconfig.compilerOptions = {
-      ...tsconfig.compilerOptions ?? {},
-      typeRoots: [MATERIALIZED_ROOT],
-      types: [surfaceId]
-    };
-    writeJson2(tsconfigPath, tsconfig);
+    const current = tsconfig.compilerOptions ?? {};
+    const alreadyRepointed = JSON.stringify(current.typeRoots) === JSON.stringify([MATERIALIZED_ROOT]) && JSON.stringify(current.types) === JSON.stringify([surfaceId]);
+    if (!alreadyRepointed) {
+      tsconfig.compilerOptions = {
+        ...current,
+        typeRoots: [MATERIALIZED_ROOT],
+        types: [surfaceId]
+      };
+      writeJson2(tsconfigPath, tsconfig);
+    }
   }
   ensureGitignoreLine(cwd, `${MATERIALIZED_ROOT}/`);
 }

package/dist/debug-launcher.d.ts

@@ -0,0 +1,43 @@
+export interface EngineTarget {
+    readonly enginePlatform: string;
+    readonly buildFolder: string;
+    readonly executable: string;
+}
+export declare const DEBUG_LAUNCHER_REL = ".vscode/defold-debug.ts";
+export declare function targetPlatform(platform: NodeJS.Platform): EngineTarget;
+export declare function engineDownloadUrl(sha1: string, enginePlatform: string, executable: string): string;
+export interface ResolveEngineOptions {
+    readonly cwd: string;
+    readonly target: EngineTarget;
+    readonly stockPath: string;
+    readonly probe: (candidate: string) => boolean;
+}
+export declare function resolveEnginePath(opts: ResolveEngineOptions): string;
+export declare function debugLaunchConfig(): {
+    name: string;
+    type: string;
+    request: string;
+    stopOnEntry: boolean;
+    verbose: boolean;
+    internalConsoleOptions: string;
+    program: {
+        command: string;
+    };
+    args: string[];
+};
+export declare const VSCODE_LAUNCH_CONTENT: {
+    version: string;
+    configurations: {
+        name: string;
+        type: string;
+        request: string;
+        stopOnEntry: boolean;
+        verbose: boolean;
+        internalConsoleOptions: string;
+        program: {
+            command: string;
+        };
+        args: string[];
+    }[];
+};
+export declare const DEBUG_LAUNCHER_SOURCE: string;

package/dist/index.js

@@ -295,6 +295,169 @@ import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFi
 import * as path7 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
+// src/debug-launcher.ts
+var PLATFORM_TARGETS = {
+  darwin: { enginePlatform: "x86_64-darwin", buildFolder: "x86_64-osx", executable: "dmengine" },
+  linux: { enginePlatform: "x86_64-linux", buildFolder: "x86_64-linux", executable: "dmengine" },
+  win32: {
+    enginePlatform: "x86_64-win32",
+    buildFolder: "x86_64-win32",
+    executable: "dmengine.exe"
+  }
+};
+var ENGINE_INFO_URL = "https://d.defold.com/stable/info.json";
+var ENGINE_ARCHIVE_BASE = "https://d.defold.com/archive/stable";
+var DEBUG_LAUNCHER_REL = ".vscode/defold-debug.ts";
+function debugLaunchConfig() {
+  return {
+    name: "Defold: Debug (TypeScript)",
+    type: "lua-local",
+    request: "launch",
+    stopOnEntry: false,
+    verbose: false,
+    internalConsoleOptions: "openOnSessionStart",
+    program: { command: "bun" },
+    args: [DEBUG_LAUNCHER_REL]
+  };
+}
+var VSCODE_LAUNCH_CONTENT = {
+  version: "0.2.0",
+  configurations: [debugLaunchConfig()]
+};
+function renderDebugLauncher() {
+  const targets = JSON.stringify(PLATFORM_TARGETS, null, 2);
+  return `import { chmodSync, copyFileSync, existsSync, mkdirSync } from "node:fs";
+import * as path from "node:path";
+
+// Windows only: paths to OpenAL32.dll and wrap_oal.dll from your Defold SDK
+// (defoldsdk/ext/lib/x86_64-win32/). Leave empty on macOS/Linux.
+const WINDOWS_OPENAL32_PATH = "";
+const WINDOWS_WRAPOAL_PATH = "";
+
+interface EngineTarget {
+  enginePlatform: string;
+  buildFolder: string;
+  executable: string;
+}
+
+const PLATFORM_TARGETS: Record<string, EngineTarget> = ${targets};
+
+const ENGINE_INFO_URL = "${ENGINE_INFO_URL}";
+const ENGINE_ARCHIVE_BASE = "${ENGINE_ARCHIVE_BASE}";
+
+const target = PLATFORM_TARGETS[process.platform];
+if (!target) {
+  console.error(\`Unsupported platform: \${process.platform}\`);
+  process.exit(1);
+}
+
+const here = path.dirname(new URL(import.meta.url).pathname);
+const stockEnginePath = path.join(here, target.executable);
+
+if (!existsSync(stockEnginePath)) {
+  const info = (await (await fetch(ENGINE_INFO_URL)).json()) as { sha1: string };
+  const url = \`\${ENGINE_ARCHIVE_BASE}/\${info.sha1}/engine/\${target.enginePlatform}/\${target.executable}\`;
+  console.log(\`Fetching \${url}\`);
+  const res = await fetch(url);
+  if (!res.ok) {
+    console.error(\`Engine download failed: \${res.status} \${res.statusText}\`);
+    process.exit(1);
+  }
+  await Bun.write(stockEnginePath, res);
+}
+
+const buildFolder = path.join("build", target.buildFolder);
+const buildEnginePath = path.join(buildFolder, target.executable);
+let enginePath = existsSync(buildEnginePath) ? buildEnginePath : stockEnginePath;
+
+if (process.platform === "win32" && enginePath === buildEnginePath) {
+  for (const [src, name] of [
+    [WINDOWS_OPENAL32_PATH, "OpenAL32.dll"],
+    [WINDOWS_WRAPOAL_PATH, "wrap_oal.dll"],
+  ] as const) {
+    const dest = path.join(buildFolder, name);
+    if (src && !existsSync(dest)) {
+      copyFileSync(src, dest);
+    }
+  }
+}
+
+// macOS: a build engine launched in place attaches to the editor process; copy
+// it aside first so it runs standalone.
+if (process.platform === "darwin" && enginePath === buildEnginePath) {
+  const tempEngine = path.join(buildFolder, "temp", target.executable);
+  mkdirSync(path.dirname(tempEngine), { recursive: true });
+  copyFileSync(buildEnginePath, tempEngine);
+  enginePath = tempEngine;
+}
+
+if (process.platform !== "win32") {
+  chmodSync(enginePath, 0o755);
+}
+
+const projectc = path.join("build", "default", "game.projectc");
+console.log(\`Launching \${enginePath} \${projectc}\`);
+const proc = Bun.spawn([enginePath, projectc], {
+  stdio: ["inherit", "inherit", "inherit"],
+});
+process.exit(await proc.exited);
+`;
+}
+var DEBUG_LAUNCHER_SOURCE = renderDebugLauncher();
+
+// src/mise-scaffold.ts
+var MANAGED_MARKER = "# managed by @defold-typescript";
+var MISE_TASKS_TOML = `${MANAGED_MARKER}
+[tasks."defold-typescript:build"]
+description = "Build the TypeScript sources with the installed defold-typescript CLI"
+run = "bunx --no-install defold-typescript build"
+
+${MANAGED_MARKER}
+[tasks."defold-typescript:watch"]
+description = "Watch and rebuild the TypeScript sources with the installed defold-typescript CLI"
+run = "bunx --no-install defold-typescript watch"
+
+${MANAGED_MARKER}
+[tasks."defold-typescript:upgrade"]
+description = "Upgrade the defold-typescript CLI to its latest release and re-pin the types dependency"
+run = ["bunx @defold-typescript/cli@latest init --force", "bun install"]
+`;
+function stripManagedBlocks(text) {
+  const lines = text.split(`
+`);
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i] ?? "";
+    if (line.trim() === MANAGED_MARKER) {
+      i += 1;
+      while (i < lines.length && (lines[i] ?? "").trim() !== "") {
+        i += 1;
+      }
+      if (i < lines.length) {
+        i += 1;
+      }
+      continue;
+    }
+    out.push(line);
+    i += 1;
+  }
+  return out.join(`
+`);
+}
+function mergeMiseToml(existing) {
+  if (existing === undefined) {
+    return MISE_TASKS_TOML;
+  }
+  const userContent = stripManagedBlocks(existing).replace(/\s*$/, "");
+  if (userContent === "") {
+    return MISE_TASKS_TOML;
+  }
+  return `${userContent}
+
+${MISE_TASKS_TOML}`;
+}
+
 // src/script-kind.ts
 var DEFAULT_TYPES_ENTRYPOINT = "@defold-typescript/types";
 var KIND_BY_EXT = {
@@ -406,43 +569,64 @@ var BIOME_JSON_CONTENT = {
   }
 };
 var VSCODE_EXTENSIONS_CONTENT = {
-  recommendations: ["sumneko.lua", "astronachos.defold"],
+  recommendations: ["sumneko.lua", "astronachos.defold", "tomblind.local-lua-debugger-vscode"],
   unwantedRecommendations: ["johnnymorganz.luau-lsp"]
 };
 var VSCODE_SETTINGS_CONTENT = {
   "Lua.workspace.ignoreDir": ["src"]
 };
+var HOOK_COMMENTS = {
+  init: "Initialize the component and return its state.",
+  update: "Update the component every frame; `dt` is the time step.",
+  fixed_update: "Update at the fixed physics time step.",
+  late_update: "Update every frame after `update`.",
+  on_message: "Handle an incoming message.",
+  on_input: "Handle input once input focus is acquired.",
+  final: "Clean up when the component is deleted.",
+  on_reload: "React to a hot reload of this script."
+};
+var HOOK_SIGNATURES = {
+  init: "",
+  update: "self, dt",
+  fixed_update: "self, dt",
+  late_update: "self, dt",
+  on_message: "self, message_id, message, sender",
+  on_input: "self, action_id, action",
+  final: "self",
+  on_reload: "self"
+};
+var SNIPPET_HOOK_ORDER = Object.keys(HOOK_SIGNATURES);
+function hookLines(includeOnInput, startTabStop) {
+  const lines = [];
+  let tabStop = startTabStop;
+  for (const hook of SNIPPET_HOOK_ORDER) {
+    if (hook === "init") {
+      continue;
+    }
+    if (hook === "on_input" && !includeOnInput) {
+      continue;
+    }
+    lines.push(`  // ${HOOK_COMMENTS[hook]}`);
+    lines.push(`  ${hook}(${HOOK_SIGNATURES[hook]}) {$${tabStop}},`);
+    tabStop += 1;
+  }
+  return lines;
+}
 function inlineSnippetBody(factory, includeOnInput) {
-  const lines = [
+  return [
     `import { ${factory} } from "@defold-typescript/types";`,
     "",
     `export const script = ${factory}({`,
-    "  // Initialize the component and return its state.",
+    `  // ${HOOK_COMMENTS.init}`,
     "  init() {",
     "    return { $0 };",
     "  },",
-    "  // Update the component every frame; `dt` is the time step.",
-    "  update(self, dt) {$1},",
-    "  // Update at the fixed physics time step.",
-    "  fixed_update(self, dt) {$2},",
-    "  // Update every frame after `update`.",
-    "  late_update(self, dt) {$3},",
-    "  // Handle an incoming message.",
-    "  on_message(self, message_id, message, sender) {$4},"
+    ...hookLines(includeOnInput, 1),
+    "});"
   ];
-  if (includeOnInput) {
-    lines.push("  // Handle input once input focus is acquired.");
-    lines.push("  on_input(self, action_id, action) {$5},");
-  }
-  lines.push("  // Clean up when the component is deleted.");
-  lines.push("  final(self) {$6},");
-  lines.push("  // React to a hot reload of this script.");
-  lines.push("  on_reload(self) {$7},");
-  lines.push("});");
-  return lines;
 }
 function typedSnippetBody(factory, includeOnInput) {
-  const lines = [
+  return [
     `import { ${factory} } from "@defold-typescript/types";`,
     "",
     "type Self = {",
@@ -451,29 +635,13 @@ function typedSnippetBody(factory, includeOnInput) {
     "};",
     "",
     `export const script = ${factory}<Self>({`,
-    "  // Initialize the component and return its state.",
+    `  // ${HOOK_COMMENTS.init}`,
     "  init(): Self {",
     "    return { $0 };",
     "  },",
-    "  // Update the component every frame; `dt` is the time step.",
-    "  update(self, dt) {$2},",
-    "  // Update at the fixed physics time step.",
-    "  fixed_update(self, dt) {$3},",
-    "  // Update every frame after `update`.",
-    "  late_update(self, dt) {$4},",
-    "  // Handle an incoming message.",
-    "  on_message(self, message_id, message, sender) {$5},"
+    ...hookLines(includeOnInput, 2),
+    "});"
   ];
-  if (includeOnInput) {
-    lines.push("  // Handle input once input focus is acquired.");
-    lines.push("  on_input(self, action_id, action) {$6},");
-  }
-  lines.push("  // Clean up when the component is deleted.");
-  lines.push("  final(self) {$7},");
-  lines.push("  // React to a hot reload of this script.");
-  lines.push("  on_reload(self) {$8},");
-  lines.push("});");
-  return lines;
 }
 var VSCODE_SNIPPETS_CONTENT = {
   "Defold script (inferred self)": {
@@ -586,6 +754,12 @@ function writeBiome(cwd, written) {
   writeJson(biomePath, BIOME_JSON_CONTENT);
   written.push("biome.json");
 }
+function writeMiseTasks(cwd, written) {
+  const misePath = path7.join(cwd, "mise.toml");
+  const existing = existsSync2(misePath) ? readFileSync6(misePath, "utf8") : undefined;
+  writeFileSync2(misePath, mergeMiseToml(existing));
+  written.push("mise.toml");
+}
 function parseJsonc(text) {
   let out = "";
   let inString = false;
@@ -707,6 +881,39 @@ function writeVscodeSnippets(cwd, written) {
   writeJson(filePath, VSCODE_SNIPPETS_CONTENT);
   written.push(".vscode/defold-typescript.code-snippets");
 }
+function writeVscodeLaunch(cwd, written) {
+  const dir = path7.join(cwd, ".vscode");
+  const filePath = path7.join(dir, "launch.json");
+  const ours = debugLaunchConfig();
+  if (existsSync2(filePath)) {
+    const existing = readVscodeJson(filePath);
+    if (existing === null) {
+      return;
+    }
+    const configs = Array.isArray(existing.configurations) ? [...existing.configurations] : [];
+    const names = new Set(configs.map((c) => isJsonObject(c) ? c.name : undefined));
+    if (!names.has(ours.name)) {
+      configs.push(ours);
+    }
+    existing.configurations = configs;
+    existing.version ??= VSCODE_LAUNCH_CONTENT.version;
+    writeJson(filePath, existing);
+    return;
+  }
+  mkdirSync2(dir, { recursive: true });
+  writeJson(filePath, VSCODE_LAUNCH_CONTENT);
+  written.push(".vscode/launch.json");
+}
+function writeVscodeDebugLauncher(cwd, written) {
+  const dir = path7.join(cwd, ".vscode");
+  const filePath = path7.join(dir, "defold-debug.ts");
+  if (existsSync2(filePath)) {
+    return;
+  }
+  mkdirSync2(dir, { recursive: true });
+  writeFileSync2(filePath, DEBUG_LAUNCHER_SOURCE);
+  written.push(".vscode/defold-debug.ts");
+}
 function writeTsSurface(cwd, written, force = false) {
   mkdirSync2(path7.join(cwd, "src"), { recursive: true });
   writeFileSync2(path7.join(cwd, "src", "main.ts"), MAIN_TS_CONTENT);
@@ -748,9 +955,12 @@ function writeTsSurface(cwd, written, force = false) {
   writeGitignore(cwd);
   written.push(".gitignore");
   writeBiome(cwd, written);
+  writeMiseTasks(cwd, written);
   writeVscodeExtensions(cwd, written);
   writeVscodeSettings(cwd, written);
   writeVscodeSnippets(cwd, written);
+  writeVscodeLaunch(cwd, written);
+  writeVscodeDebugLauncher(cwd, written);
   return selectScriptKind(kinds);
 }
 function runNewProjectInit(cwd, force = false) {
@@ -833,7 +1043,7 @@ function materializeApiSurface(opts) {
   const excluded = excludedModulesForKind(opts.scriptKind ?? null);
   const sources = listDts(sourceGeneratedDir).filter((file) => file !== "index.d.ts").filter((file) => !excluded.has(file.replace(/\.d\.ts$/, "")));
   const srcDir = path8.resolve(sourceGeneratedDir, "..", "src");
-  const overloads = ["msg-overloads.d.ts", "go-overloads.d.ts"].filter((file) => existsSync3(path8.join(srcDir, file)));
+  const overloads = ["msg-overloads.d.ts", "message-guard.d.ts", "go-overloads.d.ts"].filter((file) => existsSync3(path8.join(srcDir, file)));
   const coreTypesSrc = path8.join(srcDir, "core-types.ts");
   const includeCoreTypes = overloads.length > 0 && existsSync3(coreTypesSrc);
   const engineGlobalsSrc = path8.join(srcDir, "engine-globals.d.ts");
@@ -908,12 +1118,16 @@ function ensureMaterializedReference(cwd, materializedDir) {
   const tsconfigPath = path8.join(cwd, "tsconfig.json");
   if (existsSync3(tsconfigPath)) {
     const tsconfig = JSON.parse(readFileSync7(tsconfigPath, "utf8"));
-    tsconfig.compilerOptions = {
-      ...tsconfig.compilerOptions ?? {},
-      typeRoots: [MATERIALIZED_ROOT],
-      types: [surfaceId]
-    };
-    writeJson2(tsconfigPath, tsconfig);
+    const current = tsconfig.compilerOptions ?? {};
+    const alreadyRepointed = JSON.stringify(current.typeRoots) === JSON.stringify([MATERIALIZED_ROOT]) && JSON.stringify(current.types) === JSON.stringify([surfaceId]);
+    if (!alreadyRepointed) {
+      tsconfig.compilerOptions = {
+        ...current,
+        typeRoots: [MATERIALIZED_ROOT],
+        types: [surfaceId]
+      };
+      writeJson2(tsconfigPath, tsconfig);
+    }
   }
   ensureGitignoreLine(cwd, `${MATERIALIZED_ROOT}/`);
 }

package/dist/mise-scaffold.d.ts

@@ -0,0 +1,2 @@
+export declare const MISE_TASKS_TOML = "# managed by @defold-typescript\n[tasks.\"defold-typescript:build\"]\ndescription = \"Build the TypeScript sources with the installed defold-typescript CLI\"\nrun = \"bunx --no-install defold-typescript build\"\n\n# managed by @defold-typescript\n[tasks.\"defold-typescript:watch\"]\ndescription = \"Watch and rebuild the TypeScript sources with the installed defold-typescript CLI\"\nrun = \"bunx --no-install defold-typescript watch\"\n\n# managed by @defold-typescript\n[tasks.\"defold-typescript:upgrade\"]\ndescription = \"Upgrade the defold-typescript CLI to its latest release and re-pin the types dependency\"\nrun = [\"bunx @defold-typescript/cli@latest init --force\", \"bun install\"]\n";
+export declare function mergeMiseToml(existing?: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/cli",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "End-user CLI for scaffolding and building Defold projects written in TypeScript.",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@defold-typescript/transpiler": "0.5.2",
-    "@defold-typescript/types": "0.5.2"
+    "@defold-typescript/transpiler": "0.5.3",
+    "@defold-typescript/types": "0.5.3"
   }
 }

package/src/debug-launcher.ts

@@ -0,0 +1,165 @@
+import * as path from "node:path";
+
+export interface EngineTarget {
+  readonly enginePlatform: string;
+  readonly buildFolder: string;
+  readonly executable: string;
+}
+
+// `enginePlatform` keys the d.defold.com download path; `buildFolder` keys the
+// native-extension build output. They diverge on macOS (`x86_64-darwin` vs
+// `x86_64-osx`), which is why they are tracked separately.
+const PLATFORM_TARGETS: Record<string, EngineTarget> = {
+  darwin: { enginePlatform: "x86_64-darwin", buildFolder: "x86_64-osx", executable: "dmengine" },
+  linux: { enginePlatform: "x86_64-linux", buildFolder: "x86_64-linux", executable: "dmengine" },
+  win32: {
+    enginePlatform: "x86_64-win32",
+    buildFolder: "x86_64-win32",
+    executable: "dmengine.exe",
+  },
+};
+
+const ENGINE_INFO_URL = "https://d.defold.com/stable/info.json";
+const ENGINE_ARCHIVE_BASE = "https://d.defold.com/archive/stable";
+
+export const DEBUG_LAUNCHER_REL = ".vscode/defold-debug.ts";
+
+export function targetPlatform(platform: NodeJS.Platform): EngineTarget {
+  const target = PLATFORM_TARGETS[platform];
+  if (!target) {
+    throw new Error(
+      `defold-typescript debug: unsupported platform "${platform}"; expected one of ${Object.keys(
+        PLATFORM_TARGETS,
+      ).join(", ")}.`,
+    );
+  }
+  return target;
+}
+
+export function engineDownloadUrl(
+  sha1: string,
+  enginePlatform: string,
+  executable: string,
+): string {
+  return `${ENGINE_ARCHIVE_BASE}/${sha1}/engine/${enginePlatform}/${executable}`;
+}
+
+export interface ResolveEngineOptions {
+  readonly cwd: string;
+  readonly target: EngineTarget;
+  readonly stockPath: string;
+  readonly probe: (candidate: string) => boolean;
+}
+
+// Prefer the native-extension build engine when it exists; the stock engine is
+// the fallback for projects without native extensions.
+export function resolveEnginePath(opts: ResolveEngineOptions): string {
+  const { cwd, target, stockPath, probe } = opts;
+  const buildEnginePath = path.join(cwd, "build", target.buildFolder, target.executable);
+  return probe(buildEnginePath) ? buildEnginePath : stockPath;
+}
+
+export function debugLaunchConfig() {
+  return {
+    name: "Defold: Debug (TypeScript)",
+    type: "lua-local",
+    request: "launch",
+    stopOnEntry: false,
+    verbose: false,
+    internalConsoleOptions: "openOnSessionStart",
+    program: { command: "bun" },
+    args: [DEBUG_LAUNCHER_REL],
+  };
+}
+
+export const VSCODE_LAUNCH_CONTENT = {
+  version: "0.2.0",
+  configurations: [debugLaunchConfig()],
+};
+
+// The scaffolded launcher embeds the same platform table and archive endpoints
+// the helpers above use, so the self-contained `.vscode/defold-debug.ts` and the
+// unit-tested logic stay in lockstep. It is a Bun script: `process.platform` for
+// the OS, `fetch` for the engine download, `Bun.spawn` with inherited stdio for
+// the run (the pipe Local Lua Debugger attaches over). No shell, no Git Bash.
+function renderDebugLauncher(): string {
+  const targets = JSON.stringify(PLATFORM_TARGETS, null, 2);
+  return `import { chmodSync, copyFileSync, existsSync, mkdirSync } from "node:fs";
+import * as path from "node:path";
+
+// Windows only: paths to OpenAL32.dll and wrap_oal.dll from your Defold SDK
+// (defoldsdk/ext/lib/x86_64-win32/). Leave empty on macOS/Linux.
+const WINDOWS_OPENAL32_PATH = "";
+const WINDOWS_WRAPOAL_PATH = "";
+
+interface EngineTarget {
+  enginePlatform: string;
+  buildFolder: string;
+  executable: string;
+}
+
+const PLATFORM_TARGETS: Record<string, EngineTarget> = ${targets};
+
+const ENGINE_INFO_URL = "${ENGINE_INFO_URL}";
+const ENGINE_ARCHIVE_BASE = "${ENGINE_ARCHIVE_BASE}";
+
+const target = PLATFORM_TARGETS[process.platform];
+if (!target) {
+  console.error(\`Unsupported platform: \${process.platform}\`);
+  process.exit(1);
+}
+
+const here = path.dirname(new URL(import.meta.url).pathname);
+const stockEnginePath = path.join(here, target.executable);
+
+if (!existsSync(stockEnginePath)) {
+  const info = (await (await fetch(ENGINE_INFO_URL)).json()) as { sha1: string };
+  const url = \`\${ENGINE_ARCHIVE_BASE}/\${info.sha1}/engine/\${target.enginePlatform}/\${target.executable}\`;
+  console.log(\`Fetching \${url}\`);
+  const res = await fetch(url);
+  if (!res.ok) {
+    console.error(\`Engine download failed: \${res.status} \${res.statusText}\`);
+    process.exit(1);
+  }
+  await Bun.write(stockEnginePath, res);
+}
+
+const buildFolder = path.join("build", target.buildFolder);
+const buildEnginePath = path.join(buildFolder, target.executable);
+let enginePath = existsSync(buildEnginePath) ? buildEnginePath : stockEnginePath;
+
+if (process.platform === "win32" && enginePath === buildEnginePath) {
+  for (const [src, name] of [
+    [WINDOWS_OPENAL32_PATH, "OpenAL32.dll"],
+    [WINDOWS_WRAPOAL_PATH, "wrap_oal.dll"],
+  ] as const) {
+    const dest = path.join(buildFolder, name);
+    if (src && !existsSync(dest)) {
+      copyFileSync(src, dest);
+    }
+  }
+}
+
+// macOS: a build engine launched in place attaches to the editor process; copy
+// it aside first so it runs standalone.
+if (process.platform === "darwin" && enginePath === buildEnginePath) {
+  const tempEngine = path.join(buildFolder, "temp", target.executable);
+  mkdirSync(path.dirname(tempEngine), { recursive: true });
+  copyFileSync(buildEnginePath, tempEngine);
+  enginePath = tempEngine;
+}
+
+if (process.platform !== "win32") {
+  chmodSync(enginePath, 0o755);
+}
+
+const projectc = path.join("build", "default", "game.projectc");
+console.log(\`Launching \${enginePath} \${projectc}\`);
+const proc = Bun.spawn([enginePath, projectc], {
+  stdio: ["inherit", "inherit", "inherit"],
+});
+process.exit(await proc.exited);
+`;
+}
+
+export const DEBUG_LAUNCHER_SOURCE = renderDebugLauncher();

package/src/init.ts

@@ -1,7 +1,10 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import type { ScriptHookName } from "@defold-typescript/types";
+import { DEBUG_LAUNCHER_SOURCE, debugLaunchConfig, VSCODE_LAUNCH_CONTENT } from "./debug-launcher";
 import { CURRENT_STABLE_DEFOLD_VERSION } from "./defold-version";
+import { mergeMiseToml } from "./mise-scaffold";
 import {
   detectScriptKinds,
   type ScriptKind,
@@ -73,7 +76,7 @@ const BIOME_JSON_CONTENT = {
 };
 
 const VSCODE_EXTENSIONS_CONTENT = {
-  recommendations: ["sumneko.lua", "astronachos.defold"],
+  recommendations: ["sumneko.lua", "astronachos.defold", "tomblind.local-lua-debugger-vscode"],
   unwantedRecommendations: ["johnnymorganz.luau-lsp"],
 };
 
@@ -88,43 +91,81 @@ interface VscodeSnippet {
   description: string;
 }
 
+// One learn-more comment and one parameter list per lifecycle hook, keyed by
+// `ScriptHookName` so a hook added to the types fails to compile here until both
+// maps gain an entry (`satisfies` exhaustiveness — the type is derived from the
+// canonical `SCRIPT_HOOK_NAMES`). The hook list is read off these keys rather
+// than imported as a runtime value: the types package is type-only and not
+// node-ESM-runnable, so the CLI bundle must not resolve it at runtime. `init` is
+// special-cased by the body builders (it carries the return placeholder, not a
+// `self` param), so its signature entry is unused but still required for
+// exhaustiveness.
+const HOOK_COMMENTS = {
+  init: "Initialize the component and return its state.",
+  update: "Update the component every frame; `dt` is the time step.",
+  fixed_update: "Update at the fixed physics time step.",
+  late_update: "Update every frame after `update`.",
+  on_message: "Handle an incoming message.",
+  on_input: "Handle input once input focus is acquired.",
+  final: "Clean up when the component is deleted.",
+  on_reload: "React to a hot reload of this script.",
+} satisfies Record<ScriptHookName, string>;
+
+const HOOK_SIGNATURES = {
+  init: "",
+  update: "self, dt",
+  fixed_update: "self, dt",
+  late_update: "self, dt",
+  on_message: "self, message_id, message, sender",
+  on_input: "self, action_id, action",
+  final: "self",
+  on_reload: "self",
+} satisfies Record<ScriptHookName, string>;
+
+const SNIPPET_HOOK_ORDER = Object.keys(HOOK_SIGNATURES) as ScriptHookName[];
+
+// Emit every hook except `init` (the caller writes it with its return
+// placeholder) as a commented `name(sig) {$N},` line. Render scripts pass
+// includeOnInput=false because `RenderScriptHooks` omits `on_input`. Tab stops
+// run sequentially from `startTabStop` across the hooks actually emitted.
+function hookLines(includeOnInput: boolean, startTabStop: number): string[] {
+  const lines: string[] = [];
+  let tabStop = startTabStop;
+  for (const hook of SNIPPET_HOOK_ORDER) {
+    if (hook === "init") {
+      continue;
+    }
+    if (hook === "on_input" && !includeOnInput) {
+      continue;
+    }
+    lines.push(`  // ${HOOK_COMMENTS[hook]}`);
+    lines.push(`  ${hook}(${HOOK_SIGNATURES[hook]}) {$${tabStop}},`);
+    tabStop += 1;
+  }
+  return lines;
+}
+
 // Whole-file TS scaffolds mirroring the Defold editor's empty script/gui/render
 // templates over the lifecycle factories. Two self-typing variants per kind:
 // inline-self (TSelf inferred from `init`'s return) and typed-self (an explicit
 // dummy `Self` placeholder). Hook order mirrors the Lua templates; render omits
 // `on_input` because `RenderScriptHooks` does. The final `$0` lands inside `init`.
 function inlineSnippetBody(factory: string, includeOnInput: boolean): string[] {
-  const lines = [
+  return [
     `import { ${factory} } from "@defold-typescript/types";`,
     "",
     `export const script = ${factory}({`,
-    "  // Initialize the component and return its state.",
+    `  // ${HOOK_COMMENTS.init}`,
     "  init() {",
     "    return { $0 };",
     "  },",
-    "  // Update the component every frame; `dt` is the time step.",
-    "  update(self, dt) {$1},",
-    "  // Update at the fixed physics time step.",
-    "  fixed_update(self, dt) {$2},",
-    "  // Update every frame after `update`.",
-    "  late_update(self, dt) {$3},",
-    "  // Handle an incoming message.",
-    "  on_message(self, message_id, message, sender) {$4},",
+    ...hookLines(includeOnInput, 1),
+    "});",
   ];
-  if (includeOnInput) {
-    lines.push("  // Handle input once input focus is acquired.");
-    lines.push("  on_input(self, action_id, action) {$5},");
-  }
-  lines.push("  // Clean up when the component is deleted.");
-  lines.push("  final(self) {$6},");
-  lines.push("  // React to a hot reload of this script.");
-  lines.push("  on_reload(self) {$7},");
-  lines.push("});");
-  return lines;
 }
 
 function typedSnippetBody(factory: string, includeOnInput: boolean): string[] {
-  const lines = [
+  return [
     `import { ${factory} } from "@defold-typescript/types";`,
     "",
     "type Self = {",
@@ -133,29 +174,13 @@ function typedSnippetBody(factory: string, includeOnInput: boolean): string[] {
     "};",
     "",
     `export const script = ${factory}<Self>({`,
-    "  // Initialize the component and return its state.",
+    `  // ${HOOK_COMMENTS.init}`,
     "  init(): Self {",
     "    return { $0 };",
     "  },",
-    "  // Update the component every frame; `dt` is the time step.",
-    "  update(self, dt) {$2},",
-    "  // Update at the fixed physics time step.",
-    "  fixed_update(self, dt) {$3},",
-    "  // Update every frame after `update`.",
-    "  late_update(self, dt) {$4},",
-    "  // Handle an incoming message.",
-    "  on_message(self, message_id, message, sender) {$5},",
+    ...hookLines(includeOnInput, 2),
+    "});",
   ];
-  if (includeOnInput) {
-    lines.push("  // Handle input once input focus is acquired.");
-    lines.push("  on_input(self, action_id, action) {$6},");
-  }
-  lines.push("  // Clean up when the component is deleted.");
-  lines.push("  final(self) {$7},");
-  lines.push("  // React to a hot reload of this script.");
-  lines.push("  on_reload(self) {$8},");
-  lines.push("});");
-  return lines;
 }
 
 const VSCODE_SNIPPETS_CONTENT: Record<string, VscodeSnippet> = {
@@ -297,6 +322,13 @@ function writeBiome(cwd: string, written: string[]): void {
   written.push("biome.json");
 }
 
+function writeMiseTasks(cwd: string, written: string[]): void {
+  const misePath = path.join(cwd, "mise.toml");
+  const existing = existsSync(misePath) ? readFileSync(misePath, "utf8") : undefined;
+  writeFileSync(misePath, mergeMiseToml(existing));
+  written.push("mise.toml");
+}
+
 // Strip `//` line comments, `/* */` block comments, and trailing commas so a
 // hand-edited JSONC `.vscode` file parses with `JSON.parse`. The walk tracks
 // string state so a `//` or comma inside a value (e.g. a URL) is preserved.
@@ -438,6 +470,41 @@ function writeVscodeSnippets(cwd: string, written: string[]): void {
   written.push(".vscode/defold-typescript.code-snippets");
 }
 
+function writeVscodeLaunch(cwd: string, written: string[]): void {
+  const dir = path.join(cwd, ".vscode");
+  const filePath = path.join(dir, "launch.json");
+  const ours = debugLaunchConfig();
+  if (existsSync(filePath)) {
+    const existing = readVscodeJson(filePath);
+    if (existing === null) {
+      return;
+    }
+    const configs = Array.isArray(existing.configurations) ? [...existing.configurations] : [];
+    const names = new Set(configs.map((c) => (isJsonObject(c) ? c.name : undefined)));
+    if (!names.has(ours.name)) {
+      configs.push(ours);
+    }
+    existing.configurations = configs;
+    existing.version ??= VSCODE_LAUNCH_CONTENT.version;
+    writeJson(filePath, existing);
+    return;
+  }
+  mkdirSync(dir, { recursive: true });
+  writeJson(filePath, VSCODE_LAUNCH_CONTENT);
+  written.push(".vscode/launch.json");
+}
+
+function writeVscodeDebugLauncher(cwd: string, written: string[]): void {
+  const dir = path.join(cwd, ".vscode");
+  const filePath = path.join(dir, "defold-debug.ts");
+  if (existsSync(filePath)) {
+    return;
+  }
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(filePath, DEBUG_LAUNCHER_SOURCE);
+  written.push(".vscode/defold-debug.ts");
+}
+
 function writeTsSurface(cwd: string, written: string[], force = false): ScriptKind | null {
   mkdirSync(path.join(cwd, "src"), { recursive: true });
   writeFileSync(path.join(cwd, "src", "main.ts"), MAIN_TS_CONTENT);
@@ -483,10 +550,13 @@ function writeTsSurface(cwd: string, written: string[], force = false): ScriptKi
   written.push(".gitignore");
 
   writeBiome(cwd, written);
+  writeMiseTasks(cwd, written);
 
   writeVscodeExtensions(cwd, written);
   writeVscodeSettings(cwd, written);
   writeVscodeSnippets(cwd, written);
+  writeVscodeLaunch(cwd, written);
+  writeVscodeDebugLauncher(cwd, written);
 
   return selectScriptKind(kinds);
 }

package/src/materialize.ts

@@ -65,8 +65,8 @@ export function materializeApiSurface(
   // surface silently drops those globals. Skipped when the source has no
   // sibling `src/` (e.g. synthetic test fixtures).
   const srcDir = path.resolve(sourceGeneratedDir, "..", "src");
-  const overloads = ["msg-overloads.d.ts", "go-overloads.d.ts"].filter((file) =>
-    existsSync(path.join(srcDir, file)),
+  const overloads = ["msg-overloads.d.ts", "message-guard.d.ts", "go-overloads.d.ts"].filter(
+    (file) => existsSync(path.join(srcDir, file)),
   );
   const coreTypesSrc = path.join(srcDir, "core-types.ts");
   const includeCoreTypes = overloads.length > 0 && existsSync(coreTypesSrc);
@@ -148,12 +148,21 @@ export function ensureMaterializedReference(cwd: string, materializedDir: string
       compilerOptions?: Record<string, unknown>;
       [key: string]: unknown;
     };
-    tsconfig.compilerOptions = {
-      ...(tsconfig.compilerOptions ?? {}),
-      typeRoots: [MATERIALIZED_ROOT],
-      types: [surfaceId],
-    };
-    writeJson(tsconfigPath, tsconfig);
+    const current = tsconfig.compilerOptions ?? {};
+    // Skip the write when already repointed so the file keeps its existing
+    // formatting (a consumer's Biome/Prettier shape) instead of churning to
+    // JSON.stringify's layout on every build.
+    const alreadyRepointed =
+      JSON.stringify(current.typeRoots) === JSON.stringify([MATERIALIZED_ROOT]) &&
+      JSON.stringify(current.types) === JSON.stringify([surfaceId]);
+    if (!alreadyRepointed) {
+      tsconfig.compilerOptions = {
+        ...current,
+        typeRoots: [MATERIALIZED_ROOT],
+        types: [surfaceId],
+      };
+      writeJson(tsconfigPath, tsconfig);
+    }
   }
 
   ensureGitignoreLine(cwd, `${MATERIALIZED_ROOT}/`);

package/src/mise-scaffold.ts

@@ -0,0 +1,62 @@
+// The repo has no TOML parser and must not add one for three tasks, so the
+// managed block is emitted as a literal string and merged line-aware. Every
+// managed task is fronted by this marker so a re-merge can locate and refresh
+// the block without disturbing user-authored `[tools]`/`[tasks.*]` content.
+const MANAGED_MARKER = "# managed by @defold-typescript";
+
+// `bunx --no-install` resolves only the locally installed binary and never
+// fetches from the registry — that is the installed-version contract the types
+// pin upholds, while staying cross-platform (the bare `node_modules/.bin` path
+// is `.cmd`-shimmed on Windows). `:upgrade` is the deliberate `@latest` pull
+// that re-pins `@defold-typescript/types` via `init --force` + reinstall.
+export const MISE_TASKS_TOML = `${MANAGED_MARKER}
+[tasks."defold-typescript:build"]
+description = "Build the TypeScript sources with the installed defold-typescript CLI"
+run = "bunx --no-install defold-typescript build"
+
+${MANAGED_MARKER}
+[tasks."defold-typescript:watch"]
+description = "Watch and rebuild the TypeScript sources with the installed defold-typescript CLI"
+run = "bunx --no-install defold-typescript watch"
+
+${MANAGED_MARKER}
+[tasks."defold-typescript:upgrade"]
+description = "Upgrade the defold-typescript CLI to its latest release and re-pin the types dependency"
+run = ["bunx @defold-typescript/cli@latest init --force", "bun install"]
+`;
+
+// Drop every managed block (marker line through the next blank line or EOF),
+// leaving all other lines byte-identical, so a refresh strips the stale block
+// before the fresh one is re-appended.
+function stripManagedBlocks(text: string): string {
+  const lines = text.split("\n");
+  const out: string[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i] ?? "";
+    if (line.trim() === MANAGED_MARKER) {
+      i += 1;
+      while (i < lines.length && (lines[i] ?? "").trim() !== "") {
+        i += 1;
+      }
+      if (i < lines.length) {
+        i += 1;
+      }
+      continue;
+    }
+    out.push(line);
+    i += 1;
+  }
+  return out.join("\n");
+}
+
+export function mergeMiseToml(existing?: string): string {
+  if (existing === undefined) {
+    return MISE_TASKS_TOML;
+  }
+  const userContent = stripManagedBlocks(existing).replace(/\s*$/, "");
+  if (userContent === "") {
+    return MISE_TASKS_TOML;
+  }
+  return `${userContent}\n\n${MISE_TASKS_TOML}`;
+}