create-threenative 0.2.5 → 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.
Files changed (58) hide show
  1. package/README.md +23 -1
  2. package/agent-docs/references/assertion-reference.md +40 -1
  3. package/agent-docs/references/capability-reference.md +972 -66
  4. package/agent-docs/references/finding-assets.md +8 -1
  5. package/agent-docs/references/performance-basics.md +114 -0
  6. package/agent-docs/references/rigging-characters.md +51 -0
  7. package/agent-docs/references/webview-ui.md +3 -2
  8. package/agent-files/.agents/skills/ponytail/SKILL.md +68 -0
  9. package/agent-files/.agents/skills/threenative-assets/SKILL.md +8 -0
  10. package/agent-files/.agents/skills/threenative-context/SKILL.md +8 -0
  11. package/agent-files/.agents/skills/threenative-performance/SKILL.md +26 -10
  12. package/agent-files/.claude/hooks/ponytail-context.mjs +51 -0
  13. package/agent-files/.claude/settings.json +38 -0
  14. package/agent-files/.claude/skills/ponytail/SKILL.md +68 -0
  15. package/agent-files/.claude/skills/threenative-assets/SKILL.md +8 -0
  16. package/agent-files/.claude/skills/threenative-context/SKILL.md +8 -0
  17. package/agent-files/.claude/skills/threenative-performance/SKILL.md +26 -10
  18. package/agent-files/.codex/hooks.json +40 -0
  19. package/capabilities.json +1344 -88
  20. package/dist/index.d.ts +10 -1
  21. package/dist/index.js +186 -1
  22. package/dist/threenative.js +660 -150
  23. package/package.json +6 -6
  24. package/template-assets/patches/three@0.185.1.patch +179 -19
  25. package/templates/action-rpg/AGENTS.md +5 -5
  26. package/templates/action-rpg/CLAUDE.md +5 -5
  27. package/templates/action-rpg/package.json +8 -8
  28. package/templates/defense/AGENTS.md +5 -5
  29. package/templates/defense/CLAUDE.md +5 -5
  30. package/templates/defense/package.json +8 -8
  31. package/templates/minimal/AGENTS.md +5 -5
  32. package/templates/minimal/CLAUDE.md +5 -5
  33. package/templates/minimal/package.json +7 -7
  34. package/templates/minimal/threenative.config.ts +1 -0
  35. package/templates/platformer/AGENTS.md +5 -5
  36. package/templates/platformer/CLAUDE.md +5 -5
  37. package/templates/platformer/package.json +9 -9
  38. package/templates/puzzle/AGENTS.md +5 -5
  39. package/templates/puzzle/CLAUDE.md +5 -5
  40. package/templates/puzzle/package.json +8 -8
  41. package/templates/racing/AGENTS.md +5 -5
  42. package/templates/racing/CLAUDE.md +5 -5
  43. package/templates/racing/package.json +8 -8
  44. package/templates/runner/AGENTS.md +5 -5
  45. package/templates/runner/CLAUDE.md +5 -5
  46. package/templates/runner/package.json +8 -8
  47. package/templates/sailing/AGENTS.md +6 -6
  48. package/templates/sailing/CLAUDE.md +6 -6
  49. package/templates/sailing/package.json +8 -8
  50. package/templates/shooter/AGENTS.md +5 -5
  51. package/templates/shooter/CLAUDE.md +5 -5
  52. package/templates/shooter/package.json +8 -8
  53. package/templates/starter/AGENTS.md +8 -8
  54. package/templates/starter/CLAUDE.md +8 -8
  55. package/templates/starter/package.json +9 -9
  56. package/templates/starter/playtests/production-readiness.playtest.json +96 -0
  57. package/templates/starter/src/ui/Hud.tsx +2 -2
  58. package/templates/starter/src/ui/Menu.tsx +5 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-threenative",
3
- "version": "0.2.5",
3
+ "version": "0.2.6",
4
4
  "license": "MIT",
5
5
  "description": "Scaffold a readable ThreeNative game project.",
6
6
  "keywords": [
@@ -77,13 +77,13 @@
77
77
  "tsup": "8.5.1",
78
78
  "typescript": "5.9.3",
79
79
  "vite": "8.2.0",
80
- "@threenative/assets": "0.3.2",
81
- "@threenative/core": "0.3.2",
82
- "@threenative/physics": "0.3.2",
83
- "threenative-blender-mcp": "0.1.2"
80
+ "@threenative/assets": "0.3.3",
81
+ "@threenative/physics": "0.3.3",
82
+ "@threenative/core": "0.3.3",
83
+ "threenative-blender-mcp": "0.1.3"
84
84
  },
85
85
  "peerDependencies": {
86
- "@threenative/assets": ">=0.3.2 <0.4.0"
86
+ "@threenative/assets": ">=0.3.3 <0.4.0"
87
87
  },
88
88
  "scripts": {
89
89
  "build": "tsup --config tsup.config.ts && publint",
@@ -25,7 +25,7 @@ index 0bb9262cd029f411933d077fd44197a51ec5e8e9..868a634b4294be5f32664912a50813d5
25
25
  * Constructs a new batched mesh.
26
26
  *
27
27
  diff --git a/build/three.webgpu.js b/build/three.webgpu.js
28
- index 2e490796d4d4aa9479b04a5c46ddbf31cc05b1a1..d05599255744ccfca19dbfd0433da612583ce6ea 100644
28
+ index 2e490796d4d4aa9479b04a5c46ddbf31cc05b1a1..f7de72cffef2eb577abb0b90051a18392c88f865 100644
29
29
  --- a/build/three.webgpu.js
30
30
  +++ b/build/three.webgpu.js
31
31
  @@ -18500,7 +18500,8 @@ const instance = /*@__PURE__*/ Fn( ( [ matrices, colors = null ], builder ) => {
@@ -105,7 +105,25 @@ index 2e490796d4d4aa9479b04a5c46ddbf31cc05b1a1..d05599255744ccfca19dbfd0433da612
105
105
  /**
106
106
  * An event listener which is defined by `RenderObjects`. It performs
107
107
  * clean up tasks when `dispose()` on this render object.
108
- @@ -30707,9 +30736,18 @@ class RenderObjects {
108
+ @@ -30098,7 +30127,7 @@ class RenderObject {
109
+ */
110
+ getChainArray() {
111
+
112
+ - return [ this.object, this.material, this.context, this.lightsNode ];
113
+ + return [ this.object, this.material, this.context, this.lightsNode, this._sourceMaterial ?? this.material ];
114
+
115
+ }
116
+
117
+ @@ -30680,6 +30709,8 @@ class RenderObjects {
118
+ _chainKeys$3[ 1 ] = material;
119
+ _chainKeys$3[ 2 ] = renderContext;
120
+ _chainKeys$3[ 3 ] = lightsNode;
121
+ + // Material groups share the shadow override, but must retain separate GPU bindings.
122
+ + _chainKeys$3[ 4 ] = this.renderer._currentSourceMaterial ?? material;
123
+
124
+ //
125
+
126
+ @@ -30707,9 +30738,18 @@ class RenderObjects {
109
127
 
110
128
  }
111
129
 
@@ -118,15 +136,15 @@ index 2e490796d4d4aa9479b04a5c46ddbf31cc05b1a1..d05599255744ccfca19dbfd0433da612
118
136
  + const sourceTracked = sourceMaterial !== null && sourceMaterial !== undefined;
119
137
  + const sourceReplaced = sourceTracked && renderObject._sourceMaterial !== sourceMaterial;
120
138
  + const sourceChanged = sourceTracked && ( sourceReplaced || renderObject.sourceVersion !== sourceMaterial.version );
139
+ +
140
+ + if ( renderObject.version !== material.version || sourceChanged || renderObject.needsUpdate ) {
121
141
 
122
142
  - if ( renderObject.initialCacheKey !== renderObject.getCacheKey() ) {
123
- + if ( renderObject.version !== material.version || sourceChanged || renderObject.needsUpdate ) {
124
- +
125
143
  + if ( sourceReplaced || renderObject.initialCacheKey !== renderObject.getCacheKey() ) {
126
144
 
127
145
  renderObject.dispose();
128
146
 
129
- @@ -30719,6 +30757,8 @@ class RenderObjects {
147
+ @@ -30719,6 +30759,8 @@ class RenderObjects {
130
148
 
131
149
  renderObject.version = material.version;
132
150
 
@@ -135,7 +153,15 @@ index 2e490796d4d4aa9479b04a5c46ddbf31cc05b1a1..d05599255744ccfca19dbfd0433da612
135
153
  }
136
154
 
137
155
  }
138
- @@ -39725,7 +39765,8 @@ class VelocityNode extends TempNode {
156
+ @@ -30731,6 +30773,7 @@ class RenderObjects {
157
+ _chainKeys$3[ 1 ] = null;
158
+ _chainKeys$3[ 2 ] = null;
159
+ _chainKeys$3[ 3 ] = null;
160
+ + _chainKeys$3[ 4 ] = null;
161
+
162
+ //
163
+
164
+ @@ -39725,7 +39768,8 @@ class VelocityNode extends TempNode {
139
165
 
140
166
  const previousModelMatrix = getPreviousMatrix( object );
141
167
 
@@ -145,7 +171,7 @@ index 2e490796d4d4aa9479b04a5c46ddbf31cc05b1a1..d05599255744ccfca19dbfd0433da612
145
171
 
146
172
  //
147
173
 
148
- @@ -53841,7 +53882,7 @@ class NodeBuilder {
174
+ @@ -53841,7 +53885,7 @@ class NodeBuilder {
149
175
 
150
176
  const mrt = this.renderer.getMRT();
151
177
 
@@ -154,7 +180,7 @@ index 2e490796d4d4aa9479b04a5c46ddbf31cc05b1a1..d05599255744ccfca19dbfd0433da612
154
180
 
155
181
  }
156
182
 
157
- @@ -62731,6 +62772,7 @@ class Renderer {
183
+ @@ -62731,6 +62775,7 @@ class Renderer {
158
184
  let materialDisplacementMap;
159
185
  let materialDisplacementScale;
160
186
  let materialDisplacementBias;
@@ -162,7 +188,7 @@ index 2e490796d4d4aa9479b04a5c46ddbf31cc05b1a1..d05599255744ccfca19dbfd0433da612
162
188
 
163
189
  const previousSourceMaterial = this._currentSourceMaterial;
164
190
 
165
- @@ -62756,6 +62798,7 @@ class Renderer {
191
+ @@ -62756,6 +62801,7 @@ class Renderer {
166
192
  materialDisplacementMap = overrideMaterial.displacementMap;
167
193
  materialDisplacementScale = overrideMaterial.displacementScale;
168
194
  materialDisplacementBias = overrideMaterial.displacementBias;
@@ -170,7 +196,7 @@ index 2e490796d4d4aa9479b04a5c46ddbf31cc05b1a1..d05599255744ccfca19dbfd0433da612
170
196
 
171
197
  if ( material.positionNode && material.positionNode.isNode ) {
172
198
 
173
- @@ -62763,7 +62806,15 @@ class Renderer {
199
+ @@ -62763,7 +62809,15 @@ class Renderer {
174
200
 
175
201
  }
176
202
 
@@ -187,7 +213,7 @@ index 2e490796d4d4aa9479b04a5c46ddbf31cc05b1a1..d05599255744ccfca19dbfd0433da612
187
213
  overrideMaterial.alphaMap = material.alphaMap;
188
214
  overrideMaterial.displacementMap = material.displacementMap;
189
215
  overrideMaterial.displacementScale = material.displacementScale;
190
- @@ -62825,6 +62876,7 @@ class Renderer {
216
+ @@ -62825,6 +62879,7 @@ class Renderer {
191
217
  scene.overrideMaterial.displacementMap = materialDisplacementMap;
192
218
  scene.overrideMaterial.displacementScale = materialDisplacementScale;
193
219
  scene.overrideMaterial.displacementBias = materialDisplacementBias;
@@ -195,7 +221,31 @@ index 2e490796d4d4aa9479b04a5c46ddbf31cc05b1a1..d05599255744ccfca19dbfd0433da612
195
221
 
196
222
  }
197
223
 
198
- @@ -79586,7 +79638,8 @@ class WGSLNodeBuilder extends NodeBuilder {
224
+ @@ -78999,15 +78999,22 @@ class WGSLNodeBuilder extends NodeBuilder {
225
+ let snippet;
226
+
227
+ if ( depthSnippet ) {
228
+
229
+ snippet = `textureLoad( ${ textureProperty }, ${ uvIndexSnippet }, ${ depthSnippet }, u32( ${ levelSnippet } ) )`;
230
+
231
+ } else {
232
+
233
+ - snippet = `textureLoad( ${ textureProperty }, ${ uvIndexSnippet }, u32( ${ levelSnippet } ) )`;
234
+ + // naga v25 (wgpu-native v25.0.2.2) rejects a u32 sample index on a
235
+ + // multisampled textureLoad; i32 is accepted by every backend. Mip-level
236
+ + // operands (including the array form above) stay u32.
237
+ + const sampleData = texture ? this.renderer?.backend?.utils?.getTextureSampleData?.( texture ) : null;
238
+ + const backendMultisampled = sampleData !== null && sampleData !== undefined && sampleData.primarySamples > 1;
239
+ + const targetMultisampled = Boolean( texture && texture.renderTarget && texture.renderTarget.samples > 1 );
240
+ + const indexType = ( backendMultisampled || targetMultisampled ) ? 'i32' : 'u32';
241
+ + snippet = `textureLoad( ${ textureProperty }, ${ uvIndexSnippet }, ${ indexType }( ${ levelSnippet } ) )`;
242
+
243
+ if ( this.renderer.backend.compatibilityMode && texture.isDepthTexture ) {
244
+
245
+ snippet += '.x';
246
+
247
+ }
248
+ @@ -79586,7 +79641,8 @@ class WGSLNodeBuilder extends NodeBuilder {
199
249
 
200
250
  uniformGPU = buffer;
201
251
 
@@ -205,7 +255,23 @@ index 2e490796d4d4aa9479b04a5c46ddbf31cc05b1a1..d05599255744ccfca19dbfd0433da612
205
255
 
206
256
  } else {
207
257
 
208
- @@ -83814,6 +83867,14 @@ class WebGPUBackend extends Backend {
258
+ @@ -80329,9 +80385,12 @@ ${ flowData.code }
259
+ const textureNode = uniform.node;
260
+ const texture = textureNode.value;
261
+
262
+ - // Cube textures always need samplers (they use textureSampleLevel, not textureLoad)
263
+ - // Also textureGather always need sampler.
264
+ - const needsSampler = texture.isCubeTexture === true || ( this.isUnfilterable( texture ) === false && textureNode.isStorageTextureNode !== true ) || textureNode.gatherNode !== null;
265
+ + // The bind group layout freezes sampler inclusion once, in getUniformFromNode
266
+ + // (nodeData.uniformGPU). Re-deriving it here from live texture filter state can
267
+ + // disagree with that layout and shift every later binding index.
268
+ + const nodeData = this.getDataFromNode( textureNode, shaderStage, this.globalCache );
269
+ + const uniformGPU = nodeData.uniformGPU;
270
+ + const needsSampler = Array.isArray( uniformGPU ) && uniformGPU[ 0 ].isSampler === true && uniformGPU[ 0 ].isSampledTexture !== true;
271
+
272
+ if ( needsSampler ) {
273
+
274
+ @@ -83814,6 +83873,14 @@ class WebGPUBackend extends Backend {
209
275
  */
210
276
  this.compatibilityMode = null;
211
277
 
@@ -220,7 +286,7 @@ index 2e490796d4d4aa9479b04a5c46ddbf31cc05b1a1..d05599255744ccfca19dbfd0433da612
220
286
  /**
221
287
  * A reference to the device.
222
288
  *
223
- @@ -83926,7 +83987,9 @@ class WebGPUBackend extends Backend {
289
+ @@ -83926,7 +83993,9 @@ class WebGPUBackend extends Backend {
224
290
  xrCompatible: renderer.xr.enabled
225
291
  };
226
292
 
@@ -375,7 +441,7 @@ index 5f3d213a016b37db3b2e5d022da3dd0234d86f6d..7a9a168f29773f37ef9a51ef9f07ade9
375
441
 
376
442
  } else if ( binding.isStorageBuffer ) {
377
443
  diff --git a/src/renderers/common/RenderObject.js b/src/renderers/common/RenderObject.js
378
- index c900fa4c9654f8cf3512e96de52a2c1c83e189a6..d0a87eabffc8f667ebe9b2f0eccda0ddf3309652 100644
444
+ index c900fa4c9654f8cf3512e96de52a2c1c83e189a6..3a8b0012abf054f50ab66466bab7efa16fe1bc09 100644
379
445
  --- a/src/renderers/common/RenderObject.js
380
446
  +++ b/src/renderers/common/RenderObject.js
381
447
  @@ -299,6 +299,18 @@ class RenderObject {
@@ -397,11 +463,29 @@ index c900fa4c9654f8cf3512e96de52a2c1c83e189a6..d0a87eabffc8f667ebe9b2f0eccda0dd
397
463
  /**
398
464
  * An event listener which is defined by `RenderObjects`. It performs
399
465
  * clean up tasks when `dispose()` on this render object.
466
+ @@ -486,7 +498,7 @@ class RenderObject {
467
+ */
468
+ getChainArray() {
469
+
470
+ - return [ this.object, this.material, this.context, this.lightsNode ];
471
+ + return [ this.object, this.material, this.context, this.lightsNode, this._sourceMaterial ?? this.material ];
472
+
473
+ }
474
+
400
475
  diff --git a/src/renderers/common/RenderObjects.js b/src/renderers/common/RenderObjects.js
401
- index 676cc2bd4169427ed420f2467b1e6684bd2aeebc..0fa661db793548254a15ff43f39207abcc43ef49 100644
476
+ index 676cc2bd4169427ed420f2467b1e6684bd2aeebc..72569d0339314d26eb7a35ff2a8462a803c852a6 100644
402
477
  --- a/src/renderers/common/RenderObjects.js
403
478
  +++ b/src/renderers/common/RenderObjects.js
404
- @@ -124,9 +124,18 @@ class RenderObjects {
479
+ @@ -97,6 +97,8 @@ class RenderObjects {
480
+ _chainKeys[ 1 ] = material;
481
+ _chainKeys[ 2 ] = renderContext;
482
+ _chainKeys[ 3 ] = lightsNode;
483
+ + // Material groups share the shadow override, but must retain separate GPU bindings.
484
+ + _chainKeys[ 4 ] = this.renderer._currentSourceMaterial ?? material;
485
+
486
+ //
487
+
488
+ @@ -124,9 +126,18 @@ class RenderObjects {
405
489
 
406
490
  }
407
491
 
@@ -422,7 +506,7 @@ index 676cc2bd4169427ed420f2467b1e6684bd2aeebc..0fa661db793548254a15ff43f39207ab
422
506
 
423
507
  renderObject.dispose();
424
508
 
425
- @@ -136,6 +145,8 @@ class RenderObjects {
509
+ @@ -136,6 +147,8 @@ class RenderObjects {
426
510
 
427
511
  renderObject.version = material.version;
428
512
 
@@ -431,6 +515,14 @@ index 676cc2bd4169427ed420f2467b1e6684bd2aeebc..0fa661db793548254a15ff43f39207ab
431
515
  }
432
516
 
433
517
  }
518
+ @@ -148,6 +161,7 @@ class RenderObjects {
519
+ _chainKeys[ 1 ] = null;
520
+ _chainKeys[ 2 ] = null;
521
+ _chainKeys[ 3 ] = null;
522
+ + _chainKeys[ 4 ] = null;
523
+
524
+ //
525
+
434
526
  diff --git a/src/renderers/common/Renderer.js b/src/renderers/common/Renderer.js
435
527
  index 8dfc2ae055ad7b9d4c00e91f7d52a39e747caebe..e9d27b3ddad3b1f080a717d1f6683b60afd2b259 100644
436
528
  --- a/src/renderers/common/Renderer.js
@@ -507,9 +599,33 @@ index 06e203693ed9b168a2bddf773cd8ce8dc23196e4..37b5e0be09967e8acbd38e570b71eb20
507
599
  if ( adapter === null ) {
508
600
 
509
601
  diff --git a/src/renderers/webgpu/nodes/WGSLNodeBuilder.js b/src/renderers/webgpu/nodes/WGSLNodeBuilder.js
510
- index be07536301cd47ef2544e4a54f6abe17407f52af..6144b98ddeb5d53c5cf280bb51401385a4427547 100644
602
+ index be07536301cd47ef2544e4a54f6abe17407f52af..3b064a25a73fb35bcaed653794bda420bb004dec 100644
511
603
  --- a/src/renderers/webgpu/nodes/WGSLNodeBuilder.js
512
604
  +++ b/src/renderers/webgpu/nodes/WGSLNodeBuilder.js
605
+ @@ -736,15 +736,22 @@ generateTextureLoad( texture, textureProperty, uvIndexSnippet, levelSnippet, depthSnippet, offsetSnippet ) {
606
+ let snippet;
607
+
608
+ if ( depthSnippet ) {
609
+
610
+ snippet = `textureLoad( ${ textureProperty }, ${ uvIndexSnippet }, ${ depthSnippet }, u32( ${ levelSnippet } ) )`;
611
+
612
+ } else {
613
+
614
+ - snippet = `textureLoad( ${ textureProperty }, ${ uvIndexSnippet }, u32( ${ levelSnippet } ) )`;
615
+ + // naga v25 (wgpu-native v25.0.2.2) rejects a u32 sample index on a
616
+ + // multisampled textureLoad; i32 is accepted by every backend. Mip-level
617
+ + // operands (including the array form above) stay u32.
618
+ + const sampleData = texture ? this.renderer?.backend?.utils?.getTextureSampleData?.( texture ) : null;
619
+ + const backendMultisampled = sampleData !== null && sampleData !== undefined && sampleData.primarySamples > 1;
620
+ + const targetMultisampled = Boolean( texture && texture.renderTarget && texture.renderTarget.samples > 1 );
621
+ + const indexType = ( backendMultisampled || targetMultisampled ) ? 'i32' : 'u32';
622
+ + snippet = `textureLoad( ${ textureProperty }, ${ uvIndexSnippet }, ${ indexType }( ${ levelSnippet } ) )`;
623
+
624
+ if ( this.renderer.backend.compatibilityMode && texture.isDepthTexture ) {
625
+
626
+ snippet += '.x';
627
+
628
+ }
513
629
  @@ -1323,7 +1323,8 @@ class WGSLNodeBuilder extends NodeBuilder {
514
630
 
515
631
  uniformGPU = buffer;
@@ -520,3 +636,47 @@ index be07536301cd47ef2544e4a54f6abe17407f52af..6144b98ddeb5d53c5cf280bb51401385
520
636
 
521
637
  } else {
522
638
 
639
+ @@ -2066,9 +2067,12 @@ ${ flowData.code }
640
+ const textureNode = uniform.node;
641
+ const texture = textureNode.value;
642
+
643
+ - // Cube textures always need samplers (they use textureSampleLevel, not textureLoad)
644
+ - // Also textureGather always need sampler.
645
+ - const needsSampler = texture.isCubeTexture === true || ( this.isUnfilterable( texture ) === false && textureNode.isStorageTextureNode !== true ) || textureNode.gatherNode !== null;
646
+ + // The bind group layout freezes sampler inclusion once, in getUniformFromNode
647
+ + // (nodeData.uniformGPU). Re-deriving it here from live texture filter state can
648
+ + // disagree with that layout and shift every later binding index.
649
+ + const nodeData = this.getDataFromNode( textureNode, shaderStage, this.globalCache );
650
+ + const uniformGPU = nodeData.uniformGPU;
651
+ + const needsSampler = Array.isArray( uniformGPU ) && uniformGPU[ 0 ].isSampler === true && uniformGPU[ 0 ].isSampledTexture !== true;
652
+
653
+ if ( needsSampler ) {
654
+
655
+ diff --git a/build/three.webgpu.nodes.js b/build/three.webgpu.nodes.js
656
+ index f707acc24f5711fdae065ce920b08435b0869c1b..4c679d417f79af7994f296c005fcfaf3416c3f7a 100644
657
+ --- a/build/three.webgpu.nodes.js
658
+ +++ b/build/three.webgpu.nodes.js
659
+ @@ -78999,15 +78999,22 @@ class WGSLNodeBuilder extends NodeBuilder {
660
+ let snippet;
661
+
662
+ if ( depthSnippet ) {
663
+
664
+ snippet = `textureLoad( ${ textureProperty }, ${ uvIndexSnippet }, ${ depthSnippet }, u32( ${ levelSnippet } ) )`;
665
+
666
+ } else {
667
+
668
+ - snippet = `textureLoad( ${ textureProperty }, ${ uvIndexSnippet }, u32( ${ levelSnippet } ) )`;
669
+ + // naga v25 (wgpu-native v25.0.2.2) rejects a u32 sample index on a
670
+ + // multisampled textureLoad; i32 is accepted by every backend. Mip-level
671
+ + // operands (including the array form above) stay u32.
672
+ + const sampleData = texture ? this.renderer?.backend?.utils?.getTextureSampleData?.( texture ) : null;
673
+ + const backendMultisampled = sampleData !== null && sampleData !== undefined && sampleData.primarySamples > 1;
674
+ + const targetMultisampled = Boolean( texture && texture.renderTarget && texture.renderTarget.samples > 1 );
675
+ + const indexType = ( backendMultisampled || targetMultisampled ) ? 'i32' : 'u32';
676
+ + snippet = `textureLoad( ${ textureProperty }, ${ uvIndexSnippet }, ${ indexType }( ${ levelSnippet } ) )`;
677
+
678
+ if ( this.renderer.backend.compatibilityMode && texture.isDepthTexture ) {
679
+
680
+ snippet += '.x';
681
+
682
+ }
@@ -5,13 +5,13 @@ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit
5
5
  ## Ownership
6
6
 
7
7
  ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the dungeon, combat, stats, inventory, persistence, and every
8
- visual decision; `src/game.ts` stays portable and `src/main.ts` is the web-only React mount.
8
+ visual decision; `src/game.ts` stays portable and `src/main.ts` is the web-only React mount. 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. 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.
9
9
 
10
10
  ## Start every change
11
11
 
12
12
  1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
13
13
  `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
14
- matches with `engine_capability_detail`, and record a capability or no-match for the plan.
14
+ matches with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
15
15
  2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
16
16
  direct the user to review it, and wait for explicit approval plus an instruction to implement it.
17
17
  3. Treat returned constraints as binding. `@threenative/physics/navigation` is a browser-only
@@ -35,7 +35,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
35
35
  - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
36
36
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
37
37
  - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
38
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
38
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
39
39
 
40
40
  ## Commands and map
41
41
 
@@ -88,8 +88,8 @@ VFX appearance belongs in `src/render/vfx.ts`: keep its TSL material, geometry,
88
88
  Edit game-owned `src/render/` directly. `src/render/quality.ts` defines `low`, `medium`, and
89
89
  `high`; `isMobile()` selects `low`, otherwise `high`, and `setupPost(..., { tier: "low" })` is the
90
90
  named override. Unknown tiers throw and `TN_QUALITY_TIER` reports the chosen source. A scenario
91
- with no assertions or missing observations fails; keep the durable smoke proof and open a capture.
91
+ with no assertions or missing observations fails; keep the durable smoke proof and open a capture. 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. 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. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it beside the frame rate; `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. 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. 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.
92
92
 
93
- Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
93
+ Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/performance-basics.md`, `agent-docs/rigging-characters.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
94
94
  ## Optional multiplayer transport
95
95
  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`.
@@ -7,13 +7,13 @@ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit
7
7
  ## Ownership
8
8
 
9
9
  ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the dungeon, combat, stats, inventory, persistence, and every
10
- visual decision; `src/game.ts` stays portable and `src/main.ts` is the web-only React mount.
10
+ visual decision; `src/game.ts` stays portable and `src/main.ts` is the web-only React mount. 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. 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.
11
11
 
12
12
  ## Start every change
13
13
 
14
14
  1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
15
15
  `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
16
- matches with `engine_capability_detail`, and record a capability or no-match for the plan.
16
+ matches with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
17
17
  2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
18
18
  direct the user to review it, and wait for explicit approval plus an instruction to implement it.
19
19
  3. Treat returned constraints as binding. `@threenative/physics/navigation` is a browser-only
@@ -37,7 +37,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
37
37
  - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
38
38
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
39
39
  - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
40
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
40
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
41
41
 
42
42
  ## Commands and map
43
43
 
@@ -90,8 +90,8 @@ VFX appearance belongs in `src/render/vfx.ts`: keep its TSL material, geometry,
90
90
  Edit game-owned `src/render/` directly. `src/render/quality.ts` defines `low`, `medium`, and
91
91
  `high`; `isMobile()` selects `low`, otherwise `high`, and `setupPost(..., { tier: "low" })` is the
92
92
  named override. Unknown tiers throw and `TN_QUALITY_TIER` reports the chosen source. A scenario
93
- with no assertions or missing observations fails; keep the durable smoke proof and open a capture.
93
+ with no assertions or missing observations fails; keep the durable smoke proof and open a capture. 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. 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. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it beside the frame rate; `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. 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. 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.
94
94
 
95
- Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
95
+ Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/performance-basics.md`, `agent-docs/rigging-characters.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
96
96
  ## Optional multiplayer transport
97
97
  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`.
@@ -12,13 +12,13 @@
12
12
  "build:ios": "threenative build --target ios",
13
13
  "test:native": "pnpm build:desktop && node node_modules/@threenative/runtime-native/scripts/verify-starter-desktop.mjs",
14
14
  "pretest": "playwright install chromium",
15
- "test": "vite build && threenative-playtest --scenario \"playtests/*.playtest.json\" --browser-recipe webgpu --headed --server-command \"pnpm dev --host 127.0.0.1 --port $PORT --strictPort\"",
15
+ "test": "pnpm build:web && threenative-playtest --scenario \"playtests/*.playtest.json\" --browser-recipe webgpu --headed --server-command \"pnpm exec vite preview --host 127.0.0.1 --port $PORT --strictPort\"",
16
16
  "typecheck": "tsc --noEmit -p tsconfig.json"
17
17
  },
18
18
  "dependencies": {
19
- "@threenative/core": "0.3.2",
20
- "@threenative/physics": "0.3.2",
21
- "@threenative/ui": "0.3.2",
19
+ "@threenative/core": "0.3.3",
20
+ "@threenative/physics": "0.3.3",
21
+ "@threenative/ui": "0.3.3",
22
22
  "react": "19.2.0",
23
23
  "react-dom": "19.2.0",
24
24
  "three": "0.185.1"
@@ -26,13 +26,13 @@
26
26
  "devDependencies": {
27
27
  "@gltf-transform/cli": "4.4.2",
28
28
  "@tailwindcss/vite": "4.3.3",
29
- "@threenative/assets": "0.3.2",
30
- "@threenative/playtest": "0.3.2",
29
+ "@threenative/assets": "0.3.3",
30
+ "@threenative/playtest": "0.3.3",
31
31
  "@types/react": "19.2.0",
32
32
  "@types/react-dom": "19.2.0",
33
33
  "@types/three": "0.185.3",
34
34
  "@vitejs/plugin-react": "6.0.5",
35
- "create-threenative": "0.2.5",
35
+ "create-threenative": "0.2.6",
36
36
  "esbuild": "0.27.0",
37
37
  "playwright": "1.62.1",
38
38
  "tailwindcss": "4.3.3",
@@ -40,7 +40,7 @@
40
40
  "vite": "8.2.0"
41
41
  },
42
42
  "optionalDependencies": {
43
- "@threenative/runtime-native": "0.3.2"
43
+ "@threenative/runtime-native": "0.3.3"
44
44
  },
45
45
  "pnpm": {
46
46
  "onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],
@@ -5,13 +5,13 @@ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit
5
5
  ## Ownership
6
6
 
7
7
  ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the route, attackers, towers, economy, waves, HUD, and look;
8
- `src/game.ts` is portable and React mounts only from `src/main.ts`.
8
+ `src/game.ts` is portable and React mounts only from `src/main.ts`. 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. 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.
9
9
 
10
10
  ## Start every change
11
11
 
12
12
  1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
13
13
  `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
14
- matches with `engine_capability_detail`, and record a capability or no-match for the plan.
14
+ matches with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
15
15
  2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
16
16
  direct the user to review it, and wait for explicit approval plus an instruction to implement it.
17
17
  3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
@@ -37,7 +37,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
37
37
  - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
38
38
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
39
39
  - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
40
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
40
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
41
41
 
42
42
  ## Commands and map
43
43
 
@@ -86,8 +86,8 @@ Reference-driven authoring starts at `agent-docs/dream-loop.md`.
86
86
  Edit `src/render/` directly; `postprocessing.ts` reports stages but decides no game colour. Quality
87
87
  tiers live in `src/render/quality.ts`: `low`, `medium`, `high`; `isMobile()` chooses `low`, otherwise
88
88
  `high`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER`
89
- reports the source. A scenario with no assertions or missing observations fails; open a real capture.
89
+ reports the source. A scenario with no assertions or missing observations fails; open a real capture. 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. 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. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it beside the frame rate; `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. 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. 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.
90
90
 
91
- Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
91
+ Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/performance-basics.md`, `agent-docs/rigging-characters.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
92
92
  ## Optional multiplayer transport
93
93
  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`.
@@ -7,13 +7,13 @@ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit
7
7
  ## Ownership
8
8
 
9
9
  ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the route, attackers, towers, economy, waves, HUD, and look;
10
- `src/game.ts` is portable and React mounts only from `src/main.ts`.
10
+ `src/game.ts` is portable and React mounts only from `src/main.ts`. 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. 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.
11
11
 
12
12
  ## Start every change
13
13
 
14
14
  1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
15
15
  `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
16
- matches with `engine_capability_detail`, and record a capability or no-match for the plan.
16
+ matches with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
17
17
  2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
18
18
  direct the user to review it, and wait for explicit approval plus an instruction to implement it.
19
19
  3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
@@ -39,7 +39,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
39
39
  - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
40
40
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
41
41
  - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
42
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
42
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
43
43
 
44
44
  ## Commands and map
45
45
 
@@ -88,8 +88,8 @@ Reference-driven authoring starts at `agent-docs/dream-loop.md`.
88
88
  Edit `src/render/` directly; `postprocessing.ts` reports stages but decides no game colour. Quality
89
89
  tiers live in `src/render/quality.ts`: `low`, `medium`, `high`; `isMobile()` chooses `low`, otherwise
90
90
  `high`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER`
91
- reports the source. A scenario with no assertions or missing observations fails; open a real capture.
91
+ reports the source. A scenario with no assertions or missing observations fails; open a real capture. 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. 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. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it beside the frame rate; `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. 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. 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.
92
92
 
93
- Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
93
+ Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/performance-basics.md`, `agent-docs/rigging-characters.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
94
94
  ## Optional multiplayer transport
95
95
  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`.
@@ -11,13 +11,13 @@
11
11
  "build:android": "threenative build --target android",
12
12
  "build:ios": "threenative build --target ios",
13
13
  "pretest": "playwright install chromium",
14
- "test": "vite build && threenative-playtest --scenario \"playtests/*.playtest.json\" --browser-recipe webgpu --headed --server-command \"pnpm dev --host 127.0.0.1 --port $PORT --strictPort\"",
14
+ "test": "pnpm build:web && threenative-playtest --scenario \"playtests/*.playtest.json\" --browser-recipe webgpu --headed --server-command \"pnpm exec vite preview --host 127.0.0.1 --port $PORT --strictPort\"",
15
15
  "typecheck": "tsc --noEmit -p tsconfig.json"
16
16
  },
17
17
  "dependencies": {
18
- "@threenative/core": "0.3.2",
19
- "@threenative/physics": "0.3.2",
20
- "@threenative/ui": "0.3.2",
18
+ "@threenative/core": "0.3.3",
19
+ "@threenative/physics": "0.3.3",
20
+ "@threenative/ui": "0.3.3",
21
21
  "react": "19.2.0",
22
22
  "react-dom": "19.2.0",
23
23
  "three": "0.185.1"
@@ -25,13 +25,13 @@
25
25
  "devDependencies": {
26
26
  "@gltf-transform/cli": "4.4.2",
27
27
  "@tailwindcss/vite": "4.3.3",
28
- "@threenative/assets": "0.3.2",
29
- "@threenative/playtest": "0.3.2",
28
+ "@threenative/assets": "0.3.3",
29
+ "@threenative/playtest": "0.3.3",
30
30
  "@types/react": "19.2.0",
31
31
  "@types/react-dom": "19.2.0",
32
32
  "@types/three": "0.185.3",
33
33
  "@vitejs/plugin-react": "6.0.5",
34
- "create-threenative": "0.2.5",
34
+ "create-threenative": "0.2.6",
35
35
  "esbuild": "0.27.0",
36
36
  "playwright": "1.62.1",
37
37
  "tailwindcss": "4.3.3",
@@ -39,7 +39,7 @@
39
39
  "vite": "8.2.0"
40
40
  },
41
41
  "optionalDependencies": {
42
- "@threenative/runtime-native": "0.3.2"
42
+ "@threenative/runtime-native": "0.3.3"
43
43
  },
44
44
  "pnpm": {
45
45
  "onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],