create-threenative 0.2.15 → 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
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Kit notes: rain
|
|
2
|
+
|
|
3
|
+
Kit-specific facts moved out of the kit `AGENTS.md`. Shared conventions: `conventions.md`.
|
|
4
|
+
|
|
5
|
+
## Ownership
|
|
6
|
+
|
|
7
|
+
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, audio lifetimes, and the state bridge. This repository owns the coastal storm: weather presets and easing, the fly camera, the shaders, lightning, sound design and the interface; `src/game.ts` is portable and React mounts from `src/main.ts`.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Commands and map
|
|
11
|
+
|
|
12
|
+
`src/state.ts` owns weather validation, the four presets, easing (τ 0.67 s), the flash envelope and the `distance / 343` thunder delay; `src/scenes/Boot.ts` runs the simulation clock, auto-strikes (gated on cloud cover above 0.35) and publishes everything the UI reads. The coast, clouds, rain and bloom/grade are shaders generated from `tools/tempest-*.frag` by `node tools/generate-shaders.mjs`; edit the `.frag`, never a generated `*-shader.ts`. Their named colours and lights live in `src/render/palette.ts`, `sky.ts`, `lighting.ts` and `materials.ts`, the bolt in `lightning.ts`. The coast is one ray-marched screen quad, so it is marked with `alwaysRender`; so are the rain and the bolt, whose quads are projected by their own vertex stage. Sound is three clips baked by `tools/make-storm-audio.mjs` and played through `AudioBus` in `src/audio/storm.ts`; audio starts on a gesture, and pause, mute and tab visibility each hold it. `safe` gates every strike at one door, and `prefers-reduced-motion` turns it on at boot; `state.reducedMotion` publishes that answer for playtests. Keep `playtests/survives.playtest.json` as smoke proof, and `storm`, `lightning`, `reduced-motion` and `tiers` honest when you change what they assert. To build a game on the storm, keep its rules in a plain module and wire them in `src/scenes/Boot.ts`: `strike()` is the one door every strike passes (its distance and thunder delay are in scope), the frame function runs per-step rules after the camera moves, and the round's state is a `GameState` field the UI reads; `Billboard3D` turns world markers to the camera.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Portable authoring contracts
|
|
16
|
+
|
|
17
|
+
One world unit is one metre; the camera starts at `(1.8, 2.85, 18)` and `src/render/camera.ts` owns its clamps and speeds; manual input cancels the cinematic orbit. There is no walking actor, weapon or agent here to ground, bind or navigate. `input.vector("move").y` is +up and means forward; use one explicit `-move.y` conversion.
|
|
18
|
+
|
|
19
|
+
`src/render/quality.ts` owns `low`, `medium`, `high` (the engine chain: no built-in stage at any tier); the GPU family from `ctx.renderer.gpuClass` sets the start (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`); `isMobile()` chooses `low`, otherwise `high` when the family is `unknown`; override with `setupPost(..., { tier: "low" })`. Rain keeps 4x multisampling: `temporalAA` is off in `quality.ts`, because the study draws its own single post pass. The player's four tiers are `STUDY_TIERS` in the same file. The bridge flushes about 100 ms; a control flushes it at once.
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
## Budget real time for the look
|
|
23
|
+
|
|
24
|
+
`npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it beside the frame rate; `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds.
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
## Optional multiplayer transport
|
|
28
|
+
|
|
29
|
+
Backlight exception: this storm raymarches custom shader lighting in `src/render/lighting.ts`; standard-material `rimGain`/`fillGain` conversion is unqualified. Preserve its authored flash rim and sky fill. The cloud render-target radiance is unknown until sampled; do not claim an environment contribution from `scene.environment`.
|
|
30
|
+
|
|
31
|
+
This kit keeps both: the storm's own post pass draws bloom, grade, vignette, lens beads and dither (every built-in stage is off, named in `quality.ts`), and the core filmic curve and metered exposure do the tone map. `exposure.ts` caps the meter at +0.8 stop so the storm stays dark, and `postprocessing.ts` scales the weather exposure by 0.85 and `clouds.ts` the flash light on the clouds by 0.3 so the filmic shoulder keeps the bolt visible.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Kit notes: rts
|
|
2
|
+
|
|
3
|
+
Kit-specific facts moved out of the kit `AGENTS.md`. Shared conventions: `conventions.md`.
|
|
4
|
+
|
|
5
|
+
## Ownership
|
|
6
|
+
|
|
7
|
+
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, and the state bridge. This repository owns the rules in `src/sim/`, every visible choice in `src/render/`, the scene in `src/scenes/`, and the HUD in `src/ui/`; `src/game.ts` is portable and React mounts from `src/main.ts`. Nothing in `@threenative/*` reads or chooses their appearance, and this kit loads no physics plugin: `src/sim/` does its own collision and A*, which is what makes a match replayable and headless-testable.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Start every change
|
|
11
|
+
|
|
12
|
+
`@threenative/physics/navigation` is browser-only WASM; use portable `ctx`/Three.js for this cross-target template.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Commands and map
|
|
16
|
+
|
|
17
|
+
`src/sim/` is the whole ruleset — terrain, A*, economy, construction, production, combat, vision and a four-state AI — plain TypeScript with no renderer import, so it runs headless in `pnpm test` and replays from a seed. `src/scenes/Play.ts` steps it on a 0.05 s accumulator inside the engine's frame and reads every gesture through `ctx.input`; `src/render/` draws it (terrain displaced by the simulation's own `terrainHeight`, instanced models per (type, team), selection rings and health bars, fog of war in the terrain material); `src/ui/` is the HUD, the minimap and the command panel, where every order starts as a named intent the scene resolves. `playtests/survives.playtest.json` is the durable smoke proof; `rts-orders`, `rts-build`, `rts-train`, `rts-attack`, `rts-ai-attack`, `rts-pause`, `rts-zoom` and `performance` are the rest.
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
## Portable authoring contracts
|
|
21
|
+
|
|
22
|
+
A scene that returns a frame function from `enter()` gets that function instead of `update()`, and it runs on the fixed step, not once per drawn frame: put per-frame work there, and do not expect a variable frame delta.
|
|
23
|
+
|
|
24
|
+
This kit authors `renderer.resolutionScale: 1` to keep thin infantry, bars and rings at full resolution; use `"auto"` to restore the engine scaler. This readability policy is not an autoscaler fix or a proven FPS gain. `src/render/sky.ts` makes `assets/sky.jpg` (Poly Haven, CC0) the background and sets the fog colour (re-aim `SUN_DIRECTION` when you swap it, and re-tune the fog density: it is set for a 224 m map); there is no environment light, AstraCraft lights with a hemisphere, and `lighting.ts` sizes the sun's shadow window to the frame every frame. The rig is wider than the map at its widest zoom, so `terrain.ts` draws a plain under it (grow it with `ZOOM_RANGE.far` or the horizon goes with it). The battlefield look follows AstraCraft (PRD-765): `ground.ts` paints roads, aprons and pools into one CPU `DataTexture` (no DOM canvas, so it runs native), `environment.ts` puts a mesa on every `game.obstacles` rock plus rubble, scrub and props, one instanced or merged mesh per family. Every model is a custom TSL material, so an instanced batch's geometry is what you see — change `render/models.ts`, not the material. The shared look comes from core through `src/render/quality.ts`; this kit overrides it with `tonemapMode: "aces"`, `autoExposureEnabled: false` and `exposure: 1.02`, the AstraCraft reference look; delete those three keys to return to core's filmic curve and metered exposure. The HUD styles live in `src/style.css` under `.astra-hud`; instanced dark ring and bar backing keeps faction cues legible. Like AstraCraft it has no bloom (`bloomEnabled: false`) and no local exposure, a cosine-fourth vignette (`vignetteAmount: 0.4`), and no camera motion blur. AstraCraft colours are legacy linear values: `legacyColor` in `palette.ts` reads them. Anti-aliasing is core's: 4x MSAA on `high`, SMAA on `medium` and `low`, so units stay sharp while the camera pans. `temporalAA: true` and `motionBlurEnabled: true` are the named opt-ins. `pnpm test` proves behavior, never the look.
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
## Budget real time for the look
|
|
28
|
+
|
|
29
|
+
It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine. `npx threenative doctor` repeats the last verdict; `TN_FRAME_SPANS=1` adds the render phase's own span tree. The cheapest static object is one whose transform you never write, so do not touch a transform you do not need to; `markStatic(root)` freezes a subtree that is sure of and `invalidateStatic(object)` announces a write inside one. The terrain here is the one such subtree. The battlefield's other cost is its *materials*: every distinct material configuration compiles at boot, and boot is what a commander waits through.
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
## Optional multiplayer transport
|
|
33
|
+
|
|
34
|
+
`src/render/exposure.ts` supplies the enabled game-owned meter policy through `exposurePolicy` in `quality.ts`.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Kit notes: runner
|
|
2
|
+
|
|
3
|
+
Kit-specific facts moved out of the kit `AGENTS.md`. Shared conventions: `conventions.md`.
|
|
4
|
+
|
|
5
|
+
## Ownership
|
|
6
|
+
|
|
7
|
+
This repository owns the track, the runner, the obstacles, the dust, the HUD and the look; `src/game.ts` is portable and React mounts only from `src/main.ts`.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Start every change
|
|
11
|
+
|
|
12
|
+
No navmesh is imported, so this kit runs on every target; `@threenative/physics/navigation` would make it web and desktop only. `GPUParticles3D` is WebGPU-only and the dust depends on it.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Commands and map
|
|
16
|
+
|
|
17
|
+
`src/track.ts` is a ring of six chunks **moved and rewritten**, never rebuilt: each chunk's obstacle `InstancedMesh` is built once at a fixed slot count and its matrices rewritten on recycle. The obstacle *bodies* are the exception — disposed and recreated, because `RigidBody3D` cannot reposition a fixed body. The runner is not a rigid body — a lane snap and a jump arc feel worse in a solver — but the collision is real: `src/entities/Runner.ts` carries an `Area3D` masked to the obstacle layer and listens for `bodyEntered`, so a hit is an overlap the engine reports, not a hand-kept distance check. Its figure is `assets/mannequin.glb` (the file `minimal` ships) through `SkeletalMesh3D`; `CLIPS` names the four clips it plays. Gravity is zero in `src/game.ts` on purpose; nothing falls. The track comes from `ctx.random`, so `defineGame({ seed })` **is** the level. Register entities with `ctx.entities`; the React HUD reads `GameState`, never an entity. Keep `playtests/survives.playtest.json` as smoke proof, `playtests/stride.playtest.json` bounds the mannequin's `footSlip` at 1 m/s, and keep `streams` honest when chunk recycling changes.
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
## Portable authoring contracts
|
|
21
|
+
|
|
22
|
+
The camera reads the runner **after** the step through `afterPhysics` — in the frame function that is 0.4 m of lag at 26 m/s. `CameraShake` returns an offset; `src/render/camera.ts` adds it. `src/render/sky.ts` draws Unreal's default sky (an atmosphere with clouds) as background, environment light and height-fog colour, and `lighting.ts` tints the sun by the air it crosses; `SKY_OPTIONS` takes `sky: "photo"` for `assets/sky.jpg` or `clouds: false`, and `ground: false` once the game has its own global illumination (the sunlit ground under the horizon stands in for the bounce).
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
## Budget real time for the look
|
|
26
|
+
|
|
27
|
+
The shared filmic curve and metered exposure come from core through `src/render/quality.ts`. Runner maps logical `high` to core `medium`: the full high chain measured 51.3/52 ms p95 against its 33 ms budget. `TN_RENDER_CHAIN_TIER_OVERRIDE` reports that cap; the curve and meter stay enabled. The authored `gtaoRadius: 0.35` preserves foot contact, and `samples: 4` preserves the Three.js fallback's thin-rail anti-aliasing with SMAA. Runner keeps `ssrEnabled: false` on its rough track to retain the 33 ms p95 budget (real-display observations: 17.0/20.3 ms); `ssrEnabled: true` opts into reflections for a glossy track. Override those on the same quality preset; `tonemapMode: "aces"` and `autoExposureEnabled: false` with fixed `exposure` are explicit alternatives.
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
## Optional multiplayer transport
|
|
31
|
+
|
|
32
|
+
Kit facts: `A`/`D` or arrows change lane, `Space` jumps, `R` runs again; touch gets two lane buttons and a stick (flick up to jump). The track is a ring of `RESIDENT_CHUNKS` slices rebuilt by one `build` method in `src/track.ts`, so a long run costs what a short one does, and `defineGame({ seed })` sets the whole level. `assets/sky.jpg` is Poly Haven CC0 and `assets/mannequin.glb` is Quaternius CC0.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Kit notes: sailing
|
|
2
|
+
|
|
3
|
+
Kit-specific facts moved out of the kit `AGENTS.md`. Shared conventions: `conventions.md`.
|
|
4
|
+
|
|
5
|
+
## Ownership
|
|
6
|
+
|
|
7
|
+
This repository owns ship handling, the sea's look and tuning, `Buoyancy3D`, course order, HUD, water, and look; `src/game.ts` is portable and React mounts from `src/main.ts`.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Start every change
|
|
11
|
+
|
|
12
|
+
`@threenative/physics/navigation` is browser-only WASM; this kit uses its analytic wave field and measured hull points instead.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Commands and map
|
|
16
|
+
|
|
17
|
+
Four course marks around the headland, a helm and a set of sheets, 120 seconds of wind. The hull and rig are `assets/ship.glb` — Poly Haven's `dutch_ship_medium` (CC0; James Ray Cock, Rico Cilliers, Nicolò Zubbini) — fetched by `Boot.load()` (`props.ts#loadShipModel`, alongside the sky) and read back synchronously in `Sailing.enter()` (`props.ts#getShipModel`), then oriented by `props.ts#createShipModel`: a scene-level `load()` on `Sailing` itself would still leave the registry empty the instant `enter()` returns, since `Boot.enter()` calls `goto("sailing")` without awaiting it. `conventions.ts#measureHull` reads the physics body's box and `Buoyancy3D` hull points off the loaded model rather than a hand-tuned constant, so a different hull model never needs those numbers touched by hand. `SHIP_SAILS` in `props.ts` stays simulated cloth: the GLB's own baked sail mesh is stripped at cook time so the two never double up. `Ship.ts` uses `RigidBody3D` plus `Buoyancy3D`, and reads the hull's attitude off four swell samples rotated by the heading rather than leaving it to the solver: `Buoyancy3D`'s drag comes from the body's *linear* velocity and so damps no rotation at all, and a free body capsizes inside seconds. A helm and sheets are two axes, not one stick: `vector("move")` clamps its diagonal to unit length, which is right for a thumb and wrong for a ship that must hold full sail and hard over at once.
|
|
18
|
+
|
|
19
|
+
The sea is `SpectralOcean`, added with `ctx.add` so the compute registry runs its passes. It draws nothing: `src/render/ocean.ts` owns the mesh, the material, the mirror and every colour, and is the only file to edit for the water's look. The cascade buffers the vertex stage reads are the ones the CPU height query is copied from, so the hull floats on the surface that is drawn; two fields would leave the ship riding water nothing renders, with every assertion here still green.
|
|
20
|
+
|
|
21
|
+
The initial loading curtain also waits for the first finite CPU height in `src/scenes/ocean-readiness.ts`. It registers the existing startup hold synchronously, dispatches once after framework readiness, and releases on a real sample, including zero. The existing 45 s hold budget bounds the wait; timeout or compute failure emits `TN_SAILING_HEIGHT_READBACK_FAILED` before the gate fails open. Exit cancels the observer; restarts after startup use the ordinary compute lifecycle. This gate does not guarantee the timing of later throttled copies.
|
|
22
|
+
|
|
23
|
+
Five details are load-bearing. The material is `MeshStandardNodeMaterial`, not a basic one: a basic material takes no lights, so the sun on the water has to be faked with a `pow()` term, and the sea cannot agree with the hull floating on it. `normalNode` overrides `normalView`, so feed it a view-space normal or the reflection becomes a column of glare that follows the camera. The surface is a **logarithmic disc** centred on the ship, the cascade lookup adding the disc's own offset back: a square patch either ends inside the haze as a visible rectangular hem, or reaches the horizon with 300 m quads beside the hull. The ripple normals fade on the **pixel footprint** (`dFdx`/`dFdy` of the world position) and the slope they lose is spent as roughness, or every sea past 130 m is a mirror. And the CPU height is a coarse throttled copy: `readbackResolution` over the largest `patchSize` is the spacing between samples, and make that spacing wider than the waves and the ship sits at a smoothed mean sea level, hanging over its own troughs. It is also `undefined` until the first copy lands, which `Ship.ts` handles by falling back to mean sea level, and `surfaceHeight(ocean, x, z, dt)` is the call anything that floats should use rather than `sampleHeight` raw: it predicts the height from the same sample's measured vertical velocity and age. The hull additionally owns a `createHeightReconciler()` history: a new copy preserves the previous predicted height and velocity, then completes its correction over the measured interval between copies. `surfacePredictionCorrection` and `maxSurfacePredictionCorrection` report the waterline offset honestly; wave velocity and the attitude probes keep their measured inputs. `WaveField.sample(x, z, time)` returns height and normal and allocates; `heightAt(x, z, time)` is the same arithmetic without the jacobian and without an allocation — ask it for floats, splash and wake, and keep `sample` where you shade with the normal. `RippleField` is the sea answering back: a finite patch carrying only the disturbance, so add its `heightAt` to the sea height and its `foamAt` to the foam and never use it in place of a sea. It steps at display rate or the CFL limit, whichever is smaller; `speed`, `damping`, `foamHalfLife`, `current`, `step` and `maxSteps` override that, and a `step` over the limit is rejected with the limit in the message. Its rim absorbs, so `recenter` it on whatever the player is watching.
|
|
24
|
+
|
|
25
|
+
The sky is `assets/sky.jpg` (Poly Haven, CC0), fetched in `Boot.load` beside the ship — a scene's `load` is the one method allowed to await, and `Sailing.enter` must stay synchronous, because a playtest runner reads the registry the instant `enter()` returns. `sky.ts` draws it at `SKY_RANGE` and lights the scene at `FILL_RANGE`, and those are different numbers on purpose: half that photograph is a flat grey placeholder where a panorama's lower hemisphere should be, and at full range it becomes the largest term in every surface's light budget. Reflection is one half-res `WaterSurface3D` pass, with `markReflected` naming what the mirror may draw — it is a second draw of the world, so the sea stays off it, the sky arrives in the same texture, and there is no second sky lookup to blend against it.
|
|
26
|
+
|
|
27
|
+
Tune the sea state in `src/render/ocean.ts`, the rig and hull in `src/render/props.ts` and `src/entities/Ship.ts`, and the course in `src/scenes/Sailing.ts`. The React HUD reads published state; keep `playtests/survives.playtest.json` as smoke proof and native scenarios honest.
|
|
28
|
+
|
|
29
|
+
On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), `src/render/touch-controls.ts` adds a left stick whose vector `Sailing` adds into both the helm and the sheets; keyboard is the fallback.
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
## Portable authoring contracts
|
|
33
|
+
|
|
34
|
+
Generated conventions call `normaliseToMetres` for authored ship scale; buoyancy owns water contact. `input.vector("move").y` is +up and means forward wind; use one explicit `-move.y` conversion.
|
|
35
|
+
|
|
36
|
+
The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js.
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
## Optional multiplayer transport
|
|
40
|
+
|
|
41
|
+
`quality.ts` names one cost override, reported as `TN_RENDER_CHAIN_COST_OVERRIDE`: no final gather, SSGI or SSR (the frame is the water, and screen-space reflections over moving water read as smear) and no motion blur (it smeared the chase-camera ship and its sails). Kit facts: WASD or arrows steer, the left touch stick sails, `C` is a capsize test, `R` restarts. `SpectralOcean` displaces the drawn surface and answers the height query `Buoyancy3D` reads, so the ship floats on the water you see. `src/render/sky.ts` is adapted from MIT-licensed VictorZakharov/beautiful-water; its header keeps the credit and the MIT licence name, so keep that header.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Kit notes: shooter
|
|
2
|
+
|
|
3
|
+
Kit-specific facts moved out of the kit `AGENTS.md`. Shared conventions: `conventions.md`.
|
|
4
|
+
|
|
5
|
+
## Ownership
|
|
6
|
+
|
|
7
|
+
This repository owns the town, the soldiers, the rifle, the HUD and the look; `src/game.ts` is portable, `src/main.ts` is the web-only React mount.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Start every change
|
|
11
|
+
|
|
12
|
+
`@threenative/physics/navigation` is browser-only WASM; use the direct physics queries already in this kit instead of a navmesh or distance scan.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Commands and map
|
|
16
|
+
|
|
17
|
+
Contract: a 105-second round in a procedurally built 84 m waterfront town; 12 hits completes it, zero health or an expired clock fails it, Enter restarts. Mouse looks, WASD or arrows move, Space or left click fires, F or right click aims, R reloads, shift sprints, ctrl/C crouches. `src/render/town.ts` owns the layout — blocks, quay, pier, raised decks, routes, spawns — and every solid in it is both a collider and a raycast target. `src/entities/` owns the fight: `FpsPlayer` moves, `Rifle` fires and zeroes, `Enemy` patrols, hears, sees and shoots back, `Target` scores the plates. `src/scenes/Play.ts` wires them and `src/ui/Hud.tsx` is the only HUD. `index.html` runs `game.ts` in a web worker (`src/worker.ts`, page side `src/worker-page.ts`), so a busy page cannot stall its frames; `main.html` is the named override that runs it on the page thread. `playtests/survives.playtest.json` is the durable smoke proof. The soldiers are `assets/mannequin-combat.glb` (Quaternius UAL, CC0); the hands in `assets/player-viewmodel.glb` are "Animated FPS hands (rifle animation pack)" by Cransh, CC-BY-4.0 — https://sketchfab.com/3d-models/animated-fps-hands-rifle-animation-pack-5f2d0ed780a94724b36ab505f7564057.
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
## Portable authoring contracts
|
|
21
|
+
|
|
22
|
+
Leave `assets` absent: the cook selects target-decodable passes, and `models.compact` (default `{ flatten: true, join: true, instance: true }`) flattens the scene graph losslessly while keeping any node matching `protectedPattern` or `protectedNames`, an animation target, or a skin joint individually addressable; `compact: false` ships it as authored. `models`/`textures`/`audio`: `"none"` skip those passes and report uncooked bytes, and a codec override must satisfy four-pixel block alignment — `codec: "none"` opts out. `assets.exclude` (source-relative globs) omits files and reports saved bytes. `assets.budget` accepts `{ uncooked?: number | "none", total?: number | "none" }`, default `{ uncooked: 64_000_000, total: "none" }`: only bytes left uncooked where cooking was possible count, an unaligned source image is retained unchanged and still counted, and cooking never resizes one to fix alignment. Android/iOS skip compression and dedupe. First person, four rules: place the camera in the plugin hook after the physics step, never at the end of the frame function, or the eye sits one step behind the body and shots land in the floor on the deck stairs; start every shot at `player.aimRay()`, where the crosshair is, and let `Rifle.converge` lean the weapon to meet it; the trigger takes `pressed` and `justPressed`, because the cooldown makes the cadence and the edge catches a click the harness delivers no other way; `src/render/scale.ts` is the only size table.
|
|
23
|
+
|
|
24
|
+
Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, size it with `normaliseToMetres` at a named joint, drive `AnimationPlayer` beside its entity, and reach a held prop with `attachToBone`. `input.vector("move").y` is +up, so forward uses one explicit `-move.y`. `ctx.goto(name)` rebuilds without resetting game state (from a frame function, `goto` then `return`); `ctx.state.set({ … })` is a partial patch; `game.goto()` rebuilds and resets. Seeded randomness needs `defineGame({ seed })`. `src/render/sky.ts` draws Unreal's default sky (an atmosphere with clouds: `atmosphere.ts`, `clouds.ts`, `gpuSky.ts`) as background, environment light and height-fog colour, and `lighting.ts` tints the sun at `SUN_DIRECTION` by the air it crosses; `SKY_OPTIONS` takes `sky: "photo"` for `assets/sky.jpg` (Poly Haven, CC0) or `clouds: false`, and `ground: false` once the game has its own global illumination (the sunlit ground under the horizon stands in for the bounce); `src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` sets the start (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`); `isMobile()` chooses `low`, otherwise `high` when the family is `unknown`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw, `TN_QUALITY_TIER` reports the source, and the bridge flushes about 100 ms — keep score/phase in state, feedback in Three.js. The shared look comes from core through `src/render/quality.ts`; the filmic curve and metered auto exposure are enabled by default. `src/render/exposure.ts` holds this game's meter policy (`key` 0.14, `maxStops` 0.5, `minStops` -2). It has Unreal's bloom with no threshold (`unrealBloomEnabled`), local exposure (`localExposureEnabled`, off on `low`), a cosine-fourth vignette (`vignetteAmount: 0.4`) and no motion blur on any tier: a mouse turn smeared the whole frame and the hands (`motionBlurEnabled: true` brings it back).
|
|
25
|
+
|
|
26
|
+
When an animation looks wrong, measure it before rewriting it: `clipPoseError` scores a retargeted clip per bone in degrees relative to each rig's own bind pose, `clipTrackBindings` names tracks that bind nothing (the `<bone>.undefined` failure that plays the bind pose), `clipBoneCoverage` names bones the clip does not drive, and `boneContact` reports whether a bone reaches its prop. A soldier reads as a soldier only when every AI state picks a clip that names the action — patrol and chase `Rifle_Walk`, standing aim `Rifle_Idle`, firing `Rifle_Shoot`, crouch `Rifle_Crouch_To_Idle`/`Rifle_Crouch_Walk` (the six `Rifle_*` clips are Mixamo rifle clips retargeted onto the mannequin, and `RIFLE_HOLD` in `Enemy.ts` turns the rifle to each; the soldier's `rightHandContact`/`leftHandContact` are `boneContact` metres, held under 0.05), hit `Rifle_Hit`, dead `Death01` — crossfaded, feet snapped to the floor, body turned into the direction of travel or aim, and tinted so he does not vanish into the white first-person hands.
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
## Budget real time for the look
|
|
30
|
+
|
|
31
|
+
Open a capture after visual changes; a scenario with no assertions or missing observations fails. `npx threenative doctor` repeats the last verdict; `TN_FRAME_SPANS=1` adds the render phase's own span tree.
|
|
32
|
+
|
|
33
|
+
On a touch-primary device, `src/entities/TouchControls.ts` adds a movement stick, a look stick, and fire, aim, reload and crouch pads; the stick pushed to its rim sprints.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Kit notes: snow
|
|
2
|
+
|
|
3
|
+
Kit-specific facts moved out of the kit `AGENTS.md`. Shared conventions: `conventions.md`.
|
|
4
|
+
|
|
5
|
+
## Ownership
|
|
6
|
+
|
|
7
|
+
This repository owns the explorer, the boot print, the glade, the weather, the HUD and the look; `src/game.ts` is portable and React mounts from `src/main.ts`.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Commands and map
|
|
11
|
+
|
|
12
|
+
The snow is one `SnowField` (`@threenative/core/world`) over one `Heightfield` built in `src/terrain.ts`: indentation, bank, compaction and disturbance composed into the canonical surface that queries, the drawn mesh and the collider all read. Never keep a second height grid. `attachSnowPhysics` (`@threenative/physics`) owns the snow collider: each fixed step it reads the solver's contacts for the ball, crate and log, presses each body's own shape with its solved load, and installs the changed surface before the next step. Call `step` from `afterPhysics`, once; `observe()` reports `colliderError` and `loadProvenance` (load is a solver estimate). A kinematic `CharacterBody3D` makes no contact load, so `src/entities/Explorer.ts` plants `src/render/bootPrint.ts` itself with `snow.stamp`, only while `grounded`. Its capsule stands on a coarse walk surface (`walkSurface` in `src/terrain.ts`), not the 6 cm snow collider: Rapier sweeps a character against every triangle under it, which cost ~0.9 ms a step there.
|
|
13
|
+
|
|
14
|
+
Look lives in `src/render/`: `snowSurface.ts` (TSL material, compaction view, redraws each `takeDirtyRegions` window, one upload range per row), `weather.ts` (`GPUParticles3D` snowfall and powder), `explorer.ts`, `scenery.ts`, `props.ts`. Tune response with `depth`/`hardness` and the refill in `src/scenes/Snow.ts`. The React HUD reads `GameState` and sends intents; `src/commands.ts` routes panel verbs into the same functions as the keys. Keep `playtests/survives.playtest.json` as smoke proof and `playtests/snow-physics.playtest.json` honest: it proves drop, settle and rolling track. On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), `src/render/touch-controls.ts` adds a left movement stick; keyboard is the desktop fallback.
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
## Portable authoring contracts
|
|
18
|
+
|
|
19
|
+
The fixed step is the snow's clock: deposition, footsteps and contacts never read the frame rate. `input.vector("move").y` is +up and means forward; `Snow.ts` turns it into a camera-relative direction.
|
|
20
|
+
|
|
21
|
+
Snow keeps 4x multisampling: `temporalAA` is off in `quality.ts`, because the engine draws no velocity for the sprite flakes, and tens of thousands of them could trail. The bridge flushes about 100 ms; keep readouts in state and frame feedback in Three.js.
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
## Budget real time for the look
|
|
25
|
+
|
|
26
|
+
`npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it beside the frame rate; `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds.
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
## Optional multiplayer transport
|
|
30
|
+
|
|
31
|
+
`quality.ts` names one cost override, reported as `TN_RENDER_CHAIN_COST_OVERRIDE`: no final gather, SSGI or SSR, no temporal AA or motion blur, no bloom and no local exposure, because the core gather took the performance scenario to 38.8 ms GPU p95 against 16.7 ms, the GPU-computed flakes carry no velocity for either temporal stage, bloom veils the white glade, and local exposure lifts the explorer's shadows and flattens it against the snow. `exposure.ts` keeps core's meter and sets its exposure compensation per weather (`EXPOSURE_BIAS`: +2 stops clear, none in the blizzard, blended on the eased storm level). `Snow.ts` passes `exposureBias(weather.storm)` to `setExposureBias` on the meter that `setupPost` returns each frame, so the snowfield meters white instead of middle grey and the uniform blizzard fog does not wash out.
|
|
32
|
+
|
|
33
|
+
Kit facts: WASD or arrows walk (Shift runs), drag orbits, scroll zooms; `F` drops the ball, `G` pushes it, `B` blizzard, `C` camera view, `V` compaction view, `P` auto-explore, `R` clears every footprint, `M` sound; on touch the left stick walks. The crunch and wind clips in `assets/` are generated noise: replace either with a recording.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Kit notes: starter
|
|
2
|
+
|
|
3
|
+
Kit-specific facts moved out of the kit `AGENTS.md`. Shared conventions: `conventions.md`.
|
|
4
|
+
|
|
5
|
+
## Ownership
|
|
6
|
+
|
|
7
|
+
This repository owns gameplay and every visible choice in `src/render/`, `src/entities/`, `src/scenes/`, and `src/ui/`; `src/game.ts` is portable and React mounts from `src/main.ts`. The look ships as Unreal's default sky and a rigged figure: `src/render/sky.ts` draws an atmosphere sky with clouds (`atmosphere.ts`, `clouds.ts`, `gpuSky.ts`) that is the background, the environment light and the height-fog colour, `lighting.ts` adds the one sun at `SUN_DIRECTION`, tinted by the air it crosses, and `Player.ts` drives `assets/mannequin.glb` (Quaternius, CC0) through `SkeletalMesh3D`. Move `SUN_DIRECTION` and the sky, sun colour and fog follow; `SKY_OPTIONS` in `sky.ts` takes `sky: "photo"` (the `assets/sky.jpg` photograph, Poly Haven, CC0) or `clouds: false`, and `ground: false` once the game has its own global illumination (the sunlit ground under the horizon stands in for the bounce); swap the rig and edit `CLIPS`. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `src/render/sky.ts` makes — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Start every change
|
|
11
|
+
|
|
12
|
+
`@threenative/physics/navigation` is browser-only WASM; use returned subpaths and `attachToBone` rather than rebuilding installed systems.
|
|
13
|
+
|
|
14
|
+
For *"a bullet passes through a wall"*, `RigidBody3D` enables continuous collision by default; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web and native.
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
## Commands and map
|
|
18
|
+
|
|
19
|
+
The game boots straight into `Play`: a test arena holding a pickup, a crate, a gap you must jump and a flag, which together produce `won` or `lost`; `R` and the React restart intent rebuild from `initialState`. Keep the packaged `assets/native-proof.glb` load and its console marker for the desktop asset gate. `Play.ts` owns gameplay, `src/render/` owns the look, `src/ui/Hud.tsx`/`Menu.tsx` own UI, and `state.ts` publishes JSON-safe values. Keep `playtests/survives.playtest.json` as smoke proof and update outcome tests. `index.html` runs `game.ts` in a web worker (`src/worker.ts`, page side `src/worker-page.ts`), so a busy page cannot stall its frames; `main.html` is the named override that runs it on the page thread.
|
|
20
|
+
|
|
21
|
+
On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), local `src/render/touch-controls.ts` adds a left movement stick and right jump button; the scene passes its input to `Player`, with keyboard mapping as the desktop fallback.
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
## Portable authoring contracts
|
|
25
|
+
|
|
26
|
+
Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable; generated conventions call `GroundSnap` for floor contact and `normaliseToMetres` for authored model scale. `ctx.beforeRender(fn)` registers scene work that runs once per actual world draw, after the frame's last fixed update and before the projection packs, so `fn` reads the frame's final state; a held loader frame draws no world and dispatches nothing, and the registration clears on scene change and stop like `ctx.afterPhysics`. Automatic drawing resolution (`render.resolutionScale: "auto"` on `defineGame`) reads fresh GPU cost before presentation timing, so a host delay alone does not spend pixels while GPU headroom is observed and sustained headroom restores resolution; missing or stale GPU timing probes one rung and refunds it unless fewer pixels earn a better frame rate, oscillation holds are temporary, a numeric `resolutionScale` is the named pin override, and `TN_FRAME_BUDGET` reports the actual scale, its source, the GPU time as a mean/p50/p95/max series over resolved frames (`gpu`, with `gpuStale` counting frames that had no fresh reading and `gpu` absent rather than zero when there were none), and the draw calls and triangles each render pass submitted (main, shadow, reflection) under either policy. The engine's scene-render projection — an internal mirror that collapses repeated draws — is on by default; `render.projection: false` is the named opt-out and builds no mirror, so a game that measured it as a loss pays nothing to decline it, reported as `TN_RENDER_PROJECTION` reasonCode `disabled`. When the mirror draws props whose materials differ only in base colour, it proves a **bounded slice** of those materials each frame (`render.projection.materialChecks: "spread"`, the default) instead of all of them, so a base-colour edit still lands the same frame while any other material edit — a new roughness, map or define — leaves the batch and is drawn exactly up to `materialCheckStaleFrames` frames later, which `TN_RENDER_PROJECTION` reports. Name `"everyFrame"` to pay for every material every frame instead. A water surface's mirrored pass redraws every frame by default; `reflection.refreshInterval: N` redraws it every Nth presented frame and samples the previous reflection target in between, which halves the pass's cost at the price of up to `N - 1` frames of lag while the camera moves. React never touches the scene graph. Native UI reads published state and sends intents; mark every touch target `data-tn-interactive`, and style `[data-tn-native-select]` / `[data-tn-native-select-option]` if the game has a `<select>`: on desktop the UI is drawn into the game's own frame with no view for a native popup to open into, so the engine renders the list in the page and the project gives it a look, the same division as `[data-threenative-debug-overlay]`.
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
## The arena is a test arena, and its look is a grid
|
|
30
|
+
|
|
31
|
+
`src/render/arena.ts` owns the ground, the four walls, one pillar, and `platform()`, the single builder both ends of the course are cut from. A platform is a light metre-grid plate over a dark-grid body down to the ground: two meshes, so the player collides with exactly the triangles they can see, and the sides read as structure while the walking surface reads as floor. The ground has no collider — that is the pit under the gap, and why falling costs a life instead of landing on scenery. Move a platform and move its support surface in `Play.ts` and `Goal.ts` with it, or grounding will answer for a surface that is no longer there. The sun's shadow camera covers the diagonal of `ARENA` down to `GROUND_Y`; changing those dimensions updates coverage automatically. `materials.ts` is the whole look: two greys and one saturated colour. Light grid where the player walks, dark grid on sides and structure, and the single `accent` hue reserved for the crate, the pickup and the flagpole — what you can touch. `worldGridUVs` makes one grid tile one metre on every face of every prop, so call it after a geometry is placed and before it is given to a mesh.
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
## Quality and proof
|
|
35
|
+
|
|
36
|
+
`src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` selects the boot tier (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`; `unknown` falls back to `isMobile()`), and `adaptiveQuality.ts` reads `game.ts` frame windows. Fresh GPU time wins, with a named presentation fallback. After startup, two overloaded windows lower quality; five with 20% headroom raise it; cooldown is five seconds. Presentation fallback allows 5% timing jitter (`presentationTolerance`); `overloadBudgetMs` reports its threshold. Vsync-bound presentation alone cannot prove recovery headroom. `setupPost` exposes policy options and `targetFps`; `Play` supplies `display.maxFps` and readiness. Pin `{ tier: "low" }`; invalid tiers throw and pinned costs report. The `quality` entity and `TN_QUALITY_TIER` expose decisions; dispose on scene exit. A bounded participating medium is generated source you own: `src/render/volumetricFog.ts` and its three companions build depth-correct mist, and `STARTER_MIST` there owns this game's density, colour, bounds and its single `enabled` flag — off costs no target and no pixel. `Play` passes it the live `ctx.renderer.kind`, so the WebGL fallback allocates nothing, and it owns `scene.fog` while it lives, so aerial perspective and god rays must stay off: they render the same air. `setupPost`'s `fog` factory rebuilds it whenever the tier replaces the chain. It is lit by `ambient` until you pass `points` (unshadowed, finite-range `PointLight`s) or a `sun` whose shadow map already exists — nothing wires one for you. The shipped chain comes from `qualityPreset(tier)` and `WorldEnvironment` in `@threenative/core`. Keep this game's sky, materials, grade and effect overrides in `src/render/`; `TN_RENDER_CHAIN` reports every applied or refused stage. The neutral grade and optional film grain remain game-owned in `grade.ts` and `public/grade.cube`. Every override has a name on the same quality preset, and a missing stage observation is a failure. A scenario with no assertions or missing observations fails; open a real capture after visual changes. When a frame costs more than it should, find the object first: backtick opens the overlay, whose **Geometry** tab captures one frame on **Capture** and ranks the objects that submitted its triangles beside their projected size on screen; an agent gets the same report from `"assert": { "geometry": { "limit": 25 } }` in a scenario, which needs `runtime.geometry`. Those numbers are measured submissions reconciled against the frame's own pass totals, so the remainder the rows do not account for is reported, and what cannot be measured — a packed batch's per-member draws, unknown bounds — says so with a reason instead of reading as zero.
|
|
37
|
+
|
|
38
|
+
`src/render/temporalAA.ts` is an experimental, opt-in TRAANode provider for scene input reconstruction. Shipped quality tiers use the engine's built-in `traa` stage instead, and `debug().temporal` reports whichever one runs. Supply colour/depth/velocity from the same scene pass through a `traa` RenderChain stage, reset history on camera cuts, and dispose with the stage. The optional exact scene-pass argument enables a bounded raw4 current-footprint candidate for supported reduced rasters; it owns four-sample beauty and matching visibility replays and restores ordinary pass policy on unsupported inputs. Opaque RGB remains a pixel-frequency approximation; alpha-tested visibility uses sample interpolation. The ordinary path uses scene-pass MSAA disabled. With no weighting named it keeps history at twice the display raster with a velocity-clamped history weight (Unreal's Epic-tier TSR) and presents a display-sized resolve of it; `{ historyScale: 1, velocityWeightClamp: false }` is the named override. `temporalResolve.ts` retains optional linear/Catmull–Rom and ordinary-blend comparisons, both depth-history vetoes, and mandatory RGB clipping. Original quality/recovery, GPU cost, automatic scaling and native gates remain unqualified.
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
## One shadow for a big outdoor level
|
|
42
|
+
|
|
43
|
+
When one directional light must shadow a whole valley and a 2048² map smudges, set `sun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] })` from `@threenative/core`: camera-centred, texel-snapped clip levels, cached until the window moves and shared through Three's shadow slot. Bias, normal bias, intensity, radius, blur samples, map type and filter stay on `sun.shadow`; map sizes come from the options. Movers sort themselves: a caster whose matrix changes draws through a per-level mover map and returns to the cached levels after `staticAfterFrames` quiet frames, each change redrawing only its own region. `trackCaster(object)` pins a mover for good, `pinStatic(object)` opts an object out; call `invalidateAll()` when static geometry changes. `TN_VIRTUAL_SHADOW` reports rendered, mover-map and cached-level work.
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
## Budget real time for the look
|
|
47
|
+
|
|
48
|
+
The performance skill carries `TN_FRAME_BUDGET`, platform targets, and the `display.maxFps` rule.
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
## Optional multiplayer transport
|
|
52
|
+
|
|
53
|
+
High-tier desktop browser WebGPU adds game-owned grazing backlight (`lighting.ts`: `rimGain: 0`) and measured-dark directional fill (`fillGain: 0` or black `fillColor`). `materialLighting.ts` preserves borrowed material maps and restores originals on lower quality/exit; mobile, software, WebGL and native retain originals. `TN_ENVIRONMENT_CONTRIBUTION` reports even with overrides zero; `environmentSampling.ts` estimates actual IBL once during load; unavailable/stale samples stay unknown and disable analytic fill. Native material terms remain unqualified. One fog owner at a time: an enabled `STARTER_MIST` clears both `scene.fog` and `scene.fogNode`.
|
|
54
|
+
|
|
55
|
+
Core supplies Unreal filmic and metered defaults through `WorldEnvironment` and `qualityPreset`; this kit uses them. `shadeLikeSubstrate` in `src/render/lighting.ts` shades rough surfaces as Unreal's Substrate does (EON diffuse, no energy conservation); `material.roughDiffuse = false` opts one material out. 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.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Kit notes: tower-defense
|
|
2
|
+
|
|
3
|
+
Kit-specific facts moved out of the kit `AGENTS.md`. Shared conventions: `conventions.md`.
|
|
4
|
+
|
|
5
|
+
## Ownership
|
|
6
|
+
|
|
7
|
+
This repository owns the road, pads, enemies, towers, economy, waves, HUD, and look; `src/game.ts` is portable and React mounts only from `src/main.ts`.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Start every change
|
|
11
|
+
|
|
12
|
+
`@threenative/physics/navigation` is browser-only WASM; this kit deliberately uses an authored `PathFollow3D` route instead of a navmesh.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Commands and map
|
|
16
|
+
|
|
17
|
+
`src/balance.ts` holds every number — costs, ranges, wave rules — with no engine import; `src/waves.ts` and `src/economy.ts` are pure, so a unit test can pin them without a renderer. `src/enemies/Enemy.ts` walks the same `PathFollow3D` curve the road is drawn from; `src/towers/Tower.ts` finds targets with a jittered `intersectShape` query. Change the road and pads in `src/board/Route.ts`, the look in `src/render/`. The HUD reads `GameState` and sends intents (`arm`, `launch`, `upgrade`, `recycle`, `target`, `strike`) that `src/intents.ts` queues for the scene. Register gameplay entities with `ctx.entities`. Keep `playtests/survives.playtest.json` as smoke proof (a held key pans the camera while a wave is fought) and update the other scenarios with each rule: `defeat` is the end of the game.
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
## Budget real time for the look
|
|
21
|
+
|
|
22
|
+
The shared look comes from core through `src/render/quality.ts`; the filmic curve and metered auto exposure are enabled by default. `src/render/exposure.ts` holds this game's meter policy (`maxStops` 0.3, `minStops` -1, so the dark void keeps its depth).
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
## Optional multiplayer transport
|
|
26
|
+
|
|
27
|
+
Kit facts: `1`-`4` arm a tower and a click picks a pad, `B` builds on the best free pad, `Space` launches a wave, `U`/`X` upgrade or recycle, `F` fires the strike, `P` pauses, `H` opens the field guide, `R` restarts; right-drag, the wheel and `Q`/`E` move the camera. Four towers (Sentry, Mortar, Arc coil, Cryo) have three levels and three targeting modes, Titans arrive on waves 6 and 12, and one orbital strike recharges every 30 s. The only texture is the Poly Haven CC0 sky; every tower and enemy is built in `src/render/shapes.ts`.
|
|
@@ -125,7 +125,8 @@ atomic JSON saves also update the shared view. Invalid disk saves retain the las
|
|
|
125
125
|
valid preview and show a diagnostic; restore a valid save before submitting more
|
|
126
126
|
patches. Editor imports, workers, watchers and the document stay out of the game
|
|
127
127
|
runtime. Bake committed data before handing it to the game. The editor's GLB action and
|
|
128
|
-
`
|
|
128
|
+
`prepareWorldGLTF` from `@threenative/terrain/export` prepares the resolved world for
|
|
129
|
+
Node `cookTerrainWorld({ preparedWorld: prepared.json })` from `@threenative/assets` (terrain,
|
|
129
130
|
props, final transforms, embedded PBR maps); the root `encodeGLB` stays terrain-only. The full
|
|
130
131
|
operation list, units and patch rules ship in `node_modules/@threenative/terrain/AGENT_GUIDE.md`.
|
|
131
132
|
|
|
@@ -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 inspect hits with `engine_capability_detail`; for an existing game,
|
|
29
|
+
2. **Already installed in the engine?** For a new game, search `engine_search_capabilities` for the full request and each concrete mechanic and inspect hits with `engine_capability_detail`; 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.
|
|
@@ -6,8 +6,9 @@ description: Plan new ThreeNative games only, after kit selection plus mechanics
|
|
|
6
6
|
# ThreeNative game PRD
|
|
7
7
|
|
|
8
8
|
Use this for new games only, at step 4 of `threenative-capabilities`, after kit selection and both
|
|
9
|
-
mechanics-reference and built-in capability discovery. Existing-game changes
|
|
10
|
-
|
|
9
|
+
mechanics-reference and built-in capability discovery. Existing-game changes search per
|
|
10
|
+
change (existing-game route in `threenative-capabilities`) and keep their context; do not invoke
|
|
11
|
+
this skill to restart whole-game planning.
|
|
11
12
|
The outcome is a small, distinctive, playable plan grounded in both discovery passes.
|
|
12
13
|
|
|
13
14
|
## Plan
|
|
@@ -1,91 +1,113 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: threenative-capabilities
|
|
3
|
-
description: Route ThreeNative authoring: new
|
|
3
|
+
description: Route ThreeNative authoring: the kit AGENTS.md "Authoring flow" in detail. A new game follows kit, mechanics, built-ins, plan, assets, build, prove and report; a change to an existing game searches built-ins for each change and references for each gameplay mechanic.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# ThreeNative authoring route
|
|
7
7
|
|
|
8
|
-
This is the critical planning prerequisite for a new game and the routing entry for an
|
|
9
|
-
game.
|
|
10
|
-
|
|
8
|
+
This is the critical planning prerequisite for a new game and the routing entry for a change to an
|
|
9
|
+
existing game. The kit `AGENTS.md` "Authoring flow" lists the same eight steps with the exact calls;
|
|
10
|
+
this skill holds the detail. Classify the user's intent using the current project and plan: starter
|
|
11
|
+
code alone does not make a new-game request an existing-game change. Ask if intent is ambiguous.
|
|
11
12
|
Preserve the request's distinctive fantasy and infer concrete mechanics, not just a genre label.
|
|
12
13
|
|
|
13
|
-
**Tools.** Every server named below is in this game's `.mcp.json
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
14
|
+
**Tools.** Every server named below is in this game's `.mcp.json`. A session started in this folder
|
|
15
|
+
has them, and they can show as deferred: load them with `ToolSearch` `select:` plus the exact names,
|
|
16
|
+
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`.
|
|
17
|
+
A session started elsewhere (one that ran `create-threenative`) has none of them in its tool list:
|
|
18
|
+
run `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'` from this folder,
|
|
19
|
+
and `call.mjs <server>` lists that server's tools. A tool that is missing from your list never
|
|
20
|
+
skips its step.
|
|
18
21
|
|
|
19
22
|
## New game
|
|
20
23
|
|
|
21
|
-
Follow steps 1-8 in order; finish
|
|
22
|
-
|
|
24
|
+
Follow steps 1-8 in order; finish steps 2 and 3 before planning. Record actual results, including
|
|
25
|
+
explicit `none` with a reason; a blank result blocks plan approval. A session with no user
|
|
26
|
+
(`claude -p`, a script) records the plan and its assumptions, then continues; an interactive session
|
|
27
|
+
waits for approval. A hook blocks the first new file under `src/` until step 3 ran for the current
|
|
28
|
+
prompt (`TN_DISCOVERY_GATE=off` opts out).
|
|
23
29
|
|
|
24
|
-
1. **
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
the
|
|
30
|
+
1. **Kit** — read the user's complete request and any supplied reference image. Call
|
|
31
|
+
`engine_search_capabilities` with `scope: "request"` for the complete request: it returns the
|
|
32
|
+
matching starter kit first, with its `npx create-threenative <dir> --template <name>` command.
|
|
33
|
+
Inspect the installed `create-threenative` template `kit.json` fields and exact `--genre`
|
|
34
|
+
routing. Choose a matching kit; if no kit matches, use `minimal` (`--template minimal`). Record
|
|
35
|
+
the kit and why it fits. Keep the chosen kit's source as the starting point.
|
|
36
|
+
2. **Mechanics** — threenative-reverse-engineer is the mechanics-reference role: the
|
|
37
|
+
`threenative-engine` MCP serves it through `engine_search_references` and
|
|
30
38
|
`engine_reference_detail`. Search named games and the implied mechanics, inspect relevant
|
|
31
39
|
matches, and record pinned sources and feel rules. For Tier-2 matches, read the pinned repo
|
|
32
40
|
and use `engine_save_reference` for the nodes/cards actually walked; unavailable references
|
|
33
41
|
remain `none: references unavailable`, not fabricated matches.
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
42
|
+
A card states the numbers, never the arc. When the plan turns on how a mechanic looks moving
|
|
43
|
+
(jump arc, parry window, camera lag, hit reaction), watch a reference instead of inventing the
|
|
44
|
+
motion: `engine_watch_reference {query: "<game> <mechanic>", duration, frames}` returns a
|
|
45
|
+
`sheet.jpg` holding every frame in order; read it, then aim with `pick`, `from` and `at` when the
|
|
46
|
+
first sheet is a menu instead of gameplay. It needs `yt-dlp` and `ffmpeg`. Without the tool, fetch
|
|
47
|
+
`https://raw.githubusercontent.com/ThreeNativeHQ/threenative-reverse-engineer-mcp/main/scripts/watch.mjs`
|
|
48
|
+
and run it with `--duration 20 --frames 6`. Record the sheet path and the frame times with the
|
|
49
|
+
references. Frames are study material, not game assets: commit none of them, and cite a
|
|
50
|
+
mechanic from pinned `file:line`, never from a video. No network or no tools: record
|
|
51
|
+
`none: gameplay frames unavailable`.
|
|
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; inspect
|
|
54
|
+
hits with `engine_capability_detail`. Record installed capabilities and binding constraints. A
|
|
55
|
+
`verdict: "none"` means game-owned behavior in `src/`; do not rephrase until something matches.
|
|
56
|
+
These role names add no servers.
|
|
57
|
+
4. **Plan** — hand **Kit**, **Mechanics** and **References** to `prd-creator`. Plan the core loop
|
|
58
|
+
from both discovery passes, with controls, camera, state, acceptance checks, target platforms
|
|
59
|
+
and appearance/asset needs. With a user, get explicit approval and an instruction to implement
|
|
60
|
+
before downloads or game-source edits. Required texture selection follows the plan.
|
|
61
|
+
5. **Assets** — use threenative-asset-mcp (configured as `threenative-assets`).
|
|
62
|
+
From the mechanics matches and reference image, if provided, identify only the textures needed by the plan. Call
|
|
63
|
+
`asset_search_sources`, the returned source's search/list-files tools, then
|
|
46
64
|
`asset_download_file`; verify the returned licence and record downloaded paths/source/licence
|
|
47
65
|
in `CREDITS.md`. Follow `.agents/skills/threenative-assets/SKILL.md`; no unrelated downloads or
|
|
48
66
|
invented tool results. If no textures are required, record `none` and why. Reuse existing files.
|
|
49
|
-
6. **
|
|
67
|
+
6. **Build** — execute the plan, delegate to subagents focused on specific areas. Give each a
|
|
50
68
|
bounded task, explicit file ownership, relevant context and an acceptance check; preserve other
|
|
51
69
|
writers and avoid a single catch-all worker. The coordinator reviews and integrates the areas
|
|
52
70
|
before step 7, resolving interfaces and failures rather than trusting worker reports. Use the
|
|
53
|
-
chosen kit, discovered capabilities and downloaded textures. Keep appearance in game-owned
|
|
54
|
-
`WorldEnvironment` defaults or explicitly report named overrides.
|
|
55
|
-
no code, level layouts, character names or art; cite pinned `file:line`
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
`.agents/skills/threenative-visuals/SKILL.md` and the installed
|
|
62
|
-
`node_modules/create-threenative/agent-docs/references/dream-loop.md
|
|
63
|
-
|
|
64
|
-
image was supplied, ask for a supplied
|
|
65
|
-
as that existing contract requires; do not
|
|
66
|
-
A missing target, capture or judgment is unverified,
|
|
67
|
-
`REQUEST_CHANGES` and `NOT_OBSERVED` block completion. Fix and
|
|
71
|
+
chosen kit, discovered capabilities and downloaded textures. Keep appearance in game-owned
|
|
72
|
+
`src/render/`; use stock `WorldEnvironment` defaults or explicitly report named overrides.
|
|
73
|
+
Borrow mechanics only: no code, level layouts, character names or art; cite pinned `file:line`
|
|
74
|
+
sources.
|
|
75
|
+
7. **Prove** — follow `.agents/skills/threenative-playtest/SKILL.md`. Execute a fail-closed
|
|
76
|
+
scenario for each core mechanic with observable state, real input actions and assertions. An
|
|
77
|
+
empty assertion set or missing observation fails; a screenshot is not mechanics proof. Repair
|
|
78
|
+
failures and rerun the affected scenario. Report only platforms actually run. After mechanics
|
|
79
|
+
pass, use `.agents/skills/threenative-visuals/SKILL.md` and the installed
|
|
80
|
+
`node_modules/create-threenative/agent-docs/references/dream-loop.md` for the
|
|
81
|
+
**Reference-image visual judge**: compare a fresh, nonblank gameplay capture against the supplied
|
|
82
|
+
reference image with a fresh read-only judge. If no image was supplied, ask for a supplied
|
|
83
|
+
target or an explicitly authorized image-tool route, as that existing contract requires; do not
|
|
84
|
+
invent a target or choose a provider/model. A missing target, capture or judgment is unverified,
|
|
85
|
+
not a pass. Require `PASS`; `REQUEST_CHANGES` and `NOT_OBSERVED` block completion. Fix and
|
|
86
|
+
rejudge against the same target.
|
|
87
|
+
8. **Report** — give the user the `pnpm dev` URL, play from the spawn, and quote `TN_FRAME_BUDGET`,
|
|
88
|
+
`TN_SCENE_WARNING` and `TN_RENDER_PROJECTION`. Name every step you skipped and why.
|
|
68
89
|
|
|
69
90
|
## Existing game
|
|
70
91
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
`prd-creator` just to restart the game plan. Do not add step 8 to this route. If another binding
|
|
74
|
-
project gate conflicts, ask the user rather than silently waiving or appending it.
|
|
92
|
+
A change to an existing game skips step 1 and whole-game planning; do not invoke `prd-creator` just
|
|
93
|
+
to restart the game plan. For each change, search before you write:
|
|
75
94
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
95
|
+
- Step 3 for every change: `engine_search_capabilities` with `scope: "mechanic"`, then
|
|
96
|
+
`engine_capability_detail` on each hit, so installed systems are reused.
|
|
97
|
+
- Step 2 for each gameplay mechanic the change adds or alters: `engine_search_references`, then
|
|
98
|
+
`engine_reference_detail`; use `engine_watch_reference` when the motion is the question.
|
|
99
|
+
- Steps 5-8 for the change, using the existing game, plan and context: apply step 5 to the
|
|
100
|
+
requested change (reuse current assets and download only missing required textures), step 6
|
|
101
|
+
with the same ownership and acceptance checks (a coordinator, no catch-all worker), step 7 for
|
|
102
|
+
affected mechanics and their related regressions (keep real captures where needed to observe the
|
|
103
|
+
change), and step 8 for the change.
|
|
104
|
+
|
|
105
|
+
Ask a targeted question if essential context is missing instead of restarting discovery. If another
|
|
106
|
+
binding project gate conflicts, ask the user rather than silently waiving or appending it.
|
|
85
107
|
|
|
86
108
|
Returned capability constraints are binding, including `@threenative/physics/navigation` subpaths
|
|
87
109
|
and platform support. Use `attachToBone` for held weapons (add a portable `Bone` named `RightHand`
|
|
88
110
|
when needed) rather than rebuilding installed systems. If MCP
|
|
89
111
|
is unavailable, run `npx threenative doctor`; for a new game's capability pass, use the installed
|
|
90
112
|
`node_modules/create-threenative/agent-docs/references/capability-reference.md` and report missing
|
|
91
|
-
services honestly.
|
|
113
|
+
services honestly.
|