create-threenative 0.2.18 → 0.2.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (183) hide show
  1. package/agent-docs/references/capability-reference.md +212 -4
  2. package/agent-docs/references/kit-racing.md +4 -2
  3. package/agent-docs/references/performance-basics.md +2 -1
  4. package/agent-docs/references/terrain-authoring.md +21 -7
  5. package/agent-files/.agents/skills/prd-creator/SKILL.md +24 -0
  6. package/dist/index.js +255 -236
  7. package/dist/quality.d.ts +5 -1
  8. package/dist/quality.js +75 -6
  9. package/dist/terrain-kit.js +1 -1
  10. package/dist/threenative.js +6 -4
  11. package/dist/web-engine-post-effects.js +6 -0
  12. package/dist/web-engine-runtime.js +211 -36
  13. package/package.json +6 -6
  14. package/template-assets/assets/floor-fern-0.glb +0 -0
  15. package/template-assets/assets/floor-litter-0.glb +0 -0
  16. package/template-assets/assets/floor-log-0.glb +0 -0
  17. package/template-assets/assets/floor-log-1.glb +0 -0
  18. package/template-assets/assets/floor-stump-0.glb +0 -0
  19. package/template-assets/assets/floor-twig-0.glb +0 -0
  20. package/template-assets/quality/eslint.config.js +1 -1
  21. package/templates/action-rpg/package.json +7 -7
  22. package/templates/action-rpg/src/loot/drops.ts +3 -7
  23. package/templates/action-rpg/src/render/camera.ts +2 -2
  24. package/templates/action-rpg/src/render/clouds.ts +3 -1
  25. package/templates/action-rpg/src/render/materials.ts +3 -2
  26. package/templates/action-rpg/src/render/touch-controls.ts +7 -6
  27. package/templates/action-rpg/src/scenes/Play.ts +1 -15
  28. package/templates/adventure/AGENTS.md +3 -3
  29. package/templates/adventure/CLAUDE.md +3 -3
  30. package/templates/adventure/native-playtests/survives.playtest.json +12 -0
  31. package/templates/adventure/native-playtests/woodland-floor.playtest.json +61 -0
  32. package/templates/adventure/package.json +7 -7
  33. package/templates/adventure/playtests/grass.playtest.json +61 -0
  34. package/templates/adventure/playtests/performance.playtest.json +1 -1
  35. package/templates/adventure/playtests/survives.playtest.json +2 -2
  36. package/templates/adventure/playtests/woodland-floor.playtest.json +61 -0
  37. package/templates/adventure/src/entities/LockOn.ts +42 -4
  38. package/templates/adventure/src/entities/Warden.ts +4 -1
  39. package/templates/adventure/src/level/Vale.ts +241 -16
  40. package/templates/adventure/src/render/camera.ts +2 -2
  41. package/templates/adventure/src/render/foliage.ts +64 -20
  42. package/templates/adventure/src/render/grass.ts +325 -0
  43. package/templates/adventure/src/render/materials.ts +3 -2
  44. package/templates/adventure/src/render/palette.ts +3 -0
  45. package/templates/adventure/src/render/touch-controls.ts +4 -1
  46. package/templates/adventure/src/scenes/Play.ts +96 -1
  47. package/templates/collectathon/package.json +7 -7
  48. package/templates/collectathon/src/level/Course.ts +2 -7
  49. package/templates/collectathon/src/level/terrain.ts +2 -1
  50. package/templates/collectathon/src/render/camera.ts +2 -2
  51. package/templates/collectathon/src/render/ground.ts +4 -4
  52. package/templates/collectathon/src/render/hero.ts +1 -1
  53. package/templates/collectathon/src/render/materials.ts +0 -1
  54. package/templates/collectathon/src/render/sky.ts +4 -3
  55. package/templates/kart/package.json +6 -6
  56. package/templates/kart/src/entities/Kart.ts +2 -1
  57. package/templates/kart/src/render/course.ts +2 -1
  58. package/templates/kart/src/track/Course.ts +3 -1
  59. package/templates/minimal/package.json +6 -6
  60. package/templates/minimal/src/render/camera.ts +2 -2
  61. package/templates/minimal/src/render/clouds.ts +3 -1
  62. package/templates/minimal/src/render/materials.ts +3 -2
  63. package/templates/minimal/src/render/touch-controls.ts +7 -6
  64. package/templates/platformer/package.json +7 -7
  65. package/templates/platformer/playtests/collect.playtest.json +4 -1
  66. package/templates/platformer/src/level/Stage.ts +2 -6
  67. package/templates/platformer/src/scenes/Play.ts +2 -1
  68. package/templates/puzzle/package.json +7 -7
  69. package/templates/puzzle/src/entities/Warden.ts +3 -3
  70. package/templates/puzzle/src/render/camera.ts +2 -2
  71. package/templates/puzzle/src/render/touch-controls.ts +7 -6
  72. package/templates/racing/AGENTS.md +2 -2
  73. package/templates/racing/CLAUDE.md +2 -2
  74. package/templates/racing/CREDITS.md +29 -0
  75. package/templates/racing/assets/engine-loop.wav +0 -0
  76. package/templates/racing/assets/grass/Grass004_color.jpg +0 -0
  77. package/templates/racing/assets/grass/Grass004_normal.jpg +0 -0
  78. package/templates/racing/assets/grass/Grass004_roughness.jpg +0 -0
  79. package/templates/racing/assets/nitro-burst.wav +0 -0
  80. package/templates/racing/assets/tyre-squeal.wav +0 -0
  81. package/templates/racing/package.json +7 -7
  82. package/templates/racing/playtests/drift-natural.playtest.json +68 -0
  83. package/templates/racing/playtests/drift.playtest.json +100 -0
  84. package/templates/racing/playtests/hud.playtest.json +117 -0
  85. package/templates/racing/playtests/launch-pose.playtest.json +34 -0
  86. package/templates/racing/playtests/nitro.playtest.json +158 -0
  87. package/templates/racing/playtests/outcome.playtest.json +4 -4
  88. package/templates/racing/playtests/performance.playtest.json +1 -1
  89. package/templates/racing/playtests/steady-camera.playtest.json +88 -0
  90. package/templates/racing/src/audio/engine.ts +138 -0
  91. package/templates/racing/src/entities/CarBody.ts +83 -10
  92. package/templates/racing/src/entities/Drift.ts +243 -0
  93. package/templates/racing/src/entities/LineDriver.ts +2 -2
  94. package/templates/racing/src/entities/Nitro.ts +72 -0
  95. package/templates/racing/src/entities/RacingCar.ts +86 -21
  96. package/templates/racing/src/entities/Rival.ts +35 -21
  97. package/templates/racing/src/game.ts +6 -0
  98. package/templates/racing/src/gauges.ts +74 -0
  99. package/templates/racing/src/render/camera.ts +29 -4
  100. package/templates/racing/src/render/clouds.ts +3 -1
  101. package/templates/racing/src/render/effects.ts +244 -0
  102. package/templates/racing/src/render/materials.ts +43 -8
  103. package/templates/racing/src/render/shapes.ts +37 -0
  104. package/templates/racing/src/render/skids.ts +84 -0
  105. package/templates/racing/src/render/touch-controls.ts +10 -10
  106. package/templates/racing/src/scenes/Race.ts +277 -25
  107. package/templates/racing/src/state.ts +35 -0
  108. package/templates/racing/src/style.css +3 -0
  109. package/templates/racing/src/track/Track.ts +132 -58
  110. package/templates/racing/src/track/TrackSector.ts +19 -1
  111. package/templates/racing/src/track/circuit.ts +21 -15
  112. package/templates/racing/src/ui/GameUi.tsx +0 -2
  113. package/templates/racing/src/ui/Hud.tsx +417 -50
  114. package/templates/racing/threenative.config.ts +15 -0
  115. package/templates/racing/tools/make-racing-audio.mjs +388 -0
  116. package/templates/rain/package.json +6 -6
  117. package/templates/rain/src/render/noise-volume.ts +2 -1
  118. package/templates/rain/src/state.ts +3 -1
  119. package/templates/rain/src/ui/GameUi.tsx +1 -1
  120. package/templates/rain/src/ui/automation.ts +10 -8
  121. package/templates/rain/src/ui/tempest.ts +3 -4
  122. package/templates/rts/package.json +6 -6
  123. package/templates/rts/src/sim/terrain.ts +1 -0
  124. package/templates/rts/src/sim/types.ts +1 -0
  125. package/templates/runner/package.json +7 -7
  126. package/templates/runner/src/render/clouds.ts +3 -1
  127. package/templates/runner/src/render/materials.ts +3 -2
  128. package/templates/runner/src/render/touch-controls.ts +7 -6
  129. package/templates/runner/src/scenes/Run.ts +4 -9
  130. package/templates/sailing/package.json +7 -7
  131. package/templates/sailing/src/render/touch-controls.ts +7 -6
  132. package/templates/shooter/package.json +7 -7
  133. package/templates/shooter/src/render/clouds.ts +3 -1
  134. package/templates/snow/package.json +7 -7
  135. package/templates/snow/src/entities/Explorer.ts +6 -12
  136. package/templates/snow/src/render/bootPrint.ts +3 -1
  137. package/templates/snow/src/render/camera.ts +3 -2
  138. package/templates/snow/src/render/scenery.ts +3 -3
  139. package/templates/snow/src/render/touch-controls.ts +7 -6
  140. package/templates/snow/src/render/weather.ts +3 -5
  141. package/templates/snow/src/terrain.ts +2 -1
  142. package/templates/starter/native-playtests/render-chain.playtest.json +9 -9
  143. package/templates/starter/package.json +7 -7
  144. package/templates/starter/src/entities/Player.ts +10 -2
  145. package/templates/starter/src/render/camera.ts +2 -2
  146. package/templates/starter/src/render/clouds.ts +3 -1
  147. package/templates/starter/src/render/materials.ts +3 -2
  148. package/templates/starter/src/render/touch-controls.ts +7 -6
  149. package/templates/starter/src/scenes/Play.ts +1 -14
  150. package/templates/tower-defense/package.json +7 -7
  151. package/templates/tower-defense/src/render/shapes.ts +1 -2
  152. package/templates/tower-defense/src/scenes/Battle.ts +3 -8
  153. package/template-assets/terrain/alpine/assets.json +0 -12
  154. package/template-assets/terrain/alpine/bake.mjs +0 -6
  155. package/template-assets/terrain/alpine/credits.json +0 -164
  156. package/template-assets/terrain/alpine/heightmap.r16 +0 -0
  157. package/template-assets/terrain/alpine/recipe.json +0 -119
  158. package/template-assets/terrain/alpine/surface.json +0 -53
  159. package/template-assets/terrain/coastal/assets.json +0 -11
  160. package/template-assets/terrain/coastal/bake.mjs +0 -6
  161. package/template-assets/terrain/coastal/credits.json +0 -117
  162. package/template-assets/terrain/coastal/heightmap.r16 +0 -0
  163. package/template-assets/terrain/coastal/recipe.json +0 -113
  164. package/template-assets/terrain/coastal/surface.json +0 -41
  165. package/template-assets/terrain/desert/assets.json +0 -12
  166. package/template-assets/terrain/desert/bake.mjs +0 -6
  167. package/template-assets/terrain/desert/credits.json +0 -164
  168. package/template-assets/terrain/desert/heightmap.r16 +0 -0
  169. package/template-assets/terrain/desert/recipe.json +0 -108
  170. package/template-assets/terrain/desert/surface.json +0 -54
  171. package/template-assets/terrain/forest/assets.json +0 -65
  172. package/template-assets/terrain/forest/bake.mjs +0 -8
  173. package/template-assets/terrain/forest/credits.json +0 -225
  174. package/template-assets/terrain/forest/heightmap.r16 +0 -0
  175. package/template-assets/terrain/forest/recipe.json +0 -350
  176. package/template-assets/terrain/forest/surface.json +0 -79
  177. package/template-assets/terrain/tundra/assets.json +0 -12
  178. package/template-assets/terrain/tundra/bake.mjs +0 -6
  179. package/template-assets/terrain/tundra/credits.json +0 -164
  180. package/template-assets/terrain/tundra/heightmap.r16 +0 -0
  181. package/template-assets/terrain/tundra/recipe.json +0 -277
  182. package/template-assets/terrain/tundra/surface.json +0 -54
  183. package/templates/racing/src/ui/Menu.tsx +0 -7
package/dist/index.js CHANGED
@@ -12,6 +12,259 @@ import { createRequire as createRequire$1 } from 'module';
12
12
  import { parsePng, parseAudioConfig } from '@threenative/assets';
13
13
 
14
14
  createRequire(import.meta.url);
15
+
16
+ // ../core/mcp/servers.mjs
17
+ var MCP_SERVERS = Object.freeze({
18
+ "threenative-assets": Object.freeze({
19
+ command: "node",
20
+ args: Object.freeze(["./node_modules/@threenative/core/mcp/assets.mjs"]),
21
+ // Entries rather than an object literal: these are environment variable names, not identifiers,
22
+ // and written as property names they read as names the naming rule must judge.
23
+ env: Object.freeze(
24
+ Object.fromEntries([
25
+ ["ASSET_DOWNLOAD_DIR", "./public/assets"],
26
+ ["AUDIO_DOWNLOAD_DIR", "./public/audio"]
27
+ ])
28
+ )
29
+ }),
30
+ "threenative-sculpt": Object.freeze({
31
+ command: "node",
32
+ args: Object.freeze(["./node_modules/@threenative/core/mcp/sculpt.mjs"])
33
+ }),
34
+ "threenative-engine": Object.freeze({
35
+ command: "node",
36
+ args: Object.freeze(["./node_modules/@threenative/core/mcp/engine.mjs"])
37
+ }),
38
+ // Cooks a starter terrain kit into a world.glb. The server lives in the optional
39
+ // `@threenative/terrain` package, which the shim resolves from the project at launch.
40
+ "threenative-terrain": Object.freeze({
41
+ command: "node",
42
+ args: Object.freeze(["./node_modules/@threenative/core/mcp/terrain.mjs"])
43
+ }),
44
+ // Inspects, attaches, edits and verifies character animation. Every operation is a build-time
45
+ // edit of one GLB, so a game that animates nothing pays for nothing.
46
+ "threenative-animation": Object.freeze({
47
+ command: "node",
48
+ args: Object.freeze(["./node_modules/@threenative/core/mcp/animation.mjs"])
49
+ }),
50
+ // Google's Chrome DevTools server: performance traces, GPU timing, network, heap and console of
51
+ // the running game. It starts Chrome only on its first tool call, so a project that never
52
+ // inspects a page pays nothing. Its async stack capture inflates CPU time several times, so
53
+ // `trace-a-slow-frame.md` sends absolute CPU questions to `playtest trace` first.
54
+ "threenative-devtools": Object.freeze({
55
+ command: "node",
56
+ args: Object.freeze(["./node_modules/@threenative/core/mcp/devtools.mjs"])
57
+ })
58
+ });
59
+ var SERVER_FORMATS = Object.freeze({
60
+ // Claude Code (`.mcp.json`), Cursor and the Gemini CLI all read this one.
61
+ mcpServers: Object.freeze({
62
+ key: "mcpServers",
63
+ entry: (server) => ({
64
+ command: server.command,
65
+ args: [...server.args],
66
+ ...server.env === void 0 ? {} : { env: { ...server.env } }
67
+ })
68
+ }),
69
+ // VS Code names the table `servers` and requires an explicit transport per server.
70
+ vscode: Object.freeze({
71
+ key: "servers",
72
+ entry: (server) => ({
73
+ type: "stdio",
74
+ command: server.command,
75
+ args: [...server.args],
76
+ ...server.env === void 0 ? {} : { env: { ...server.env } }
77
+ })
78
+ }),
79
+ // opencode folds the command and its arguments into one array and spells the environment
80
+ // `environment`. A server it does not mark enabled is written down and never started.
81
+ opencode: Object.freeze({
82
+ key: "mcp",
83
+ entry: (server) => ({
84
+ type: "local",
85
+ command: [server.command, ...server.args],
86
+ enabled: true,
87
+ ...server.env === void 0 ? {} : { environment: { ...server.env } }
88
+ })
89
+ }),
90
+ // Zed calls them context servers and needs `source: "custom"` to accept a command of our own.
91
+ zed: Object.freeze({
92
+ key: "context_servers",
93
+ entry: (server) => ({
94
+ source: "custom",
95
+ command: server.command,
96
+ args: [...server.args],
97
+ ...server.env === void 0 ? {} : { env: { ...server.env } }
98
+ })
99
+ })
100
+ });
101
+ Object.freeze(Object.keys(SERVER_FORMATS));
102
+ function mergeMcpServers(existing, format = "mcpServers") {
103
+ const shape = SERVER_FORMATS[format];
104
+ if (shape === void 0) throw new Error(`Unknown MCP config format '${format}'.`);
105
+ const malformed = existing !== void 0 && (typeof existing !== "object" || existing === null || Array.isArray(existing));
106
+ if (malformed) {
107
+ throw new Error("MCP config root must be an object.");
108
+ }
109
+ const previous = existing ?? {};
110
+ const existingServers = previous[shape.key];
111
+ if (existingServers !== void 0 && (typeof existingServers !== "object" || existingServers === null || Array.isArray(existingServers))) {
112
+ throw new Error(`MCP config '${shape.key}' must be an object.`);
113
+ }
114
+ const servers = { ...existingServers ?? {} };
115
+ for (const [name, server] of Object.entries(servers)) {
116
+ if (typeof server !== "object" || server === null || Array.isArray(server)) {
117
+ throw new Error(`MCP server '${name}' in '${shape.key}' must be an object.`);
118
+ }
119
+ }
120
+ let changed = false;
121
+ const conflicts = [];
122
+ for (const [name, server] of Object.entries(MCP_SERVERS)) {
123
+ const wanted = shape.entry(server);
124
+ if (Object.hasOwn(servers, name)) {
125
+ if (JSON.stringify(servers[name]) !== JSON.stringify(wanted)) conflicts.push(name);
126
+ continue;
127
+ }
128
+ servers[name] = wanted;
129
+ changed = true;
130
+ }
131
+ return { changed, conflicts, config: { ...previous, [shape.key]: servers } };
132
+ }
133
+ function codexServerBlock(name, server) {
134
+ const args = server.args.map((argument) => JSON.stringify(argument)).join(", ");
135
+ const lines = [
136
+ `[mcp_servers.${name}]`,
137
+ `command = ${JSON.stringify(server.command)}`,
138
+ `args = [${args}]`
139
+ ];
140
+ if (server.env !== void 0) {
141
+ lines.push("", `[mcp_servers.${name}.env]`);
142
+ for (const [key, value] of Object.entries(server.env)) {
143
+ lines.push(`${key} = ${JSON.stringify(value)}`);
144
+ }
145
+ }
146
+ return lines.join("\n");
147
+ }
148
+ var CODEX_MCP_SERVERS = Object.freeze(
149
+ Object.entries(MCP_SERVERS).map(
150
+ ([name, server]) => Object.freeze({ body: codexServerBlock(name, server), name })
151
+ )
152
+ );
153
+
154
+ // ../core/src/version.ts
155
+ var CORE_VERSION = "0.3.15";
156
+ var MCP_HOSTS = Object.freeze([
157
+ Object.freeze({
158
+ id: "claude-code",
159
+ label: "Claude Code",
160
+ file: ".mcp.json",
161
+ format: "mcpServers"
162
+ }),
163
+ Object.freeze({ id: "codex", label: "Codex", file: ".codex/config.toml", format: "codex" }),
164
+ Object.freeze({ id: "cursor", label: "Cursor", file: ".cursor/mcp.json", format: "mcpServers" }),
165
+ Object.freeze({ id: "vscode", label: "VS Code", file: ".vscode/mcp.json", format: "vscode" }),
166
+ Object.freeze({
167
+ id: "gemini-cli",
168
+ label: "Gemini CLI",
169
+ file: ".gemini/settings.json",
170
+ format: "mcpServers"
171
+ }),
172
+ Object.freeze({
173
+ id: "opencode",
174
+ label: "opencode",
175
+ file: "opencode.json",
176
+ format: "opencode",
177
+ // Written only when this installer creates the file, so a second install still reports
178
+ // "unchanged" rather than rewriting a config the user has since edited.
179
+ seed: Object.freeze({ $schema: "https://opencode.ai/config.json" })
180
+ }),
181
+ Object.freeze({ id: "zed", label: "Zed", file: ".zed/settings.json", format: "zed" })
182
+ ]);
183
+ function ensureJsonMcpConfig(target, file, format, seed = void 0) {
184
+ const configPath = path8.join(target, file);
185
+ let existing;
186
+ if (existsSync(configPath)) {
187
+ try {
188
+ existing = JSON.parse(readFileSync(configPath, "utf8"));
189
+ } catch {
190
+ return "unreadable";
191
+ }
192
+ }
193
+ let merged;
194
+ try {
195
+ merged = mergeMcpServers(existing, format);
196
+ } catch {
197
+ return "unreadable";
198
+ }
199
+ const { changed, config, conflicts } = merged;
200
+ if (!changed) return conflicts.length > 0 ? "conflict" : "unchanged";
201
+ const written = existing === void 0 ? { ...seed, ...config } : config;
202
+ mkdirSync(path8.dirname(configPath), { recursive: true });
203
+ writeFileSync(configPath, `${JSON.stringify(written, null, 2)}
204
+ `);
205
+ return conflicts.length > 0 ? "conflict" : existing === void 0 ? "created" : "updated";
206
+ }
207
+ function ensureCodexMcpConfig(target) {
208
+ const directory = path8.join(target, ".codex");
209
+ const configPath = path8.join(directory, "config.toml");
210
+ const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
211
+ const missing = CODEX_MCP_SERVERS.filter(
212
+ ({ name }) => !existing.includes(`[mcp_servers.${name}]`)
213
+ );
214
+ if (missing.length === 0) return "unchanged";
215
+ mkdirSync(directory, { recursive: true });
216
+ const separator = existing.length === 0 || existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
217
+ writeFileSync(
218
+ configPath,
219
+ `${existing}${separator}${missing.map(({ body }) => body).join("\n\n")}
220
+ `
221
+ );
222
+ return existing.length === 0 ? "created" : "updated";
223
+ }
224
+ function ensureHostMcpConfigs(target) {
225
+ const outcomes = /* @__PURE__ */ new Map();
226
+ for (const host of MCP_HOSTS) {
227
+ try {
228
+ outcomes.set(
229
+ host.id,
230
+ host.format === "codex" ? ensureCodexMcpConfig(target) : ensureJsonMcpConfig(target, host.file, host.format, host.seed)
231
+ );
232
+ } catch {
233
+ outcomes.set(host.id, "unreadable");
234
+ }
235
+ }
236
+ return outcomes;
237
+ }
238
+
239
+ // src/mcp-servers.ts
240
+ var CORE_PACKAGE_NAME = "@threenative/core";
241
+ var CORE_PACKAGE_VERSION = CORE_VERSION;
242
+ function serverEntryPath(server) {
243
+ const entry = server.args[0];
244
+ if (entry === void 0) {
245
+ throw new Error("TN_MCP_TABLE: an MCP server entry declares no shim to launch.");
246
+ }
247
+ return entry;
248
+ }
249
+
250
+ // src/core-pair.ts
251
+ function parts(value) {
252
+ const match = /^(\d+)\.(\d+)\.(\d+)/u.exec(value.trim());
253
+ if (match === null) return void 0;
254
+ const parsed = [Number(match[1]), Number(match[2]), Number(match[3])];
255
+ return parsed.every(Number.isSafeInteger) ? parsed : void 0;
256
+ }
257
+ function pairsWithCore(installed) {
258
+ if (installed === void 0) return false;
259
+ const have = parts(installed);
260
+ const paired = parts(CORE_PACKAGE_VERSION);
261
+ if (have === void 0 || paired === void 0) return false;
262
+ const [haveMajor, haveMinor, havePatch] = have;
263
+ const [pairedMajor, pairedMinor, pairedPatch] = paired;
264
+ if (haveMajor !== pairedMajor) return haveMajor > pairedMajor;
265
+ if (haveMinor !== pairedMinor) return haveMinor > pairedMinor;
266
+ return havePatch >= pairedPatch;
267
+ }
15
268
  var SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([".glb", ".gltf"]);
16
269
  var METRE_UPPER_BOUND = 10;
17
270
  var CENTIMETRE_LOWER_BOUND = 100;
@@ -289,240 +542,6 @@ async function inspectCommand(argv, write = (text) => process.stdout.write(text)
289
542
  ` : formatAssetInspection(result));
290
543
  return result;
291
544
  }
292
-
293
- // ../core/mcp/servers.mjs
294
- var MCP_SERVERS = Object.freeze({
295
- "threenative-assets": Object.freeze({
296
- command: "node",
297
- args: Object.freeze(["./node_modules/@threenative/core/mcp/assets.mjs"]),
298
- // Entries rather than an object literal: these are environment variable names, not identifiers,
299
- // and written as property names they read as names the naming rule must judge.
300
- env: Object.freeze(
301
- Object.fromEntries([
302
- ["ASSET_DOWNLOAD_DIR", "./public/assets"],
303
- ["AUDIO_DOWNLOAD_DIR", "./public/audio"]
304
- ])
305
- )
306
- }),
307
- "threenative-sculpt": Object.freeze({
308
- command: "node",
309
- args: Object.freeze(["./node_modules/@threenative/core/mcp/sculpt.mjs"])
310
- }),
311
- "threenative-engine": Object.freeze({
312
- command: "node",
313
- args: Object.freeze(["./node_modules/@threenative/core/mcp/engine.mjs"])
314
- }),
315
- // Cooks a starter terrain kit into a world.glb. The server lives in the optional
316
- // `@threenative/terrain` package, which the shim resolves from the project at launch.
317
- "threenative-terrain": Object.freeze({
318
- command: "node",
319
- args: Object.freeze(["./node_modules/@threenative/core/mcp/terrain.mjs"])
320
- }),
321
- // Inspects, attaches, edits and verifies character animation. Every operation is a build-time
322
- // edit of one GLB, so a game that animates nothing pays for nothing.
323
- "threenative-animation": Object.freeze({
324
- command: "node",
325
- args: Object.freeze(["./node_modules/@threenative/core/mcp/animation.mjs"])
326
- }),
327
- // Google's Chrome DevTools server: performance traces, GPU timing, network, heap and console of
328
- // the running game. It starts Chrome only on its first tool call, so a project that never
329
- // inspects a page pays nothing. Its async stack capture inflates CPU time several times, so
330
- // `trace-a-slow-frame.md` sends absolute CPU questions to `playtest trace` first.
331
- "threenative-devtools": Object.freeze({
332
- command: "node",
333
- args: Object.freeze(["./node_modules/@threenative/core/mcp/devtools.mjs"])
334
- })
335
- });
336
- var SERVER_FORMATS = Object.freeze({
337
- // Claude Code (`.mcp.json`), Cursor and the Gemini CLI all read this one.
338
- mcpServers: Object.freeze({
339
- key: "mcpServers",
340
- entry: (server) => ({
341
- command: server.command,
342
- args: [...server.args],
343
- ...server.env === void 0 ? {} : { env: { ...server.env } }
344
- })
345
- }),
346
- // VS Code names the table `servers` and requires an explicit transport per server.
347
- vscode: Object.freeze({
348
- key: "servers",
349
- entry: (server) => ({
350
- type: "stdio",
351
- command: server.command,
352
- args: [...server.args],
353
- ...server.env === void 0 ? {} : { env: { ...server.env } }
354
- })
355
- }),
356
- // opencode folds the command and its arguments into one array and spells the environment
357
- // `environment`. A server it does not mark enabled is written down and never started.
358
- opencode: Object.freeze({
359
- key: "mcp",
360
- entry: (server) => ({
361
- type: "local",
362
- command: [server.command, ...server.args],
363
- enabled: true,
364
- ...server.env === void 0 ? {} : { environment: { ...server.env } }
365
- })
366
- }),
367
- // Zed calls them context servers and needs `source: "custom"` to accept a command of our own.
368
- zed: Object.freeze({
369
- key: "context_servers",
370
- entry: (server) => ({
371
- source: "custom",
372
- command: server.command,
373
- args: [...server.args],
374
- ...server.env === void 0 ? {} : { env: { ...server.env } }
375
- })
376
- })
377
- });
378
- Object.freeze(Object.keys(SERVER_FORMATS));
379
- function mergeMcpServers(existing, format = "mcpServers") {
380
- const shape = SERVER_FORMATS[format];
381
- if (shape === void 0) throw new Error(`Unknown MCP config format '${format}'.`);
382
- const malformed = existing !== void 0 && (typeof existing !== "object" || existing === null || Array.isArray(existing));
383
- if (malformed) {
384
- throw new Error("MCP config root must be an object.");
385
- }
386
- const previous = existing ?? {};
387
- const existingServers = previous[shape.key];
388
- if (existingServers !== void 0 && (typeof existingServers !== "object" || existingServers === null || Array.isArray(existingServers))) {
389
- throw new Error(`MCP config '${shape.key}' must be an object.`);
390
- }
391
- const servers = { ...existingServers ?? {} };
392
- for (const [name, server] of Object.entries(servers)) {
393
- if (typeof server !== "object" || server === null || Array.isArray(server)) {
394
- throw new Error(`MCP server '${name}' in '${shape.key}' must be an object.`);
395
- }
396
- }
397
- let changed = false;
398
- const conflicts = [];
399
- for (const [name, server] of Object.entries(MCP_SERVERS)) {
400
- const wanted = shape.entry(server);
401
- if (Object.hasOwn(servers, name)) {
402
- if (JSON.stringify(servers[name]) !== JSON.stringify(wanted)) conflicts.push(name);
403
- continue;
404
- }
405
- servers[name] = wanted;
406
- changed = true;
407
- }
408
- return { changed, conflicts, config: { ...previous, [shape.key]: servers } };
409
- }
410
- function codexServerBlock(name, server) {
411
- const args = server.args.map((argument) => JSON.stringify(argument)).join(", ");
412
- const lines = [
413
- `[mcp_servers.${name}]`,
414
- `command = ${JSON.stringify(server.command)}`,
415
- `args = [${args}]`
416
- ];
417
- if (server.env !== void 0) {
418
- lines.push("", `[mcp_servers.${name}.env]`);
419
- for (const [key, value] of Object.entries(server.env)) {
420
- lines.push(`${key} = ${JSON.stringify(value)}`);
421
- }
422
- }
423
- return lines.join("\n");
424
- }
425
- var CODEX_MCP_SERVERS = Object.freeze(
426
- Object.entries(MCP_SERVERS).map(
427
- ([name, server]) => Object.freeze({ body: codexServerBlock(name, server), name })
428
- )
429
- );
430
-
431
- // ../core/src/version.ts
432
- var CORE_VERSION = "0.3.13";
433
- var MCP_HOSTS = Object.freeze([
434
- Object.freeze({
435
- id: "claude-code",
436
- label: "Claude Code",
437
- file: ".mcp.json",
438
- format: "mcpServers"
439
- }),
440
- Object.freeze({ id: "codex", label: "Codex", file: ".codex/config.toml", format: "codex" }),
441
- Object.freeze({ id: "cursor", label: "Cursor", file: ".cursor/mcp.json", format: "mcpServers" }),
442
- Object.freeze({ id: "vscode", label: "VS Code", file: ".vscode/mcp.json", format: "vscode" }),
443
- Object.freeze({
444
- id: "gemini-cli",
445
- label: "Gemini CLI",
446
- file: ".gemini/settings.json",
447
- format: "mcpServers"
448
- }),
449
- Object.freeze({
450
- id: "opencode",
451
- label: "opencode",
452
- file: "opencode.json",
453
- format: "opencode",
454
- // Written only when this installer creates the file, so a second install still reports
455
- // "unchanged" rather than rewriting a config the user has since edited.
456
- seed: Object.freeze({ $schema: "https://opencode.ai/config.json" })
457
- }),
458
- Object.freeze({ id: "zed", label: "Zed", file: ".zed/settings.json", format: "zed" })
459
- ]);
460
- function ensureJsonMcpConfig(target, file, format, seed = void 0) {
461
- const configPath = path8.join(target, file);
462
- let existing;
463
- if (existsSync(configPath)) {
464
- try {
465
- existing = JSON.parse(readFileSync(configPath, "utf8"));
466
- } catch {
467
- return "unreadable";
468
- }
469
- }
470
- let merged;
471
- try {
472
- merged = mergeMcpServers(existing, format);
473
- } catch {
474
- return "unreadable";
475
- }
476
- const { changed, config, conflicts } = merged;
477
- if (!changed) return conflicts.length > 0 ? "conflict" : "unchanged";
478
- const written = existing === void 0 ? { ...seed, ...config } : config;
479
- mkdirSync(path8.dirname(configPath), { recursive: true });
480
- writeFileSync(configPath, `${JSON.stringify(written, null, 2)}
481
- `);
482
- return conflicts.length > 0 ? "conflict" : existing === void 0 ? "created" : "updated";
483
- }
484
- function ensureCodexMcpConfig(target) {
485
- const directory = path8.join(target, ".codex");
486
- const configPath = path8.join(directory, "config.toml");
487
- const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
488
- const missing = CODEX_MCP_SERVERS.filter(
489
- ({ name }) => !existing.includes(`[mcp_servers.${name}]`)
490
- );
491
- if (missing.length === 0) return "unchanged";
492
- mkdirSync(directory, { recursive: true });
493
- const separator = existing.length === 0 || existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
494
- writeFileSync(
495
- configPath,
496
- `${existing}${separator}${missing.map(({ body }) => body).join("\n\n")}
497
- `
498
- );
499
- return existing.length === 0 ? "created" : "updated";
500
- }
501
- function ensureHostMcpConfigs(target) {
502
- const outcomes = /* @__PURE__ */ new Map();
503
- for (const host of MCP_HOSTS) {
504
- try {
505
- outcomes.set(
506
- host.id,
507
- host.format === "codex" ? ensureCodexMcpConfig(target) : ensureJsonMcpConfig(target, host.file, host.format, host.seed)
508
- );
509
- } catch {
510
- outcomes.set(host.id, "unreadable");
511
- }
512
- }
513
- return outcomes;
514
- }
515
-
516
- // src/mcp-servers.ts
517
- var CORE_PACKAGE_NAME = "@threenative/core";
518
- var CORE_PACKAGE_VERSION = CORE_VERSION;
519
- function serverEntryPath(server) {
520
- const entry = server.args[0];
521
- if (entry === void 0) {
522
- throw new Error("TN_MCP_TABLE: an MCP server entry declares no shim to launch.");
523
- }
524
- return entry;
525
- }
526
545
  var ORIENTATIONS = ["landscape", "portrait", "sensor"];
527
546
  var CONFIG_FILE = "threenative.config.ts";
528
547
  var ConfigFailure = class extends Error {
@@ -3410,10 +3429,10 @@ async function installedCoreVersion(game) {
3410
3429
  }
3411
3430
  async function assertEnginePair(game) {
3412
3431
  const installed = await installedCoreVersion(game);
3413
- if (installed === CORE_PACKAGE_VERSION) return;
3432
+ if (pairsWithCore(installed)) return;
3414
3433
  const got = installed === void 0 ? "no installed core" : `${CORE_PACKAGE_NAME}@${installed}`;
3415
3434
  throw new Error(
3416
- `TN_AUTHORING_LAYER_PAIR: this create-threenative pairs with ${CORE_PACKAGE_NAME}@${CORE_PACKAGE_VERSION}, and this game installs ${got}. Run '${ENGINE_PAIR_UPGRADE}' first, then 'pnpm exec threenative doctor --fix'.`
3435
+ `TN_AUTHORING_LAYER_PAIR: this create-threenative pairs with ${CORE_PACKAGE_NAME}@${CORE_PACKAGE_VERSION} or newer, and this game installs ${got}. Run '${ENGINE_PAIR_UPGRADE}' first, then 'pnpm exec threenative doctor --fix'.`
3417
3436
  );
3418
3437
  }
3419
3438
  async function authoringLayerStatus(game, root = templateRoot()) {
package/dist/quality.d.ts CHANGED
@@ -3,10 +3,14 @@ import { Linter } from 'eslint';
3
3
  interface IQualityOptions {
4
4
  /** The project root: where `tsconfig.json` lives and the typed rules resolve from. */
5
5
  readonly root: string;
6
+ /** The reinvention rows (`reinventions.ts`). A scaffolded config turns them on; a game made
7
+ * before they existed passes only `root`, and an upgrade never rewrites that file, so its own
8
+ * code keeps the rules it was made with. */
9
+ readonly reinventions?: boolean;
6
10
  }
7
11
  /** The default correctness gate for a generated game: TypeScript-aware async rules, React hook
8
12
  * rules when React is installed, scoped suppressions, and the ThreeNative game rules (`threenative/*`: frame-callback cost, UI state use).
9
13
  * Formatting is Biome's job, not this config's. */
10
- declare function qualityConfig({ root }: IQualityOptions): Linter.Config[];
14
+ declare function qualityConfig({ root, reinventions }: IQualityOptions): Linter.Config[];
11
15
 
12
16
  export { type IQualityOptions, qualityConfig };
package/dist/quality.js CHANGED
@@ -166368,6 +166368,7 @@ var import_parser = __toESM(require_dist9());
166368
166368
 
166369
166369
  // src/quality/hotCallbacks.ts
166370
166370
  var FRAME_METHODS = /* @__PURE__ */ new Set(["render", "update"]);
166371
+ var ENTITY_FRAME_METHODS = /* @__PURE__ */ new Set(["fixedUpdate", "step", "tick", "update"]);
166371
166372
  var FRAME_HOOKS = /* @__PURE__ */ new Map([
166372
166373
  ["afterPhysics", "ctx.afterPhysics"],
166373
166374
  ["beforeRender", "ctx.beforeRender"],
@@ -166402,16 +166403,25 @@ function hookName(parent, node) {
166402
166403
  const name = calleeMember(parent, node);
166403
166404
  return name === void 0 ? void 0 : FRAME_HOOKS.get(name);
166404
166405
  }
166406
+ function methodLabel(parent, sceneLocals) {
166407
+ if (parent.type !== "MethodDefinition" || parent.static || parent.key.type !== "Identifier")
166408
+ return void 0;
166409
+ const owner = parent.parent?.parent ?? void 0;
166410
+ const base = owner?.superClass;
166411
+ const isSceneBase = base?.type === "Identifier" && sceneLocals.has(base.name);
166412
+ if (isSceneBase)
166413
+ return FRAME_METHODS.has(parent.key.name) ? `Scene.${parent.key.name}` : void 0;
166414
+ if (!ENTITY_FRAME_METHODS.has(parent.key.name)) return void 0;
166415
+ const className2 = owner?.id?.name;
166416
+ return className2 === void 0 ? parent.key.name : `${className2}.${parent.key.name}`;
166417
+ }
166405
166418
  function trackHotCallbacks() {
166406
166419
  const sceneLocals = /* @__PURE__ */ new Set();
166407
166420
  const frames = [];
166408
166421
  const frameName = (node) => {
166409
166422
  const parent = node.parent;
166410
- if (parent.type === "MethodDefinition" && !parent.static && parent.key.type === "Identifier") {
166411
- const base = parent.parent?.parent?.superClass;
166412
- const isSceneBase = base?.type === "Identifier" && sceneLocals.has(base.name);
166413
- if (isSceneBase && FRAME_METHODS.has(parent.key.name)) return `Scene.${parent.key.name}`;
166414
- }
166423
+ const method = methodLabel(parent, sceneLocals);
166424
+ if (method !== void 0) return method;
166415
166425
  const hook = hookName(parent, node);
166416
166426
  if (hook !== void 0) return hook;
166417
166427
  const member = calleeMember(parent, node);
@@ -166634,6 +166644,64 @@ var threenativePlugin = {
166634
166644
  }
166635
166645
  };
166636
166646
 
166647
+ // src/quality/reinventions.ts
166648
+ var PRNG_OUTSIDE = ["src/audio.ts", "src/audio/**", "src/render/**", "src/ui/**"];
166649
+ var REINVENTIONS = [
166650
+ {
166651
+ selector: ':matches(CallExpression[callee.object.name="Math"][callee.property.name="random"], Literal[value=1664525], Literal[value=1013904223], Literal[value=1831565813])',
166652
+ capability: "createRandom",
166653
+ source: "core",
166654
+ outside: PRNG_OUTSIDE,
166655
+ message: "A hand-written PRNG (Math.random or the LCG constants) is a capability the engine ships: use `createRandom(seed)` from `@threenative/core`, or `ctx.random`, so the same seed replays the same game."
166656
+ },
166657
+ {
166658
+ selector: 'BinaryExpression[operator="-"][left.value=1][right.callee.object.name="Math"][right.callee.property.name="exp"]',
166659
+ capability: "MathUtils.damp",
166660
+ source: "three",
166661
+ message: "`1 - Math.exp(-\u2026)` is a damp factor the engine ships: use `MathUtils.damp(current, target, rate, dt)` from `three`, which is the same curve with the rate named."
166662
+ },
166663
+ {
166664
+ selector: ':matches(MemberExpression[object.name="location"][property.name="search"], MemberExpression[object.property.name="location"][property.name="search"])',
166665
+ capability: "debugFlag",
166666
+ source: "core",
166667
+ message: "Reading `location.search` by hand is a launch seam the engine owns: use `debugFlag(name)` or `debugValue(name)` from `@threenative/core` (`?name` on web, `TN_DEBUG_NAME` on native)."
166668
+ },
166669
+ {
166670
+ selector: 'AssignmentExpression[left.property.name="matrixWorldAutoUpdate"][right.value=false]',
166671
+ capability: "renderer.matrixWorld",
166672
+ source: "core",
166673
+ message: "Turning `matrixWorldAutoUpdate` off by hand is the engine's own walk: set `renderer.matrixWorld` in the game config for a whole scene, or `markStatic(node)` for one node that never moves."
166674
+ },
166675
+ {
166676
+ selector: 'BinaryExpression[operator="-"][left.type="ConditionalExpression"][left.consequent.value=1][left.alternate.value=0][right.type="ConditionalExpression"][right.consequent.value=1][right.alternate.value=0]',
166677
+ capability: "InputMap.axis",
166678
+ source: "core",
166679
+ message: "An axis built from raw keys is a binding the engine already reads: declare it in `defineGame({ input })` and use `ctx.input.axis(name)` from `@threenative/core`."
166680
+ },
166681
+ {
166682
+ selector: 'BinaryExpression[operator="*"][right.type="BinaryExpression"][right.operator="-"][right.left.value=3][right.right.type="BinaryExpression"][right.right.operator="*"][right.right.left.value=2]',
166683
+ capability: "MathUtils.smoothstep",
166684
+ source: "three",
166685
+ message: "`x * x * (3 - 2 * x)` is the engine's smoothstep: use `MathUtils.smoothstep(x, 0, 1)` from `three`, which clamps the same way."
166686
+ }
166687
+ ];
166688
+ function reinventionRules(rows) {
166689
+ return {
166690
+ "no-restricted-syntax": [
166691
+ "error",
166692
+ ...rows.map(({ selector, message }) => ({ selector, message }))
166693
+ ]
166694
+ };
166695
+ }
166696
+ function reinventionConfigs(files) {
166697
+ const always = REINVENTIONS.filter((row) => row.outside === void 0);
166698
+ const ignores = [...new Set(REINVENTIONS.flatMap((row) => row.outside ?? []))];
166699
+ return [
166700
+ { files: [...files], rules: reinventionRules(always) },
166701
+ { files: [...files], ignores, rules: reinventionRules(REINVENTIONS) }
166702
+ ];
166703
+ }
166704
+
166637
166705
  // src/quality/index.ts
166638
166706
  var asPlugin = (plugin) => plugin;
166639
166707
  var SOURCE = ["src/**/*.ts", "src/**/*.tsx"];
@@ -166641,7 +166709,7 @@ function hasReact(root) {
166641
166709
  const manifest = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
166642
166710
  return ["dependencies", "devDependencies"].some((field) => manifest[field]?.react !== void 0);
166643
166711
  }
166644
- function qualityConfig({ root }) {
166712
+ function qualityConfig({ root, reinventions = false }) {
166645
166713
  const config = [
166646
166714
  { ignores: ["**/node_modules/**", "**/dist/**", "**/.threenative/**", "**/dist-native/**"] },
166647
166715
  {
@@ -166675,6 +166743,7 @@ function qualityConfig({ root }) {
166675
166743
  }
166676
166744
  }
166677
166745
  ];
166746
+ if (reinventions) config.push(...reinventionConfigs(SOURCE));
166678
166747
  if (hasReact(root)) {
166679
166748
  config.push({
166680
166749
  files: ["src/**/*.tsx"],
@@ -4,7 +4,7 @@ import path from 'path';
4
4
  import { fileURLToPath } from 'url';
5
5
 
6
6
  createRequire(import.meta.url);
7
- var KITS = ["alpine", "coastal", "desert", "forest", "tundra"];
7
+ var KITS = ["alpine", "coastal", "desert", "tundra"];
8
8
  var COPIED = [
9
9
  "assets.json",
10
10
  "bake.mjs",