create-threenative 0.2.14 → 0.2.17
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 +10 -0
- package/agent-docs/kit-router.md +14 -0
- package/agent-docs/kit-stuck.md +7 -0
- package/agent-docs/references/capability-reference.md +958 -30
- package/agent-docs/references/conventions.md +271 -0
- package/agent-docs/references/kit-action-rpg.md +40 -0
- package/agent-docs/references/kit-adventure.md +40 -0
- package/agent-docs/references/kit-collectathon.md +38 -0
- package/agent-docs/references/kit-kart.md +31 -0
- package/agent-docs/references/kit-minimal.md +29 -0
- package/agent-docs/references/kit-platformer.md +34 -0
- package/agent-docs/references/kit-puzzle.md +22 -0
- package/agent-docs/references/kit-racing.md +26 -0
- package/agent-docs/references/kit-rain.md +31 -0
- package/agent-docs/references/kit-rts.md +34 -0
- package/agent-docs/references/kit-runner.md +32 -0
- package/agent-docs/references/kit-sailing.md +41 -0
- package/agent-docs/references/kit-shooter.md +33 -0
- package/agent-docs/references/kit-snow.md +33 -0
- package/agent-docs/references/kit-starter.md +55 -0
- package/agent-docs/references/kit-tower-defense.md +27 -0
- package/agent-docs/references/terrain-authoring.md +2 -1
- package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
- package/agent-files/.agents/skills/prd-creator/SKILL.md +3 -2
- package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +81 -59
- package/agent-files/.claude/hooks/discovery-gate.mjs +125 -0
- package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
- package/agent-files/.claude/settings.json +25 -0
- package/agent-files/.codex/hooks.json +18 -1
- package/dist/index.js +256 -120
- package/dist/terrain-kit.d.ts +7 -0
- package/dist/terrain-kit.js +82 -0
- package/dist/threenative.js +23 -4
- package/dist/web-engine-gltf-loader.js +20 -7
- package/dist/web-engine-post-effects.js +34 -4
- package/dist/web-engine-runtime.js +6119 -3311
- package/package.json +13 -8
- package/template-assets/patches/three@0.187.0.patch +2004 -407
- package/templates/action-rpg/AGENTS.md +99 -84
- package/templates/action-rpg/CLAUDE.md +99 -84
- package/templates/action-rpg/kit.json +1 -0
- package/templates/action-rpg/package.json +7 -7
- package/templates/action-rpg/playtests/spells.playtest.json +20 -0
- package/templates/action-rpg/src/game.ts +1 -0
- package/templates/action-rpg/src/render/atmosphere.ts +5 -16
- package/templates/action-rpg/src/render/gpuSky.ts +4 -7
- package/templates/action-rpg/src/render/quality.ts +3 -1
- package/templates/action-rpg/src/scenes/Play.ts +26 -0
- package/templates/action-rpg/src/ui/AbilityBar.tsx +1 -1
- package/templates/action-rpg/threenative.config.ts +0 -3
- package/templates/adventure/AGENTS.md +87 -44
- package/templates/adventure/CLAUDE.md +87 -44
- package/templates/adventure/package.json +7 -7
- package/templates/collectathon/AGENTS.md +88 -42
- package/templates/collectathon/CLAUDE.md +88 -42
- package/templates/collectathon/package.json +7 -7
- package/templates/kart/AGENTS.md +82 -42
- package/templates/kart/CLAUDE.md +82 -42
- package/templates/kart/package.json +6 -6
- package/templates/minimal/AGENTS.md +100 -84
- package/templates/minimal/CLAUDE.md +100 -84
- package/templates/minimal/package.json +6 -6
- package/templates/minimal/src/render/atmosphere.ts +5 -16
- package/templates/minimal/src/render/gpuSky.ts +4 -7
- package/templates/platformer/AGENTS.md +90 -46
- package/templates/platformer/CLAUDE.md +90 -46
- package/templates/platformer/package.json +7 -7
- package/templates/puzzle/AGENTS.md +92 -80
- package/templates/puzzle/CLAUDE.md +92 -80
- package/templates/puzzle/package.json +7 -7
- package/templates/racing/AGENTS.md +95 -82
- package/templates/racing/CLAUDE.md +95 -82
- package/templates/racing/package.json +7 -7
- package/templates/racing/src/render/atmosphere.ts +5 -16
- package/templates/racing/src/render/gpuSky.ts +4 -7
- package/templates/rain/AGENTS.md +92 -84
- package/templates/rain/CLAUDE.md +92 -84
- package/templates/rain/native-playtests/lightning.playtest.json +85 -10
- package/templates/rain/package.json +6 -6
- package/templates/rain/playtests/reduced-motion.playtest.json +6 -0
- package/templates/rain/src/scenes/Boot.ts +1 -0
- package/templates/rain/src/state.ts +7 -0
- package/templates/rain/src/ui/GameUi.tsx +7 -1
- package/templates/rts/AGENTS.md +96 -85
- package/templates/rts/CLAUDE.md +96 -85
- package/templates/rts/package.json +6 -6
- package/templates/runner/AGENTS.md +92 -80
- package/templates/runner/CLAUDE.md +92 -80
- package/templates/runner/package.json +7 -7
- package/templates/runner/playtests/performance.playtest.json +1 -1
- package/templates/runner/src/render/atmosphere.ts +5 -16
- package/templates/runner/src/render/gpuSky.ts +4 -7
- package/templates/runner/src/render/lighting.ts +53 -11
- package/templates/runner/src/scenes/Run.ts +4 -3
- package/templates/runner/threenative.config.ts +0 -3
- package/templates/sailing/AGENTS.md +91 -79
- package/templates/sailing/CLAUDE.md +91 -79
- package/templates/sailing/package.json +7 -7
- package/templates/sailing/playtests/sails.playtest.json +1 -0
- package/templates/sailing/src/render/sky.ts +4 -0
- package/templates/sailing/threenative.config.ts +0 -3
- package/templates/shooter/AGENTS.md +93 -68
- package/templates/shooter/CLAUDE.md +93 -68
- package/templates/shooter/package.json +7 -7
- package/templates/shooter/src/render/atmosphere.ts +5 -16
- package/templates/shooter/src/render/gpuSky.ts +4 -7
- package/templates/shooter/src/render/quality.ts +3 -1
- package/templates/snow/AGENTS.md +90 -76
- package/templates/snow/CLAUDE.md +90 -76
- package/templates/snow/package.json +7 -7
- package/templates/snow/threenative.config.ts +0 -3
- package/templates/starter/AGENTS.md +104 -88
- package/templates/starter/CLAUDE.md +104 -88
- package/templates/starter/native-playtests/render-chain.playtest.json +24 -24
- package/templates/starter/native-playtests/smooth-motion.playtest.json +3 -3
- package/templates/starter/package.json +7 -7
- package/templates/starter/src/entities/Player.ts +10 -22
- package/templates/starter/src/render/atmosphere.ts +5 -16
- package/templates/starter/src/render/gpuSky.ts +4 -7
- package/templates/starter/src/render/lighting.ts +54 -4
- package/templates/starter/src/render/temporalAA.ts +8 -7
- package/templates/starter/src/render/temporalAAFrame.ts +30 -9
- package/templates/starter/src/render/temporalAAResolve.ts +15 -1
- package/templates/starter/src/render/temporalClampRelease.ts +183 -0
- package/templates/starter/src/render/temporalHistoryResolve.ts +90 -0
- package/templates/starter/src/render/temporalMoire.ts +190 -0
- package/templates/starter/src/render/temporalResolve.ts +75 -16
- package/templates/starter/src/render/temporalResolveDepth.ts +2 -0
- package/templates/starter/src/scenes/Play.ts +41 -29
- package/templates/tower-defense/AGENTS.md +92 -81
- package/templates/tower-defense/CLAUDE.md +92 -81
- package/templates/tower-defense/package.json +7 -7
- package/capabilities.json +0 -9197
- package/templates/AGENTS.md +0 -21
- package/templates/CLAUDE.md +0 -23
- package/templates/action-rpg/.codex/config.toml +0 -23
- package/templates/action-rpg/.cursor/mcp.json +0 -38
- package/templates/action-rpg/.gemini/settings.json +0 -38
- package/templates/action-rpg/.mcp.json +0 -38
- package/templates/action-rpg/.vscode/mcp.json +0 -43
- package/templates/action-rpg/.zed/settings.json +0 -43
- package/templates/action-rpg/opencode.json +0 -49
- package/templates/adventure/.codex/config.toml +0 -23
- package/templates/adventure/.cursor/mcp.json +0 -38
- package/templates/adventure/.gemini/settings.json +0 -38
- package/templates/adventure/.mcp.json +0 -38
- package/templates/adventure/.vscode/mcp.json +0 -43
- package/templates/adventure/.zed/settings.json +0 -43
- package/templates/adventure/opencode.json +0 -49
- package/templates/collectathon/.codex/config.toml +0 -23
- package/templates/collectathon/.cursor/mcp.json +0 -38
- package/templates/collectathon/.gemini/settings.json +0 -38
- package/templates/collectathon/.mcp.json +0 -38
- package/templates/collectathon/.vscode/mcp.json +0 -43
- package/templates/collectathon/.zed/settings.json +0 -43
- package/templates/collectathon/opencode.json +0 -49
- package/templates/kart/.codex/config.toml +0 -23
- package/templates/kart/.cursor/mcp.json +0 -38
- package/templates/kart/.gemini/settings.json +0 -38
- package/templates/kart/.mcp.json +0 -38
- package/templates/kart/.vscode/mcp.json +0 -43
- package/templates/kart/.zed/settings.json +0 -43
- package/templates/kart/opencode.json +0 -49
- package/templates/minimal/.codex/config.toml +0 -23
- package/templates/minimal/.cursor/mcp.json +0 -38
- package/templates/minimal/.gemini/settings.json +0 -38
- package/templates/minimal/.mcp.json +0 -38
- package/templates/minimal/.vscode/mcp.json +0 -43
- package/templates/minimal/.zed/settings.json +0 -43
- package/templates/minimal/opencode.json +0 -49
- package/templates/platformer/.codex/config.toml +0 -23
- package/templates/platformer/.cursor/mcp.json +0 -38
- package/templates/platformer/.gemini/settings.json +0 -38
- package/templates/platformer/.mcp.json +0 -38
- package/templates/platformer/.vscode/mcp.json +0 -43
- package/templates/platformer/.zed/settings.json +0 -43
- package/templates/platformer/opencode.json +0 -49
- package/templates/puzzle/.codex/config.toml +0 -23
- package/templates/puzzle/.cursor/mcp.json +0 -38
- package/templates/puzzle/.gemini/settings.json +0 -38
- package/templates/puzzle/.mcp.json +0 -38
- package/templates/puzzle/.vscode/mcp.json +0 -43
- package/templates/puzzle/.zed/settings.json +0 -43
- package/templates/puzzle/opencode.json +0 -49
- package/templates/racing/.codex/config.toml +0 -23
- package/templates/racing/.cursor/mcp.json +0 -38
- package/templates/racing/.gemini/settings.json +0 -38
- package/templates/racing/.mcp.json +0 -38
- package/templates/racing/.vscode/mcp.json +0 -43
- package/templates/racing/.zed/settings.json +0 -43
- package/templates/racing/opencode.json +0 -49
- package/templates/rain/.codex/config.toml +0 -23
- package/templates/rain/.cursor/mcp.json +0 -38
- package/templates/rain/.gemini/settings.json +0 -38
- package/templates/rain/.mcp.json +0 -38
- package/templates/rain/.vscode/mcp.json +0 -43
- package/templates/rain/.zed/settings.json +0 -43
- package/templates/rain/opencode.json +0 -49
- package/templates/rts/.codex/config.toml +0 -23
- package/templates/rts/.cursor/mcp.json +0 -38
- package/templates/rts/.gemini/settings.json +0 -38
- package/templates/rts/.mcp.json +0 -38
- package/templates/rts/.vscode/mcp.json +0 -43
- package/templates/rts/.zed/settings.json +0 -43
- package/templates/rts/opencode.json +0 -49
- package/templates/runner/.codex/config.toml +0 -23
- package/templates/runner/.cursor/mcp.json +0 -38
- package/templates/runner/.gemini/settings.json +0 -38
- package/templates/runner/.mcp.json +0 -38
- package/templates/runner/.vscode/mcp.json +0 -43
- package/templates/runner/.zed/settings.json +0 -43
- package/templates/runner/README.md +0 -43
- package/templates/runner/opencode.json +0 -49
- package/templates/sailing/.codex/config.toml +0 -23
- package/templates/sailing/.cursor/mcp.json +0 -38
- package/templates/sailing/.gemini/settings.json +0 -38
- package/templates/sailing/.mcp.json +0 -38
- package/templates/sailing/.vscode/mcp.json +0 -43
- package/templates/sailing/.zed/settings.json +0 -43
- package/templates/sailing/README.md +0 -28
- package/templates/sailing/opencode.json +0 -49
- package/templates/shooter/.codex/config.toml +0 -23
- package/templates/shooter/.cursor/mcp.json +0 -38
- package/templates/shooter/.gemini/settings.json +0 -38
- package/templates/shooter/.mcp.json +0 -38
- package/templates/shooter/.vscode/mcp.json +0 -43
- package/templates/shooter/.zed/settings.json +0 -43
- package/templates/shooter/opencode.json +0 -49
- package/templates/snow/.codex/config.toml +0 -23
- package/templates/snow/.cursor/mcp.json +0 -38
- package/templates/snow/.gemini/settings.json +0 -38
- package/templates/snow/.mcp.json +0 -38
- package/templates/snow/.vscode/mcp.json +0 -43
- package/templates/snow/.zed/settings.json +0 -43
- package/templates/snow/README.md +0 -26
- package/templates/snow/opencode.json +0 -49
- package/templates/starter/.codex/config.toml +0 -23
- package/templates/starter/.cursor/mcp.json +0 -38
- package/templates/starter/.gemini/settings.json +0 -38
- package/templates/starter/.mcp.json +0 -38
- package/templates/starter/.vscode/mcp.json +0 -43
- package/templates/starter/.zed/settings.json +0 -43
- package/templates/starter/opencode.json +0 -49
- package/templates/tower-defense/.codex/config.toml +0 -23
- package/templates/tower-defense/.cursor/mcp.json +0 -38
- package/templates/tower-defense/.gemini/settings.json +0 -38
- package/templates/tower-defense/.mcp.json +0 -38
- package/templates/tower-defense/.vscode/mcp.json +0 -43
- package/templates/tower-defense/.zed/settings.json +0 -43
- package/templates/tower-defense/README.md +0 -16
- package/templates/tower-defense/opencode.json +0 -49
|
@@ -5,7 +5,11 @@
|
|
|
5
5
|
// sun misses — so there is no hemisphere or ambient light stacked on top to flatten the frame.
|
|
6
6
|
// The rig is returned because `WorldEnvironment`'s godrays stage raymarches against a shadow map,
|
|
7
7
|
// so `setupPost` needs the key light itself; a shadowless one is refused by name.
|
|
8
|
-
|
|
8
|
+
//
|
|
9
|
+
// The sun's shadow box travels with the runner. The track is endless, so a box left at the start
|
|
10
|
+
// line covers the first stretch and nothing after it: past it the runner, the obstacles and the
|
|
11
|
+
// rails cast no shadow at all. `follow` aims the box at the ground the chase camera sees.
|
|
12
|
+
import { Color, DirectionalLight, Matrix4, PCFSoftShadowMap, type Scene, Vector3 } from "three";
|
|
9
13
|
import {
|
|
10
14
|
SUN_ILLUMINANCE,
|
|
11
15
|
SUN_KELVIN,
|
|
@@ -30,13 +34,26 @@ function atmosphereSun(): DirectionalLight {
|
|
|
30
34
|
return key;
|
|
31
35
|
}
|
|
32
36
|
|
|
37
|
+
/** How far up its own ray the sun sits. The shadow camera's depth range starts at that distance. */
|
|
38
|
+
const SUN_DISTANCE = 30;
|
|
39
|
+
/** How far ahead of the runner the shadow box is centred: the ground the chase camera sees. */
|
|
40
|
+
const LEAD = 12;
|
|
41
|
+
const UP = new Vector3(0, 1, 0);
|
|
42
|
+
const ORIGIN = new Vector3();
|
|
43
|
+
|
|
33
44
|
type ShadowRenderer = { shadowMap: { enabled: boolean; type: number } };
|
|
34
45
|
|
|
35
|
-
export
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
46
|
+
export interface ILighting {
|
|
47
|
+
readonly key: DirectionalLight;
|
|
48
|
+
readonly fill: DirectionalLight;
|
|
49
|
+
/**
|
|
50
|
+
* Put the sun's shadow box on the runner, so the ground in frame keeps its shadows all run long.
|
|
51
|
+
* The track runs down -Z, so the box leads the runner there. Call it once per rendered frame.
|
|
52
|
+
*/
|
|
53
|
+
follow(target: Vector3): void;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
export function setupLighting(scene: Scene, renderer: ShadowRenderer, mobile = false): ILighting {
|
|
40
57
|
renderer.shadowMap.enabled = true;
|
|
41
58
|
renderer.shadowMap.type = PCFSoftShadowMap;
|
|
42
59
|
|
|
@@ -44,16 +61,17 @@ export function setupLighting(
|
|
|
44
61
|
// down-track so it rakes across the obstacles and throws each one's shadow back toward the
|
|
45
62
|
// The photo sky keeps the warm white matched by eye to its photographed midday sun.
|
|
46
63
|
const key = SKY_OPTIONS.sky === "photo" ? new DirectionalLight(0xfff1e0, 4.5) : atmosphereSun();
|
|
47
|
-
|
|
64
|
+
const offset = SUN_DIRECTION.clone().multiplyScalar(SUN_DISTANCE);
|
|
65
|
+
key.position.copy(offset);
|
|
48
66
|
key.castShadow = true;
|
|
49
|
-
// One map fitted to what the chase camera can see from the runner: 4096² is
|
|
50
|
-
//
|
|
67
|
+
// One map fitted to what the chase camera can see from the runner: 4096² is about a centimetre a
|
|
68
|
+
// texel, so every shadow has the same softness. Phones take 2048².
|
|
51
69
|
const size = mobile ? 2048 : 4096;
|
|
52
70
|
key.shadow.mapSize.set(size, size);
|
|
53
71
|
key.shadow.radius = 2;
|
|
54
72
|
key.shadow.camera.near = 1;
|
|
55
73
|
key.shadow.camera.far = 140;
|
|
56
|
-
const extent =
|
|
74
|
+
const extent = mobile ? 16 : 24;
|
|
57
75
|
key.shadow.camera.left = -extent;
|
|
58
76
|
key.shadow.camera.right = extent;
|
|
59
77
|
key.shadow.camera.top = extent;
|
|
@@ -62,6 +80,9 @@ export function setupLighting(
|
|
|
62
80
|
key.shadow.bias = -0.0002;
|
|
63
81
|
key.shadow.normalBias = 0.005;
|
|
64
82
|
scene.add(key);
|
|
83
|
+
// three reads the target's world matrix, which only a scene traversal refreshes: a target left
|
|
84
|
+
// out of the graph stays at the origin however its position reads.
|
|
85
|
+
scene.add(key.target);
|
|
65
86
|
|
|
66
87
|
// The sky alone leaves every down-track face in its own shade, so the runner reads as a dark
|
|
67
88
|
// silhouette against the obstacle it is about to hit — the one comparison the game asks the
|
|
@@ -71,7 +92,28 @@ export function setupLighting(
|
|
|
71
92
|
fill.position.set(0, 8, 20);
|
|
72
93
|
scene.add(fill);
|
|
73
94
|
|
|
74
|
-
|
|
95
|
+
// A shadow map is a grid in the light's own frame. Slide the box by a fraction of a texel and every
|
|
96
|
+
// sample lands between texels, so the whole map crawls with the runner. Both ends snap to whole
|
|
97
|
+
// texels of that grid instead, which leaves every texel on one fixed cell of the world however the
|
|
98
|
+
// runner moves. The sun never turns, so the frame is built once.
|
|
99
|
+
const texel = (2 * extent) / size;
|
|
100
|
+
const intoLight = new Matrix4().lookAt(offset, ORIGIN, UP).invert();
|
|
101
|
+
const outOfLight = intoLight.clone().invert();
|
|
102
|
+
const centre = new Vector3();
|
|
103
|
+
|
|
104
|
+
return {
|
|
105
|
+
key,
|
|
106
|
+
fill,
|
|
107
|
+
follow(target: Vector3): void {
|
|
108
|
+
centre.set(target.x, 0, target.z - LEAD).applyMatrix4(intoLight);
|
|
109
|
+
centre.x = Math.round(centre.x / texel) * texel;
|
|
110
|
+
centre.y = Math.round(centre.y / texel) * texel;
|
|
111
|
+
centre.applyMatrix4(outOfLight);
|
|
112
|
+
key.target.position.copy(centre);
|
|
113
|
+
key.target.updateMatrixWorld();
|
|
114
|
+
key.position.copy(centre).add(offset);
|
|
115
|
+
},
|
|
116
|
+
};
|
|
75
117
|
}
|
|
76
118
|
|
|
77
119
|
/** Material conventions are game-owned; each scene gets independent mutable controls. */
|
|
@@ -69,7 +69,7 @@ export class Run extends Scene<GameState, RunnerPhysics> {
|
|
|
69
69
|
if (this.#model === undefined)
|
|
70
70
|
throw new Error("Run.enter ran before load() loaded mannequin.glb.");
|
|
71
71
|
setupSky(ctx.scene, this.#sky, ctx.renderer.softwareAdapter !== undefined);
|
|
72
|
-
const
|
|
72
|
+
const lighting = setupLighting(
|
|
73
73
|
ctx.scene,
|
|
74
74
|
ctx.renderer.raw as Parameters<typeof setupLighting>[1],
|
|
75
75
|
isMobile(),
|
|
@@ -89,7 +89,7 @@ export class Run extends Scene<GameState, RunnerPhysics> {
|
|
|
89
89
|
materialTier = tier;
|
|
90
90
|
this.#materialLighting?.setEnabled(materialLightingEnabled(tier, materialEnvironment));
|
|
91
91
|
},
|
|
92
|
-
godraysLight: key,
|
|
92
|
+
godraysLight: lighting.key,
|
|
93
93
|
mobile: isMobile(),
|
|
94
94
|
software: ctx.renderer.softwareAdapter !== undefined,
|
|
95
95
|
gpuClass: ctx.renderer.gpuClass?.class,
|
|
@@ -139,13 +139,14 @@ export class Run extends Scene<GameState, RunnerPhysics> {
|
|
|
139
139
|
afterPhysics(ctx, (dt) => {
|
|
140
140
|
const offset = shake.update(dt);
|
|
141
141
|
chaseRunner(camera, runner.mesh.position, dt, offset.position);
|
|
142
|
+
lighting.follow(runner.mesh.position);
|
|
142
143
|
dust.position.set(runner.mesh.position.x, 0.15, runner.mesh.position.z + 0.6);
|
|
143
144
|
});
|
|
144
145
|
|
|
145
146
|
// Collect only after the loaded character and scene receivers are attached.
|
|
146
147
|
this.#materialLighting = ctx.entities.add(
|
|
147
148
|
"material-lighting",
|
|
148
|
-
createMaterialLighting(ctx.scene, ctx.camera, key, {
|
|
149
|
+
createMaterialLighting(ctx.scene, ctx.camera, lighting.key, {
|
|
149
150
|
...materialEnvironment,
|
|
150
151
|
enabled: materialLightingEnabled(materialTier, materialEnvironment),
|
|
151
152
|
overrides: { fillGain: 0 },
|
|
@@ -1,9 +1,6 @@
|
|
|
1
1
|
import type { IThreeNativeConfig } from "@threenative/core";
|
|
2
2
|
|
|
3
3
|
const config: IThreeNativeConfig = {
|
|
4
|
-
// Pinned to the legacy engine: the native engine does not bind three/tsl deltaTime yet (PRD-573 slice 8).
|
|
5
|
-
// Delete this line when `pnpm build --target desktop` passes without it, and the game runs on the native engine.
|
|
6
|
-
engine: "threejs",
|
|
7
4
|
app: {
|
|
8
5
|
id: "com.threenative.__PROJECT_ID__",
|
|
9
6
|
name: "__PROJECT_NAME__",
|
|
@@ -1,95 +1,107 @@
|
|
|
1
|
-
|
|
1
|
+
<!-- shared: kit-identity -->
|
|
2
|
+
# AGENTS.md — __PROJECT_NAME__ (Sailing, the sailing kit)
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
A wind-and-wave sailing starter with buoyancy, ordered course buoys, and a ship you can reshape. Routing words: sailing. `CLAUDE.md` is a copy of this file.
|
|
5
|
+
<!-- /shared -->
|
|
4
6
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
+
<!-- shared: kit-router -->
|
|
8
|
+
## Authoring flow
|
|
7
9
|
|
|
8
|
-
|
|
10
|
+
Detail for each step: `threenative-capabilities` skill. Do the steps in order. A step with no result records `none: <reason>`. A blank step blocks the next. A hook blocks the first new file under `src/` until step 3 ran for the current prompt (`TN_DISCOVERY_GATE=off` opts out; Codex needs `/hooks` trust).
|
|
9
11
|
|
|
10
|
-
1. **
|
|
11
|
-
2. **
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
12
|
+
1. **Kit** (new game only): `engine_search_capabilities {situation: "<the whole request>", scope: "request"}` returns the matching starter kit first. This folder is already a kit.
|
|
13
|
+
2. **Mechanics**: per mechanic, `engine_search_references {situation}`, then `engine_reference_detail` on each hit for pinned constants and feel. To see a mechanic move, `engine_watch_reference {query: "<game> <mechanic>"}` returns a contact sheet of real gameplay. Borrow mechanics only: no code, level layouts, character names or art. Cite `file:line`.
|
|
14
|
+
3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`, then `engine_capability_detail {symbol, importPath}` on every hit. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
|
|
15
|
+
4. **Plan** (new game, or a change to several systems): `prd-creator` with the kit, references and built-ins. With a user, wait for explicit approval, then implement. With no user (`claude -p`, a script), record the plan and assumptions, then continue.
|
|
16
|
+
5. **Assets**: `asset_search_sources`, the source's search tool, then `asset_download_file`; record source and licence in `CREDITS.md`. Nothing fits: `sculpt_plan`. A rigged GLB: `animation_inspect` (`threenative-assets` skill).
|
|
17
|
+
6. **Build**: gameplay in `src/`, look in `src/render/` (`threenative-context` and `threenative-ui` skills). For parallel work, give each subagent one area and its files, then integrate.
|
|
18
|
+
7. **Prove**: one fail-closed playtest per mechanic, then `pnpm test` (`threenative-playtest` skill). A fresh judge compares a `--browser-recipe webgpu --headed` capture to the reference image (`threenative-visuals` skill; `node_modules/create-threenative/agent-docs/references/dream-loop.md`).
|
|
19
|
+
8. **Report**: the `pnpm dev` URL, `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`, `TN_RENDER_PROJECTION`, and each skipped step with its reason.
|
|
18
20
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
|
|
22
|
-
piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
|
|
23
|
-
bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
|
|
24
|
-
(API, expectation, result, replacement); never stall the game.
|
|
25
|
-
|
|
26
|
-
## Workflow skills
|
|
27
|
-
|
|
28
|
-
- `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
|
|
29
|
-
- `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
|
|
30
|
-
- `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
|
|
31
|
-
- `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
|
|
32
|
-
- `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
|
|
33
|
-
- `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets; read it first when the game is slow or stutters: `playtest trace`, then the `threenative-devtools` MCP server.
|
|
34
|
-
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
|
|
35
|
-
- `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
|
|
36
|
-
- Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template pins `engine: "threejs"` in `threenative.config.ts` because the native engine does not bind some of its imports yet. The pin keeps upstream Three.js on web and the legacy host on desktop. A native build names each unbound import with `TN_NATIVE_ENGINE_UNBOUND`. Android and iOS use the legacy host.
|
|
37
|
-
|
|
38
|
-
## Commands and map
|
|
39
|
-
|
|
40
|
-
```sh
|
|
41
|
-
pnpm dev
|
|
42
|
-
pnpm build
|
|
43
|
-
pnpm build --target desktop
|
|
44
|
-
pnpm test:native
|
|
45
|
-
pnpm exec threenative-playtest --scenario playtests/live/render-motion.playtest.json --live-clock --browser-recipe webgpu --headed --server-command "pnpm dev --host 127.0.0.1 --port $PORT --strictPort"
|
|
46
|
-
```
|
|
21
|
+
A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
|
|
22
|
+
<!-- /shared -->
|
|
47
23
|
|
|
48
|
-
|
|
24
|
+
<!-- shared: kit-mcp -->
|
|
25
|
+
## MCP servers
|
|
49
26
|
|
|
50
|
-
|
|
27
|
+
`.mcp.json` wires six servers, and a session started in this folder loads them. Their tools can show as deferred: load them with `ToolSearch` `select:` plus the exact names, for example `select:mcp__threenative-engine__engine_search_capabilities,mcp__threenative-engine__engine_capability_detail,mcp__threenative-engine__engine_search_references,mcp__threenative-engine__engine_reference_detail,mcp__threenative-engine__engine_watch_reference`. A session started outside this folder runs `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`; `call.mjs <server>` lists that server's tools.
|
|
51
28
|
|
|
52
|
-
|
|
29
|
+
- `threenative-engine`: before any new mechanic, helper or render stage, and on a slow frame or a wrong image. `engine_search_capabilities`, `engine_capability_detail`, `engine_search_references`, `engine_reference_detail`, `engine_watch_reference`.
|
|
30
|
+
- `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
|
|
31
|
+
- `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
|
|
32
|
+
- `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
|
|
33
|
+
- `threenative-terrain`: a starter terrain kit. `terrain_generate`.
|
|
34
|
+
- `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
|
|
35
|
+
<!-- /shared -->
|
|
53
36
|
|
|
54
|
-
|
|
37
|
+
## This kit
|
|
55
38
|
|
|
56
|
-
|
|
39
|
+
<!-- shared: kit-files -->
|
|
40
|
+
Source in `src/`: `conventions.ts`, `entities/`, `game.ts`, `main.ts`, `render/`, `scenes/`, `state.ts`, `ui/`.
|
|
41
|
+
8 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
|
|
42
|
+
Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agent-docs/references/auto-exposure.md`).
|
|
43
|
+
Kit notes: `node_modules/create-threenative/agent-docs/references/kit-sailing.md`.
|
|
44
|
+
<!-- /shared -->
|
|
57
45
|
|
|
58
|
-
|
|
46
|
+
Four course marks around the headland, a helm and sheets, 120 seconds of wind. The hull is `assets/ship.glb` (Poly Haven `dutch_ship_medium`, CC0), loaded in `Boot.load()`.
|
|
47
|
+
The sea is `SpectralOcean`; `src/render/ocean.ts` owns its look. `Buoyancy3D` floats the ship on the drawn surface.
|
|
59
48
|
|
|
60
|
-
|
|
49
|
+
<!-- shared: kit-commands -->
|
|
50
|
+
## Commands
|
|
61
51
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
52
|
+
```sh
|
|
53
|
+
pnpm dev # play in the browser
|
|
54
|
+
pnpm test # typecheck, lint, format, then every playtest
|
|
55
|
+
pnpm build --target desktop # also: web, android, ios
|
|
56
|
+
pnpm test:native # native proof
|
|
57
|
+
npx threenative doctor # build, import, device or blank-frame failure
|
|
58
|
+
```
|
|
59
|
+
<!-- /shared -->
|
|
60
|
+
|
|
61
|
+
<!-- shared: kit-conventions -->
|
|
62
|
+
## Conventions
|
|
63
|
+
|
|
64
|
+
Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
|
|
65
|
+
|
|
66
|
+
- **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
|
|
67
|
+
- **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
|
|
68
|
+
- **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
|
|
69
|
+
- **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
|
|
70
|
+
- **Anti-aliasing** `#aa`: 4x MSAA on `high`, else SMAA. Override: `temporalAA: true`.
|
|
71
|
+
- **World-matrix walk** `#matrix-world`: visible subtrees only. Override: `renderer.matrixWorld: "all"`. Marker: `TN_PROJECTION`.
|
|
72
|
+
- **Projected-pixel cull** `#projected-cull`: under 0.5 px. Override: `minimumProjectedPixels`; `alwaysRender(obj)`. Marker: `TN_RENDER_PROJECTION`.
|
|
73
|
+
- **Physics interpolation** `#interpolation`: on for bodies and `ctx.camera`. Override: `physicsInterpolation: false`. Marker: `TN_PHYSICS_INTERPOLATION`.
|
|
74
|
+
- **Continuous collision** `#continuous`: on for `RigidBody3D`. Override: `continuousCollision: false`. Marker: `body.continuousCollision`.
|
|
75
|
+
- **Loading** `#loading`: `loadAll` keeps order; `addInSlices` attaches in 8 ms slices. Override: `concurrency`, `sliceSize`, `marker: false`. Marker: `TN_LOAD_ALL`.
|
|
76
|
+
- **Loading curtain** `#startup`: `ctx.startup.hold(label, () => ready)`. Override: reveal on measured readiness only.
|
|
77
|
+
- **Asset cache** `#asset-cache`: on, with idle fill. Override: `assets: { cache: false, backgroundFill: false }`. Marker: `ctx.assets.cache`.
|
|
78
|
+
- **Asset cook** `#asset-cook`: compact, shared images. Override: `compact: false`; `assets.exclude`; `assets.budget`. Marker: `TN_ASSETS_CONFIG`.
|
|
79
|
+
- **Animation rate** `#animation-rate`: `updateRate: "auto"`. Override: `updateRate: 1`. Marker: `updateRateReport`.
|
|
80
|
+
- **One metre is one metre** `#scale`: `normaliseToMetres`. Override: per-call options.
|
|
81
|
+
- **Rigged assets** `#rigged`: `.glb` in `assets/`; `AnimationPlayer` drives clips. Override: `ctx.assets.model("hero.glb")` in `Scene.load()`.
|
|
82
|
+
- **Clip conformance** `#clip-conformance`: measure a clip before rewriting it. Override: `clipPoseError`; `clipTrackBindings`; `clipBoneCoverage`. Marker: `boneContact`.
|
|
83
|
+
- **Unlit foliage** `#unlit-foliage`: warns. Override: `material.userData.tnUnlitOk = true`. Marker: `TN_UNLIT_FOLIAGE`.
|
|
84
|
+
- **Material backlight** `#backlight`: none, as in stock Unreal. Override: `rimGain`; `fillGain`.
|
|
85
|
+
- **Environment contribution** `#env-contribution`: reported even at zero. Override: `environmentSampling`. Marker: `TN_ENVIRONMENT_CONTRIBUTION`.
|
|
86
|
+
- **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
|
|
87
|
+
- **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
|
|
88
|
+
- **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
|
|
89
|
+
- **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
|
|
90
|
+
- **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
|
|
91
|
+
- **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
|
|
92
|
+
- **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
|
|
93
|
+
- **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
|
|
94
|
+
- **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
|
|
95
|
+
- **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
|
|
96
|
+
- **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
|
|
97
|
+
<!-- /shared -->
|
|
98
|
+
|
|
99
|
+
<!-- shared: kit-stuck -->
|
|
100
|
+
## When the framework blocks you, write plain Three.js
|
|
86
101
|
|
|
87
|
-
|
|
102
|
+
When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you** (API, expectation, result, replacement); do not stall the game.
|
|
88
103
|
|
|
89
|
-
|
|
90
|
-
## Optional multiplayer transport
|
|
91
|
-
For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
|
|
92
|
-
Material backlighting lives in `src/render/lighting.ts`: named `rimGain` and `fillGain` controls preserve the authored palette; `materialLighting.ts` reports `TN_ENVIRONMENT_CONTRIBUTION`. Admission is limited to high hardware desktop WebGPU; mobile/software/WebGL/native retain original materials. Existing authored fill stays authoritative.
|
|
93
|
-
`src/render/exposure.ts` is optional game policy; pass it as `exposurePolicy` in `quality.ts` to use it. Core owns adaptation and its readback. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds.
|
|
104
|
+
## Stuck
|
|
94
105
|
|
|
95
|
-
|
|
106
|
+
`npx threenative doctor`, then `npx @threenative/playtest doctor`; a missing observation is not zero. A confirmed engine bug: `file-engine-bug` skill. Smallest correct change: `ponytail` skill. Slow frame: `threenative-performance` skill.
|
|
107
|
+
<!-- /shared -->
|