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.
- 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
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-threenative",
|
|
3
|
-
"version": "0.2.
|
|
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.
|
|
81
|
-
"@threenative/
|
|
82
|
-
"@threenative/
|
|
83
|
-
"threenative-blender-mcp": "0.1.
|
|
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.
|
|
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..
|
|
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
|
-
@@ -
|
|
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 +
|
|
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
|
-
@@ -
|
|
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 +
|
|
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 +
|
|
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 +
|
|
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 +
|
|
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 +
|
|
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
|
-
@@ -
|
|
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
|
-
@@ -
|
|
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 +
|
|
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..
|
|
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..
|
|
476
|
+
index 676cc2bd4169427ed420f2467b1e6684bd2aeebc..72569d0339314d26eb7a35ff2a8462a803c852a6 100644
|
|
402
477
|
--- a/src/renderers/common/RenderObjects.js
|
|
403
478
|
+++ b/src/renderers/common/RenderObjects.js
|
|
404
|
-
@@ -
|
|
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 +
|
|
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..
|
|
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": "
|
|
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.
|
|
20
|
-
"@threenative/physics": "0.3.
|
|
21
|
-
"@threenative/ui": "0.3.
|
|
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.
|
|
30
|
-
"@threenative/playtest": "0.3.
|
|
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.
|
|
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.
|
|
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": "
|
|
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.
|
|
19
|
-
"@threenative/physics": "0.3.
|
|
20
|
-
"@threenative/ui": "0.3.
|
|
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.
|
|
29
|
-
"@threenative/playtest": "0.3.
|
|
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.
|
|
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.
|
|
42
|
+
"@threenative/runtime-native": "0.3.3"
|
|
43
43
|
},
|
|
44
44
|
"pnpm": {
|
|
45
45
|
"onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],
|