@defold-typescript/types 0.50.1 → 0.52.0

package/scripts/regen.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import messagesDoc from "../fixtures/messages_doc.json" with { type: "json" };
 import {
+  type ApiFunction,
   type ApiModule,
   parseDefoldApiDoc,
   type SkipOverloadRule,
@@ -15,10 +16,10 @@ import {
   type SymbolSignature,
 } from "../src/emit-dts";
 import {
-  applyMessageDeprecations,
-  applyMessageFieldCorrections,
+  applyMessageOverlays,
   type EmitBuiltinMessagesOptions,
   emitBuiltinMessages,
+  type MessageCatalog,
   parseMessagesDoc,
 } from "../src/emit-messages";
 import type { TranslationStore } from "../src/example-store";
@@ -43,6 +44,7 @@ import { loadTranslations } from "./example-store-io";
 import { synthesizeProseConstants } from "./prose-constants";
 import { restoreSharedHandleMethods } from "./shared-handle-methods";
 import { groupDocsByNamespace, mergeApiDocs, type readZip } from "./sync-api-docs";
+import { compareVersions, versionOf } from "./target-version";
 
 export interface ApiTargetModule {
   readonly namespace: string;
@@ -399,21 +401,24 @@ export interface MessagesManifestEntry {
 
 // Unlike MODULE_MANIFEST, this surface is hand-maintained: Defold ships no
 // machine-readable export for built-in message ids, so refresh fixtures/
-// messages_doc.json by hand from the Defold API reference. The
-// message-payload-drift test guards the payload shapes against drift.
+// messages_doc.json by hand from the default target's API reference. The
+// message-payload-drift test holds its message ids, field names and optionality
+// to that reference in both directions; what only the engine states is
+// MESSAGE_ENGINE_CORRECTIONS.
 export const MESSAGES_MANIFEST: MessagesManifestEntry = {
   doc: messagesDoc,
   outFile: "builtin-messages.d.ts",
 };
 
+export function builtinMessagesCatalog(entry: MessagesManifestEntry): MessageCatalog {
+  return applyMessageOverlays(parseMessagesDoc(entry.doc));
+}
+
 export function generateBuiltinMessagesDeclaration(
   entry: MessagesManifestEntry,
   opts: EmitBuiltinMessagesOptions = {},
 ): string {
-  return emitBuiltinMessages(
-    applyMessageFieldCorrections(applyMessageDeprecations(parseMessagesDoc(entry.doc))),
-    opts,
-  );
+  return emitBuiltinMessages(builtinMessagesCatalog(entry), opts);
 }
 
 export interface GenerateResult {
@@ -456,21 +461,32 @@ export interface GenerateOptions {
   translations?: TranslationStore;
   urlParameters?: UrlParameterTable;
   registeredConstants?: ReadonlySet<string>;
+  bindingEvidence?: ReadonlySet<string>;
+  nilRaisingSlots?: ReadonlyMap<string, readonly number[]>;
   // The modules the entry is emitted beside, the entry among them. Routing
   // reads this set instead of looking the entry up in a committed manifest, so
   // a surface built with its own import root still routes as a whole.
   surface?: readonly ModuleManifestEntry[];
 }
 
+// What a target's own engine source decides for its emit (`targetBindingOptions`).
+export type TargetBindingOptions = Pick<
+  GenerateOptions,
+  "registeredConstants" | "bindingEvidence" | "nilRaisingSlots"
+>;
+
 interface PreparedGeneratedModule {
   module: ApiModule;
   knownConstantFqns: ReadonlySet<string>;
   translations: TranslationStore;
   urlParameters: UrlParameterTable;
   registeredConstants: ReadonlySet<string> | undefined;
+  bindingEvidence: ReadonlySet<string> | undefined;
+  nilRaisingSlots: ReadonlyMap<string, readonly number[]> | undefined;
   typeLeaves: Readonly<Record<string, string>> | undefined;
   declaredTypes: ReadonlyMap<string, string> | undefined;
   dropped: string[];
+  withheldFunctions: ApiFunction[];
 }
 
 // Parse a manifest entry, apply its `skipFunctions` and `skipOverloads` filters, and resolve the
@@ -482,7 +498,7 @@ function prepareGeneratedModule(
   options?: GenerateOptions,
 ): PreparedGeneratedModule {
   const routed = routedModuleOf(entry, options?.surface);
-  const { module, dropped } = routed?.prepared ?? withheldApiModule(entry);
+  const { module, dropped, withheldFunctions } = routed?.prepared ?? withheldApiModule(entry);
   const knownConstantFqns = options?.knownConstantFqns ?? collectConstantFqns();
   const translations = options?.translations ?? loadTranslations();
   const urlParameters = options?.urlParameters ?? committedUrlParameters();
@@ -492,14 +508,17 @@ function prepareGeneratedModule(
     translations,
     urlParameters,
     registeredConstants: options?.registeredConstants,
+    bindingEvidence: options?.bindingEvidence,
+    nilRaisingSlots: options?.nilRaisingSlots,
     typeLeaves: entry.typeLeaves,
     declaredTypes: routed?.declaredTypes,
     dropped,
+    withheldFunctions,
   };
 }
 
 interface RoutedSurface {
-  readonly modules: ReadonlyMap<ModuleManifestEntry, { module: ApiModule; dropped: string[] }>;
+  readonly modules: ReadonlyMap<ModuleManifestEntry, WithheldModule>;
   readonly declaredTypes: ReadonlyMap<string, string>;
 }
 
@@ -513,10 +532,7 @@ function routeSurface(entries: readonly ModuleManifestEntry[]): RoutedSurface {
     modules: new Map(
       entries.map((member, index) => [
         member,
-        {
-          module: routed[index] as ApiModule,
-          dropped: (withheld[index] as { dropped: string[] }).dropped,
-        },
+        { ...(withheld[index] as WithheldModule), module: routed[index] as ApiModule },
       ]),
     ),
     declaredTypes: declaredTypePaths(routed),
@@ -534,7 +550,7 @@ function routedModuleOf(
   callerSurface?: readonly ModuleManifestEntry[],
 ):
   | {
-      prepared: { module: ApiModule; dropped: string[] };
+      prepared: WithheldModule;
       declaredTypes: ReadonlyMap<string, string>;
     }
   | undefined {
@@ -622,8 +638,14 @@ function committedSurfaceOf(
   };
 }
 
+interface WithheldModule {
+  module: ApiModule;
+  dropped: string[];
+  withheldFunctions: ApiFunction[];
+}
+
 // The parsed module with the entry's `skipFunctions` and `skipOverloads` applied.
-function withheldApiModule(entry: ModuleManifestEntry): { module: ApiModule; dropped: string[] } {
+function withheldApiModule(entry: ModuleManifestEntry): WithheldModule {
   let module = parseDefoldApiDoc(entry.doc);
   const prefix = `${module.namespace}.`;
   const dropped: string[] = [];
@@ -651,7 +673,8 @@ function withheldApiModule(entry: ModuleManifestEntry): { module: ApiModule; dro
     }
     return withheld(name);
   };
-  module.functions = module.functions.filter((fn) => !withheld(fn.name));
+  const withheldFunctions = module.functions.filter((fn) => withheld(fn.name));
+  module.functions = module.functions.filter((fn) => !withheldFunctions.includes(fn));
   module.variables = module.variables.filter((v) => !withheld(v.name));
   const withheldConstants = new Set<string>();
   module.constants = module.constants.filter((c) => {
@@ -667,7 +690,7 @@ function withheldApiModule(entry: ModuleManifestEntry): { module: ApiModule; dro
   if (module.structs) module.structs = module.structs.filter((s) => !withheldType(s.name));
   module.typedefs = module.typedefs.filter((t) => t.aliasOf === undefined || !withheldType(t.name));
   module = withholdOverloads(module, entry.skipOverloads ?? []);
-  return { module, dropped };
+  return { module, dropped, withheldFunctions };
 }
 
 // The field corrections one target's runtime entries leave inert: every entry is
@@ -739,15 +762,21 @@ export function generateModuleDeclaration(
     translations,
     urlParameters,
     registeredConstants,
+    bindingEvidence,
+    nilRaisingSlots,
     typeLeaves,
     declaredTypes,
     dropped,
+    withheldFunctions,
   } = prepareGeneratedModule(entry, options);
   const emitted = emitDeclarations(module, {
     knownConstantFqns,
     translations,
     urlParameters,
+    withheldFunctions,
     ...(registeredConstants ? { registeredConstants } : {}),
+    ...(bindingEvidence ? { bindingEvidence } : {}),
+    ...(nilRaisingSlots ? { nilRaisingSlots } : {}),
     ...(typeLeaves ? { typeLeaves } : {}),
     ...(declaredTypes ? { declaredTypes } : {}),
     ...(entry.indexBaseSource ? { indexBaseSource: entry.indexBaseSource } : {}),
@@ -772,13 +801,19 @@ export function generateModuleSignatures(
     knownConstantFqns,
     urlParameters,
     registeredConstants,
+    bindingEvidence,
+    nilRaisingSlots,
     typeLeaves,
     declaredTypes,
+    withheldFunctions,
   } = prepareGeneratedModule(entry, options);
   return emitSymbolSignatures(module, {
     knownConstantFqns,
     urlParameters,
+    withheldFunctions,
     ...(registeredConstants ? { registeredConstants } : {}),
+    ...(bindingEvidence ? { bindingEvidence } : {}),
+    ...(nilRaisingSlots ? { nilRaisingSlots } : {}),
     ...(typeLeaves ? { typeLeaves } : {}),
     ...(declaredTypes ? { declaredTypes } : {}),
   });
@@ -845,9 +880,17 @@ export function kindStdlibReferences(entry: KindManifestEntry): string {
 // `generateKindIndex` stays pure; `srcAugmentationScopingViolations` in
 // `./augmentation-namespaces` is what catches a future restricted augmentation
 // added without one, by reading the namespaces each file really re-opens.
+// `since` is the first Defold release, a bare semver, whose engine has what the
+// augmentation declares; a surface generated for an older target omits it.
+// `requiresGoInstance` lists the exact functions an augmentation declares that
+// need a game object, so it rides no index of a kind without one; the same
+// guard checks this list against the functions the file declares, in both
+// directions.
 interface UniversalExtraImport {
   readonly specifier: string;
   readonly restrictedTo?: string;
+  readonly since?: string;
+  readonly requiresGoInstance?: readonly string[];
 }
 
 const UNIVERSAL_EXTRA_IMPORTS: readonly UniversalExtraImport[] = [
@@ -857,10 +900,19 @@ const UNIVERSAL_EXTRA_IMPORTS: readonly UniversalExtraImport[] = [
   { specifier: "../../src/msg-overloads" },
   { specifier: "../../src/message-guard" },
   { specifier: "../../src/window-event-guard" },
+  { specifier: "../../src/physics-event-guard" },
   { specifier: "../../src/scene-addresses" },
-  { specifier: "../../src/go-overloads" },
+  // `go.property` is listed by hand: `GetScript` finds no `.script` instance in
+  // a render script and returns null rather than raising, and `Script_Property`
+  // raises on that null itself, a check the bindings manifest does not record.
+  {
+    specifier: "../../src/go-overloads",
+    requiresGoInstance: ["go.get", "go.set", "go.property"],
+  },
   { specifier: "../../src/component-properties" },
   { specifier: "../../src/render-overloads", restrictedTo: "render" },
+  { specifier: "../../src/gui-overloads", restrictedTo: "gui" },
+  { specifier: "../../src/gui-texture-removal", restrictedTo: "gui", since: "1.13.1" },
   { specifier: "../../src/vmath-overloads" },
   { specifier: "../../src/sys-overloads" },
 ];
@@ -883,14 +935,57 @@ export const RESTRICTED_SRC_AUGMENTATIONS: Readonly<Record<string, string>> = Ob
   ).map((entry) => [entry.specifier.slice(SRC_IMPORT_PREFIX.length), entry.restrictedTo as string]),
 );
 
-// Read those augmentations as surface-root files. Mirrors
-// `loadTargetEditorModules`: a missing file throws with its path rather than
-// filtering silently, so a renamed augmentation fails loud instead of vanishing
-// from every materialized surface.
+// The `src/*` augmentations that declare a function needing a game object, as
+// `<module name> -> <the functions it declares that need one>`. Exported so the
+// scoping guard and the wall probe read the same list.
+export const GO_INSTANCE_SRC_FUNCTIONS: Readonly<Record<string, readonly string[]>> =
+  Object.fromEntries(
+    UNIVERSAL_EXTRA_IMPORTS.filter(
+      (entry) =>
+        entry.requiresGoInstance !== undefined && entry.specifier.startsWith(SRC_IMPORT_PREFIX),
+    ).map((entry) => [
+      entry.specifier.slice(SRC_IMPORT_PREFIX.length),
+      entry.requiresGoInstance as readonly string[],
+    ]),
+  );
+
+// The same augmentations as module names. Exported so the materialized kind
+// indexes drop them the same way the in-repo ones do.
+export const GO_INSTANCE_SRC_AUGMENTATIONS: readonly string[] =
+  Object.keys(GO_INSTANCE_SRC_FUNCTIONS);
+
+// The `src/*` augmentations gated to a release, as `<module name> -> <since>`.
+export const SRC_AUGMENTATION_GATES: Readonly<Record<string, string>> = Object.fromEntries(
+  UNIVERSAL_EXTRA_IMPORTS.filter(
+    (entry) => entry.since !== undefined && entry.specifier.startsWith(SRC_IMPORT_PREFIX),
+  ).map((entry) => [entry.specifier.slice(SRC_IMPORT_PREFIX.length), entry.since as string]),
+);
+
+function admitsTarget(entry: UniversalExtraImport, target: ApiTarget): boolean {
+  return entry.since === undefined || compareVersions(versionOf(target), entry.since) >= 0;
+}
+
+// The `src/*` augmentations a surface generated for `target` carries: those
+// whose gate the target's version meets. Every surface writer reads this one
+// filter, so the committed indexes, the kind indexes and both materializers
+// agree on which arms a target declares.
+export function srcAugmentationModulesFor(target: ApiTarget): readonly string[] {
+  return UNIVERSAL_EXTRA_IMPORTS.filter(
+    (entry) => entry.specifier.startsWith(SRC_IMPORT_PREFIX) && admitsTarget(entry, target),
+  ).map((entry) => entry.specifier.slice(SRC_IMPORT_PREFIX.length));
+}
+
+// Read those augmentations as surface-root files, narrowed to `target`'s set
+// when one is given. Mirrors `loadTargetEditorModules`: a missing file throws
+// with its path rather than filtering silently, so a renamed augmentation fails
+// loud instead of vanishing from every materialized surface.
 export function loadSrcAugmentations(
   packageRoot: string = PACKAGE_ROOT,
+  target?: ApiTarget,
 ): { path: string; contents: string }[] {
-  return SRC_AUGMENTATION_MODULES.map((name) => {
+  const modules =
+    target === undefined ? SRC_AUGMENTATION_MODULES : srcAugmentationModulesFor(target);
+  return modules.map((name) => {
     const from = resolve(packageRoot, "src", `${name}.d.ts`);
     let contents: string;
     try {
@@ -902,6 +997,76 @@ export function loadSrcAugmentations(
   });
 }
 
+export const GO_INSTANCE_FUNCTIONS_FILE = "go-instance-functions.json";
+
+export type GoInstanceFunctions = Readonly<Record<string, readonly string[]>>;
+
+// The functions that need a game-object instance on `target`, keyed by fqn,
+// read from the manifest `go-instance-functions.ts` commits beside the target's
+// fixtures. `null` for a target with no vendored engine source to derive it
+// from, whose surfaces keep every function.
+export function loadGoInstanceFunctions(
+  target: ApiTarget,
+  packageRoot: string = PACKAGE_ROOT,
+): GoInstanceFunctions | null {
+  const path = resolve(packageRoot, target.fixturesDir, GO_INSTANCE_FUNCTIONS_FILE);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf8")) as GoInstanceFunctions;
+}
+
+// The functions a kind with no game object omits, by the bare name of the
+// module declaring them: `<module> -> <local names>`. A module declaring none,
+// or declaring only names its skip rules already withhold, has no entry.
+export function goInstanceWalls(
+  modules: readonly ModuleManifestEntry[],
+  needsGoInstance: GoInstanceFunctions | null,
+): Map<string, string[]> {
+  const walls = new Map<string, string[]>();
+  if (needsGoInstance === null) return walls;
+  const fqns = Object.keys(needsGoInstance);
+  for (const entry of modules) {
+    const prefix = `${entry.namespace}.`;
+    const localOf = (name: string): string =>
+      name.startsWith(prefix) ? name.slice(prefix.length) : name;
+    const declared = new Set(parseDefoldApiDoc(entry.doc).functions.map((fn) => localOf(fn.name)));
+    const rules = entry.skipFunctions ?? [];
+    const skipped = (local: string): boolean =>
+      rules.some((rule) => (rule.endsWith(".") ? local.startsWith(rule) : local === rule));
+    const walled = fqns
+      .filter((fqn) => fqn.startsWith(prefix))
+      .map(localOf)
+      .filter((local) => !local.includes(".") && declared.has(local) && !skipped(local))
+      .sort();
+    if (walled.length > 0) walls.set(entry.outFile.replace(/\.d\.ts$/, ""), walled);
+  }
+  return walls;
+}
+
+// The modules a kind with no game object is emitted from: each walled module is
+// replaced by a copy that withholds the functions needing one and lands in
+// `dir`, one level below the surface root. The surface is returned whole
+// because a copy routes its types across its siblings, never alone.
+export function goInstanceFreeSurface(
+  modules: readonly ModuleManifestEntry[],
+  walls: ReadonlyMap<string, readonly string[]>,
+  dir: string,
+): { surface: ModuleManifestEntry[]; copies: ModuleManifestEntry[] } {
+  const copies: ModuleManifestEntry[] = [];
+  const surface = modules.map((entry) => {
+    const walled = walls.get(entry.outFile.replace(/\.d\.ts$/, ""));
+    if (walled === undefined) return entry;
+    const copy: ModuleManifestEntry = {
+      ...entry,
+      outFile: `${dir}/${entry.outFile}`,
+      importsFrom: oneLevelDeeper(entry.importsFrom ?? "../src/core-types"),
+      skipFunctions: [...(entry.skipFunctions ?? []), ...walled],
+    };
+    copies.push(copy);
+    return copy;
+  });
+  return { surface, copies };
+}
+
 const DEFAULT_FACTORY_MODULE = "../../src/lifecycle";
 
 export interface KindManifestEntry {
@@ -927,12 +1092,23 @@ export interface KindManifestEntry {
   readonly propertyTypes?: boolean;
   // Whether the kind's VM is LuaJIT. The editor runs plain Lua 5.1.
   readonly jit?: boolean;
+  // Set for a kind whose script has no game object: the directory, beside the
+  // surface root, holding copies of the modules that declare a function needing
+  // one, with those functions withheld. Its index imports the copies instead.
+  readonly goInstanceFreeDir?: string;
 }
 
 export const KIND_MODULE_MANIFEST: readonly KindManifestEntry[] = [
   { kind: "script", factory: "defineScript" },
   { kind: "gui-script", restricted: "gui", factory: "defineGuiScript" },
-  { kind: "render-script", restricted: "render", factory: "defineRenderScript" },
+  {
+    kind: "render-script",
+    restricted: "render",
+    factory: "defineRenderScript",
+    // Only the GUI component registers a game-object resolver
+    // (`comp_gui.cpp`), so every `CheckGOInstance` raises in a render script.
+    goInstanceFreeDir: "render-script-modules",
+  },
   {
     kind: "editor-script",
     // Empty on purpose: the emitted namespaces come from the declaring target's
@@ -979,17 +1155,30 @@ export function generateKindIndex(kind: string, target: ApiTarget = DEFAULT_TARG
   const entry = KIND_MODULE_MANIFEST.find((e) => e.kind === kind);
   if (!entry) throw new Error(`unknown script kind: ${kind}`);
   const srcPrefix = targetSrcPrefix(target);
+  // A kind with no game object loses what needs one, on a target whose engine
+  // source records what that is; a module declaring such a function is
+  // imported from its filtered copy.
+  const freeDir = entry.goInstanceFreeDir;
+  const needsGoInstance = freeDir === undefined ? null : loadGoInstanceFunctions(target);
+  const walls = goInstanceWalls(MODULE_MANIFEST, needsGoInstance);
   const universalNamespaces = MODULE_MANIFEST.filter(
     (m) => !Object.hasOwn(RESTRICTED_NAMESPACES, m.namespace),
-  ).map((m) => `../${m.outFile.replace(/\.d\.ts$/, "")}`);
+  )
+    .map((m) => m.outFile.replace(/\.d\.ts$/, ""))
+    .sort()
+    .map((base) => (walls.has(base) ? `../${freeDir}/${base}` : `../${base}`));
   // An augmentation bound to a restricted namespace rides only that namespace's
-  // kind index; every unmarked entry stays universal.
+  // kind index; every unmarked entry stays universal. A gated entry rides only a
+  // target its gate admits, and a marked one only a kind with a game object.
   const extraImports = UNIVERSAL_EXTRA_IMPORTS.filter(
-    (extra) => extra.restrictedTo === undefined || extra.restrictedTo === entry.restricted,
+    (extra) =>
+      (extra.restrictedTo === undefined || extra.restrictedTo === entry.restricted) &&
+      (needsGoInstance === null || extra.requiresGoInstance === undefined) &&
+      admitsTarget(extra, target),
   ).map((extra) => extra.specifier);
   const modules = (
     entry.only === undefined
-      ? [...new Set([...universalNamespaces.sort(), ...extraImports.sort()])]
+      ? [...new Set([...universalNamespaces, ...extraImports.sort()])]
       : [...editorKindModules(target), ...(entry.extraModules ?? [])]
   ).map((path) => retargetSrcPath(path, srcPrefix));
   const lines = modules.map((path) => `import "${path}";`);
@@ -1034,11 +1223,11 @@ export function generateVersionIndex(
 // The authored augmentations a committed per-version index imports, addressed
 // back into the package's `src/`. The in-repo surface has no copies beside its
 // modules, so a skipped symbol would otherwise be declared on no versioned
-// surface at all. Derived from `SRC_AUGMENTATION_MODULES`, so a new augmentation
+// surface at all. Derived from `srcAugmentationModulesFor`, so a new augmentation
 // reaches the pinned surfaces on the same edit that reaches the materialized ones.
 export function versionSrcAugmentationImports(target: ApiTarget): string[] {
   const srcPrefix = target.coreTypesImport.slice(0, -"core-types".length);
-  return SRC_AUGMENTATION_MODULES.map((name) => `${srcPrefix}${name}`);
+  return srcAugmentationModulesFor(target).map((name) => `${srcPrefix}${name}`);
 }
 
 // The `src/`-relative prefix a kind index living in `<generatedDir>/kinds/` needs
@@ -1069,6 +1258,9 @@ export function targetKindManifest(target: ApiTarget): readonly KindManifestEntr
 
 // Every `src/*` augmentation bound to a kind-restricted namespace carries its
 // `restrictedTo` marker, and every marker names a namespace its file re-opens.
+// Likewise `requiresGoInstance` sits on exactly the files declaring a function
+// the default target's manifest lists, read from this package whatever root the
+// files come from, and lists exactly the functions its file declares.
 // Exported so a test can reach the guard the entry point runs; never called on
 // import, so the dynamic import below stays unreached from an installed package.
 export async function assertSrcAugmentationScoping(
@@ -1076,13 +1268,18 @@ export async function assertSrcAugmentationScoping(
 ): Promise<number> {
   // Imported here rather than at module scope: it imports the devDependency
   // `typescript`, and `resolve` loads this module from an installed package.
-  const { srcAugmentationScopingViolations } = await import("./augmentation-namespaces");
-  const files = loadSrcAugmentations(packageRoot);
-  const violations = srcAugmentationScopingViolations(
-    files,
-    RESTRICTED_SRC_AUGMENTATIONS,
-    RESTRICTED_NAMESPACES,
+  const { goInstanceMarkerViolations, srcAugmentationScopingViolations } = await import(
+    "./augmentation-namespaces"
   );
+  const files = loadSrcAugmentations(packageRoot);
+  const violations = [
+    ...srcAugmentationScopingViolations(files, RESTRICTED_SRC_AUGMENTATIONS, RESTRICTED_NAMESPACES),
+    ...goInstanceMarkerViolations(
+      files,
+      GO_INSTANCE_SRC_FUNCTIONS,
+      new Set(Object.keys(loadGoInstanceFunctions(DEFAULT_TARGET) ?? {})),
+    ),
+  ];
   if (violations.length > 0) {
     throw new Error(`src augmentation scoping violations:\n${violations.join("\n")}`);
   }
@@ -1127,14 +1324,12 @@ export async function regenerate(
 
   // Imported here rather than at module scope: the vendored engine bindings are
   // not published, and `resolve` loads this module from an installed package.
-  const { registeredConstantFqns } = await import("./engine-binding-extract");
+  const { targetBindingOptions } = await import("./binding-pin");
   const generated = resolve(import.meta.dir, "..", "generated");
   io.mkdir(resolve(generated, "editor-vm"));
-  const defaultRegistered = registeredConstantFqns(DEFAULT_TARGET);
+  const defaultBinding = targetBindingOptions(DEFAULT_TARGET);
   for (const entry of MODULE_MANIFEST) {
-    const { contents, dropped } = generateModuleDeclaration(entry, {
-      ...(defaultRegistered ? { registeredConstants: defaultRegistered } : {}),
-    });
+    const { contents, dropped } = generateModuleDeclaration(entry, defaultBinding);
     if (dropped.length > 0) {
       io.log(`note: dropped skipped member(s) from ${entry.namespace}: ${dropped.join(", ")}`);
     }
@@ -1183,10 +1378,9 @@ export async function regenerate(
   };
   for (const entry of VERSIONED_MODULE_MANIFEST) {
     const target = versionedTargets.find((t) => t.id === entry.versionId);
-    const registeredConstants = target ? registeredConstantFqns(target) : undefined;
     const { contents, dropped } = generateModuleDeclaration(
       entry,
-      registeredConstants ? { registeredConstants } : undefined,
+      target ? targetBindingOptions(target) : undefined,
     );
     if (dropped.length > 0) {
       io.log(
@@ -1222,6 +1416,24 @@ export async function regenerate(
     }
   }
 
+  // The copies a kind with no game object imports instead of the modules that
+  // declare a function needing one; `generateKindIndex` routes to this same set.
+  const defaultWalls = goInstanceWalls(MODULE_MANIFEST, loadGoInstanceFunctions(DEFAULT_TARGET));
+  for (const entry of KIND_MODULE_MANIFEST) {
+    if (entry.goInstanceFreeDir === undefined) continue;
+    const { surface, copies } = goInstanceFreeSurface(
+      MODULE_MANIFEST,
+      defaultWalls,
+      entry.goInstanceFreeDir,
+    );
+    io.mkdir(resolve(generated, entry.goInstanceFreeDir));
+    for (const copy of copies) {
+      const out = resolve(generated, copy.outFile);
+      io.write(out, generateModuleDeclaration(copy, { ...defaultBinding, surface }).contents);
+      io.log(`wrote ${out}`);
+    }
+  }
+
   const kindsDir = resolve(generated, "kinds");
   io.mkdir(kindsDir);
   for (const entry of KIND_MODULE_MANIFEST) {

package/scripts/signature-store-fs.ts

@@ -23,6 +23,7 @@ export const BASE_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures",
 export const SOCKET_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "socket.json");
 export const VMATH_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "vmath.json");
 export const GO_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "go.json");
+export const GUI_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "gui.json");
 export const MSG_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "msg.json");
 export const RENDER_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "render.json");
 export const SYS_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "sys.json");

package/scripts/target-version.ts

@@ -0,0 +1,26 @@
+const VERSION_FROM_ID = /^defold-(\d+\.\d+\.\d+)$/;
+
+// A ref-doc target names its release outright; a committed one carries it in
+// its id.
+export function versionOf(target: {
+  readonly id: string;
+  readonly source?: { readonly version: string } | null;
+}): string {
+  if (target.source) return target.source.version;
+  const match = VERSION_FROM_ID.exec(target.id);
+  if (!match?.[1]) throw new Error(`cannot derive a release version from target id "${target.id}"`);
+  return match[1];
+}
+
+function versionTuple(version: string): number[] {
+  return version.split(".").map((part) => Number.parseInt(part, 10));
+}
+
+export function compareVersions(a: string, b: string): number {
+  const [ta, tb] = [versionTuple(a), versionTuple(b)];
+  for (let index = 0; index < Math.max(ta.length, tb.length); index += 1) {
+    const diff = (ta[index] ?? 0) - (tb[index] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}

package/src/api-doc.ts

@@ -1,4 +1,5 @@
 import { correctedDoc, docCorrectionKey } from "./doc-corrections";
+import { SCRIPT_HOOK_NAMES } from "./lifecycle";
 
 export interface ApiModule {
   namespace: string;
@@ -16,6 +17,12 @@ export interface ApiModule {
   enums?: ApiEnum[];
   /** Each ref-doc `STRUCT`. Absent on a hand-built module, read as an empty list. */
   structs?: ApiStruct[];
+  /**
+   * Each lifecycle hook the reference documents as a bare-named `FUNCTION` under
+   * `go` or `gui`. The engine calls it as a script global and binds nothing under
+   * the name. Absent on a hand-built module.
+   */
+  scriptHooks?: ApiFunction[];
 }
 
 /** A ref-doc `STRUCT`: a named table shape. */
@@ -193,6 +200,17 @@ export const FUNCTION_NAME_CORRECTIONS: ReadonlyMap<string, FunctionNameCorrecti
   ],
 ]);
 
+// The engine reads each hook a script defines with `lua_getglobal` over
+// `SCRIPT_FUNCTION_NAMES` (`gameobject_script.cpp`, and `gui.cpp` for GUI
+// scripts) and registers no module function under the name, yet the reference
+// documents the hooks as bare-named `go` and `gui` functions.
+export const SCRIPT_HOOK_NAMESPACES: ReadonlySet<string> = new Set(["go", "gui"]);
+const SCRIPT_HOOK_NAME_SET: ReadonlySet<string> = new Set(SCRIPT_HOOK_NAMES);
+
+function isScriptHook(namespace: string, name: string): boolean {
+  return SCRIPT_HOOK_NAMESPACES.has(namespace) && SCRIPT_HOOK_NAME_SET.has(name);
+}
+
 export function parseDefoldApiDoc(input: unknown): ApiModule {
   if (!isRecord(input)) {
     throw new Error(`parseDefoldApiDoc: expected object, got ${describeKind(input)}`);
@@ -218,12 +236,17 @@ export function parseDefoldApiDoc(input: unknown): ApiModule {
   const typedefs: ApiTypedef[] = [];
   const enums: ApiEnum[] = [];
   const structs: ApiStruct[] = [];
+  const scriptHooks: ApiFunction[] = [];
 
   for (const element of elements) {
     if (!isRecord(element)) continue;
     const type = element.type;
     if (type === "FUNCTION") {
       const fn = withDocCorrections(parseFunction(element));
+      if (isScriptHook(namespace, fn.name)) {
+        scriptHooks.push(fn);
+        continue;
+      }
       const corrected = FUNCTION_NAME_CORRECTIONS.get(fn.name);
       functions.push(corrected === undefined ? fn : { ...fn, name: corrected.name });
     } else if (type === "VARIABLE") {
@@ -264,6 +287,7 @@ export function parseDefoldApiDoc(input: unknown): ApiModule {
     typedefs,
     enums,
     structs,
+    scriptHooks,
   };
 }
 
@@ -310,6 +334,8 @@ function withDocCorrections(fn: ApiFunction): ApiFunction {
   };
   return {
     ...fn,
+    brief: correctedDoc(docCorrectionKey(fn.name, "brief"), fn.brief),
+    description: correctedDoc(docCorrectionKey(fn.name, "description"), fn.description),
     parameters: fn.parameters.map(correct("param")),
     returnValues: fn.returnValues.map(correct("return")),
   };