@defold-typescript/types 0.51.0 → 0.53.0

package/identity-vocabulary.json

@@ -132,7 +132,6 @@
     "b2d.joint.LIMIT_STATE": "number",
     "b2d.shape.SHAPE_TYPE": "number",
     "buffer.VALUE_TYPE": "number",
-    "buffer.ValueType": "number",
     "bullet3d.collision_object.ACTIVATION_STATE": "number",
     "bullet3d.collision_object.COLLISION_FLAG": "number",
     "bullet3d.collision_object.INTERNAL_TYPE": "number",
@@ -140,20 +139,15 @@
     "bullet3d.rigid_body.FLAG": "number",
     "bullet3d.shape.SHAPE_TYPE": "number",
     "camera.ORTHO_MODE": "number",
-    "collectionfactory.Status": "number",
     "collectionfactory.STATUS": "number",
     "collectionproxy.RESULT": "number",
     "crash.SYSFIELD": "number",
-    "factory.Status": "number",
     "factory.STATUS": "number",
-    "go.Easing": "number",
     "go.EASING": "number",
-    "go.Playback": "number",
     "go.PLAYBACK": "number",
     "graphics.BLEND_EQUATION": "number",
     "graphics.BLEND_FACTOR": "number",
     "graphics.BUFFER_TYPE": "number",
-    "graphics.BufferType": "number",
     "graphics.COMPARE_FUNC": "number",
     "graphics.COMPRESSION_TYPE": "number",
     "graphics.CONTEXT_FEATURE": "number",
@@ -162,7 +156,6 @@
     "graphics.DATA_TYPE": "number",
     "graphics.FACE_TYPE": "number",
     "graphics.SEMANTIC_TYPE": "number",
-    "graphics.State": "number",
     "graphics.STATE": "number",
     "graphics.STENCIL_OP": "number",
     "graphics.TEXTURE_FILTER": "number",
@@ -171,55 +164,37 @@
     "graphics.TEXTURE_USAGE_FLAG": "number",
     "graphics.TEXTURE_WRAP": "number",
     "gui.ADJUST": "number",
-    "gui.AdjustMode": "number",
     "gui.ANCHOR": "number",
     "gui.BLEND": "number",
-    "gui.BlendMode": "number",
     "gui.CLIPPING_MODE": "number",
-    "gui.ClippingMode": "number",
-    "gui.Easing": "number",
     "gui.EASING": "number",
     "gui.KEYBOARD_TYPE": "number",
-    "gui.KeyboardType": "number",
-    "gui.NodeType": "number",
-    "gui.PieBounds": "number",
     "gui.PIEBOUNDS": "number",
-    "gui.Pivot": "number",
     "gui.PIVOT": "number",
-    "gui.Playback": "number",
     "gui.PLAYBACK": "number",
     "gui.PROP": "number",
-    "gui.Property": "number",
     "gui.RESULT": "number",
     "gui.SAFE_AREA": "number",
-    "gui.SafeAreaMode": "number",
     "gui.SIZE_MODE": "number",
-    "gui.SizeMode": "number",
     "gui.TYPE": "number",
-    "gui.XAnchor": "number",
-    "gui.YAnchor": "number",
     "image.TYPE": "string",
     "liveupdate.LIVEUPDATE": "number",
     "material.CONSTANT_TYPE": "number",
     "particlefx.EMITTER_STATE": "number",
     "physics.JOINT_TYPE": "number",
     "physics.SHAPE_TYPE": "number",
-    "profiler.Mode": "number",
     "profiler.MODE": "number",
     "profiler.VIEW_MODE": "number",
-    "profiler.ViewMode": "number",
     "render.ClearBufferKey": "number",
     "render.CONTEXT_EVENT": "number",
     "render.FRUSTUM_PLANES": "number",
     "render.RENDER_TARGET_FLAG": "number",
+    "render.RenderTargetTextureType": "number",
     "render.SORT": "number",
     "sys.NETWORK": "number",
-    "sys.NetworkConnectivity": "number",
     "sys.REQUEST_STATUS": "number",
     "tilemap.TRANSFORM": "number",
     "window.DIMMING": "number",
-    "window.DimModeState": "number",
-    "window.DimModeStateSettable": "number",
     "window.WINDOW_EVENT": "number"
   },
   "stringConstants": [
@@ -297,6 +272,7 @@
     "b2d.joint.create_wheel:param:definition",
     "b2d.shape.ray_cast:param:max_fraction",
     "b2d.shape.set_shape:param:update_mass",
+    "buffer.get_bytes:param:stream_name",
     "go.cancel_animations:param:url",
     "go.world_to_local_position:param:url",
     "go.world_to_local_transform:param:url",
@@ -327,7 +303,6 @@
     "factory.unload:param:url",
     "gui.move_above:param:reference",
     "gui.move_below:param:reference",
-    "gui.set:param:value",
     "gui.set_parent:param:parent",
     "html5.set_interaction_listener:param:callback",
     "resource.create_buffer:param:table",
@@ -339,6 +314,16 @@
   ],
   "parameterCorrections": {
     "buffer.get_bytes:param:stream_name": { "pins": [["hash"]], "adds": ["string"] },
+    "bullet3d.constraint.get_slider_motor:param:motor": {
+      "pins": [["string"]],
+      "adds": ["\"linear\"", "\"angular\""],
+      "removes": ["string"]
+    },
+    "bullet3d.constraint.set_slider_motor:param:motor": {
+      "pins": [["string"]],
+      "adds": ["\"linear\"", "\"angular\""],
+      "removes": ["string"]
+    },
     "camera.get_aspect_ratio:param:camera": {
       "pins": [["url", "number", "nil"]],
       "adds": ["string", "Hash"]
@@ -427,6 +412,20 @@
       "pins": [["url"]],
       "adds": ["string", "Hash"]
     },
+    "go.animate:param:playback": {
+      "pins": [
+        [
+          "go.PLAYBACK_ONCE_FORWARD",
+          "go.PLAYBACK_ONCE_BACKWARD",
+          "go.PLAYBACK_ONCE_PINGPONG",
+          "go.PLAYBACK_LOOP_FORWARD",
+          "go.PLAYBACK_LOOP_BACKWARD",
+          "go.PLAYBACK_LOOP_PINGPONG"
+        ],
+        ["go.PLAYBACK"]
+      ],
+      "replaces": ["go.Playback"]
+    },
     "go.delete:param:id": {
       "pins": [
         ["string", "hash", "url", "table"],
@@ -439,12 +438,18 @@
       "pins": [["nil", "string", "constant"]],
       "adds": ["Hash"]
     },
+    "gui.clone_tree:param:node": { "pins": [["node"]], "adds": ["undefined"] },
+    "gui.get_tree:param:node": { "pins": [["node"]], "adds": ["undefined"] },
     "gui.screen_to_local:param:screen_position": { "pins": [["vector3"]], "adds": ["Vector4"] },
     "gui.set_rotation:param:rotation": { "pins": [["quaternion", "vector4"]], "adds": ["Vector3"] },
     "gui.set_screen_position:param:screen_position": { "pins": [["vector3"]], "adds": ["Vector4"] },
-    "gui.set:param:value": {
-      "pins": [["number", "vector4", "vector3", "quaternion"]],
-      "adds": ["Matrix4", "Hash"]
+    "gui.set_xanchor:param:anchor": {
+      "pins": [["constant"], ["gui.ANCHOR"]],
+      "replaces": ["Exclude<gui.Anchor, typeof gui.ANCHOR_BOTTOM | typeof gui.ANCHOR_TOP>"]
+    },
+    "gui.set_yanchor:param:anchor": {
+      "pins": [["constant"], ["gui.ANCHOR"]],
+      "replaces": ["Exclude<gui.Anchor, typeof gui.ANCHOR_LEFT | typeof gui.ANCHOR_RIGHT>"]
     },
     "model.get_mesh_enabled:param:mesh_id": {
       "pins": [["string", "hash", "url"]],
@@ -458,15 +463,30 @@
     "physics.get_maskbit:param:group": { "pins": [["string"]], "adds": ["Hash"] },
     "physics.set_group:param:group": { "pins": [["string"]], "adds": ["Hash"] },
     "physics.set_maskbit:param:group": { "pins": [["string"]], "adds": ["Hash"] },
+    "render.disable_state:param:state": {
+      "pins": [["graphics.STATE"]],
+      "adds": [
+        "Exclude<graphics.State, typeof graphics.STATE_ALPHA_TEST_SUPPORTED | typeof graphics.STATE_SCISSOR_TEST>"
+      ],
+      "removes": ["graphics.State"]
+    },
     "render.disable_texture:param:binding": {
       "pins": [["texture", "string", "hash"]],
-      "adds": ["number"]
+      "adds": ["number"],
+      "removes": ["Opaque<\"texture\">"]
     },
     "render.draw:param:predicate": {
-      "pins": [["number"], ["render_predicate"]],
+      "pins": [["number"]],
       "adds": ["Opaque<\"render_predicate\">"],
       "removes": ["number"]
     },
+    "render.enable_state:param:state": {
+      "pins": [["graphics.STATE"]],
+      "adds": [
+        "Exclude<graphics.State, typeof graphics.STATE_ALPHA_TEST_SUPPORTED | typeof graphics.STATE_SCISSOR_TEST>"
+      ],
+      "removes": ["graphics.State"]
+    },
     "render.enable_texture:param:handle_or_name": {
       "pins": [["texture", "string", "hash"]],
       "adds": ["Opaque<\"render_target\">", "number"]
@@ -479,6 +499,26 @@
       "pins": [["render_target"]],
       "adds": ["string", "Hash"]
     },
+    "render.set_blend_func_separate:param:destination_factor_alpha": {
+      "pins": [["number"]],
+      "adds": ["graphics.BlendFactor"],
+      "removes": ["number"]
+    },
+    "render.set_blend_func_separate:param:destination_factor_color": {
+      "pins": [["number"]],
+      "adds": ["graphics.BlendFactor"],
+      "removes": ["number"]
+    },
+    "render.set_blend_func_separate:param:source_factor_alpha": {
+      "pins": [["number"]],
+      "adds": ["graphics.BlendFactor"],
+      "removes": ["number"]
+    },
+    "render.set_blend_func_separate:param:source_factor_color": {
+      "pins": [["number"]],
+      "adds": ["graphics.BlendFactor"],
+      "removes": ["number"]
+    },
     "render.set_camera:param:camera": {
       "pins": [["url", "number", "nil"]],
       "adds": ["string", "Hash"]
@@ -519,8 +559,8 @@
     },
     "window.set_dim_mode:param:mode": {
       "pins": [["window.DIMMING"]],
-      "adds": ["window.DimModeStateSettable"],
-      "removes": ["window.DIMMING"]
+      "adds": ["Exclude<window.Dimming, typeof window.DIMMING_UNKNOWN>"],
+      "removes": ["window.Dimming"]
     }
   },
   "returnCorrections": {
@@ -539,6 +579,10 @@
         "undefined"
       ]
     },
+    "bullet3d.shape.get_shape": {
+      "pins": [["bullet3d.shape.definition"]],
+      "replaces": ["bullet3d.shape.Definition", "{ type: typeof bullet3d.shape.SHAPE_TYPE_MESH }"]
+    },
     "collectionfactory.create": {
       "pins": [["table"], ["table<hash, hash>"]],
       "replaces": ["LuaTable<Hash, Hash> & { get: LuaTableGetMethod<string, Hash> }"]
@@ -561,6 +605,14 @@
         "LuaTable<Hash, Opaque<\"node\">> & { get: LuaTableGetMethod<string, Opaque<\"node\">> }"
       ]
     },
+    "gui.get_xanchor": {
+      "pins": [["constant"], ["gui.ANCHOR"]],
+      "replaces": ["Exclude<gui.Anchor, typeof gui.ANCHOR_BOTTOM | typeof gui.ANCHOR_TOP>"]
+    },
+    "gui.get_yanchor": {
+      "pins": [["constant"], ["gui.ANCHOR"]],
+      "replaces": ["Exclude<gui.Anchor, typeof gui.ANCHOR_LEFT | typeof gui.ANCHOR_RIGHT>"]
+    },
     "gui.new_texture": {
       "pins": [["number"]],
       "replaces": ["number", "undefined"],

package/index.d.ts

@@ -35,6 +35,8 @@ import "./src/go-overloads";
 import "./src/component-properties";
 import "./generated/graphics";
 import "./generated/gui";
+import "./src/gui-overloads";
+import "./src/gui-texture-removal";
 import "./generated/html5";
 import "./generated/http";
 import "./generated/image";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -77,6 +77,7 @@
     "fixtures/messages_doc.json",
     "fixtures/defold-*",
     "!fixtures/defold-*/engine-bindings",
+    "!fixtures/defold-*/engine-evidence",
     "!fixtures/defold-*/annotations",
     "examples/translations.json",
     "!src/**/*.test.ts",
@@ -93,6 +94,7 @@
     "!scripts/example-typecheck.ts",
     "!scripts/example-variant-drift.ts",
     "!scripts/engine-binding-extract.ts",
+    "!scripts/go-instance-functions.ts",
     "!scripts/binding-pin.ts",
     "!scripts/sync-engine-bindings.ts",
     "!scripts/engine-binding-diff.ts",

package/scripts/generate-api-availability.ts

@@ -28,37 +28,17 @@ import {
 } from "../src/emit-dts";
 import { splitTopLevel } from "../src/luals-type-expr";
 import { type ApiTarget, loadApiTargets, loadTargetModules } from "./regen";
+import { compareVersions, versionOf } from "./target-version";
 
 const PACKAGE_ROOT = resolve(import.meta.dir, "..");
 const MIGRATIONS_PATH = resolve(PACKAGE_ROOT, "api-migrations.json");
 const AVAILABILITY_PATH = resolve(PACKAGE_ROOT, "api-availability.json");
 
-const VERSION_FROM_ID = /^defold-(\d+\.\d+\.\d+)$/;
-
 export interface AvailabilityArtifact {
   readonly versions: readonly string[];
   readonly records: readonly ApiAvailability[];
 }
 
-export function versionOf(target: ApiTarget): string {
-  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));
-}
-
-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;
-}
-
 // Every complete committed surface, newest first. The committed targets are the
 // `source == null` entries of `api-targets.json` (ref-doc-sourced historical
 // targets are resolved on demand and never a committed-derivation input). This
@@ -98,8 +78,12 @@ export function identityCorrections(): IdentityCorrections {
         key,
         {
           pins: correctionPins(correction),
-          ...(correction.adds === undefined ? {} : { adds: union(correction.adds) }),
-          ...(correction.removes === undefined ? {} : { removes: [...correction.removes] }),
+          ...(correction.ts !== undefined
+            ? { replaces: union(correction.ts) }
+            : {
+                ...(correction.adds === undefined ? {} : { adds: union(correction.adds) }),
+                ...(correction.removes === undefined ? {} : { removes: [...correction.removes] }),
+              }),
         },
       ]),
     ),
@@ -118,7 +102,9 @@ export function identityCorrections(): IdentityCorrections {
       ]),
     ),
     constantFamilies: Object.fromEntries(
-      CONSTANT_UNION_ALIASES.map((alias) => [`${alias.home}.${alias.name}`, alias.members]),
+      CONSTANT_UNION_ALIASES.flatMap((alias) =>
+        "name" in alias ? [[`${alias.home}.${alias.name}`, alias.members] as const] : [],
+      ),
     ),
   };
 }

package/scripts/generate-api-signatures.ts

@@ -1,16 +1,18 @@
 import { resolve } from "node:path";
 import { symbolIdentityKey } from "../src/api-availability";
-import type { SlotTypes } from "../src/emit-dts";
-import { selectCompleteVersionSurfaces, versionOf } from "./generate-api-availability";
+import type { SlotType, SlotTypes } from "../src/emit-dts";
+import { signatureArmsFor } from "../src/signature-store";
+import { selectCompleteVersionSurfaces } from "./generate-api-availability";
 import {
   type ApiTarget,
-  type GenerateOptions,
   generateModuleSignatures,
   loadApiTargets,
   loadTargetModules,
   type ModuleManifestEntry,
+  type TargetBindingOptions,
 } from "./regen";
 import { loadSignatureFile } from "./signature-store-fs";
+import { versionOf } from "./target-version";
 
 const PACKAGE_ROOT = resolve(import.meta.dir, "..");
 const SIGNATURES_PATH = resolve(PACKAGE_ROOT, "api-signatures.json");
@@ -35,9 +37,7 @@ export interface BuildSignaturesOptions {
   // every target is emitted ungated and with no binding-pinned correction.
   // Supplied by the in-repo callers only: the vendored bindings it reads are not
   // published.
-  readonly emitOptionsOf?: (
-    target: ApiTarget,
-  ) => Pick<GenerateOptions, "registeredConstants" | "bindingEvidence">;
+  readonly emitOptionsOf?: (target: ApiTarget) => TargetBindingOptions;
 }
 
 // The authored replacement for a symbol the skip filter withheld, read from the
@@ -45,22 +45,59 @@ export interface BuildSignaturesOptions {
 // One seam keeps all three artifacts consistent: `overloads-signature-parity`
 // pins the store to the `src/*-overloads.d.ts` declarations, so folding the
 // store in cannot drift from the surface a consumer actually compiles against.
-function authoredSignature(packageRoot: string, namespace: string, fqn: string): string | null {
+// Only the arms the target's version declares are folded.
+function authoredSignature(
+  packageRoot: string,
+  namespace: string,
+  fqn: string,
+  version: string,
+): string | null {
   const store = loadSignatureFile(resolve(packageRoot, "signatures", `${namespace}.json`));
-  const forms = store[fqn]?.signatures ?? [];
+  const override = store[fqn];
+  const forms = override ? signatureArmsFor(override, version).signatures : [];
   return forms.length > 0 ? forms.join("\n") : null;
 }
 
+interface UnfilteredSurface {
+  readonly entries: readonly ModuleManifestEntry[];
+  readonly of: ReadonlyMap<ModuleManifestEntry, ModuleManifestEntry>;
+}
+
+const unfilteredSurfaces = new WeakMap<readonly ModuleManifestEntry[], UnfilteredSurface>();
+
+// The surface with every member's `skipFunctions` cleared, built once per
+// surface: dropping functions moves no type declaration, so it routes exactly
+// as the filtered one does.
+function unfilteredSurfaceOf(surface: readonly ModuleManifestEntry[]): UnfilteredSurface {
+  let unfiltered = unfilteredSurfaces.get(surface);
+  if (unfiltered === undefined) {
+    const of = new Map(surface.map((member) => [member, { ...member, skipFunctions: [] }]));
+    unfiltered = { entries: [...of.values()], of };
+    unfilteredSurfaces.set(surface, unfiltered);
+  }
+  return unfiltered;
+}
+
 // The symbols `skipFunctions` removed from this module, as the difference
 // between the unfiltered and filtered signature emits. Derived rather than
 // re-matched so the withholding rules stay owned by `prepareGeneratedModule`.
-export function withheldSymbols(entry: ModuleManifestEntry): { key: string; fqn: string }[] {
+// Both emits route in `surface`, the modules the entry is emitted beside, so a
+// slot naming a sibling's type resolves in the unfiltered emit too.
+export function withheldSymbols(
+  entry: ModuleManifestEntry,
+  surface: readonly ModuleManifestEntry[],
+): { key: string; fqn: string }[] {
   if ((entry.skipFunctions ?? []).length === 0) return [];
   const kept = new Set(
-    generateModuleSignatures(entry).map(({ identity }) => symbolIdentityKey(identity)),
+    generateModuleSignatures(entry, { surface }).map(({ identity }) => symbolIdentityKey(identity)),
   );
+  const unfiltered = unfilteredSurfaceOf(surface);
+  const self = unfiltered.of.get(entry);
+  if (self === undefined) {
+    throw new Error(`module "${entry.namespace}" is not a member of the surface it is emitted in`);
+  }
   const withheld: { key: string; fqn: string }[] = [];
-  for (const { identity } of generateModuleSignatures({ ...entry, skipFunctions: [] })) {
+  for (const { identity } of generateModuleSignatures(self, { surface: unfiltered.entries })) {
     const key = symbolIdentityKey(identity);
     if (kept.has(key)) continue;
     const fqn = key.split("\0")[2] as string;
@@ -69,6 +106,18 @@ export function withheldSymbols(entry: ModuleManifestEntry): { key: string; fqn:
   return withheld;
 }
 
+// The slots two arms record identically. One ledger cannot describe arms whose
+// types differ at a slot, so that slot is dropped and its row falls back to the
+// ref-doc token.
+function commonSlots(a: SlotTypes, b: SlotTypes): SlotTypes {
+  const common: Record<string, SlotType> = {};
+  for (const [slot, record] of Object.entries(a)) {
+    const other = b[slot];
+    if (other?.type === record.type && other.optional === record.optional) common[slot] = record;
+  }
+  return common;
+}
+
 function sortObjectKeys<T>(record: Record<string, T>): Record<string, T> {
   const sorted: Record<string, T> = {};
   for (const key of Object.keys(record).sort()) sorted[key] = record[key] as T;
@@ -86,9 +135,21 @@ export function buildSignaturesArtifact(options: BuildSignaturesOptions = {}): S
     const perSymbol: Record<string, string> = {};
     const perSymbolSlots: Record<string, SlotTypes> = {};
     const emitOptions = options.emitOptionsOf?.(target);
-    for (const entry of loadTargetModules(target, packageRoot)) {
+    const surface = loadTargetModules(target, packageRoot);
+    for (const entry of surface) {
       for (const signature of generateModuleSignatures(entry, emitOptions)) {
         const key = symbolIdentityKey(signature.identity);
+        // Two ref-doc elements can normalize to one identity (the Box2D backend
+        // forms of a `b2d.world` query), so each keeps its arms in fixture order
+        // and the key keeps only the slots every arm shares.
+        const earlier = perSymbol[key];
+        if (earlier !== undefined) {
+          perSymbol[key] = `${earlier}\n${signature.tsSignature}`;
+          const common = commonSlots(perSymbolSlots[key] ?? {}, signature.slotTypes);
+          if (Object.keys(common).length > 0) perSymbolSlots[key] = common;
+          else delete perSymbolSlots[key];
+          continue;
+        }
         perSymbol[key] = signature.tsSignature;
         if (Object.keys(signature.slotTypes).length > 0) {
           perSymbolSlots[key] = sortObjectKeys({ ...signature.slotTypes });
@@ -96,8 +157,8 @@ export function buildSignaturesArtifact(options: BuildSignaturesOptions = {}): S
       }
       // An authored fold replaces the declaration text wholesale, so whatever
       // slots the generated emit had recorded no longer describe it.
-      for (const { key, fqn } of withheldSymbols(entry)) {
-        const authored = authoredSignature(packageRoot, entry.namespace, fqn);
+      for (const { key, fqn } of withheldSymbols(entry, surface)) {
+        const authored = authoredSignature(packageRoot, entry.namespace, fqn, version);
         if (authored !== null) {
           perSymbol[key] = authored;
           delete perSymbolSlots[key];

package/scripts/materialize-version.ts

@@ -2,19 +2,23 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import {
   type ApiTarget,
-  type GenerateOptions,
+  GO_INSTANCE_SRC_AUGMENTATIONS,
   generateBuiltinMessagesDeclaration,
   generateModuleDeclaration,
   generateVersionIndex,
+  goInstanceFreeSurface,
+  goInstanceWalls,
   KIND_MODULE_MANIFEST,
   type KindManifestEntry,
   kindStdlibReferences,
+  loadGoInstanceFunctions,
   loadSrcAugmentations,
   loadTargetEditorModules,
   MESSAGES_MANIFEST,
   type ModuleManifestEntry,
   type ResolveTargetOptions,
   resolveTargetModules,
+  type TargetBindingOptions,
 } from "./regen";
 
 export {
@@ -41,6 +45,11 @@ export interface RenderMaterializedKindIndexOptions {
   // the universal set outright — an editor kind is disjoint from the runtime
   // surface, not a narrowing of it.
   readonly editorModules?: readonly string[];
+  // The universal modules the surface also carries as copies without the
+  // functions that need a game object, set when the target records which those
+  // are. A kind with no game object imports the copies instead and drops the
+  // augmentations marked as needing one; every other kind ignores it.
+  readonly goInstanceFreeModules?: readonly string[];
 }
 
 // The installed subpath a materialized kind re-exports its factory from: the
@@ -57,11 +66,21 @@ function installedFactoryModule(entry: KindManifestEntry): string {
 export function renderMaterializedKindIndex(opts: RenderMaterializedKindIndexOptions): string {
   const entry = KIND_MODULE_MANIFEST.find((e) => e.kind === opts.kind);
   if (!entry) throw new Error(`unknown script kind: ${opts.kind}`);
+  const freeDir = entry.goInstanceFreeDir;
+  const copied =
+    freeDir === undefined || opts.goInstanceFreeModules === undefined
+      ? null
+      : new Set(opts.goInstanceFreeModules);
+  const universal = opts.universalModules.filter(
+    (mod) => copied === null || !GO_INSTANCE_SRC_AUGMENTATIONS.includes(mod),
+  );
   const modules =
     entry.only === undefined
-      ? [...new Set(["engine-globals", ...opts.universalModules])].sort()
+      ? [...new Set(["engine-globals", ...universal])].sort()
       : [...(opts.editorModules ?? [])];
-  const lines = modules.map((mod) => `import "../${mod}";`);
+  const lines = modules.map((mod) =>
+    copied?.has(mod) ? `import "../${freeDir}/${mod}";` : `import "../${mod}";`,
+  );
   if (entry.only === undefined && opts.restrictedModule) {
     lines.push(`import "../${opts.restrictedModule}";`);
   }
@@ -89,14 +108,15 @@ export interface BuildVersionedSurfaceOptions {
   // script kind without the generator knowing what a script kind is.
   readonly excludeModules?: readonly string[];
   // The hand-authored `src/*` augmentations to carry beside the modules.
-  // Defaults to reading them from the types package on disk; a caller with no
-  // filesystem (a Worker) supplies the bytes and gets an identical file map.
+  // Defaults to reading the target's set (`srcAugmentationModulesFor`) from the
+  // types package on disk; a caller with no filesystem (a Worker) supplies the
+  // same bytes and gets an identical file map.
   readonly augmentations?: readonly VersionedSurfaceFile[];
   // What the target's own engine source decides for its emit
   // (`targetBindingOptions`). Only an in-repo caller rebuilding a vendored
   // target's committed surface passes it; a published install vendors no engine
   // source, and the ref-doc targets it materializes have none to read.
-  readonly emitOptions?: Pick<GenerateOptions, "registeredConstants" | "bindingEvidence">;
+  readonly emitOptions?: TargetBindingOptions;
 }
 
 export interface MaterializeVersionedSurfaceOptions extends BuildVersionedSurfaceOptions {
@@ -142,7 +162,7 @@ export async function buildVersionedSurfaceFiles(
   ).filter((entry) => kept(entry.outFile));
 
   const augmentations = (
-    opts.augmentations ?? loadSrcAugmentations(opts.resolveOpts?.packageRoot ?? undefined)
+    opts.augmentations ?? loadSrcAugmentations(opts.resolveOpts?.packageRoot ?? undefined, target)
   ).filter((file) => kept(file.path));
 
   // Re-rooting an entry makes it a new object no committed manifest holds, so
@@ -158,6 +178,27 @@ export async function buildVersionedSurfaceFiles(
       })),
   );
 
+  // A target whose engine source records the functions that need a game object
+  // carries, for each kind without one, copies of the modules declaring them
+  // with those functions withheld. Nothing else differs, so a target with no
+  // record writes no copy.
+  const walls = goInstanceWalls(
+    modules,
+    loadGoInstanceFunctions(target, opts.resolveOpts?.packageRoot ?? undefined),
+  );
+  for (const kind of KIND_MODULE_MANIFEST) {
+    const dir = kind.goInstanceFreeDir;
+    if (dir === undefined || walls.size === 0) continue;
+    const surface = rerooted(goInstanceFreeSurface(modules, walls, dir).surface);
+    for (const entry of surface) {
+      if (!entry.outFile.startsWith(`${dir}/`)) continue;
+      files.push({
+        path: entry.outFile,
+        contents: generateModuleDeclaration(entry, { ...opts.emitOptions, surface }).contents,
+      });
+    }
+  }
+
   files.push(...augmentations);
   files.push({ path: "core-types.d.ts", contents: CORE_TYPES_REEXPORT });