create-threenative 0.2.4 → 0.2.6
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/README.md +23 -1
- package/agent-docs/references/assertion-reference.md +40 -1
- package/agent-docs/references/capability-reference.md +972 -66
- package/agent-docs/references/finding-assets.md +8 -1
- package/agent-docs/references/performance-basics.md +114 -0
- package/agent-docs/references/rigging-characters.md +51 -0
- package/agent-docs/references/webview-ui.md +3 -2
- package/agent-files/.agents/skills/ponytail/SKILL.md +68 -0
- package/agent-files/.agents/skills/threenative-assets/SKILL.md +8 -0
- package/agent-files/.agents/skills/threenative-context/SKILL.md +8 -0
- package/agent-files/.agents/skills/threenative-performance/SKILL.md +26 -10
- package/agent-files/.claude/hooks/ponytail-context.mjs +51 -0
- package/agent-files/.claude/settings.json +38 -0
- package/agent-files/.claude/skills/ponytail/SKILL.md +68 -0
- package/agent-files/.claude/skills/threenative-assets/SKILL.md +8 -0
- package/agent-files/.claude/skills/threenative-context/SKILL.md +8 -0
- package/agent-files/.claude/skills/threenative-performance/SKILL.md +26 -10
- package/agent-files/.codex/hooks.json +40 -0
- package/capabilities.json +1344 -88
- package/dist/index.d.ts +10 -1
- package/dist/index.js +186 -1
- package/dist/threenative.js +660 -150
- package/package.json +6 -6
- package/template-assets/patches/three@0.185.1.patch +179 -19
- package/templates/action-rpg/AGENTS.md +5 -5
- package/templates/action-rpg/CLAUDE.md +5 -5
- package/templates/action-rpg/package.json +8 -8
- package/templates/defense/AGENTS.md +5 -5
- package/templates/defense/CLAUDE.md +5 -5
- package/templates/defense/package.json +8 -8
- package/templates/minimal/AGENTS.md +5 -5
- package/templates/minimal/CLAUDE.md +5 -5
- package/templates/minimal/package.json +7 -7
- package/templates/minimal/threenative.config.ts +1 -0
- package/templates/platformer/AGENTS.md +5 -5
- package/templates/platformer/CLAUDE.md +5 -5
- package/templates/platformer/package.json +9 -9
- package/templates/puzzle/AGENTS.md +5 -5
- package/templates/puzzle/CLAUDE.md +5 -5
- package/templates/puzzle/package.json +8 -8
- package/templates/racing/AGENTS.md +5 -5
- package/templates/racing/CLAUDE.md +5 -5
- package/templates/racing/package.json +8 -8
- package/templates/runner/AGENTS.md +5 -5
- package/templates/runner/CLAUDE.md +5 -5
- package/templates/runner/package.json +8 -8
- package/templates/sailing/AGENTS.md +6 -6
- package/templates/sailing/CLAUDE.md +6 -6
- package/templates/sailing/package.json +8 -8
- package/templates/shooter/AGENTS.md +5 -5
- package/templates/shooter/CLAUDE.md +5 -5
- package/templates/shooter/package.json +8 -8
- package/templates/starter/AGENTS.md +8 -8
- package/templates/starter/CLAUDE.md +8 -8
- package/templates/starter/package.json +9 -9
- package/templates/starter/playtests/production-readiness.playtest.json +96 -0
- package/templates/starter/src/ui/Hud.tsx +2 -2
- package/templates/starter/src/ui/Menu.tsx +5 -1
|
@@ -6,9 +6,16 @@ asset tools when the asset is conventional; build anything specific to this game
|
|
|
6
6
|
|
|
7
7
|
Installing `@threenative/core` writes the `.mcp.json` that launches `threenative-asset-mcp`, so
|
|
8
8
|
your host lists its tools alongside your own. Your host reads that file from the directory it was
|
|
9
|
-
launched in: start the session in this project, not in a parent of it. It advertises
|
|
9
|
+
launched in: start the session in this project, not in a parent of it. It advertises 44; these 8
|
|
10
10
|
are the loop you will use for nearly everything:
|
|
11
11
|
|
|
12
|
+
For a humanoid that needs a skeleton or more motion, use the complete
|
|
13
|
+
[`rigging-characters.md`](rigging-characters.md) recipe. Inspect with `asset_inspect_rig`,
|
|
14
|
+
preserve or fit a rig with `asset_auto_rig`, select and bake donor clips with
|
|
15
|
+
`asset_retarget_animations`, and confirm the result with `asset_preview_animation` on a nonblank
|
|
16
|
+
contact sheet. AETHER / 02 is the pinned sample; its 18-bone rig has no fingers or toes, and the
|
|
17
|
+
tools report those absent roles instead of inventing them.
|
|
18
|
+
|
|
12
19
|
For a bespoke animated creature, use the complete [`creating-creatures.md`](creating-creatures.md)
|
|
13
20
|
recipe. It keeps the editable spec and claims under `.threenative/creatures/`, compiles the GLB
|
|
14
21
|
into the configured `assets/` source, and requires independent preview review before game
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Performance basics — what the engine already does, and what you choose
|
|
2
|
+
|
|
3
|
+
Every frame this framework runs the same measured loop. Some performance work is done for you;
|
|
4
|
+
the rest is a content choice only the game can make. This page is the short list of both, so you
|
|
5
|
+
reach for the right abstraction before you profile anything.
|
|
6
|
+
|
|
7
|
+
## The split
|
|
8
|
+
|
|
9
|
+
- **The engine decides what it can measure where it is used**: world-transform preparation, scene
|
|
10
|
+
batching and projection, per-pass culling, resolution, load scheduling, asset cooking, first-use
|
|
11
|
+
warmup, and the frame meter. Do not hand-roll these — a hand-rolled version usually costs you the
|
|
12
|
+
engine's version.
|
|
13
|
+
- **You decide what cannot be read from the code**: how much detail is on screen, how many objects,
|
|
14
|
+
what never moves, how far shadows reach, how many particles. Those are content decisions, and the
|
|
15
|
+
frame meter reports what they cost.
|
|
16
|
+
|
|
17
|
+
If you can measure the value where it is used, let the engine decide; a constant you are told to
|
|
18
|
+
revisit later is the engine's job, not yours.
|
|
19
|
+
|
|
20
|
+
## Automatic — leave it alone
|
|
21
|
+
|
|
22
|
+
- **Scene batching and projection.** The engine merges equal geometry and material into fewer draws
|
|
23
|
+
and projects the authored scene automatically. A per-mesh `onBeforeRender` / `onAfterRender` hook
|
|
24
|
+
that packs buffers or mutates geometry makes the whole scene decline projection. Put once-per-draw
|
|
25
|
+
work in `ctx.beforeRender(fn)` instead: it runs after the frame's last fixed update and before
|
|
26
|
+
projection packs, on the batched and unbatched paths alike.
|
|
27
|
+
- **Transform preparation.** Exactly one world-matrix preparation runs per actual world draw. Never
|
|
28
|
+
call `updateMatrixWorld(true)` yourself, and do not set `scene.matrixWorldAutoUpdate = false`
|
|
29
|
+
unless you then update the scene yourself. Marking a measured-static subtree
|
|
30
|
+
`matrixWorldAutoUpdate = false` is allowed and the engine will skip it, but its parents must stay
|
|
31
|
+
still. For one node that never moves, `node.updateMatrix(); node.matrixAutoUpdate = false` is the
|
|
32
|
+
cheaper pair: it skips the per-object compose and leaves the walk intact.
|
|
33
|
+
- **Per-pass culling.** The main camera, each shadow and each reflection pass cull their own way,
|
|
34
|
+
and the engine owns that. Do not set `frustumCulled = false` on a batch, and do not give one
|
|
35
|
+
batch bounds that span the map.
|
|
36
|
+
- **The projected-size cut is yours to tune**, not the engine's: `renderer.minimumProjectedPixels`
|
|
37
|
+
(default `0.5`; a shipped title raised it to `2`) drops what the render camera cannot resolve
|
|
38
|
+
before it is submitted. Raise it before you write LOD machinery, and read `TN_PROJECTION` to see
|
|
39
|
+
how many objects it actually drops. Shadow casters are never dropped on the main view alone, so a
|
|
40
|
+
scene of small casters stays expensive — `castShadow = false` on props the cut would otherwise
|
|
41
|
+
drop is the game's call.
|
|
42
|
+
- **Resolution.** `render.resolutionScale: "auto"` holds GPU headroom and never lowers resolution
|
|
43
|
+
on a CPU overrun; `TN_FRAME_BUDGET` reports the scale actually used. A number is the named pin
|
|
44
|
+
override.
|
|
45
|
+
- **Quality.** Each template ships `src/render/quality.ts` (three tiers, platform default,
|
|
46
|
+
`TN_QUALITY_TIER`) and `adaptiveQuality.ts` (measured frame windows). Use the tiers; do not invent
|
|
47
|
+
a fourth switch.
|
|
48
|
+
- **Loading.** `loadAll(items, load)` loads with bounded concurrency and returns results in the
|
|
49
|
+
input's order. `addInSlices(objects, add)` attaches hundreds of objects across frames. A pool that
|
|
50
|
+
pushes results lands a different asset every load.
|
|
51
|
+
- **Assets.** The build cooks textures to KTX2/Basis, deduplicates model images and reports bytes;
|
|
52
|
+
`assets.budget` fails the build over a ceiling. Do not ship unpacked 4K textures and plan to
|
|
53
|
+
optimize later.
|
|
54
|
+
- **First use.** `warmUpScene(scene, camera)` compiles what a scene needs in slices, presenting a
|
|
55
|
+
frame between each. Warm up the real scene before interactive play; do not pre-touch every
|
|
56
|
+
possible variant.
|
|
57
|
+
|
|
58
|
+
## Where the frame actually goes, in that order
|
|
59
|
+
|
|
60
|
+
Ask these three questions before you profile anything, because they decide who owns the fix:
|
|
61
|
+
|
|
62
|
+
1. **Is the GPU busy?** `TN_FRAME_BUDGET` carries `gpuMs`. A frame with a 16 ms `render` phase and a
|
|
63
|
+
2 ms GPU is not a rendering problem — the GPU is idle and waiting for JavaScript.
|
|
64
|
+
`gpuMs` is sampled one frame in eight (`renderer.gpuTimestampFrameInterval`, default `8`): reading
|
|
65
|
+
every pass of every frame cost native Midway 161 ms/s of main-thread JavaScript.
|
|
66
|
+
2. **How many objects does the scene walk?** `TN_PROJECTION` reports `considered`, `culled`,
|
|
67
|
+
`exemptShadowCasters` and `exemptFrustumCulled` for the frame. Three.js visits every object once
|
|
68
|
+
per pass (main, each shadow, each reflection) and that visit is roughly 2 µs each on a desktop
|
|
69
|
+
core: 1,600 objects is ~3.5 ms of a 16 ms render before a single draw is issued. This is the
|
|
70
|
+
number to move, and the only lever is fewer objects.
|
|
71
|
+
3. **Is it the engine's own work?** It usually is not: measured on a 1,561-mesh game, the engine's
|
|
72
|
+
whole share — camera cull, frame-op recorder, frame meter — was under 1.5 ms of a 20 ms frame,
|
|
73
|
+
with the rest being three.js's walk over the game's scene plus the game's own `update`.
|
|
74
|
+
|
|
75
|
+
A GPU that is idle with a slow `render` phase is an object-count problem, not a graphics problem.
|
|
76
|
+
|
|
77
|
+
## Reach for these before you write your own
|
|
78
|
+
|
|
79
|
+
| You have | Use | What it gives you |
|
|
80
|
+
| --- | --- | --- |
|
|
81
|
+
| Many copies of one shape | `InstancedBatch` | One draw, no per-copy mesh |
|
|
82
|
+
| Many *different* shapes that never move relative to each other — a ship, a rig, a building, the static parts of an imported model | `mergeParts` | One mesh per material, so the walk visits one object instead of dozens; pass `preserve: ["uv", "normal"]` when the pieces carry authored normals or texture UVs |
|
|
83
|
+
| One over-detailed body seen at many distances | `ClusteredBatch` / `ClusteredMesh` | Each copy submits the detail its distance earns |
|
|
84
|
+
| A particle surface | `GPUParticles3D` | Pooled dispatch, game-owned appearance |
|
|
85
|
+
| Bullet streaks | `TracerPool3D` | Pooled travelling meshes |
|
|
86
|
+
| A sprite that faces the camera | `Billboard3D` | No hand-written per-frame orientation |
|
|
87
|
+
| One directional shadow over an open world | `VirtualShadowNode` | Camera-centred, texel-snapped clip levels; `trackCaster` for movers |
|
|
88
|
+
| Distance detail swaps | three's `LOD` | Standard, and the engine can still batch it |
|
|
89
|
+
| Raycasts over a large static scene | `GPUSceneBVH` / `ScenePicker` | Built once, queried many times |
|
|
90
|
+
|
|
91
|
+
## The shortcuts that cost a frame
|
|
92
|
+
|
|
93
|
+
- One mesh per bullet or particle. Pool them (`TracerPool3D`, `GPUParticles3D`) or instance them.
|
|
94
|
+
- A fresh `Vector3`, array or object per entity inside `update`. Hoist it out of the loop and reuse
|
|
95
|
+
it; allocation shows up as GC in the trace, not in the average.
|
|
96
|
+
- A per-mesh render hook that packs buffers. That is `ctx.beforeRender` once per draw.
|
|
97
|
+
- Many shadow-casting lights, or one 4K shadow map for a whole valley. One directional light plus
|
|
98
|
+
`VirtualShadowNode`.
|
|
99
|
+
- The same large equirect on `scene.background` and `scene.environment`. The environment light is
|
|
100
|
+
charged again and moves in power-of-two steps — see `agent-docs/mobile-memory-budget.md`.
|
|
101
|
+
- A unique material or texture per copy. Share materials and images; the batcher merges equal
|
|
102
|
+
material and geometry.
|
|
103
|
+
|
|
104
|
+
## Measure, then change one thing
|
|
105
|
+
|
|
106
|
+
`TN_FRAME_BUDGET` reports `fps`, `gpuMs` and the five phases (`update`, `render`, `overlay`,
|
|
107
|
+
`residual`, `hostGap`) plus per-pass draws and triangles; `TN_PROJECTION` reports the object census
|
|
108
|
+
(`considered`, `culled`, `exemptShadowCasters`) and the cut's threshold; `TN_RENDER_PROJECTION`
|
|
109
|
+
reports whether the scene batched and, when it did not, the reason. Launching with `DEV_MODE=true`
|
|
110
|
+
puts the frame rate on screen in a corner chip and turns on the engine's dev surfaces (backtick
|
|
111
|
+
opens the object and geometry inspector), so the number is visible while you play instead of after
|
|
112
|
+
you grep. `npx @threenative/playtest perf` turns a log into a windowed report. When the percentile is
|
|
113
|
+
bad but the cause is not obvious, `agent-docs/trace-a-slow-frame.md` names the function before you
|
|
114
|
+
change a line.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Rigging characters — the full MCP tool loop
|
|
2
|
+
|
|
3
|
+
Companion to the humanoid paragraph in `finding-assets.md`. Reach for these tools when a game
|
|
4
|
+
needs a rigged character or extra motion on an existing one. The model choice, clip selection,
|
|
5
|
+
material changes and intentional motion adjustments stay authored game data; the tools only
|
|
6
|
+
produce the GLB.
|
|
7
|
+
|
|
8
|
+
AETHER / 02 is the pinned default sample: an 18-bone humanoid with 11 clips, five materials, both
|
|
9
|
+
UV sets, tangents and two material extensions. `SkeletalMesh3D` loads it and its `hand.R` is the
|
|
10
|
+
weapon attachment bone. It is CC0, and was built from a 14-unit source robot, so its source size
|
|
11
|
+
is preserved unless a game explicitly authors a `SkeletalMesh3D.size` override.
|
|
12
|
+
|
|
13
|
+
## 1. Inspect before deciding
|
|
14
|
+
|
|
15
|
+
`asset_inspect_rig` takes a local GLB path, or `{ "sourceId": "aether-02" }` to acquire the pinned
|
|
16
|
+
sample into the development cache, plus optional local UAL ZIP/GLB libraries. It reports meshes,
|
|
17
|
+
joints, suggested bone-role mappings with ambiguity, attribute and extension support, measured
|
|
18
|
+
bounds, clips, and the actual attachment candidates. It never downloads the animation libraries;
|
|
19
|
+
supply local archives or select release donors by clip id.
|
|
20
|
+
|
|
21
|
+
## 2. Preserve or fit a rig
|
|
22
|
+
|
|
23
|
+
`asset_auto_rig` preserves an existing valid rig by default. For an unrigged upright biped it fits
|
|
24
|
+
an 18-joint skeleton from measured geometry, then binds smooth (up to four normalized influences)
|
|
25
|
+
or rigid (one bone per connected mechanical region) weights and publishes the skinned GLB under the
|
|
26
|
+
project root. When the anatomy is ambiguous — arms joined to the torso, legs not separated — it
|
|
27
|
+
returns a correction request with the measured landmarks instead of a bad rig; pass corrected
|
|
28
|
+
`overrides` and call it again. Replacing a real rig requires `replaceRig: true`.
|
|
29
|
+
|
|
30
|
+
## 3. Select and retarget motion
|
|
31
|
+
|
|
32
|
+
`asset_retarget_animations` fetches only the donor clips you select from the pinned release and
|
|
33
|
+
bakes them onto the target: `{ "id": "ual1/Walk_Loop", "variant": "in_place" }`. In-place is the
|
|
34
|
+
normal game-controlled locomotion output; root motion explicitly uses the matching `root_motion`
|
|
35
|
+
variant. New clips keep their namespace (`ual1/Walk_Loop`) so an existing `Walk` is never
|
|
36
|
+
overwritten. Existing target clips survive unless you pass `keepExistingClips: false` for a
|
|
37
|
+
game-minimal export. Target materials, UVs, tangents and extensions are preserved.
|
|
38
|
+
|
|
39
|
+
## 4. Confirm with a contact sheet
|
|
40
|
+
|
|
41
|
+
`asset_preview_animation` renders a prepared GLB from two to six angles with an optional clip time
|
|
42
|
+
or an explicit bone pose, and publishes a nonblank contact sheet under the project root. A missing
|
|
43
|
+
rendering backend returns an explicit `unavailable` result; a blank frame fails. Inspect the sheet
|
|
44
|
+
before delivery — a valid animation container alone is not approval.
|
|
45
|
+
|
|
46
|
+
## 5. Cook and play
|
|
47
|
+
|
|
48
|
+
Load the prepared GLB the ordinary way and play clips with `SkeletalMesh3D` and its update loop.
|
|
49
|
+
Attach a game-authored weapon with `attachToBone(character.root, "hand.R", weapon)`. Credit the
|
|
50
|
+
source and keep its license notice with the asset; the donor libraries are CC0, and the pinned
|
|
51
|
+
clips are fetched once into the development cache on first use, then reused offline.
|
|
@@ -10,10 +10,11 @@ ships, and never the game itself. The scene stays in the native runtime; only th
|
|
|
10
10
|
| web | the page itself, beside `GameCanvas` | shipped |
|
|
11
11
|
| Android | a transparent `WebView` over the SDL surface | shipped, proven on a Pixel 8 |
|
|
12
12
|
| desktop (Linux) | a transparent WebKitGTK window over the game window | shipped |
|
|
13
|
-
| desktop (Windows
|
|
13
|
+
| desktop (Windows) | a transparent WebView2 surface over the game | implemented; final distribution verification is platform-specific |
|
|
14
|
+
| desktop (macOS) | a transparent `WKWebView` over the game | implemented; final distribution verification is platform-specific |
|
|
14
15
|
| iOS | a transparent `WKWebView` over the Metal layer | written, **unproven on hardware** |
|
|
15
16
|
|
|
16
|
-
Turn it off with `ui: { renderer: "native" }` in `threenative.config.ts`. That ships no web view
|
|
17
|
+
`ui.renderer` defaults to `"web"`. Turn it off with `ui: { renderer: "native" }` in `threenative.config.ts`. That ships no web view
|
|
17
18
|
and no extra process, and draws `View`/`Text` quads inside the rendered frame instead.
|
|
18
19
|
|
|
19
20
|
## Two things cross the boundary, and nothing else
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ponytail
|
|
3
|
+
description: >
|
|
4
|
+
Force the laziest solution that actually works: smallest, shortest, most minimal.
|
|
5
|
+
Use on any coding task in this game — writing, adding, refactoring, fixing,
|
|
6
|
+
reviewing, or picking a dependency — and whenever a request smells over-built
|
|
7
|
+
("simplest", "minimal", "yagni", "do less", "shortest path", "too much code",
|
|
8
|
+
"bloat", "boilerplate"). Adds YAGNI and reuse to the engine's capability-first
|
|
9
|
+
rule: never hand-write what an installed @threenative system already does.
|
|
10
|
+
Source: github.com/DietrichGebert/ponytail (MIT). Do NOT use for non-coding
|
|
11
|
+
requests (general knowledge, prose, translation, summaries, recipes).
|
|
12
|
+
argument-hint: "[off]"
|
|
13
|
+
license: MIT
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# Ponytail — lazy senior dev
|
|
17
|
+
|
|
18
|
+
You are a lazy senior developer. Lazy means efficient, not careless. The best code
|
|
19
|
+
is the code never written. Active every response; this project's hook re-injects the
|
|
20
|
+
ruleset every session and prompt, and `PONYTAIL=off` or "stop ponytail" turns it off.
|
|
21
|
+
|
|
22
|
+
## The ladder
|
|
23
|
+
|
|
24
|
+
Stop at the first rung that holds. The ladder runs *after* you understand the
|
|
25
|
+
problem, not instead of it: read the code the change touches and trace the real
|
|
26
|
+
flow end to end, then climb. Two rungs work → take the higher one and move on.
|
|
27
|
+
|
|
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?** Search `engine_search_capabilities` for the full request and each concrete mechanic, inspect hits with `engine_capability_detail`, and 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; never skip it because the task looks small, and never jump to hand-written code while it is unsearched.
|
|
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
|
+
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
|
+
5. **Already-installed dependency solves it?** Use it; never add a new one for what a few lines can do.
|
|
33
|
+
6. **Can it be one line?** One line.
|
|
34
|
+
7. **Only then:** the minimum code that works, in this game's `src/`.
|
|
35
|
+
|
|
36
|
+
## Rules
|
|
37
|
+
|
|
38
|
+
- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
|
|
39
|
+
- No boilerplate, no scaffolding "for later"; later can scaffold for itself. Deletion over addition. Boring over clever.
|
|
40
|
+
- Fewest files possible. Shortest working diff wins — but only once you understand the problem. The smallest change in the wrong place is a second bug.
|
|
41
|
+
- Complex request? Ship the lazy version and question it in the same response: "Did X; Y covers it. Need full X? Say so." Never stall on a question you can default.
|
|
42
|
+
- Two same-size options? Take the one correct on edge cases — lazy means less code, not the flimsier algorithm.
|
|
43
|
+
- Bug fix = root cause, not symptom: grep every caller of the function you touch and fix the shared one. One guard where all callers route through is smaller than a guard per caller, and patching only the path the ticket names leaves a sibling caller broken.
|
|
44
|
+
- Mark a deliberate corner cut with a `ponytail:` comment naming the ceiling and the upgrade path.
|
|
45
|
+
|
|
46
|
+
## Output
|
|
47
|
+
|
|
48
|
+
Code first. Then at most three short lines: what was skipped, when to add it.
|
|
49
|
+
Pattern: `[code] → skipped: [X], add when [Y].` No essays, no feature tours, no
|
|
50
|
+
design notes. Explanation the user explicitly asked for (a plan, a report, per-phase
|
|
51
|
+
notes) is not debt — give it in full.
|
|
52
|
+
|
|
53
|
+
## When NOT to be lazy
|
|
54
|
+
|
|
55
|
+
Never simplify away: understanding the problem (a small diff you do not understand is
|
|
56
|
+
just laziness dressed up as efficiency), input validation at trust boundaries, error
|
|
57
|
+
handling that prevents data loss, security, accessibility, anything explicitly
|
|
58
|
+
requested, and the calibration real hardware needs. Lazy code without its check is
|
|
59
|
+
unfinished: non-trivial logic leaves ONE runnable check behind — the smallest thing
|
|
60
|
+
that fails if the logic breaks. In this game the proof is a playtest scenario, never a
|
|
61
|
+
new test framework; trivial one-liners need no test.
|
|
62
|
+
|
|
63
|
+
## Boundaries
|
|
64
|
+
|
|
65
|
+
Ponytail governs what you build, not how you talk. "stop ponytail" / "normal mode" /
|
|
66
|
+
`PONYTAIL=off`: revert. Level persists until changed or session end.
|
|
67
|
+
|
|
68
|
+
The shortest path to done is the right path.
|
|
@@ -34,6 +34,14 @@ For a bespoke animated creature, follow `agent-docs/creating-creatures.md`. Call
|
|
|
34
34
|
visual review before delivery. `creature_status` distinguishes compile-only availability from
|
|
35
35
|
optional preview/check dependencies; an unavailable renderer is not approval.
|
|
36
36
|
|
|
37
|
+
For a humanoid that needs a skeleton or more motion, follow `agent-docs/rigging-characters.md`.
|
|
38
|
+
Inspect first with `asset_inspect_rig` (a local GLB or the pinned `aether-02` sample), auto-rig an
|
|
39
|
+
unrigged biped with `asset_auto_rig` (or pass explicit landmarks when it returns a correction
|
|
40
|
+
request), select donors with `asset_retarget_animations` (in-place by default; `root_motion` only
|
|
41
|
+
from the matching `_RM` donor), and confirm the result with `asset_preview_animation` on a
|
|
42
|
+
nonblank contact sheet before cooking. The 18-bone AETHER sample has no fingers or toes; the
|
|
43
|
+
tools report those absent roles instead of inventing them.
|
|
44
|
+
|
|
37
45
|
Choose the sculpt branch before coding: conventional → asset tools; trivial → portable geometry;
|
|
38
46
|
bespoke with a reference → `sculpt_plan`, `sculpt_spec_gate` until every region passes, one
|
|
39
47
|
factory per pass in `src/render/`, then `sculpt_compare` and `sculpt_pass_gate` against a real
|
|
@@ -14,6 +14,7 @@ The recipes are in `agent-docs/ctx-cookbook.md` and imports still require
|
|
|
14
14
|
| `ctx.goto("<scene-name>")` | hand reset | async scene rebuild |
|
|
15
15
|
| `ctx.tween(...)` | `Math.sin`/`lerp` accumulator | timed interpolation with optional `ease` |
|
|
16
16
|
| `ctx.after(...)` / `ctx.every(...)` | timer branches in `update` | disposable schedules |
|
|
17
|
+
| `ctx.beforeRender(fn)` | per-frame packing in `update` or an object `onBeforeRender` hook | one dispatch per actual world draw, after the last fixed step and before the projection; cleared like `ctx.afterPhysics` |
|
|
17
18
|
| `ctx.random.range(-1, 1)` | `Math.random()` | reproducible when `seed` is configured |
|
|
18
19
|
| `ctx.pointer.on(...)` / `ctx.pointer.drag(...)` | hover/press/drag bookkeeping | web/native pointer-id stream |
|
|
19
20
|
| `ctx.raycast()` / `ctx.raycastAll()` | `new Raycaster()` | backend-neutral intersections |
|
|
@@ -29,6 +30,13 @@ restart, `game.goto("<scene-name>")` from React resets declared initial state fi
|
|
|
29
30
|
uses `ctx.state.set({ /* copy this game's initial-state shape */ })` before the goto. `ctx.random` is
|
|
30
31
|
deterministic only when `defineGame({ seed })` is configured.
|
|
31
32
|
|
|
33
|
+
`ctx.beforeRender(fn)` runs once per actual world draw, after the frame's last fixed update and
|
|
34
|
+
before the projection reconciles, so `fn` reads the frame's final state; a held, loader-only frame
|
|
35
|
+
draws no world and dispatches nothing. It is cleared on scene change and stop, like
|
|
36
|
+
`ctx.afterPhysics`. Reach for it when the draw itself consumes per-frame CPU work — packing an
|
|
37
|
+
instanced batch, rebuilding a buffer — instead of an object `onBeforeRender` hook, which makes the
|
|
38
|
+
render projection decline the whole frame.
|
|
39
|
+
|
|
32
40
|
`pnpm budgets` rejects superseded raw constructs such as `new Audio(`, `Math.random(`,
|
|
33
41
|
`new Raycaster(`, `.visible = false`, and `new Box3().setFromObject(`; use the named capability or
|
|
34
42
|
annotate a genuinely necessary line with a non-empty `// engine-override: reason`.
|
|
@@ -5,14 +5,28 @@ description: Measure ThreeNative frame budgets and report platform evidence with
|
|
|
5
5
|
|
|
6
6
|
# ThreeNative performance evidence
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
8
|
+
Pool objects; load static GLBs through `ctx.assets.model()`; never claim Android/iOS from a
|
|
9
|
+
desktop proof. `TN_FRAME_BUDGET` reports `fps`, `hostGap`, `update`, `render`, `overlay`,
|
|
10
|
+
`residual` and per-pass draws and triangles. `defineGame({ frameBudget: false })` silences
|
|
11
|
+
output, never measurement.
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
## When the scene is the problem
|
|
14
|
+
|
|
15
|
+
`TN_SCENE_WARNING` fires when the GPU used under a third of a frame whose render phase overran
|
|
16
|
+
the display period: move draws and objects, not settings. `npx threenative doctor` and
|
|
17
|
+
`DEV_MODE=true` repeat it; `TN_FRAME_SPANS=1` splits that phase.
|
|
18
|
+
The largest static win is free — three skips per-object binding updates when nothing changed, so
|
|
19
|
+
not writing a transform saved 7.35 ms on 1,561 objects where `markStatic(root)` saved 0.009 ms.
|
|
20
|
+
|
|
21
|
+
## Use the shipped defaults
|
|
22
|
+
|
|
23
|
+
The engine prepares transforms, batches, culls, scales resolution and cooks assets;
|
|
24
|
+
read `agent-docs/performance-basics.md` before hand-rolling any.
|
|
25
|
+
Unexecuted platforms stay unverified; never invent numbers.
|
|
26
|
+
Withdraw thermally-confounded Tiers 1–3 comparisons; always report Tier 4. Bounded proof:
|
|
27
|
+
`{"performance":{"maxFrameMsP95":33,"minFps":30,"maxPhaseMsP95":{"render":12},"maxPassDrawCalls":{"shadow":400}}}`,
|
|
28
|
+
defined in `agent-docs/assertion-reference.md#performance`; pass bounds fail closed without a
|
|
29
|
+
per-pass split.
|
|
16
30
|
|
|
17
31
|
|Tier|Measure|Floor|Target|
|
|
18
32
|
|---|---|---:|---:|
|
|
@@ -37,6 +51,8 @@ fields are defined in `agent-docs/assertion-reference.md#performance`.
|
|
|
37
51
|
|4|Thermal-status|≤2|≤1|
|
|
38
52
|
|4|Whole-device-current|—|report;not-gated|
|
|
39
53
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
54
|
+
Android: budget a ~500 MiB driver floor before textures; a dual-use equirectangular
|
|
55
|
+
environment adds ~48 MiB: `agent-docs/mobile-memory-budget.md`.
|
|
56
|
+
|
|
57
|
+
Name the hot function: `--cpu-prof <file>` (native, or a browser/desktop playtest) writes a
|
|
58
|
+
DevTools `.cpuprofile`.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Project-scoped ponytail activation. Runs only where this file is installed: the engine repo
|
|
3
|
+
// and every project `create-threenative` generates. It injects the same ruleset on session,
|
|
4
|
+
// prompt and subagent start so the AGENTS.md rule cannot drift out of the model's context.
|
|
5
|
+
//
|
|
6
|
+
// It is deliberately small: no mode file, no statusline, no state written outside the project.
|
|
7
|
+
// `PONYTAIL=off` (or removing this hook) turns it off.
|
|
8
|
+
|
|
9
|
+
if (process.env.PONYTAIL === "off") process.exit(0);
|
|
10
|
+
|
|
11
|
+
const RULESET = [
|
|
12
|
+
"PONYTAIL MODE ACTIVE — laziest solution that actually works.",
|
|
13
|
+
"",
|
|
14
|
+
"Before writing code, stop at the first rung that holds (read the code the change touches first):",
|
|
15
|
+
"1. Does this need to exist? No -> skip it (YAGNI).",
|
|
16
|
+
"2. Already installed in the engine? Search `engine_search_capabilities` and inspect with `engine_capability_detail` — reuse the returned system. This rung IS the critical capability gate; a shipped node, convention, helper or subpath is the answer, never hand-write what it already does.",
|
|
17
|
+
"3. Already in this game? Reuse what is in `src/`.",
|
|
18
|
+
"4. Stdlib or engine convention (loadAll, addInSlices, GroundSnap, an input vector, a physics query)? Use it.",
|
|
19
|
+
"5. Already-installed dependency? Use it; add none for a few lines.",
|
|
20
|
+
"6. One line? One line.",
|
|
21
|
+
"7. Only then: the minimum code that works.",
|
|
22
|
+
"",
|
|
23
|
+
"No unrequested abstractions, no boilerplate, no scaffolding for later; deletion over addition; fewest files; shortest diff once you understand the problem. Bug fix = grep every caller and fix the shared function once. Code first, then at most three short lines (`[code] -> skipped: [X], add when [Y].`).",
|
|
24
|
+
"Never simplify away: understanding the problem, trust-boundary validation, error handling that prevents data loss, security, accessibility, anything explicitly requested, hardware calibration. Non-trivial logic leaves ONE runnable check behind — here that is a playtest scenario.",
|
|
25
|
+
'Off: "stop ponytail" / `PONYTAIL=off`. Full rules: `.claude/skills/ponytail/SKILL.md` or `.agents/skills/ponytail/SKILL.md`.',
|
|
26
|
+
].join("\n");
|
|
27
|
+
|
|
28
|
+
let stdin = "";
|
|
29
|
+
process.stdin.setEncoding("utf8");
|
|
30
|
+
process.stdin.on("data", (chunk) => {
|
|
31
|
+
stdin += chunk;
|
|
32
|
+
});
|
|
33
|
+
process.stdin.on("end", emit);
|
|
34
|
+
process.stdin.on("error", () => process.exit(0));
|
|
35
|
+
// Never hang a session, and never fail one: an unreadable skill or closed stdin exits quietly.
|
|
36
|
+
setTimeout(() => process.exit(0), 3000).unref();
|
|
37
|
+
|
|
38
|
+
function emit() {
|
|
39
|
+
let event = "SessionStart";
|
|
40
|
+
try {
|
|
41
|
+
event = JSON.parse(stdin || "{}").hook_event_name || event;
|
|
42
|
+
} catch {
|
|
43
|
+
// Malformed stdin still gets the ruleset; the event name only shapes the envelope.
|
|
44
|
+
}
|
|
45
|
+
process.stdout.write(
|
|
46
|
+
JSON.stringify({
|
|
47
|
+
hookSpecificOutput: { hookEventName: event, additionalContext: RULESET },
|
|
48
|
+
}),
|
|
49
|
+
);
|
|
50
|
+
process.exit(0);
|
|
51
|
+
}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
{
|
|
2
|
+
"hooks": {
|
|
3
|
+
"SessionStart": [
|
|
4
|
+
{
|
|
5
|
+
"hooks": [
|
|
6
|
+
{
|
|
7
|
+
"type": "command",
|
|
8
|
+
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/ponytail-context.mjs\"",
|
|
9
|
+
"timeout": 5,
|
|
10
|
+
"statusMessage": "Loading ponytail..."
|
|
11
|
+
}
|
|
12
|
+
]
|
|
13
|
+
}
|
|
14
|
+
],
|
|
15
|
+
"UserPromptSubmit": [
|
|
16
|
+
{
|
|
17
|
+
"hooks": [
|
|
18
|
+
{
|
|
19
|
+
"type": "command",
|
|
20
|
+
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/ponytail-context.mjs\"",
|
|
21
|
+
"timeout": 5
|
|
22
|
+
}
|
|
23
|
+
]
|
|
24
|
+
}
|
|
25
|
+
],
|
|
26
|
+
"SubagentStart": [
|
|
27
|
+
{
|
|
28
|
+
"hooks": [
|
|
29
|
+
{
|
|
30
|
+
"type": "command",
|
|
31
|
+
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/ponytail-context.mjs\"",
|
|
32
|
+
"timeout": 5
|
|
33
|
+
}
|
|
34
|
+
]
|
|
35
|
+
}
|
|
36
|
+
]
|
|
37
|
+
}
|
|
38
|
+
}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ponytail
|
|
3
|
+
description: >
|
|
4
|
+
Force the laziest solution that actually works: smallest, shortest, most minimal.
|
|
5
|
+
Use on any coding task in this game — writing, adding, refactoring, fixing,
|
|
6
|
+
reviewing, or picking a dependency — and whenever a request smells over-built
|
|
7
|
+
("simplest", "minimal", "yagni", "do less", "shortest path", "too much code",
|
|
8
|
+
"bloat", "boilerplate"). Adds YAGNI and reuse to the engine's capability-first
|
|
9
|
+
rule: never hand-write what an installed @threenative system already does.
|
|
10
|
+
Source: github.com/DietrichGebert/ponytail (MIT). Do NOT use for non-coding
|
|
11
|
+
requests (general knowledge, prose, translation, summaries, recipes).
|
|
12
|
+
argument-hint: "[off]"
|
|
13
|
+
license: MIT
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# Ponytail — lazy senior dev
|
|
17
|
+
|
|
18
|
+
You are a lazy senior developer. Lazy means efficient, not careless. The best code
|
|
19
|
+
is the code never written. Active every response; this project's hook re-injects the
|
|
20
|
+
ruleset every session and prompt, and `PONYTAIL=off` or "stop ponytail" turns it off.
|
|
21
|
+
|
|
22
|
+
## The ladder
|
|
23
|
+
|
|
24
|
+
Stop at the first rung that holds. The ladder runs *after* you understand the
|
|
25
|
+
problem, not instead of it: read the code the change touches and trace the real
|
|
26
|
+
flow end to end, then climb. Two rungs work → take the higher one and move on.
|
|
27
|
+
|
|
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?** Search `engine_search_capabilities` for the full request and each concrete mechanic, inspect hits with `engine_capability_detail`, and 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; never skip it because the task looks small, and never jump to hand-written code while it is unsearched.
|
|
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
|
+
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
|
+
5. **Already-installed dependency solves it?** Use it; never add a new one for what a few lines can do.
|
|
33
|
+
6. **Can it be one line?** One line.
|
|
34
|
+
7. **Only then:** the minimum code that works, in this game's `src/`.
|
|
35
|
+
|
|
36
|
+
## Rules
|
|
37
|
+
|
|
38
|
+
- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
|
|
39
|
+
- No boilerplate, no scaffolding "for later"; later can scaffold for itself. Deletion over addition. Boring over clever.
|
|
40
|
+
- Fewest files possible. Shortest working diff wins — but only once you understand the problem. The smallest change in the wrong place is a second bug.
|
|
41
|
+
- Complex request? Ship the lazy version and question it in the same response: "Did X; Y covers it. Need full X? Say so." Never stall on a question you can default.
|
|
42
|
+
- Two same-size options? Take the one correct on edge cases — lazy means less code, not the flimsier algorithm.
|
|
43
|
+
- Bug fix = root cause, not symptom: grep every caller of the function you touch and fix the shared one. One guard where all callers route through is smaller than a guard per caller, and patching only the path the ticket names leaves a sibling caller broken.
|
|
44
|
+
- Mark a deliberate corner cut with a `ponytail:` comment naming the ceiling and the upgrade path.
|
|
45
|
+
|
|
46
|
+
## Output
|
|
47
|
+
|
|
48
|
+
Code first. Then at most three short lines: what was skipped, when to add it.
|
|
49
|
+
Pattern: `[code] → skipped: [X], add when [Y].` No essays, no feature tours, no
|
|
50
|
+
design notes. Explanation the user explicitly asked for (a plan, a report, per-phase
|
|
51
|
+
notes) is not debt — give it in full.
|
|
52
|
+
|
|
53
|
+
## When NOT to be lazy
|
|
54
|
+
|
|
55
|
+
Never simplify away: understanding the problem (a small diff you do not understand is
|
|
56
|
+
just laziness dressed up as efficiency), input validation at trust boundaries, error
|
|
57
|
+
handling that prevents data loss, security, accessibility, anything explicitly
|
|
58
|
+
requested, and the calibration real hardware needs. Lazy code without its check is
|
|
59
|
+
unfinished: non-trivial logic leaves ONE runnable check behind — the smallest thing
|
|
60
|
+
that fails if the logic breaks. In this game the proof is a playtest scenario, never a
|
|
61
|
+
new test framework; trivial one-liners need no test.
|
|
62
|
+
|
|
63
|
+
## Boundaries
|
|
64
|
+
|
|
65
|
+
Ponytail governs what you build, not how you talk. "stop ponytail" / "normal mode" /
|
|
66
|
+
`PONYTAIL=off`: revert. Level persists until changed or session end.
|
|
67
|
+
|
|
68
|
+
The shortest path to done is the right path.
|
|
@@ -34,6 +34,14 @@ For a bespoke animated creature, follow `agent-docs/creating-creatures.md`. Call
|
|
|
34
34
|
visual review before delivery. `creature_status` distinguishes compile-only availability from
|
|
35
35
|
optional preview/check dependencies; an unavailable renderer is not approval.
|
|
36
36
|
|
|
37
|
+
For a humanoid that needs a skeleton or more motion, follow `agent-docs/rigging-characters.md`.
|
|
38
|
+
Inspect first with `asset_inspect_rig` (a local GLB or the pinned `aether-02` sample), auto-rig an
|
|
39
|
+
unrigged biped with `asset_auto_rig` (or pass explicit landmarks when it returns a correction
|
|
40
|
+
request), select donors with `asset_retarget_animations` (in-place by default; `root_motion` only
|
|
41
|
+
from the matching `_RM` donor), and confirm the result with `asset_preview_animation` on a
|
|
42
|
+
nonblank contact sheet before cooking. The 18-bone AETHER sample has no fingers or toes; the
|
|
43
|
+
tools report those absent roles instead of inventing them.
|
|
44
|
+
|
|
37
45
|
Choose the sculpt branch before coding: conventional → asset tools; trivial → portable geometry;
|
|
38
46
|
bespoke with a reference → `sculpt_plan`, `sculpt_spec_gate` until every region passes, one
|
|
39
47
|
factory per pass in `src/render/`, then `sculpt_compare` and `sculpt_pass_gate` against a real
|
|
@@ -14,6 +14,7 @@ The recipes are in `agent-docs/ctx-cookbook.md` and imports still require
|
|
|
14
14
|
| `ctx.goto("<scene-name>")` | hand reset | async scene rebuild |
|
|
15
15
|
| `ctx.tween(...)` | `Math.sin`/`lerp` accumulator | timed interpolation with optional `ease` |
|
|
16
16
|
| `ctx.after(...)` / `ctx.every(...)` | timer branches in `update` | disposable schedules |
|
|
17
|
+
| `ctx.beforeRender(fn)` | per-frame packing in `update` or an object `onBeforeRender` hook | one dispatch per actual world draw, after the last fixed step and before the projection; cleared like `ctx.afterPhysics` |
|
|
17
18
|
| `ctx.random.range(-1, 1)` | `Math.random()` | reproducible when `seed` is configured |
|
|
18
19
|
| `ctx.pointer.on(...)` / `ctx.pointer.drag(...)` | hover/press/drag bookkeeping | web/native pointer-id stream |
|
|
19
20
|
| `ctx.raycast()` / `ctx.raycastAll()` | `new Raycaster()` | backend-neutral intersections |
|
|
@@ -29,6 +30,13 @@ restart, `game.goto("<scene-name>")` from React resets declared initial state fi
|
|
|
29
30
|
uses `ctx.state.set({ /* copy this game's initial-state shape */ })` before the goto. `ctx.random` is
|
|
30
31
|
deterministic only when `defineGame({ seed })` is configured.
|
|
31
32
|
|
|
33
|
+
`ctx.beforeRender(fn)` runs once per actual world draw, after the frame's last fixed update and
|
|
34
|
+
before the projection reconciles, so `fn` reads the frame's final state; a held, loader-only frame
|
|
35
|
+
draws no world and dispatches nothing. It is cleared on scene change and stop, like
|
|
36
|
+
`ctx.afterPhysics`. Reach for it when the draw itself consumes per-frame CPU work — packing an
|
|
37
|
+
instanced batch, rebuilding a buffer — instead of an object `onBeforeRender` hook, which makes the
|
|
38
|
+
render projection decline the whole frame.
|
|
39
|
+
|
|
32
40
|
`pnpm budgets` rejects superseded raw constructs such as `new Audio(`, `Math.random(`,
|
|
33
41
|
`new Raycaster(`, `.visible = false`, and `new Box3().setFromObject(`; use the named capability or
|
|
34
42
|
annotate a genuinely necessary line with a non-empty `// engine-override: reason`.
|
|
@@ -5,14 +5,28 @@ description: Measure ThreeNative frame budgets and report platform evidence with
|
|
|
5
5
|
|
|
6
6
|
# ThreeNative performance evidence
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
8
|
+
Pool objects; load static GLBs through `ctx.assets.model()`; never claim Android/iOS from a
|
|
9
|
+
desktop proof. `TN_FRAME_BUDGET` reports `fps`, `hostGap`, `update`, `render`, `overlay`,
|
|
10
|
+
`residual` and per-pass draws and triangles. `defineGame({ frameBudget: false })` silences
|
|
11
|
+
output, never measurement.
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
## When the scene is the problem
|
|
14
|
+
|
|
15
|
+
`TN_SCENE_WARNING` fires when the GPU used under a third of a frame whose render phase overran
|
|
16
|
+
the display period: move draws and objects, not settings. `npx threenative doctor` and
|
|
17
|
+
`DEV_MODE=true` repeat it; `TN_FRAME_SPANS=1` splits that phase.
|
|
18
|
+
The largest static win is free — three skips per-object binding updates when nothing changed, so
|
|
19
|
+
not writing a transform saved 7.35 ms on 1,561 objects where `markStatic(root)` saved 0.009 ms.
|
|
20
|
+
|
|
21
|
+
## Use the shipped defaults
|
|
22
|
+
|
|
23
|
+
The engine prepares transforms, batches, culls, scales resolution and cooks assets;
|
|
24
|
+
read `agent-docs/performance-basics.md` before hand-rolling any.
|
|
25
|
+
Unexecuted platforms stay unverified; never invent numbers.
|
|
26
|
+
Withdraw thermally-confounded Tiers 1–3 comparisons; always report Tier 4. Bounded proof:
|
|
27
|
+
`{"performance":{"maxFrameMsP95":33,"minFps":30,"maxPhaseMsP95":{"render":12},"maxPassDrawCalls":{"shadow":400}}}`,
|
|
28
|
+
defined in `agent-docs/assertion-reference.md#performance`; pass bounds fail closed without a
|
|
29
|
+
per-pass split.
|
|
16
30
|
|
|
17
31
|
|Tier|Measure|Floor|Target|
|
|
18
32
|
|---|---|---:|---:|
|
|
@@ -37,6 +51,8 @@ fields are defined in `agent-docs/assertion-reference.md#performance`.
|
|
|
37
51
|
|4|Thermal-status|≤2|≤1|
|
|
38
52
|
|4|Whole-device-current|—|report;not-gated|
|
|
39
53
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
54
|
+
Android: budget a ~500 MiB driver floor before textures; a dual-use equirectangular
|
|
55
|
+
environment adds ~48 MiB: `agent-docs/mobile-memory-budget.md`.
|
|
56
|
+
|
|
57
|
+
Name the hot function: `--cpu-prof <file>` (native, or a browser/desktop playtest) writes a
|
|
58
|
+
DevTools `.cpuprofile`.
|