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
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
# Conventions every kit applies
|
|
2
|
+
|
|
3
|
+
Each convention is on by default, has a named override on the same object, and reports when it is
|
|
4
|
+
overridden. The kit `AGENTS.md` lists the ones that kit applies; this page holds the detail, one
|
|
5
|
+
anchor per registry row (`conventions.json`).
|
|
6
|
+
|
|
7
|
+
<a id="look"></a>
|
|
8
|
+
## Look
|
|
9
|
+
|
|
10
|
+
Default: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Reports: TN_WORLD_ENVIRONMENT.
|
|
11
|
+
|
|
12
|
+
The default look is `tonemapMode: "filmic"` with metered auto exposure. Lights are in lux, as in Unreal (EV100 exposure): the sun is 6 lux, and while the meter is off the fixed `exposure` is 2.4. `tonemapMode: "aces"` and `autoExposureEnabled: false` with a fixed `exposure` are the overrides. Set `tonemapMode: "aces"` to choose ACES, or `autoExposureEnabled: false` with a fixed `exposure` to choose manual exposure, on the same quality preset; the render log reports the override. The filmic curve and metered auto exposure are on by default here. Set `tonemapMode: "aces"` or `autoExposureEnabled: false` with a fixed `exposure` on the same preset to override the curve or the meter.
|
|
13
|
+
|
|
14
|
+
<a id="quality"></a>
|
|
15
|
+
## Quality tier
|
|
16
|
+
|
|
17
|
+
Default: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Reports: TN_QUALITY_TIER.
|
|
18
|
+
|
|
19
|
+
Anti-aliasing is core's: 4x MSAA on `high`, SMAA on `medium` and `low`; `temporalAA: true` is the named opt-in. `src/render/exposure.ts` is optional game policy; pass it as `exposurePolicy` in `quality.ts` to use it. `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" })`. The native production collector's explicit `--hosted-software` profile selects the existing `low` preset only when no tier override is passed; `TN_QUALITY_TIER` reports `source=hosted-software`. `high` draws 4x MSAA and `medium` and `low` SMAA; `temporalAA: true` is the named opt-in. Unknown tiers throw and `TN_QUALITY_TIER` reports the source. Quality tiers live in `src/render/quality.ts`: `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" })`.
|
|
20
|
+
|
|
21
|
+
<a id="resolution"></a>
|
|
22
|
+
## Resolution scale
|
|
23
|
+
|
|
24
|
+
Default: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Reports: TN_FRAME_BUDGET.
|
|
25
|
+
|
|
26
|
+
WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it.
|
|
27
|
+
|
|
28
|
+
<a id="frame-budget"></a>
|
|
29
|
+
## Budget real time for the look
|
|
30
|
+
|
|
31
|
+
Default: frame meter and scene verdict on. Override: `frameBudget: false`. Reports: TN_FRAME_BUDGET, TN_SCENE_WARNING.
|
|
32
|
+
|
|
33
|
+
`TN_FRAME_BUDGET` reports the actual scale under both policies. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. `performance.playtest.json` pins no frame time: the harness holds every tier to 16.7 ms p95 (60 fps) of the engine's own CPU and GPU cost (plus the frame interval on a real display), and a `TN_SCENE_WARNING` or a `TN_RENDER_PROJECTION` decline fails the run, so answer it by cutting unique geometry or materials.
|
|
34
|
+
|
|
35
|
+
<a id="aa"></a>
|
|
36
|
+
## Anti-aliasing
|
|
37
|
+
|
|
38
|
+
Default: 4x MSAA on `high`, else SMAA. Override: `temporalAA: true`.
|
|
39
|
+
|
|
40
|
+
<a id="matrix-world"></a>
|
|
41
|
+
## World-matrix walk
|
|
42
|
+
|
|
43
|
+
Default: visible subtrees only. Override: `renderer.matrixWorld: "all"`. Reports: TN_PROJECTION.
|
|
44
|
+
|
|
45
|
+
The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way.
|
|
46
|
+
|
|
47
|
+
<a id="projected-cull"></a>
|
|
48
|
+
## Projected-pixel cull
|
|
49
|
+
|
|
50
|
+
Default: under 0.5 px. Override: `minimumProjectedPixels`; `alwaysRender(obj)`. Reports: TN_RENDER_PROJECTION.
|
|
51
|
+
|
|
52
|
+
The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept.
|
|
53
|
+
|
|
54
|
+
<a id="interpolation"></a>
|
|
55
|
+
## Physics interpolation
|
|
56
|
+
|
|
57
|
+
Default: on for bodies and `ctx.camera`. Override: `physicsInterpolation: false`. Reports: TN_PHYSICS_INTERPOLATION.
|
|
58
|
+
|
|
59
|
+
Physics bodies and `ctx.camera` interpolate between fixed ticks by default; `physicsInterpolation: false` disables it globally, `body.interpolate = false` disables one body, `ctx.interpolate(object)` opts in another transform, and `ctx.resetInterpolation(object)` resets game-driven teleports (`TN_PHYSICS_INTERPOLATION` reports the setting and tracked count).
|
|
60
|
+
|
|
61
|
+
<a id="continuous"></a>
|
|
62
|
+
## Continuous collision
|
|
63
|
+
|
|
64
|
+
Default: on for `RigidBody3D`. Override: `continuousCollision: false`. Reports: body.continuousCollision.
|
|
65
|
+
|
|
66
|
+
For *"a bullet passes through a wall"*, `RigidBody3D` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
|
|
67
|
+
|
|
68
|
+
<a id="loading"></a>
|
|
69
|
+
## Loading
|
|
70
|
+
|
|
71
|
+
Default: `loadAll` keeps order; `addInSlices` attaches in 8 ms slices. Override: `concurrency`, `sliceSize`, `marker: false`. Reports: TN_LOAD_ALL.
|
|
72
|
+
|
|
73
|
+
Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement.
|
|
74
|
+
|
|
75
|
+
<a id="startup"></a>
|
|
76
|
+
## Loading curtain
|
|
77
|
+
|
|
78
|
+
Default: `ctx.startup.hold(label, () => ready)`. Override: reveal on measured readiness only.
|
|
79
|
+
|
|
80
|
+
Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step.
|
|
81
|
+
|
|
82
|
+
<a id="asset-cache"></a>
|
|
83
|
+
## Asset cache
|
|
84
|
+
|
|
85
|
+
Default: on, with idle fill. Override: `assets: { cache: false, backgroundFill: false }`. Reports: ctx.assets.cache.
|
|
86
|
+
|
|
87
|
+
Assets download on demand and stay on disk between web visits: await everything the spawn camera sees before the reveal, and `await ctx.assets.prefetch(["next-level.glb"])` before `ctx.goto` only for what is out of view (a reveal before the visible content loads shows a half-built world); the idle fill downloads the rest after the reveal. Overrides on `defineGame`'s `assets`: `cache: false`, `backgroundFill: false`, both reported on `ctx.assets.cache`; native hosts read installed files.
|
|
88
|
+
|
|
89
|
+
<a id="asset-cook"></a>
|
|
90
|
+
## Asset cook
|
|
91
|
+
|
|
92
|
+
Default: compact, shared images. Override: `compact: false`; `assets.exclude`; `assets.budget`. Reports: TN_ASSETS_CONFIG.
|
|
93
|
+
|
|
94
|
+
Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `models.compact` (default `{ flatten: true, join: true, instance: true }`) flattens the scene graph, merges primitives by material and batches a mesh shared by several nodes as `EXT_mesh_gpu_instancing` — all lossless, keeping any node matching `protectedPattern` (or named in `protectedNames`), an animation target, or a skin joint individually addressable; `compact: false` ships the scene graph as authored. `models: "none"` / `textures: "none"` / `audio: "none"` skip those passes and report uncooked bytes. `assets.exclude` defaults to `[]`; source-relative globs (for example `["unused/**"]`) omit matching files and report 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 toward `uncooked`. Automatic texture cooking retains unaligned source images unchanged and reports `block-size`; those bytes still count toward the uncooked budget. Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
|
|
95
|
+
|
|
96
|
+
<a id="animation-rate"></a>
|
|
97
|
+
## Animation rate
|
|
98
|
+
|
|
99
|
+
Default: `updateRate: "auto"`. Override: `updateRate: 1`. Reports: updateRateReport.
|
|
100
|
+
|
|
101
|
+
`updateRate: "auto"` is the default and follows measured camera policy; `updateRate: 1` is full evaluation, another positive safe integer names a frame interval, and `updateRateReport` shows the effective rate, override status and latest evaluation; one-shots/fades, public mixer listeners/speed overrides, root-motion `AnimationComposer`, automatic camera-ray targets and camera-parented rigs stay full-rate.
|
|
102
|
+
|
|
103
|
+
<a id="stride-sync"></a>
|
|
104
|
+
## Stride sync
|
|
105
|
+
|
|
106
|
+
Default: on. Override: `strideSync: false`.
|
|
107
|
+
|
|
108
|
+
<a id="ground-snap"></a>
|
|
109
|
+
## Feet on the floor
|
|
110
|
+
|
|
111
|
+
Default: `GroundSnap`. Override: `enabled: false`.
|
|
112
|
+
|
|
113
|
+
Generated conventions call `GroundSnap` for floor contact and `normaliseToMetres` for authored model scale.
|
|
114
|
+
|
|
115
|
+
<a id="attach"></a>
|
|
116
|
+
## Held prop
|
|
117
|
+
|
|
118
|
+
Default: `attachToBone`. Override: a portable `Bone` named `RightHand`.
|
|
119
|
+
|
|
120
|
+
<a id="scale"></a>
|
|
121
|
+
## One metre is one metre
|
|
122
|
+
|
|
123
|
+
Default: `normaliseToMetres`. Override: per-call options.
|
|
124
|
+
|
|
125
|
+
<a id="rigged"></a>
|
|
126
|
+
## Rigged assets
|
|
127
|
+
|
|
128
|
+
Default: `.glb` in `assets/`; `AnimationPlayer` drives clips. Override: `ctx.assets.model("hero.glb")` in `Scene.load()`.
|
|
129
|
+
|
|
130
|
+
Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity.
|
|
131
|
+
|
|
132
|
+
<a id="clip-conformance"></a>
|
|
133
|
+
## Clip conformance
|
|
134
|
+
|
|
135
|
+
Default: measure a clip before rewriting it. Override: `clipPoseError`; `clipTrackBindings`; `clipBoneCoverage`. Reports: boneContact.
|
|
136
|
+
|
|
137
|
+
`clipPoseError` scores a retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing (the `<bone>.undefined` failure that plays the bind pose instead of the animation), `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is supposed to be touching.
|
|
138
|
+
|
|
139
|
+
<a id="rough-diffuse"></a>
|
|
140
|
+
## Rough diffuse
|
|
141
|
+
|
|
142
|
+
Default: on. Override: `material.roughDiffuse = false`.
|
|
143
|
+
|
|
144
|
+
<a id="unlit-foliage"></a>
|
|
145
|
+
## Unlit foliage
|
|
146
|
+
|
|
147
|
+
Default: warns. Override: `material.userData.tnUnlitOk = true`. Reports: TN_UNLIT_FOLIAGE.
|
|
148
|
+
|
|
149
|
+
Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `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. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the scene's environment light — 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.
|
|
150
|
+
|
|
151
|
+
<a id="backlight"></a>
|
|
152
|
+
## Material backlight
|
|
153
|
+
|
|
154
|
+
Default: none, as in stock Unreal. Override: `rimGain`; `fillGain`.
|
|
155
|
+
|
|
156
|
+
Material backlighting lives in `src/render/lighting.ts`: named `rimGain` and `fillGain` controls preserve the authored palette; `materialLighting.ts` reports `TN_ENVIRONMENT_CONTRIBUTION`.
|
|
157
|
+
|
|
158
|
+
<a id="env-contribution"></a>
|
|
159
|
+
## Environment contribution
|
|
160
|
+
|
|
161
|
+
Default: reported even at zero. Override: `environmentSampling`. Reports: TN_ENVIRONMENT_CONTRIBUTION.
|
|
162
|
+
|
|
163
|
+
<a id="shadows"></a>
|
|
164
|
+
## Shadows
|
|
165
|
+
|
|
166
|
+
Default: soft by source radius. Override: `penumbraScale`; `VirtualShadowNode` options. Reports: TN_SHADOW_TIER.
|
|
167
|
+
|
|
168
|
+
<a id="pointer-look"></a>
|
|
169
|
+
## Pointer look
|
|
170
|
+
|
|
171
|
+
Default: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
|
|
172
|
+
|
|
173
|
+
Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out.
|
|
174
|
+
|
|
175
|
+
<a id="static"></a>
|
|
176
|
+
## Static scenery
|
|
177
|
+
|
|
178
|
+
Default: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Reports: TN_RENDERLIST_VALIDATE.
|
|
179
|
+
|
|
180
|
+
So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
|
|
181
|
+
|
|
182
|
+
<a id="spans"></a>
|
|
183
|
+
## Frame spans
|
|
184
|
+
|
|
185
|
+
Default: off. Override: `TN_FRAME_SPANS=1`. Reports: TN_FRAME_SPANS.
|
|
186
|
+
|
|
187
|
+
`npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it on screen (it draws the verdict alone — no frame rate, which reads throttled under a compositor or a virtual display; see `agent-docs/references/performance-basics.md`); `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds.
|
|
188
|
+
|
|
189
|
+
<a id="spells"></a>
|
|
190
|
+
## Spells
|
|
191
|
+
|
|
192
|
+
Default: every factory ships a stock look. Override: per-call options on `@threenative/core/spells`.
|
|
193
|
+
|
|
194
|
+
<a id="net"></a>
|
|
195
|
+
## Multiplayer
|
|
196
|
+
|
|
197
|
+
Default: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Reports: TN_NET_UNAVAILABLE.
|
|
198
|
+
|
|
199
|
+
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`.
|
|
200
|
+
|
|
201
|
+
<a id="desktop-mode"></a>
|
|
202
|
+
## Desktop window
|
|
203
|
+
|
|
204
|
+
Default: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
|
|
205
|
+
|
|
206
|
+
Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window.
|
|
207
|
+
|
|
208
|
+
<a id="terrain"></a>
|
|
209
|
+
## Terrain
|
|
210
|
+
|
|
211
|
+
Default: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
|
|
212
|
+
|
|
213
|
+
For terrain generation or editing, read `node_modules/create-threenative/agent-docs/references/terrain-authoring.md`; install optional `@threenative/terrain`, bake before play, and own its appearance in `src/render/`; test water proximity with its `createSegmentIndex` and steep ground with `slopeQuantile`, never a per-point scan or fixed degrees.
|
|
214
|
+
|
|
215
|
+
<a id="navigation"></a>
|
|
216
|
+
## Navigation
|
|
217
|
+
|
|
218
|
+
Default: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
|
|
219
|
+
|
|
220
|
+
This kit needs no navmesh and imports none, so it runs on every target; adding `@threenative/physics/navigation` would make it web and desktop only.
|
|
221
|
+
|
|
222
|
+
<a id="move-axis"></a>
|
|
223
|
+
## Move input
|
|
224
|
+
|
|
225
|
+
Default: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
|
|
226
|
+
|
|
227
|
+
`input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion.
|
|
228
|
+
|
|
229
|
+
<a id="scene-change"></a>
|
|
230
|
+
## Scene change
|
|
231
|
+
|
|
232
|
+
Default: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
|
|
233
|
+
|
|
234
|
+
`ctx.goto(name)` rebuilds without resetting game state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })` is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's state.
|
|
235
|
+
|
|
236
|
+
<a id="seed"></a>
|
|
237
|
+
## Randomness
|
|
238
|
+
|
|
239
|
+
Default: unseeded. Override: `defineGame({ seed })`.
|
|
240
|
+
|
|
241
|
+
Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
|
|
242
|
+
|
|
243
|
+
<a id="engine"></a>
|
|
244
|
+
## Engine
|
|
245
|
+
|
|
246
|
+
Default: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Reports: TN_NATIVE_ENGINE_UNBOUND.
|
|
247
|
+
|
|
248
|
+
Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. `engine: "threejs"` switches to upstream Three.js only when the user asks for it; it is never a fix for a build error.
|
|
249
|
+
|
|
250
|
+
<a id="general"></a>
|
|
251
|
+
## Other portable contracts
|
|
252
|
+
|
|
253
|
+
### Ownership
|
|
254
|
+
|
|
255
|
+
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge.
|
|
256
|
+
|
|
257
|
+
### Workflow skills
|
|
258
|
+
|
|
259
|
+
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. A native build names each unbound import with `TN_NATIVE_ENGINE_UNBOUND`. Android and iOS use the legacy host. This template runs on it: `threenative.config.ts` names no `engine`.
|
|
260
|
+
|
|
261
|
+
### Portable authoring contracts
|
|
262
|
+
|
|
263
|
+
Android/iOS currently skip compression and model dedupe. A number sets that ceiling; `"none"` disables both gates. Either disabled gate still reports bytes. An explicit compression codec override must satisfy four-pixel block alignment; `codec: "none"` opts out. Cooking never silently resizes an image to fix alignment. Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable. That smoke tier is not physical performance evidence and does not change an ordinary desktop run. Unknown tiers throw. Keep state values human-readable; the bridge flushes about 100 ms and per-frame feel stays in scene-owned Three.js. When an animation looks wrong, measure it before rewriting it. Scenes use `load`, `enter`, `update`, `exit`, `render`.
|
|
264
|
+
|
|
265
|
+
### Budget real time for the look
|
|
266
|
+
|
|
267
|
+
It has Unreal's bloom with no threshold (`unrealBloomEnabled`), local exposure (`localExposureEnabled`, off on `low`), a cosine-fourth vignette (`vignetteAmount: 0.4`) and no camera motion blur (`motionBlurEnabled: true` is the opt-in). The grade is neutral and the frame has no film grain. Each stage has a named override: `unrealBloomEnabled: false` returns to Three's `BloomNode` (`bloomStrength`, `bloomRadius`, `bloomThreshold`), and `vignetteAmount: 0` removes the vignette. For a colour grade or grain, add the starter's `grade.ts` and `public/grade.cube`, then set `gradeIntensity` and `grainIntensity`. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`. Open a capture after visual changes. A scenario with no assertions or missing observations fails. Edit `src/render/` directly; `postprocessing.ts` reports stages but decides no game colour. A scenario with no assertions or missing observations fails; open a real capture.
|
|
268
|
+
|
|
269
|
+
### Optional multiplayer transport
|
|
270
|
+
|
|
271
|
+
Admission is limited to high hardware desktop WebGPU; mobile/software/WebGL/native retain original materials. Existing authored fill stays authoritative. 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. Core supplies Unreal filmic and metered defaults through `WorldEnvironment` and `qualityPreset`.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Kit notes: action-rpg
|
|
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 dungeon, combat, stats, inventory, persistence, and every visual decision; `src/game.ts` stays portable and `src/main.ts` is the web-only React mount.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Start every change
|
|
11
|
+
|
|
12
|
+
`@threenative/physics/navigation` is a browser-only WASM boundary here; use returned subpaths, and `attachToBone` for the blade in `hand_r`. Spells: keys cast `@threenative/core/spells` factories (`createFireball`, `createThunderstrike`, `createGlacialSpike`) through one `SpellWorld` and a `CastPool`; update both each frame. Change a spell only through the named overrides on its factory call. Damage, mana, cooldowns and targets stay in the game: read `cast.pos` and `cast.phase`. `reducedFlashes` caps flashes (WCAG 2.3.1).
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Workflow skills
|
|
16
|
+
|
|
17
|
+
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.
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
## Commands and map
|
|
21
|
+
|
|
22
|
+
Controls: WASD/arrows move; Space/F attacks; E casts Arcane Surge; Shift rolls; Q/U equips or unequips; P/L tests inventory; T defeats the visible enemy; C/R checkpoints; H/X damage or defeat. Three rooms lead through two doorways to a boss win or zero-health loss. `StatBlock.ts` and `Inventory.ts` are game-owned; use `intersectShape` for range, `intersectRay` for line of sight.
|
|
23
|
+
|
|
24
|
+
Every figure is `assets/mannequin-combat.glb` — hero, raiders and boss alike — instanced through `SkeletalMesh3D` in `src/entities/Fighter.ts`: `requiredClips` fails the load by name, `normaliseToMetres(model, { axis: "height", metres: 1.545 })` puts the `Head` joint where a 1.8 m capsule expects it, hostiles are the same rig in a red-orange material, and the boss the same rig at 1.3x. Actions play the file's own clips — `Sword_Attack`, `Spell_Simple_Shoot`, `Punch_Jab`, `Hit_Chest`, `Death01`, `PickUp_Table`, `Roll` — and a corpse keeps its entity registered so its death clip finishes. `src/scenes/Play.ts` wires the loop and hands each room `Group` from `src/render/dungeon.ts` to `buildStaticColliders`; `src/entities/` owns gameplay, `src/render/` the look, `src/ui/` React, and `state.ts` publishes JSON-safe health, room and inventory. Keep `playtests/survives.playtest.json` as the smoke proof and update the other scenarios with gameplay. The state bridge flushes about 100 ms, so per-frame feedback stays in scene-owned Three.js.
|
|
25
|
+
|
|
26
|
+
On a touch-primary device, `src/render/touch-controls.ts` adds a left movement stick, attack and Arcane Surge buttons; keyboard controls remain available on desktop.
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
## Portable authoring contracts
|
|
30
|
+
|
|
31
|
+
Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable; generated conventions call `GroundSnap` for floor contact, `normaliseToMetres` for authored model scale, and `attachToBone` for held props. Register testable entities with `ctx.entities`; `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, instance with `SkeletalMesh3D` to clone safely and validate clips, then call `character.update(dt)` from the owning scene's `update(dt)`. `attachToBone` re-parents a game-owned mesh to a named joint, so the hand moves the sword in every clip for free; the model faces +Z, so `facingVector` is `(sin, 0, cos)` of `figure.rotation.y`. `game.goto("<scene-name>")` also rebuilds the scene, but resets the game's state.
|
|
32
|
+
|
|
33
|
+
`AnimationPlayer` re-times a looping clip to the ground the body covers so feet do not skate — in-place clips too, off a planted foot; a speed past what the clip carries is **clamped at 3x**, so set it near `player.stride.clipGroundSpeed`. `strideSync: false` opts out, `maxFootSlide` bounds it. `clipPoseError` scores a retarget against its source per bone in degrees — whole quaternions relative to each rig's bind pose, so bind conventions cancel and an axis-rolled limb is caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing (`<bone>.undefined`, which plays the bind pose), `clipBoneCoverage` names bones the clip does not drive, which keep the previous clip's pose, and `boneContact` reports in metres whether a bone reaches its prop.
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
## Budget real time for the look
|
|
37
|
+
|
|
38
|
+
`src/render/` is yours to edit and is where the base look lives: the prototype test scene, a metre grid in world UVs over a light floor and a dark structure, `palette.ts`'s five roles with exactly one saturated `accent` for anything you can touch, Unreal's default sky behind everything (`sky.ts`; `SKY_OPTIONS` takes `sky: "photo"` for the photograph), and bevelled `RoundedBoxGeometry` sunk by its bevel radius. Torch point lights are the only warm light. `quality.ts` defines `low`, `medium`, and `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`, and `setupPost(..., { tier: "low" })` is the named override — unknown tiers throw and `TN_QUALITY_TIER` reports the source. The shared look comes from core through `src/render/quality.ts`, and `neutralLook` there names this kit's overrides: ACES at a fixed `exposure` of `0.62 * Math.PI` (0.62 was picked under a 6 x pi sun) with the kit's bloom and occlusion, the neutral look the owner chose over core's filmic curve and metered exposure (delete a line to take core's value back). `src/render/exposure.ts` holds this game's meter policy (`maxStops` 0.3, `minStops` -2, so shaded walls keep their depth). The preset also names one cost override, `finalGatherMethod: "none"` with `ssgiEnabled: false` and `ssrEnabled: false`, because the volumetric atmosphere already owns the frame (the render log reports it as `TN_RENDER_CHAIN_COST_OVERRIDE`). Set `tonemapMode: "aces"` to choose ACES, or `autoExposureEnabled: false` with a fixed `exposure` to choose manual exposure, on the same quality preset. VFX appearance belongs in `src/render/vfx.ts`: keep its TSL material, geometry, colour, blend, curves, timing and capacity there; gameplay creates `GPUParticles3D` once, adds it with `ctx.add`, and calls `emitParticle({ count, origin })` from the real attack, hit or Arcane Surge path. A burst gets its own world-space ring slots, so an older burst keeps flying; `process` reads age from `buffers.births`. An emitter the camera cannot see for a second pauses by default: it stops simulating and drawing, and a burst that expires meanwhile stays gone. `onCull` in `vfx.ts` also takes `"clear"` (restart on return); `graceSeconds: Infinity` disables the cull for one emitter.
|
|
39
|
+
|
|
40
|
+
A scenario with no assertions or missing observations fails; keep the durable smoke proof and open a capture.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Kit notes: adventure
|
|
2
|
+
|
|
3
|
+
Kit-specific facts moved out of the kit `AGENTS.md`. Shared conventions: `conventions.md`.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
Lantern Vale: Wren, a lantern-bearer, takes the Ember Blade from a chest in a walled clearing, then clears the Moss Hollow — a three-room dungeon with a push-block puzzle, a small key, a locked door and the Stone Warden, a boss that is only hurt while dazed. Mosslings hop and bite, Flicker bats circle and swoop, and Thornbacks show a thorned plate that only a cut from behind gets round. Lock-on targeting, a sword slash, a shield, a roll, half-hearts and a heart vessel. Every model is procedural, with no mesh file; five shared tiling photos (`src/render/surface.ts`, licences in `assets/tex-PROVENANCE.md`) give the floor, stone, bark and planks their grain, so a wooden, stone or bark mesh takes `surfaced(color, surface)`, not plain `lit()` (`survives` fails on one: `untexturedSurfaces`); Wren's idle, walk and run are `AnimationClip`s built in code.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Ownership
|
|
11
|
+
|
|
12
|
+
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, the state bridge and the default look. This repository owns the clearing and the dungeon, Wren's feel, the lock-on, the hostiles, the puzzle, the HUD and every model; `src/game.ts` is portable and React mounts from `src/main.ts`.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Start every change
|
|
16
|
+
|
|
17
|
+
`@threenative/physics/navigation` is Recast WASM that Android and iOS refuse, so this kit does not import it: a Mossling steers with a ray to Wren and slides along the wall that ray hits (`src/entities/Mossling.ts`). Keep new hostiles on direct physics queries (`intersectRay`, `intersectShape`, `Area3D`).
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
## Commands and map
|
|
21
|
+
|
|
22
|
+
Status: the web target is proven by `pnpm test`, which runs every `playtests/*.playtest.json` in a WebGPU browser. Desktop is claimed only where `native-playtests/survives.playtest.json` ran with `--target desktop`; Android and iOS have not been run for this kit.
|
|
23
|
+
|
|
24
|
+
`src/entities/Hero.ts` owns Wren — `ADVENTURE_FEEL` is the one table of feel constants, and `playtests/move.playtest.json` proves run speed, stop time and turn time against it. `LockOn.ts` picks and holds a target, `Mossling.ts`, `Flicker.ts`, `Thornback.ts`, `Warden.ts` and `Dummy.ts` are the targets (each hostile telegraphs before it strikes), `Block.ts` and `Switch.ts` are the puzzle, `Door.ts` and `Chest.ts` the passages and the loot; `src/interact.ts` is the one `interact` prompt picker; `src/level/Vale.ts` and `Hollow.ts` build the places and tag the solid meshes; `valeHeight(x, z)` in `Vale.ts` is the vale's one ground (banks, outcrops, a stream bed and a rise to the dungeon, the arena and the play spaces kept level), so place every entity, pickup and `setup.place` through it, and ground steeper than 45° is rock Wren cannot climb; `src/scenes/Play.ts` wires them; `src/render/` is ordinary Three.js and every model in the game (`foliage.ts` is the vale's instanced planting, its floor and the canopy's shade, never solid; `effects.ts` the embers, sparks, fireflies and the companion's trail `Play.ts` fires through four pooled `GPUParticles3D` emitters; `props.ts` the hut, the signs, the pitcher lantern and the companion orb); `src/ui/Hud.tsx` is the one HUD (hearts in halves, keys, the prompt). The camera and the sun are written in `afterPhysics`, never in the scene's frame function, because `moveAndSlide` only queues motion. Keep `playtests/survives.playtest.json` as smoke proof and `touch-controls.ts` aligned with the input map in `src/game.ts`. Collision is the engine's, from your geometry: `buildStaticColliders(ctx, root, { predicate: isSolid })` turns the tagged meshes into fixed trimesh bodies. A `CollisionShape3D` capsule is centred on the body's origin, so the origin is Wren's waist and her rig is pushed down by `halfHeight + radius`; forget that and she floats a body-length above every floor. Entities a scenario places (`player`, `mossling.N`, `flicker.N`, `thornback.N`, `dummy.N`, `warden`, `block`, `chest.sword`, `chest.key`) are registered in `load()`, because `setup.place` runs before `enter()`.
|
|
25
|
+
|
|
26
|
+
Play gates: `playtests/explore.playtest.json` drives 7200 ticks of seeded random input and fails on any page error; `controls.playtest.json` presses each control the HUD shows, from the spawn, and fails when one changes nothing; `look.playtest.json` fails when mouse motion does not turn `camera.main`; `stride.playtest.json` bounds `footSlip` (`maxSlip` and `maxSlideSpeed: 1`, 1 m/s) on the sole nodes `footL`/`footR`, so the run cycle must follow ground speed: limbs use AnimationPlayer clips with strideRoot, never a timer. A new key binding joins `explore`'s `move` or `actions` and the `controls` scenario in the same change; a mouse button joins `controls` as a `pointerPosition` (`buttons` 1 left, 2 right, 4 middle), because `explore` presses keys only. Controls are the PC scheme: click slash, right-click (hold) shield, Tab or middle click lock on (again: next target, then off), space roll or hop, E open, WASD move, mouse look; J, Shift and Q (hold) stay as secondary keys the HUD omits. The left click is its own input name, `slash`, because the first click only captures the pointer (`look` is `pointerRelative`): `readHeroInput` counts it only when the pointer was already captured on the step before. Mouse look turns the camera by `input.vector("look").x` once captured; the camera never swings back by itself, so there is no auto swing to pause, and while a target is locked its framing owns the view and the mouse is ignored. The slash needs the Ember Blade, so `controls` opens the chest first and the HUD says so until Wren has it.
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
## Portable authoring contracts
|
|
30
|
+
|
|
31
|
+
No model here is imported, so there is no authored scale to normalise and the collider is the body: the generated scale-and-snap conventions do not apply. A weapon stays in the hand that holds it: the Ember Blade rides the rig's `RightHand` bone through `attachToBone` in `src/entities/Hero.ts`; parent any new prop the same way.
|
|
32
|
+
|
|
33
|
+
No material backlighting ships: as in a stock Unreal scene, the sun, the sky light, the torches and each material's own colour are the whole light. The look is the engine's default: `src/render/postprocessing.ts` builds `new WorldEnvironment({ ...qualityPreset(tier), ...overrides })` from `@threenative/core`, which is the stock Unreal 5.8.3 look — the filmic tone curve, metered auto exposure, bloom, ambient occlusion and 4x MSAA. `TN_RENDER_CHAIN` reports what ran. To change it, add an override on that object (`tonemapMode: "aces"`, or `autoExposureEnabled: false` with a fixed `exposure`) in `quality.ts`; do not vendor the chain. `src/render/sky.ts` builds the gradient background and its environment light from `palette.ts`, the height mist on `scene.fogNode` and the sun shafts (soft additive tubes, because the core `godRays` stage does not run on the owned engine yet); `SUN_DIRECTION` aims `lighting.ts`'s sun, and `setIndoors` drops the sky light under the Hollow's roof so the torches carry the rooms.
|
|
34
|
+
|
|
35
|
+
Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order**, and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement.
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
## Budget real time for the look
|
|
39
|
+
|
|
40
|
+
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 and the `DEV_MODE=true` chip shows it on screen; `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. Do not touch a transform you do not need to: three skips the per-object binding update when nothing changed. `markStatic(root)` composes a never-moving subtree once, and `invalidateStatic(object)` announces a write inside one. Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Kit notes: collectathon
|
|
2
|
+
|
|
3
|
+
Kit-specific facts moved out of the kit `AGENTS.md`. Shared conventions: `conventions.md`.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
Pip, a stout sprout-keeper in a teal knit beanie and a belted mustard tunic, roams one free island for three Sunseeds: reach the summit, collect the eight red gems, climb the wall-kick shaft. The moveset is a 3D platformer's: run, single, double and triple jump, crouch, back flip, side flip, long jump, wall kick, ledge grab, dive and ground pound, with an eight-wedge health meter, coins that heal, and three kinds of walker. Every model and animation is procedural — no mesh or clip file. The tiling surfaces (grass, sand, rock, stone, bark, planks) are generated WebP images in `assets/` (`tex-*.webp`, shared by the kits and copied when a source names the file), each traced in `tex-PROVENANCE.md`; keep `assets/` at most 1.5 MB (the scaffold spec checks both), load textures in `Scene.load()` through `loadSurfaces(ctx.assets)` in `src/render/surface.ts`, and never sample a tile plainly: `stochastic`, `macro` and `triplanar` there hide its repeat. Paint a one-off texture in code with `paintedTexture` in `src/render/materials.ts`.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Ownership
|
|
11
|
+
|
|
12
|
+
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, the state bridge, and the look's render chain (`WorldEnvironment` from `@threenative/core`: the filmic tone curve and metered auto exposure). This repository owns the course, the hero's feel, the walkers, the pickups, the HUD, the camera, and the scene's own sky, sun and materials; `src/game.ts` is portable and React mounts from `src/main.ts`.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Start every change
|
|
16
|
+
|
|
17
|
+
`@threenative/physics/navigation` is browser-only WASM, and this course needs no navigation: walkers chase in a straight line inside a leash, and the course is authored geometry, so the hero collides with exactly the triangles it sees and desktop/native stays honest.
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
## Commands and map
|
|
21
|
+
|
|
22
|
+
`src/entities/Hero.ts` owns the moveset: one action state machine on a `CharacterBody3D` and `HERO_FEEL`, the one table of metres and seconds (run cap 9.6 m/s, jumps 12.6 / 15.6 / 20.7 m/s up, 0.3 s chain window with a 0.12 s press buffer, one air double jump per flight at 12.6 m/s from a second press 0.1 s after take-off, 0.167 s wall-kick window that a press up to 0.12 s before the bonk also reaches (a press at a wall is a kick, never the air double), long jump ×1.5 at half gravity, ledge band 1.0–1.6 m above the feet, found by wall rays 0.3 m and 1.5 m above them) the course is laid out from — change a number there and a gap in `src/level/Course.ts` changes its meaning. The stick is camera-relative. The wall and the ledge are found with `ctx.physics.directSpaceState.intersectRay` against the static world's layer (`WORLD_LAYER`), because `moveAndSlide` reports the floor and not the wall. `Walker.ts` is the three enemy kinds, each with a telegraph before it attacks: a bumblet chaser, a hopper that crouches then hops, and a thornback that rears then charges (a stomp, a dive or a ground pound defeats a bumblet or a hopper; a thornback's spikes hurt a stomp, so only a dive or a pound beats it; a touch costs a wedge), `Pickup.ts` a coin, red gem or Sunseed; `src/scenes/Play.ts` registers every placeable entity in `load()` so a scenario's `setup.place` reaches it, then owns wedges, Sunseeds, checkpoints and the kill plane; `src/render/` is ordinary Three.js and every model in the game, `src/level/terrain.ts` shapes the island (hills, cliffs, the castle plateau) on core's `Heightfield` and keeps every route and level zone at y = 0, so place things with `course.ground(x, z)`, never a fixed height; `src/render/ground.ts` writes the blend weights `surface.ts` paints it with (grass, path sand, rock by slope), `src/render/castle.ts` is the castle and the signpost, `src/render/water.ts` the sea (tinted by a baked depth map of the island, its swell core's `WaveField` from `Course.ts`), `src/render/foliage.ts` the instanced planting, meadow and pebbles (never solid; `course.meadow.update(camera.position)` thins far grass each frame, `GRASS_SHARE` in `quality.ts` sets the share per tier), and `playtests/survives.playtest.json` asserts the relief, slope shares, castle, grass, pebbles and signpost; `src/render/effects.ts` is every particle look (the dust, flash, pollen and sparkle emitters and the `BURSTS` table), and `Play.ts` fires them through four pooled `GPUParticles3D` spawn emitters, proven by `playtests/effects.playtest.json`; `src/ui/Hud.tsx` is the one HUD. The orbit camera (`src/render/camera.ts`, turned by the mouse once a click takes the pointer lock, proven by `playtests/look.playtest.json`) and the sun are written in `afterPhysics`, never in the scene's frame function, because `moveAndSlide` only queues motion; the camera pulls in front of any wall on a ray the scene passes it, and when a wall boxes it in it cuts to the clearest side, never steeper than 35°. The orbiting platform is a kinematic `RigidBody3D` the scene moves by its mesh: the engine carries a character standing on it, so there is no carry code here. Keep `playtests/survives.playtest.json` as smoke proof and `touch-controls.ts`/`touch-layout.ts` aligned with the native playtest; `playtests/` holds one scenario per move (`jump-chain`, `double-tap`, `double-tap-air`, `acrobatics`, `wall-kick`, `ledge`, `ledge-angle`, `ledge-too-high`) and per rule (`collect`, `combat`, `enemies`, `thornback`, `telegraphs`, `camera`). Collision is the engine's, from your geometry: `buildStaticColliders(ctx, course.group, { predicate: (object) => object.userData.solid === true, reachableCeiling: 40 })` turns the tagged walkable meshes into fixed trimesh bodies; the raised ceiling keeps the 16 m shaft walls solid. A `CollisionShape3D` capsule is centred on the body's origin, so the origin is the hero's waist and its rig is pushed down by `halfHeight + radius`; forget that and the hero floats a body-length above every surface.
|
|
23
|
+
|
|
24
|
+
Play gates: `playtests/explore.playtest.json` drives 7200 ticks of seeded random input and fails on any page error; `look.playtest.json` fails when mouse motion does not turn `camera.main`. A procedural rig bounds its feet with `footSlip` on sole nodes named `footL`/`footR`: `maxSlideSpeed: 1` fails a planted sole that slides faster than 1 m/s, and unnamed soles fail closed. A new key binding joins `explore`'s `move` or `actions` in the same change.
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
## Portable authoring contracts
|
|
28
|
+
|
|
29
|
+
Leave `assets` absent: this kit ships no authored model, texture or sound, so the cook has nothing to do. Before adding one, read `node_modules/create-threenative/agent-docs/references/finding-assets.md`; the cook's passes, `assets.exclude` globs and `assets.budget` ceilings count bytes left uncooked and are reported either way.
|
|
30
|
+
|
|
31
|
+
No model here is imported, so there is no authored scale to normalise and the collider is the body: the generated scale-and-snap conventions do not apply to this template.
|
|
32
|
+
|
|
33
|
+
`src/render/sky.ts` builds the sky (gradient, sun halo, seeded cumulus) from `palette.ts` and uses it as both background and environment light, and `SUN_DIRECTION` aims `lighting.ts`'s one authored sun. No material backlighting ships: as in a stock Unreal scene, the sun, the sky light and each material's own colour are the whole light. The look's chain is core's, not vendored: `src/render/postprocessing.ts` calls `new WorldEnvironment(qualityPreset(tier))`, and `qualityPreset` in `src/render/quality.ts` is the `@threenative/core` preset plus this game's overrides, each with its reason — it starts empty, so the game gets the stock Unreal 5.8.3 look (`TN_WORLD_ENVIRONMENT` reports the filmic curve and `TN_AUTO_EXPOSURE` the meter), metered at 0 EV by the starter kits' shared `src/render/kitExposure.ts`. Pin `tonemapMode: "aces"`, or `autoExposureEnabled: false` with a fixed `exposure`, there and only there, and say why.
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
## Budget real time for the look
|
|
37
|
+
|
|
38
|
+
Recipes are installed with the scaffold, under `node_modules/create-threenative/agent-docs/references/`: `assertion-reference`, `build-profiles`, `capability-reference`, `capture-the-frame`, `creating-creatures`, `ctx-cookbook`, `debug-surface`, `finding-assets`, `gameplay-recipes`, `menu-screens`, `mobile-memory-budget`, `performance-basics`, `rigging-characters`, `sculpt-from-a-reference`, `trace-a-slow-frame`, `visual-baseline` and `webview-ui` (`.md`).
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Kit notes: kart
|
|
2
|
+
|
|
3
|
+
Kit-specific facts moved out of the kit `AGENTS.md`. Shared conventions: `conventions.md`.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
Eight toy karts race three laps of Clover Cup, a figure-8 course with a bridge over its own underpass, a creek, a kicker jump and four boost pads. The feel is a 1990s kart racer's: a throttle that ramps, a hop that turns into a power-slide, wiggles against the slide that charge a mini-turbo through three spark colours, grass at x0.70 speed, walls that bounce, item boxes with a roulette weighted by place (burr, acorn, nitro can), seven CPU drivers on a rubber band, a 3-2-1 countdown with a rocket start, a minimap and a finish screen. Every model and texture is procedural — no mesh, image or animation file: keep `assets/` absent (the scaffold spec checks it) and build every look in code in `src/render/`.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Ownership
|
|
11
|
+
|
|
12
|
+
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, the state bridge, the particle and shadow systems (`GPUParticles3D`, the renderer's shadow map), and the look's render chain (`WorldEnvironment` from `@threenative/core`: the filmic tone curve and metered auto exposure). This repository owns the course, the kart's feel, the CPU drivers, the items, the race rules, the HUD, the chase camera, and the scene's own sky, sun and materials; `src/game.ts` is portable and React mounts from `src/main.ts`. `ctx.camera` interpolates between fixed ticks by default; `ctx.interpolate(object)` opts in another transform and `ctx.resetInterpolation(object)` resets a game-driven teleport.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Start every change
|
|
16
|
+
|
|
17
|
+
This kit carries no physics package: a kart lives in track space (a place along the course's centre line plus metres right of it), so walls, surfaces, jumps and the lap counter are plain arithmetic on `src/track/Course.ts` and run the same on every target. `@threenative/physics/navigation` is browser-only WASM and the CPUs need none: they follow the centre line on a lane.
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
## Commands and map
|
|
21
|
+
|
|
22
|
+
`src/entities/Kart.ts` owns the feel: `KART_FEEL` is the one table of metres, seconds and ticks (24 m/s 150cc top speed, a throttle that gains less in each tenth of its range, the 0.35 m hop, the 28% drift floor, mini-turbo stages, 80-tick pad and nitro boosts, grass and water drag), each value cited to the MK64 decompilation it was read from; change a number there and the course's pads, jump and walls change their meaning. `Kart.step(input, dt)` is the whole model and reads the same `IKartInput` from the keyboard, the touch layout or a `Driver` (`src/entities/Driver.ts`, the CPU and the player's autopilot on `KeyP`: a look-ahead point on a lane, a lift in tight corners, a power-slide through long bends, the rubber band's `catchingUp` and `coasting`). `src/track/Course.ts` builds the closed centre line one sample per metre, the surfaces by lateral offset, the 11 m walls, the bridge, the jump, the pads, the boxes and the checkpoints; read the road height with `course.heightAt(index, x, z)`, never a fixed y. `src/track/Race.ts` is the lap rule (lap −1 on the grid, a lap only after every checkpoint in order, a backwards crossing takes it back, the −3..+6 index window) and the ranking; `src/entities/Items.ts` the roulette curve by place and the burr and acorn; `src/scenes/Race.ts` registers every kart (`player`, `cpu.1`..`cpu.7`), every pooled item (`burr.0`.., `acorn.0`..), `course`, `effects` and `race` in `load()` so a scenario's `setup.place` reaches them, then runs the countdown, the karts, the boxes, the hits, the finish and the HUD state. `src/render/` is ordinary Three.js and every model in the game: `course.ts` (terrain, road ribbons, kerbs, toy-block walls, bridge, gantry, trees), `kart.ts` (eight original liveries), `items.ts`, `camera.ts` (the chase camera), `effects.ts` (every particle look and the `BURSTS` table, fired through pooled `GPUParticles3D` emitters), `skids.ts`, `sky.ts` and `lighting.ts`; `src/ui/Hud.tsx` is the one HUD. `playtests/` holds one scenario per mechanic (`drift`, `surfaces`, `wall`, `items`, `laps`, `race`) plus `performance`; keep `playtests/survives.playtest.json` as smoke proof (the kart on the road, the core look, the course relief) and `touch-controls.ts`/`touch-layout.ts` aligned with the native playtest.
|
|
23
|
+
|
|
24
|
+
Play gates: `playtests/explore.playtest.json` drives 7200 ticks of seeded random input and fails on any page error. A new key binding joins `explore`'s `move` or `actions` in the same change.
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
## Portable authoring contracts
|
|
28
|
+
|
|
29
|
+
No model here is imported, so there is no authored scale to normalise: the generated scale-and-snap conventions do not apply to this template. Steering is the x of `input.vector("move")` with no keys on its up and down, because a vector is normalised and W held with D would cut the steer to 0.71; the left stick still feeds it. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("driver.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity.
|
|
30
|
+
|
|
31
|
+
`src/render/sky.ts` builds the sky from `palette.ts` and uses it as both background and environment light, and `lighting.ts` aims the one authored sun and follows the player's kart so its shadow stays sharp. No material backlighting ships: as in a stock Unreal scene, the sun, the sky light and each material's own colour are the whole light. The look's chain is core's, not vendored: `src/render/postprocessing.ts` calls `new WorldEnvironment(qualityPreset(tier))`, and `qualityPreset` in `src/render/quality.ts` is the `@threenative/core` preset plus this game's overrides, each with its reason — it starts empty, so the game gets the stock Unreal 5.8.3 look (`TN_WORLD_ENVIRONMENT` reports the filmic curve and `TN_AUTO_EXPOSURE` the meter), metered at 0 EV by the starter kits' shared `src/render/kitExposure.ts`. Pin `tonemapMode: "aces"`, or `autoExposureEnabled: false` with a fixed `exposure`, there and only there, and say why. `low` casts no shadows; `medium` and `high` draw one 2048² map that follows the player's kart (`lighting.ts`).
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Kit notes: minimal
|
|
2
|
+
|
|
3
|
+
Kit-specific facts moved out of the kit `AGENTS.md`. Shared conventions: `conventions.md`.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
This template has no React or Tailwind.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Ownership
|
|
11
|
+
|
|
12
|
+
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state store. This repository owns `src/render/`, `src/entities/`, and `src/scenes/`; all are ordinary user code, and nothing in `@threenative/*` reads or chooses their appearance.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Start every change
|
|
16
|
+
|
|
17
|
+
`@threenative/physics/navigation` is browser-only WASM; use portable `ctx`/Three.js for this cross-target template.
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
## Commands and map
|
|
21
|
+
|
|
22
|
+
`src/main.ts` boots the canvas; `src/scenes/Play.ts` owns the lifecycle; `src/entities/Player.ts` drives `assets/mannequin.glb` (Quaternius, CC0) through `SkeletalMesh3D`; the arena is one `Group` handed to `buildStaticColliders`; `render/camera.ts` follows from `afterPhysics`. No HUD; `playtests/survives.playtest.json` is the durable smoke proof.
|
|
23
|
+
|
|
24
|
+
On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), the local `src/render/touch-controls.ts` adds a left movement stick and a right jump button. The scene passes its returned input to `Player`; keep the keyboard mapping as the desktop fallback.
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
## Portable authoring contracts
|
|
28
|
+
|
|
29
|
+
`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); WebGPU adds a `VirtualShadowNode`. The shared look comes from core through `src/render/quality.ts`: the filmic curve and metered auto exposure are enabled by default. `pnpm test` proves behavior, never the look.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Kit notes: platformer
|
|
2
|
+
|
|
3
|
+
Kit-specific facts moved out of the kit `AGENTS.md`. Shared conventions: `conventions.md`.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
A chibi fox runs ninety-seven metres of floating meadow, rope bridges and stompable walkers to a goal flag: three hearts, five gems, a double jump and a dash. Every model is procedural — no mesh file, no texture, no animation clip.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Ownership
|
|
11
|
+
|
|
12
|
+
This repository owns the route, the fox's feel, the walkers, the pickups, the HUD, and the look; `src/game.ts` is portable and React mounts from `src/main.ts`.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Start every change
|
|
16
|
+
|
|
17
|
+
`@threenative/physics/navigation` is browser-only WASM, and this route needs no navigation: it is authored geometry, so the fox collides with exactly the triangles it sees and desktop/native stays honest.
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
## Commands and map
|
|
21
|
+
|
|
22
|
+
`src/entities/Fox.ts` owns movement and feel — the one table of constants the route is balanced around; `Walker.ts` is a stompable patrol, `Pickup.ts` a collectible; `src/level/Stage.ts` builds the route and tags the walkable meshes, `Checkpoints.ts` owns hearts and respawns; `src/render/` is ordinary Three.js and every model in the game; `src/ui/Hud.tsx` is the one HUD. The camera and the sun are written in `afterPhysics`, never in the scene's frame function, because `moveAndSlide` only queues motion. Keep `playtests/survives.playtest.json` as smoke proof and `touch-controls.ts`/`touch-layout.ts` aligned with the native playtest. Collision is the engine's, from your geometry: `buildStaticColliders(ctx, stage.group, { predicate: (object) => object.userData.solid === true })` turns the tagged walkable meshes into fixed trimesh bodies and leaves thousands of decorative ones out of it. A `CollisionShape3D` capsule is centred on the body's origin, so the origin is the fox's waist and its rig is pushed down by `halfHeight + radius`; forget that and the fox floats a body-length above every surface.
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
## Portable authoring contracts
|
|
26
|
+
|
|
27
|
+
No model here is imported, so there is no authored scale to normalise and the collider is the body: the generated scale-and-snap conventions do not apply to this template.
|
|
28
|
+
|
|
29
|
+
`src/render/sky.ts` builds the gradient background from `palette.ts`; a separate measured environment lights the scene, the background's lower hemisphere matches `skyFloor`, and `SUN_DIRECTION` aims `lighting.ts`'s authored sun.
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
## Optional multiplayer transport
|
|
33
|
+
|
|
34
|
+
The generated `quality.ts` uses those core defaults; game exposure policy stays in `src/render/exposure.ts`. `tonemapMode: "aces"` and `autoExposureEnabled: false` with fixed `exposure` are named overrides on the same preset.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Kit notes: puzzle
|
|
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 vault, the warden, the crates, the seal, the HUD and the look; `src/game.ts` is portable and React mounts only from `src/main.ts`.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Commands and map
|
|
11
|
+
|
|
12
|
+
Forty-five dynamic bodies from seed 6132 — 41 solid crates to shove, 4 phase crates to walk through, and a seal to stand on. `src/scenes/Play.ts` authors the layout, drops the pile on the first observed frame so the settle is provable, and refuses a crate inside the seal (`assertClearOfSeal`) or in the crossing (`assertLaneClear`) — a check: the lane check once made a finishable level unfinishable when two crates placed elsewhere shifted the jitter. `src/render/vault.ts` returns the geometry and the solid boxes, so `src/render/` imports no framework package. The third collision layer in `src/entities/Crate.ts` is the glowing ward: it has to fall and stack, so it cannot be a sensor, and it must be transparent to *everything the player can move*. `Warden.ts` sets `pushesDynamicBodies` (Rapier's `false` default reads as a broken collider); `Seal.ts` ends the run on a backend-reported **overlap**, never a distance check. V replays the vault twice and publishes the drift. `src/render/touch-controls.ts` adds a thumbstick on touch, and `playtests/survives.playtest.json` is the smoke proof; keep the other thirteen honest.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Portable authoring contracts
|
|
16
|
+
|
|
17
|
+
The vault is one fixed three-quarter shot that drifts a fraction of a metre toward the warden, so the camera reads the body in the frame function; a trailing follow camera is a different game.
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
## Optional multiplayer transport
|
|
21
|
+
|
|
22
|
+
`src/render/exposure.ts` clamps the meter (`maxStops` 0.5, `minStops` -2) because the room is dark by design and an open meter turns it into a pale box. `quality.ts` names one cost override, reported as `TN_RENDER_CHAIN_COST_OVERRIDE`: no final gather, SSGI, SSR, motion blur or local exposure, half-resolution occlusion, and the kit bloom instead of the Unreal bloom, because the core stack took the performance scenario over 16.7 ms GPU p95 with 45 bodies.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Kit notes: racing
|
|
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 car feel, track, race rules, rescue, HUD, and look; `src/game.ts` is portable and React mounts from `src/main.ts`. A bullet that passes through a wall is not a collider bug: `RigidBody3D` defaults to continuous collision, `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web and native.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Start every change
|
|
11
|
+
|
|
12
|
+
`@threenative/physics/navigation` is browser-only WASM; this kit uses `VehicleBody3D` for the cars and `PathFollow3D` for the rival's line, and no navmesh.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Commands and map
|
|
16
|
+
|
|
17
|
+
`src/track/Track.ts` owns the circuit, its collision layers and the grid; `Lap.ts` orders `Area3D` gates and counts a lap on the car's **measured** travel direction; `TrackSector.ts` ray-probes the road and rescues from it; `Ranking.ts` ranks route progress. `src/entities/CarBody.ts` builds the one chassis both cars drive — a `VehicleBody3D` whose wheels are read off the four **named** wheel groups in `shapes.ts`. `RacingCar.ts` turns input into `engineForce` / `brake` / `steering` and nothing else; `Rival.ts` is that same car under a pure-pursuit controller at a constant pace. Keep `playtests/survives.playtest.json` as the smoke proof, and on a touch device `src/render/touch-controls.ts` adds the stick and buttons.
|
|
18
|
+
|
|
19
|
+
**Two things about the vehicle are invisible in the API.** `suspensionStiffness` is a frequency squared, so the strut sags `gravity / (4 * stiffness)` and Godot's default of 20 bottoms it out, and a positive steering angle turns the chassis toward its own `-z` — so the input is negated once and the visual front wheels take that same signed angle. `CarBody.ts` carries every other number.
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
## Portable authoring contracts
|
|
23
|
+
|
|
24
|
+
Generated conventions call `normaliseToMetres` for authored vehicle scale; the four `VehicleBody3D` wheels own floor contact, so no car gets `GroundSnap`. `input.vector("move").y` is +up and means throttle, and `+x` is right.
|
|
25
|
+
|
|
26
|
+
`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). The shared look comes from core through `src/render/quality.ts`: the filmic curve and metered auto exposure are enabled by default. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js. Racing keeps its deliberate gather, SSR and sharpening overrides in `quality.ts`: reflected rough tarmac and sharpening produced unstable speckles/bands, and the game retains its 33 ms / 30 FPS budget. The curve and meter stay enabled. The HUD uses the existing opaque `bg-panel` behind race, position, speed/time/boost and outcome text so a brighter road or sky does not erase the readouts.
|