create-threenative 0.2.17 → 0.2.18
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.
- package/agent-docs/kit-mcp.md +1 -1
- package/agent-docs/kit-router.md +1 -1
- package/agent-docs/references/assertion-reference.md +54 -110
- package/agent-docs/references/capability-reference.md +580 -22
- package/agent-docs/references/conventions.md +28 -0
- package/agent-docs/references/performance-basics.md +8 -4
- package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
- package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +7 -4
- package/agent-files/.claude/hooks/discovery-gate.mjs +2 -2
- package/dist/index.d.ts +97 -6
- package/dist/index.js +769 -277
- package/dist/threenative.js +96 -17
- package/dist/web-engine-ccd-ik-solver.js +127 -0
- package/dist/web-engine-gltf-loader.js +52 -14
- package/dist/web-engine-post-effects.js +5 -10
- package/dist/web-engine-runtime.js +3648 -546
- package/package.json +8 -7
- package/template-assets/clearwater/README.md +1 -1
- package/template-assets/patches/manifest.json +18 -0
- package/template-assets/terrain/alpine/assets.json +12 -0
- package/template-assets/terrain/alpine/bake.mjs +6 -0
- package/template-assets/terrain/alpine/credits.json +164 -0
- package/template-assets/terrain/alpine/heightmap.r16 +0 -0
- package/template-assets/terrain/alpine/recipe.json +119 -0
- package/template-assets/terrain/alpine/surface.json +53 -0
- package/template-assets/terrain/coastal/assets.json +11 -0
- package/template-assets/terrain/coastal/bake.mjs +6 -0
- package/template-assets/terrain/coastal/credits.json +117 -0
- package/template-assets/terrain/coastal/heightmap.r16 +0 -0
- package/template-assets/terrain/coastal/recipe.json +113 -0
- package/template-assets/terrain/coastal/surface.json +41 -0
- package/template-assets/terrain/desert/assets.json +12 -0
- package/template-assets/terrain/desert/bake.mjs +6 -0
- package/template-assets/terrain/desert/credits.json +164 -0
- package/template-assets/terrain/desert/heightmap.r16 +0 -0
- package/template-assets/terrain/desert/recipe.json +108 -0
- package/template-assets/terrain/desert/surface.json +54 -0
- package/template-assets/terrain/forest/assets.json +65 -0
- package/template-assets/terrain/forest/bake.mjs +8 -0
- package/template-assets/terrain/forest/credits.json +225 -0
- package/template-assets/terrain/forest/heightmap.r16 +0 -0
- package/template-assets/terrain/forest/recipe.json +350 -0
- package/template-assets/terrain/forest/surface.json +79 -0
- package/template-assets/terrain/tundra/assets.json +12 -0
- package/template-assets/terrain/tundra/bake.mjs +6 -0
- package/template-assets/terrain/tundra/credits.json +164 -0
- package/template-assets/terrain/tundra/heightmap.r16 +0 -0
- package/template-assets/terrain/tundra/recipe.json +277 -0
- package/template-assets/terrain/tundra/surface.json +54 -0
- package/templates/action-rpg/AGENTS.md +8 -4
- package/templates/action-rpg/CLAUDE.md +8 -4
- package/templates/action-rpg/package.json +7 -7
- package/templates/action-rpg/src/game.ts +1 -1
- package/templates/action-rpg/src/render/atmosphere.ts +6 -0
- package/templates/action-rpg/src/render/backlightControls.ts +10 -0
- package/templates/action-rpg/src/render/backlightMaterial.ts +4 -4
- package/templates/action-rpg/src/render/clouds.ts +13 -0
- package/templates/action-rpg/src/render/materialLighting.ts +5 -5
- package/templates/action-rpg/src/render/quality.ts +7 -32
- package/templates/action-rpg/src/scenes/Play.ts +4 -1
- package/templates/action-rpg/src/style.css +4 -0
- package/templates/action-rpg/vite.config.ts +2 -0
- package/templates/adventure/AGENTS.md +7 -2
- package/templates/adventure/CLAUDE.md +7 -2
- package/templates/adventure/kit.json +5 -1
- package/templates/adventure/package.json +7 -7
- package/templates/adventure/src/game.ts +1 -1
- package/templates/adventure/src/style.css +4 -0
- package/templates/adventure/tsconfig.json +1 -1
- package/templates/adventure/vite.config.ts +2 -0
- package/templates/collectathon/AGENTS.md +7 -2
- package/templates/collectathon/CLAUDE.md +7 -2
- package/templates/collectathon/package.json +7 -7
- package/templates/collectathon/src/game.ts +1 -1
- package/templates/collectathon/src/level/Course.ts +55 -9
- package/templates/collectathon/src/level/terrain.ts +27 -6
- package/templates/collectathon/src/main.ts +1 -0
- package/templates/collectathon/src/render/foliage.ts +359 -98
- package/templates/collectathon/src/render/sky.ts +76 -12
- package/templates/collectathon/src/render/water.ts +32 -10
- package/templates/collectathon/src/scenes/Play.ts +18 -5
- package/templates/collectathon/src/style.css +4 -0
- package/templates/collectathon/tsconfig.json +1 -1
- package/templates/collectathon/vite.config.ts +2 -0
- package/templates/kart/AGENTS.md +7 -2
- package/templates/kart/CLAUDE.md +7 -2
- package/templates/kart/package.json +6 -6
- package/templates/kart/src/game.ts +1 -1
- package/templates/kart/src/main.ts +1 -0
- package/templates/kart/src/style.css +4 -0
- package/templates/kart/tsconfig.json +1 -1
- package/templates/kart/vite.config.ts +2 -0
- package/templates/minimal/AGENTS.md +8 -3
- package/templates/minimal/CLAUDE.md +8 -3
- package/templates/minimal/package.json +6 -6
- package/templates/minimal/playtests/stands-still.playtest.json +30 -0
- package/templates/minimal/src/game.ts +1 -1
- package/templates/minimal/src/render/atmosphere.ts +6 -0
- package/templates/minimal/src/render/backlightControls.ts +10 -0
- package/templates/minimal/src/render/backlightMaterial.ts +4 -4
- package/templates/minimal/src/render/camera.ts +13 -2
- package/templates/minimal/src/render/clouds.ts +13 -0
- package/templates/minimal/src/render/lighting.ts +4 -2
- package/templates/minimal/src/render/materialLighting.ts +5 -5
- package/templates/minimal/src/render/materials.ts +10 -0
- package/templates/minimal/src/render/quality.ts +7 -32
- package/templates/minimal/src/scenes/Play.ts +4 -1
- package/templates/minimal/vite.config.ts +7 -1
- package/templates/platformer/AGENTS.md +9 -4
- package/templates/platformer/CLAUDE.md +9 -4
- package/templates/platformer/index.html +1 -1
- package/templates/platformer/main.html +12 -0
- package/templates/platformer/package.json +7 -7
- package/templates/platformer/playtests/gamepad-idle.playtest.json +21 -0
- package/templates/platformer/playtests/gamepad.playtest.json +30 -0
- package/templates/platformer/src/entities/Fox.ts +21 -6
- package/templates/platformer/src/game.ts +1 -1
- package/templates/platformer/src/main.ts +1 -0
- package/templates/platformer/src/render/backlightControls.ts +10 -0
- package/templates/platformer/src/render/backlightMaterial.ts +4 -4
- package/templates/platformer/src/render/materialLighting.ts +5 -5
- package/templates/platformer/src/render/quality.ts +7 -32
- package/templates/platformer/src/scenes/Play.ts +2 -1
- package/templates/platformer/src/style.css +4 -0
- package/templates/platformer/src/worker-page.ts +29 -0
- package/templates/platformer/src/worker.ts +5 -0
- package/templates/platformer/tsconfig.json +1 -1
- package/templates/platformer/vite.config.ts +4 -0
- package/templates/puzzle/AGENTS.md +7 -2
- package/templates/puzzle/CLAUDE.md +7 -2
- package/templates/puzzle/package.json +7 -7
- package/templates/puzzle/src/game.ts +1 -1
- package/templates/puzzle/src/render/backlightControls.ts +10 -0
- package/templates/puzzle/src/render/backlightMaterial.ts +4 -4
- package/templates/puzzle/src/render/materialLighting.ts +5 -5
- package/templates/puzzle/src/render/quality.ts +7 -32
- package/templates/puzzle/src/scenes/Play.ts +1 -1
- package/templates/puzzle/src/style.css +4 -0
- package/templates/puzzle/tsconfig.json +1 -1
- package/templates/puzzle/vite.config.ts +2 -0
- package/templates/racing/AGENTS.md +7 -2
- package/templates/racing/CLAUDE.md +7 -2
- package/templates/racing/package.json +7 -7
- package/templates/racing/src/game.ts +1 -1
- package/templates/racing/src/render/atmosphere.ts +6 -0
- package/templates/racing/src/render/backlightControls.ts +10 -0
- package/templates/racing/src/render/backlightMaterial.ts +4 -4
- package/templates/racing/src/render/clouds.ts +13 -0
- package/templates/racing/src/render/materialLighting.ts +5 -5
- package/templates/racing/src/render/quality.ts +7 -32
- package/templates/racing/src/scenes/Race.ts +4 -1
- package/templates/racing/src/style.css +4 -0
- package/templates/racing/tsconfig.json +1 -1
- package/templates/racing/vite.config.ts +2 -0
- package/templates/rain/AGENTS.md +6 -2
- package/templates/rain/CLAUDE.md +6 -2
- package/templates/rain/package.json +6 -6
- package/templates/rain/src/game.ts +1 -1
- package/templates/rain/vite.config.ts +6 -0
- package/templates/rts/AGENTS.md +6 -2
- package/templates/rts/CLAUDE.md +6 -2
- package/templates/rts/package.json +6 -6
- package/templates/rts/src/game.ts +1 -1
- package/templates/rts/src/render/backlightControls.ts +10 -0
- package/templates/rts/src/render/backlightMaterial.ts +4 -4
- package/templates/rts/src/render/materialLighting.ts +5 -5
- package/templates/rts/src/render/quality.ts +7 -31
- package/templates/rts/src/scenes/Play.ts +1 -1
- package/templates/rts/src/style.css +4 -0
- package/templates/rts/vite.config.ts +2 -0
- package/templates/runner/AGENTS.md +7 -2
- package/templates/runner/CLAUDE.md +7 -2
- package/templates/runner/package.json +7 -7
- package/templates/runner/src/game.ts +1 -1
- package/templates/runner/src/render/atmosphere.ts +6 -0
- package/templates/runner/src/render/backlightControls.ts +10 -0
- package/templates/runner/src/render/backlightMaterial.ts +4 -4
- package/templates/runner/src/render/clouds.ts +13 -0
- package/templates/runner/src/render/materialLighting.ts +5 -5
- package/templates/runner/src/render/quality.ts +7 -32
- package/templates/runner/src/scenes/Run.ts +4 -1
- package/templates/runner/src/style.css +4 -0
- package/templates/runner/tsconfig.json +1 -1
- package/templates/runner/vite.config.ts +2 -0
- package/templates/sailing/AGENTS.md +7 -2
- package/templates/sailing/CLAUDE.md +7 -2
- package/templates/sailing/package.json +7 -7
- package/templates/sailing/src/game.ts +1 -1
- package/templates/sailing/src/render/backlightControls.ts +10 -0
- package/templates/sailing/src/render/backlightMaterial.ts +4 -4
- package/templates/sailing/src/render/environmentSetup.ts +1 -1
- package/templates/sailing/src/render/materialLighting.ts +5 -5
- package/templates/sailing/src/render/quality.ts +7 -32
- package/templates/sailing/src/style.css +5 -0
- package/templates/sailing/vite.config.ts +6 -0
- package/templates/shooter/AGENTS.md +6 -2
- package/templates/shooter/CLAUDE.md +6 -2
- package/templates/shooter/package.json +7 -7
- package/templates/shooter/src/game.ts +3 -2
- package/templates/shooter/src/render/atmosphere.ts +6 -0
- package/templates/shooter/src/render/backlightControls.ts +10 -0
- package/templates/shooter/src/render/backlightMaterial.ts +4 -4
- package/templates/shooter/src/render/clouds.ts +13 -0
- package/templates/shooter/src/render/materialLighting.ts +5 -5
- package/templates/shooter/src/render/quality.ts +7 -32
- package/templates/shooter/src/scenes/Play.ts +4 -1
- package/templates/shooter/src/style.css +4 -0
- package/templates/shooter/vite.config.ts +2 -0
- package/templates/snow/AGENTS.md +7 -2
- package/templates/snow/CLAUDE.md +7 -2
- package/templates/snow/package.json +7 -7
- package/templates/snow/src/game.ts +1 -1
- package/templates/snow/src/render/backlightControls.ts +10 -0
- package/templates/snow/src/render/backlightMaterial.ts +4 -4
- package/templates/snow/src/render/materialLighting.ts +5 -5
- package/templates/snow/src/render/quality.ts +7 -32
- package/templates/snow/src/style.css +5 -0
- package/templates/snow/vite.config.ts +6 -0
- package/templates/starter/AGENTS.md +8 -3
- package/templates/starter/CLAUDE.md +8 -3
- package/templates/starter/package.json +7 -7
- package/templates/starter/src/entities/Crate.ts +5 -2
- package/templates/starter/src/game.ts +4 -3
- package/templates/starter/src/render/adaptiveQuality.ts +17 -0
- package/templates/starter/src/render/atmosphere.ts +6 -0
- package/templates/starter/src/render/backlightControls.ts +10 -0
- package/templates/starter/src/render/backlightMaterial.ts +4 -4
- package/templates/starter/src/render/clouds.ts +13 -0
- package/templates/starter/src/render/contactShadow.ts +1 -1
- package/templates/starter/src/render/materialLighting.ts +5 -5
- package/templates/starter/src/render/postprocessing.ts +11 -10
- package/templates/starter/src/render/quality.ts +14 -1
- package/templates/starter/src/scenes/Play.ts +12 -3
- package/templates/starter/src/state.ts +2 -0
- package/templates/starter/src/style.css +4 -0
- package/templates/starter/src/ui/Menu.tsx +5 -1
- package/templates/starter/vite.config.ts +2 -0
- package/templates/tower-defense/AGENTS.md +7 -2
- package/templates/tower-defense/CLAUDE.md +7 -2
- package/templates/tower-defense/package.json +7 -7
- package/templates/tower-defense/src/game.ts +1 -1
- package/templates/tower-defense/src/render/backlightControls.ts +10 -0
- package/templates/tower-defense/src/render/backlightMaterial.ts +4 -4
- package/templates/tower-defense/src/render/materialLighting.ts +5 -5
- package/templates/tower-defense/src/render/quality.ts +7 -32
- package/templates/tower-defense/src/scenes/Battle.ts +1 -1
- package/templates/tower-defense/src/style.css +4 -0
- package/templates/tower-defense/tsconfig.json +1 -1
- package/templates/tower-defense/vite.config.ts +2 -0
- package/templates/action-rpg/src/render/environmentContribution.ts +0 -188
- package/templates/action-rpg/src/render/environmentRadiance.ts +0 -36
- package/templates/action-rpg/src/render/environmentSampleCache.ts +0 -43
- package/templates/action-rpg/src/render/environmentSampling.ts +0 -193
- package/templates/action-rpg/src/render/environmentSnapshot.ts +0 -53
- package/templates/minimal/src/render/environmentContribution.ts +0 -188
- package/templates/minimal/src/render/environmentRadiance.ts +0 -36
- package/templates/minimal/src/render/environmentSampleCache.ts +0 -43
- package/templates/minimal/src/render/environmentSampling.ts +0 -193
- package/templates/minimal/src/render/environmentSnapshot.ts +0 -53
- package/templates/platformer/src/render/environmentContribution.ts +0 -188
- package/templates/platformer/src/render/environmentRadiance.ts +0 -36
- package/templates/platformer/src/render/environmentSampleCache.ts +0 -43
- package/templates/platformer/src/render/environmentSampling.ts +0 -193
- package/templates/platformer/src/render/environmentSnapshot.ts +0 -53
- package/templates/puzzle/src/render/environmentContribution.ts +0 -188
- package/templates/puzzle/src/render/environmentRadiance.ts +0 -36
- package/templates/puzzle/src/render/environmentSampleCache.ts +0 -43
- package/templates/puzzle/src/render/environmentSampling.ts +0 -193
- package/templates/puzzle/src/render/environmentSnapshot.ts +0 -53
- package/templates/racing/src/render/environmentContribution.ts +0 -188
- package/templates/racing/src/render/environmentRadiance.ts +0 -36
- package/templates/racing/src/render/environmentSampleCache.ts +0 -43
- package/templates/racing/src/render/environmentSampling.ts +0 -193
- package/templates/racing/src/render/environmentSnapshot.ts +0 -53
- package/templates/rts/src/render/environmentContribution.ts +0 -188
- package/templates/rts/src/render/environmentRadiance.ts +0 -36
- package/templates/rts/src/render/environmentSampleCache.ts +0 -43
- package/templates/rts/src/render/environmentSampling.ts +0 -193
- package/templates/rts/src/render/environmentSnapshot.ts +0 -53
- package/templates/runner/src/render/environmentContribution.ts +0 -188
- package/templates/runner/src/render/environmentRadiance.ts +0 -36
- package/templates/runner/src/render/environmentSampleCache.ts +0 -43
- package/templates/runner/src/render/environmentSampling.ts +0 -193
- package/templates/runner/src/render/environmentSnapshot.ts +0 -53
- package/templates/sailing/src/render/environmentContribution.ts +0 -188
- package/templates/sailing/src/render/environmentRadiance.ts +0 -36
- package/templates/sailing/src/render/environmentSampleCache.ts +0 -43
- package/templates/sailing/src/render/environmentSampling.ts +0 -193
- package/templates/sailing/src/render/environmentSnapshot.ts +0 -53
- package/templates/shooter/src/render/environmentContribution.ts +0 -188
- package/templates/shooter/src/render/environmentRadiance.ts +0 -36
- package/templates/shooter/src/render/environmentSampleCache.ts +0 -43
- package/templates/shooter/src/render/environmentSampling.ts +0 -193
- package/templates/shooter/src/render/environmentSnapshot.ts +0 -53
- package/templates/snow/src/render/environmentContribution.ts +0 -188
- package/templates/snow/src/render/environmentRadiance.ts +0 -36
- package/templates/snow/src/render/environmentSampleCache.ts +0 -43
- package/templates/snow/src/render/environmentSampling.ts +0 -193
- package/templates/snow/src/render/environmentSnapshot.ts +0 -53
- package/templates/starter/src/render/environmentContribution.ts +0 -188
- package/templates/starter/src/render/environmentRadiance.ts +0 -36
- package/templates/starter/src/render/environmentSampleCache.ts +0 -43
- package/templates/starter/src/render/environmentSampling.ts +0 -193
- package/templates/starter/src/render/environmentSnapshot.ts +0 -53
- package/templates/starter/src/render/rendererGate.ts +0 -36
- package/templates/tower-defense/src/render/environmentContribution.ts +0 -188
- package/templates/tower-defense/src/render/environmentRadiance.ts +0 -36
- package/templates/tower-defense/src/render/environmentSampleCache.ts +0 -43
- package/templates/tower-defense/src/render/environmentSampling.ts +0 -193
- package/templates/tower-defense/src/render/environmentSnapshot.ts +0 -53
|
@@ -11,6 +11,13 @@ Default: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `
|
|
|
11
11
|
|
|
12
12
|
The default look is `tonemapMode: "filmic"` with metered auto exposure. Lights are in lux, as in Unreal (EV100 exposure): the sun is 6 lux, and while the meter is off the fixed `exposure` is 2.4. `tonemapMode: "aces"` and `autoExposureEnabled: false` with a fixed `exposure` are the overrides. Set `tonemapMode: "aces"` to choose ACES, or `autoExposureEnabled: false` with a fixed `exposure` to choose manual exposure, on the same quality preset; the render log reports the override. The filmic curve and metered auto exposure are on by default here. Set `tonemapMode: "aces"` or `autoExposureEnabled: false` with a fixed `exposure` on the same preset to override the curve or the meter.
|
|
13
13
|
|
|
14
|
+
<a id="ao-indirect"></a>
|
|
15
|
+
## Ambient occlusion
|
|
16
|
+
|
|
17
|
+
Default: darkens indirect light only; the sun keeps its light. Override: `gtaoIndirectOnly: false` (whole frame); `gtaoEnabled: false`. Reports: TN_WORLD_ENVIRONMENT.
|
|
18
|
+
|
|
19
|
+
The contact occlusion (`gtaoEnabled`, on at `high` and `medium`) darkens only the light that reaches a surface from around it: sky, ambient, environment and baked irradiance. A sunlit crease keeps its sunlight, as in Unreal 5.8.3. The owned engine writes each draw's indirect diffuse light to its `indirectDiffuse` target, and the stage takes the occlusion off that share. Set `gtaoIndirectOnly: false` on the quality preset to multiply the whole frame instead. `engine: "threejs"` has no such target, so it needs `gtaoRadius` and multiplies the whole frame.
|
|
20
|
+
|
|
14
21
|
<a id="quality"></a>
|
|
15
22
|
## Quality tier
|
|
16
23
|
|
|
@@ -205,6 +212,13 @@ Default: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--w
|
|
|
205
212
|
|
|
206
213
|
Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window.
|
|
207
214
|
|
|
215
|
+
<a id="cpu-priority"></a>
|
|
216
|
+
## CPU priority
|
|
217
|
+
|
|
218
|
+
Default: game threads first. Override: `display.priority: "normal"`. Reports: TN_PROCESS_PRIORITY.
|
|
219
|
+
|
|
220
|
+
A shipped native game asks the OS for more CPU than other programs: its game, render and present threads take a higher priority (desktop nice -10, Android nice -4 plus an ADPF hint session) and its own background work (shader compiles, workers, HUD processes) yields. It needs no admin rights; a refused raise is reported, not fatal. `TN_PROCESS_PRIORITY` states what the OS applied. Set `display.priority: "normal"` only when the user asks for the OS default; the web build ignores it.
|
|
221
|
+
|
|
208
222
|
<a id="terrain"></a>
|
|
209
223
|
## Terrain
|
|
210
224
|
|
|
@@ -219,6 +233,13 @@ Default: none; browser-only WASM. Override: import `@threenative/physics/navigat
|
|
|
219
233
|
|
|
220
234
|
This kit needs no navmesh and imports none, so it runs on every target; adding `@threenative/physics/navigation` would make it web and desktop only.
|
|
221
235
|
|
|
236
|
+
<a id="gamepad"></a>
|
|
237
|
+
## Controller
|
|
238
|
+
|
|
239
|
+
Default: W3C standard mapping on every pad, radial dead zone `0.2`, and a button press or a decisive stick move claims which pad is read. Override: `gamepadDeadZone: 0` for raw axes. Reports: TN_GAMEPAD.
|
|
240
|
+
|
|
241
|
+
A game binds standard indices and nothing else: `buttons: [0]` is the south face button on an Xbox pad, an 8BitDo and a Steam Deck, `buttons: [6, 7]` are the triggers, and `ctx.input.vector("move")` reads the left stick. A pad the browser reports without a mapping is normalized from a vendor:product row in `@threenative/core`; a pad nothing knows is ignored and reported once as `TN_GAMEPAD … unmapped`, never read with raw indices, because raw index 0 fires whatever action that device happened to number 0. One pad at a time is read, and it is the one the player last claimed: a button press, or a stick travelling past half tilt. A stick resting past the dead zone claims nothing, and one jittering across it claims nothing either, so a worn pad left on the couch, an idle wheel or a paired-but-idle dongle cannot take the input — at boot or in the middle of a move. The claimed pad keeps the slot while idle, which is what lets its releases be read; a pad that disappears or turns unmapped hands over. At `gamepadDeadZone: 0` a noisy stick does produce claims, which is what raw axes mean. Both sticks carry the radial dead zone: a stick resting at `0.08` reads zero, and one past the zone is rescaled so full tilt is still `1`.
|
|
242
|
+
|
|
222
243
|
<a id="move-axis"></a>
|
|
223
244
|
## Move input
|
|
224
245
|
|
|
@@ -247,6 +268,13 @@ Default: owned C++ engine. Override: `engine: "threejs"` only when the user asks
|
|
|
247
268
|
|
|
248
269
|
Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. `engine: "threejs"` switches to upstream Three.js only when the user asks for it; it is never a fix for a build error.
|
|
249
270
|
|
|
271
|
+
<a id="engine-catalog"></a>
|
|
272
|
+
## Refused imports
|
|
273
|
+
|
|
274
|
+
Default: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Reports: TN_ENGINE_CATALOG.
|
|
275
|
+
|
|
276
|
+
Refused imports: `createEngineCatalogPlugin()` in `vite.config.ts` reads every `import { … } from "three"`, `"three/webgpu"` and `"three/tsl"` in game source. When the installed Wasm engine refuses a name, the dev overlay and `threenative build` fail at that import line with the code the page would throw at first use (`TN_NATIVE_UNCATALOGUED_<NAME>`, or the catalog entry's own diagnostic). Pick a bound class instead: `engine_search_capabilities` names it. `mode: "warn"` reports instead of failing and prints `TN_ENGINE_CATALOG: warn`. Under `engine: "threejs"` the check is off and prints `TN_ENGINE_CATALOG: off (engine threejs)`. Member and argument gaps of a `partial` entry stay runtime diagnostics.
|
|
277
|
+
|
|
250
278
|
<a id="general"></a>
|
|
251
279
|
## Other portable contracts
|
|
252
280
|
|
|
@@ -33,10 +33,14 @@ revisit later is the engine's job, not yours.
|
|
|
33
33
|
- **Web threads.** The dev and preview servers send `Cross-Origin-Opener-Policy: same-origin` and
|
|
34
34
|
`Cross-Origin-Embedder-Policy: require-corp`, and the build writes both into `dist/_headers`, so the
|
|
35
35
|
page is cross-origin isolated and loads the threaded engine: the world-matrix walk splits over up
|
|
36
|
-
to 8 workers. `TN_FRAME_BUDGET` reports `threads: "on (N)"`.
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
36
|
+
to 8 workers. `TN_FRAME_BUDGET` reports `threads: "on (N)"`. A host that sends no headers (GitHub
|
|
37
|
+
Pages, a plain static server) gets them from the build's `tn-isolation-sw.js` service worker,
|
|
38
|
+
which reloads the page once; it needs https or localhost. The dev server, playtests and
|
|
39
|
+
conformance fail closed with `TN_WEB_THREADS_OFF` when the page is not isolated or the pool starts
|
|
40
|
+
no worker. A shipped build still loads there: it falls back to the single-thread engine, warns
|
|
41
|
+
`TN_WEB_THREADS_OFF` with the fix, and reports `threads: "off (<reason>)"`. Plain http on a LAN
|
|
42
|
+
address and an itch.io frame without its "SharedArrayBuffer support" option are such pages.
|
|
43
|
+
`TN_WASM_THREADS_MISSING` names a missing threaded build. A cross-origin asset without a `Cross-Origin-Resource-Policy` header needs
|
|
40
44
|
`credentialless` in place of `require-corp`. `?tnIsolation=0` serves a page without the headers.
|
|
41
45
|
- **Per-pass culling.** The main camera, each shadow and each reflection pass cull their own way,
|
|
42
46
|
and the engine owns that. Do not set `frustumCulled = false` on a batch, and do not give one
|
|
@@ -26,7 +26,7 @@ problem, not instead of it: read the code the change touches and trace the real
|
|
|
26
26
|
flow end to end, then climb. Two rungs work → take the higher one and move on.
|
|
27
27
|
|
|
28
28
|
1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
|
|
29
|
-
2. **Already installed in the engine?** For a new game, search `engine_search_capabilities` for the full request and each concrete mechanic and
|
|
29
|
+
2. **Already installed in the engine?** For a new game, search `engine_search_capabilities` for the full request and each concrete mechanic and read every row (a row answers; `engine_capability_detail` is only for a symbol the search did not return); for a change to an existing game, search for that change (and references for each gameplay mechanic) as the existing-game route in `threenative-capabilities` says, without restarting whole-game discovery or planning. Reuse the returned system — a node, convention, helper or subpath that already ships is the answer, not a thing to re-implement. This rung *is* the critical capability gate; keep a change's recorded result rather than treating each edit as a new game. Keep installed systems instead of hand-writing replacements.
|
|
30
30
|
3. **Already in this game?** Reuse a helper, type, or pattern that already lives in `src/`. Re-implementing what sits a few files over is the most common slop.
|
|
31
31
|
4. **Stdlib or engine convention does it?** `loadAll`, `addInSlices`, `GroundSnap`, an input vector, a physics query — reach for those before writing your own loop.
|
|
32
32
|
5. **Already-installed dependency solves it?** Use it; never add a new one for what a few lines can do.
|
|
@@ -50,8 +50,10 @@ prompt (`TN_DISCOVERY_GATE=off` opts out).
|
|
|
50
50
|
mechanic from pinned `file:line`, never from a video. No network or no tools: record
|
|
51
51
|
`none: gameplay frames unavailable`.
|
|
52
52
|
3. **Built-ins** — engine_capabilities built-in discovery, served by the same MCP: call
|
|
53
|
-
`engine_search_capabilities` with `scope: "mechanic"` per mechanic, system or symptom
|
|
54
|
-
|
|
53
|
+
`engine_search_capabilities` with `scope: "mechanic"` per mechanic, system or symptom, and read
|
|
54
|
+
every row — it carries the import path, signature, example, constraints, overrides and
|
|
55
|
+
deprecations, so call `engine_capability_detail` only for a symbol the search did not return.
|
|
56
|
+
Record installed capabilities and binding constraints. A
|
|
55
57
|
`verdict: "none"` means game-owned behavior in `src/`; do not rephrase until something matches.
|
|
56
58
|
These role names add no servers.
|
|
57
59
|
4. **Plan** — hand **Kit**, **Mechanics** and **References** to `prd-creator`. Plan the core loop
|
|
@@ -92,8 +94,9 @@ prompt (`TN_DISCOVERY_GATE=off` opts out).
|
|
|
92
94
|
A change to an existing game skips step 1 and whole-game planning; do not invoke `prd-creator` just
|
|
93
95
|
to restart the game plan. For each change, search before you write:
|
|
94
96
|
|
|
95
|
-
- Step 3 for every change: `engine_search_capabilities` with `scope: "mechanic"`, then
|
|
96
|
-
`engine_capability_detail`
|
|
97
|
+
- Step 3 for every change: `engine_search_capabilities` with `scope: "mechanic"`, then read every
|
|
98
|
+
row — `engine_capability_detail` only for a symbol the search did not return — so installed
|
|
99
|
+
systems are reused.
|
|
97
100
|
- Step 2 for each gameplay mechanic the change adds or alters: `engine_search_references`, then
|
|
98
101
|
`engine_reference_detail`; use `engine_watch_reference` when the motion is the question.
|
|
99
102
|
- Steps 5-8 for the change, using the existing game, plan and context: apply step 5 to the
|
|
@@ -114,12 +114,12 @@ try {
|
|
|
114
114
|
log = readFileSync(logFile, "utf8");
|
|
115
115
|
} catch (error) {
|
|
116
116
|
deny(
|
|
117
|
-
`Discovery gate: cannot read ${path.relative(root, logFile)} (${error.code ?? error.message}), so the engine was not searched in this project. Before you create ${created.join(", ")}, run ${SEARCH} and engine_capability_detail
|
|
117
|
+
`Discovery gate: cannot read ${path.relative(root, logFile)} (${error.code ?? error.message}), so the engine was not searched in this project. Before you create ${created.join(", ")}, run ${SEARCH} and read every row; engine_capability_detail is only for a symbol the search did not return. Outside this folder: ${BRIDGE}. Opt out with TN_DISCOVERY_GATE=off.`,
|
|
118
118
|
);
|
|
119
119
|
process.exit(0);
|
|
120
120
|
}
|
|
121
121
|
const since = Date.parse(state.prompt ?? "") || 0;
|
|
122
122
|
if (!searchedSince(log, since))
|
|
123
123
|
deny(
|
|
124
|
-
`Discovery gate: no engine_search_capabilities call since the last user prompt. Before you create ${created.join(", ")}, run ${SEARCH}
|
|
124
|
+
`Discovery gate: no engine_search_capabilities call since the last user prompt. Before you create ${created.join(", ")}, run ${SEARCH} and read every row — engine_capability_detail is only for a symbol the search did not return — and use what it returns. Outside this folder: ${BRIDGE}. Opt out with TN_DISCOVERY_GATE=off.`,
|
|
125
125
|
);
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,41 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import { IThreeNativeIconVariants, ThreeNativeOrientation, IThreeNativeBootSplash, IThreeNativeConfig, ThreeNativeUiRenderer, IThreeNativeAudioConfig, IThreeNativeLodConfig, IThreeNativeTexturesConfig } from '@threenative/core';
|
|
3
3
|
|
|
4
|
+
interface IEngineCatalogOptions {
|
|
5
|
+
/** "error" (the default) fails the edit and the build; "warn" reports, and the page throws at first use. */
|
|
6
|
+
readonly mode?: "error" | "warn";
|
|
7
|
+
}
|
|
8
|
+
interface ITransformContext {
|
|
9
|
+
error(failure: {
|
|
10
|
+
readonly message: string;
|
|
11
|
+
readonly id: string;
|
|
12
|
+
readonly loc?: {
|
|
13
|
+
readonly file: string;
|
|
14
|
+
readonly line: number;
|
|
15
|
+
readonly column: number;
|
|
16
|
+
};
|
|
17
|
+
}): never;
|
|
18
|
+
warn(message: string): void;
|
|
19
|
+
}
|
|
20
|
+
interface IEngineCatalogVitePlugin {
|
|
21
|
+
readonly name: string;
|
|
22
|
+
readonly enforce: "pre";
|
|
23
|
+
config(): {
|
|
24
|
+
worker: {
|
|
25
|
+
plugins: () => object[];
|
|
26
|
+
};
|
|
27
|
+
};
|
|
28
|
+
configResolved(config: {
|
|
29
|
+
readonly root: string;
|
|
30
|
+
}): Promise<void>;
|
|
31
|
+
transform(this: ITransformContext, code: string, id: string): Promise<null>;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Fails a game file's `import { X } from "three"` when the Wasm engine refuses `X` (PRD-830). Off,
|
|
35
|
+
* and reported once, under `engine: "threejs"` and for the native host's bundle.
|
|
36
|
+
*/
|
|
37
|
+
declare function createEngineCatalogPlugin(options?: IEngineCatalogOptions): IEngineCatalogVitePlugin;
|
|
38
|
+
|
|
4
39
|
interface IEngineFreshnessVitePlugin {
|
|
5
40
|
readonly name: string;
|
|
6
41
|
config(config: {
|
|
@@ -51,6 +86,7 @@ interface IResolvedThreeNativeConfig {
|
|
|
51
86
|
readonly orientation: ThreeNativeOrientation;
|
|
52
87
|
readonly fullscreen: boolean;
|
|
53
88
|
readonly keepScreenOn: boolean;
|
|
89
|
+
readonly priority: "game" | "normal";
|
|
54
90
|
readonly maxFps: number;
|
|
55
91
|
};
|
|
56
92
|
readonly window: {
|
|
@@ -214,8 +250,11 @@ interface IWebBrandVitePlugin {
|
|
|
214
250
|
load(id: string): Promise<string | null>;
|
|
215
251
|
configResolved(config: {
|
|
216
252
|
readonly root: string;
|
|
253
|
+
readonly command?: "build" | "serve";
|
|
217
254
|
}): Promise<void>;
|
|
218
|
-
transformIndexHtml(html: string
|
|
255
|
+
transformIndexHtml(html: string, context?: {
|
|
256
|
+
readonly bundle?: Readonly<Record<string, IBundleFile>>;
|
|
257
|
+
}): string;
|
|
219
258
|
configureServer(server: IMiddlewareServer): void;
|
|
220
259
|
configurePreviewServer(server: IMiddlewareServer): void;
|
|
221
260
|
generateBundle(this: {
|
|
@@ -237,15 +276,30 @@ interface IMiddlewareServer {
|
|
|
237
276
|
use(handler: Middleware): void;
|
|
238
277
|
};
|
|
239
278
|
}
|
|
279
|
+
interface IBundleFile {
|
|
280
|
+
readonly fileName: string;
|
|
281
|
+
readonly type: string;
|
|
282
|
+
readonly moduleIds?: readonly string[];
|
|
283
|
+
}
|
|
240
284
|
declare function renderWebManifest(root: string, config: IResolvedThreeNativeConfig): string;
|
|
241
285
|
declare function createWebBrandPlugin(): IWebBrandVitePlugin;
|
|
242
286
|
|
|
243
287
|
/**
|
|
244
|
-
* The asset decoders the web
|
|
245
|
-
*
|
|
246
|
-
*
|
|
288
|
+
* The asset decoders the web build ships, per format.
|
|
289
|
+
*
|
|
290
|
+
* Meshopt geometry decodes on both engines: on `engine: "threenative"` the engine's own glTF loader
|
|
291
|
+
* decompresses EXT/KHR_meshopt_compression with meshoptimizer, which `pnpm wasm:build` provisions
|
|
292
|
+
* and without which the `tn-native-engine-web` target refuses to link (PRD-861).
|
|
293
|
+
*
|
|
294
|
+
* KTX2 decodes on both engines too: the owned engine transcodes KHR_texture_basisu to BC7 or ETC2
|
|
295
|
+
* and uploads the blocks, or RGBA8 on a device with neither (PRD-867), and three's KTX2Loader runs
|
|
296
|
+
* on it. The web cook keeps an authored WebP a KTX2 cannot undercut, so Midway's KTX2 cook is
|
|
297
|
+
* 98,236,952 B against 125,132,608 B with WebP model textures.
|
|
298
|
+
*
|
|
299
|
+
* `threenative build` and each template's dev-server asset watch both read it, so the two cook the
|
|
300
|
+
* same bytes.
|
|
247
301
|
*/
|
|
248
|
-
declare function webRuntimeDecoders(
|
|
302
|
+
declare function webRuntimeDecoders(_config: {
|
|
249
303
|
readonly engine?: "threejs" | "threenative";
|
|
250
304
|
}): {
|
|
251
305
|
readonly ktx2: boolean;
|
|
@@ -307,8 +361,19 @@ declare function stampLoadingSource(canonical: string, template: string): string
|
|
|
307
361
|
* render-chain plumbing is not: it is the same 600 lines in every kit, and keeping seven copies by
|
|
308
362
|
* hand let one fall a revision behind without anything failing. A file belongs here only when a
|
|
309
363
|
* kit editing it would be a mistake rather than a choice.
|
|
364
|
+
*
|
|
365
|
+
* `__tests__/shared-render-drift.spec.ts` fails on any render source that ships byte-identical in
|
|
366
|
+
* two or more kits and is missing here, so a new copy cannot land unrestamped. The environment
|
|
367
|
+
* measure-and-sample mechanism and the backlight used to be seven of these copies; they live in
|
|
368
|
+
* `@threenative/core/render/environment` now (PRD-833).
|
|
310
369
|
*/
|
|
311
370
|
declare const SHARED_RENDER_SOURCES: readonly string[];
|
|
371
|
+
/**
|
|
372
|
+
* The shared sources `createProject` also writes into a kit that does not ship them. A kit owns its
|
|
373
|
+
* look, so presence is per kit: `starter` ships the temporal detail stage and the collectathon kits
|
|
374
|
+
* do not, and all four still get the same plumbing.
|
|
375
|
+
*/
|
|
376
|
+
declare const ADDED_RENDER_SOURCES: readonly string[];
|
|
312
377
|
declare function canonicalRenderSourcePath(relativePath: string, root?: string): string;
|
|
313
378
|
/** Re-copies every shared render source into each kit that ships it. */
|
|
314
379
|
declare function restampSharedRenderCopies(root?: string): Promise<readonly string[]>;
|
|
@@ -339,10 +404,36 @@ declare function projectMcpServers(target: string): string[];
|
|
|
339
404
|
*/
|
|
340
405
|
declare function referenceDigest(target: string, genre: string, run?: (args: string[]) => string): string;
|
|
341
406
|
declare function cliHelp(): string;
|
|
407
|
+
interface IAuthoringLayerStatus {
|
|
408
|
+
/** The create-threenative version running this check, which is the one the game installed. */
|
|
409
|
+
readonly installed: string;
|
|
410
|
+
readonly kit?: string;
|
|
411
|
+
/** Why the layer cannot be checked; set instead of `stale`'s meaning. */
|
|
412
|
+
readonly problem?: string;
|
|
413
|
+
/** Layer paths whose bytes differ from the installed package, and dropped files still present. */
|
|
414
|
+
readonly stale: readonly string[];
|
|
415
|
+
readonly stamped?: string;
|
|
416
|
+
}
|
|
417
|
+
interface IAuthoringLayerFix {
|
|
418
|
+
readonly deleted: readonly string[];
|
|
419
|
+
readonly kept: readonly string[];
|
|
420
|
+
readonly written: readonly string[];
|
|
421
|
+
}
|
|
422
|
+
/** How far the game's authoring layer is from what the installed create-threenative renders. */
|
|
423
|
+
declare function authoringLayerStatus(game: string, root?: string): Promise<IAuthoringLayerStatus>;
|
|
424
|
+
/**
|
|
425
|
+
* `threenative doctor --fix` (PRD-829): re-renders the authoring layer from the installed package with
|
|
426
|
+
* the scaffold's writers. A file whose bytes still match the stamp is overwritten, an edited one is
|
|
427
|
+
* kept unless `force`, and a file the package dropped is deleted only when unedited. Without a stamp,
|
|
428
|
+
* every differing file counts as edited.
|
|
429
|
+
*/
|
|
430
|
+
declare function fixAuthoringLayer(game: string, options: {
|
|
431
|
+
readonly force: boolean;
|
|
432
|
+
}, root?: string): Promise<IAuthoringLayerFix>;
|
|
342
433
|
declare function createProject(options: IScaffoldOptions, cwd?: string, root?: string): Promise<IScaffoldResult>;
|
|
343
434
|
/** The inverse of `scripts/workspace-packages.ts`'s `workspacePackageSourceFlag`; exported so
|
|
344
435
|
* the pair is gated rather than trusted. */
|
|
345
436
|
declare function packageNameFromFlag(flag: string): string | undefined;
|
|
346
437
|
declare function parseArgs(argv: readonly string[]): IScaffoldOptions;
|
|
347
438
|
|
|
348
|
-
export { type IKitManifest, type IScaffoldOptions, type IScaffoldResult, SHARED_RENDER_SOURCES, type ScaffoldTemplate, canonicalLoadingPath, canonicalRenderSourcePath, cliHelp, createEngineFreshnessPlugin, createProject, createWebBrandPlugin, discoverKitManifests, discoverStampedTemplates, discoverTemplateNames, hashEngineDist, kitManifest, packageNameFromFlag, parseArgs, projectMcpServers, referenceDigest, renderWebManifest, restampSharedRenderCopies, restampTemplateLoadingCopies, scaffoldCompletionMessage, scaffoldNextSteps, stampLoadingSource, templateForGenre, templateRoot, webRuntimeDecoders };
|
|
439
|
+
export { ADDED_RENDER_SOURCES, type IAuthoringLayerFix, type IAuthoringLayerStatus, type IKitManifest, type IScaffoldOptions, type IScaffoldResult, SHARED_RENDER_SOURCES, type ScaffoldTemplate, authoringLayerStatus, canonicalLoadingPath, canonicalRenderSourcePath, cliHelp, createEngineCatalogPlugin, createEngineFreshnessPlugin, createProject, createWebBrandPlugin, discoverKitManifests, discoverStampedTemplates, discoverTemplateNames, fixAuthoringLayer, hashEngineDist, kitManifest, packageNameFromFlag, parseArgs, projectMcpServers, referenceDigest, renderWebManifest, restampSharedRenderCopies, restampTemplateLoadingCopies, scaffoldCompletionMessage, scaffoldNextSteps, stampLoadingSource, templateForGenre, templateRoot, webRuntimeDecoders };
|