create-threenative 0.2.4 → 0.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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/README.md CHANGED
@@ -29,6 +29,28 @@ cd my-game
29
29
  npm install
30
30
  ```
31
31
 
32
+ ## Branding your game
33
+
34
+ The identity a player sees is yours, and it lives only in generated game files — never in a
35
+ package. Three surfaces carry it:
36
+
37
+ - `threenative.config.ts` — `app.name`, `app.icon` (and `app.icons` per platform), the desktop
38
+ `window.title`, and `bootSplash` for the launch background. `app.id` is the reverse-DNS identity
39
+ the installer and file manager show.
40
+ - `public/` — the images those fields point at. Replacing the scaffold's `public/icon.png` is what
41
+ stops a packaged app shipping the engine's default icon.
42
+ - `src/render/` — `loading.ts` owns the in-game loading appearance; every file there is generated
43
+ game source you can rewrite.
44
+
45
+ `threenative doctor --target desktop` reports which of those a desktop build actually resolves.
46
+
47
+ Once a desktop release container exists, inspect the brand it actually carries rather than the
48
+ config you meant to ship:
49
+ `node node_modules/@threenative/runtime-native/scripts/verify-starter-desktop.mjs --container <unpacked-directory> --config .threenative/build/config.json`.
50
+ It compares the launcher/file-manager name, the embedded icon bytes and the declared loading
51
+ sequence against that config, and refuses a container that still carries the engine's default icon
52
+ — which the scaffold's own `public/icon.png` is until you replace it.
53
+
32
54
  The published package declares those Node and pnpm minimums. Its asset pipeline reaches `sharp`
33
55
  through `@gltf-transform/functions` → `ndarray-pixels` → `sharp`; `@threenative/core` also brings
34
56
  the asset MCP's `sharp` copy. On a machine whose system has an incompatible global libvips, let
@@ -48,7 +70,7 @@ hidden by the install recipe.
48
70
  Inside a generated project, `npx threenative doctor --text` reports what would break a build:
49
71
  missing or version-mismatched `@threenative` packages, a portable entry with no default game
50
72
  export, no web entry, no scenario, no capability search for your agent. Naming the build you
51
- intend — `--target web|desktop|android|ios`, optionally with `--mode debug|release` — makes that
73
+ intend — `--target web|desktop|android|ios` (iOS is not a supported target yet), optionally with `--mode debug|release` — makes that
52
74
  build's prerequisites decide the verdict instead of warning beside "available".
53
75
 
54
76
  Tool discovery reports four separate facts, because three of them are routinely mistaken for the
@@ -452,7 +452,7 @@ Proves console, network, runtime, and readiness diagnostics stayed clean. **Use
452
452
 
453
453
  ### `performance`
454
454
 
455
- Proves a live render sample exists and optionally bounds frame time, an fps floor, per-phase frame budget, draw calls, and triangles. **Use when** that is the thing the scenario must prove.
455
+ Proves a live render sample exists and optionally bounds frame time, an fps floor, per-phase frame budget, whole-frame or per-pass draw calls and triangles. **Use when** that is the thing the scenario must prove.
456
456
 
457
457
  - **Supported on:** web, desktop, bevy · **Requires:** runtime.performance
458
458
 
@@ -462,12 +462,17 @@ Proves a live render sample exists and optionally bounds frame time, an fps floo
462
462
  | `minFps` | number | no |
463
463
  | `maxPhaseMsP95` | { [phase]: number } | no |
464
464
  | `maxDrawCalls` | number | no |
465
+ | `maxPassDrawCalls` | { [pass: 'main' | 'shadow' | 'reflection' | 'nested']: number } | no |
466
+ | `maxPassTriangles` | { [pass: 'main' | 'shadow' | 'reflection' | 'nested']: number } | no |
465
467
  | `maxTriangles` | number | no |
466
468
 
467
469
 
468
470
  ```json
469
471
  {
470
472
  "performance": {
473
+ "maxPassDrawCalls": {
474
+ "shadow": 400
475
+ },
471
476
  "maxPhaseMsP95": {
472
477
  "render": 12
473
478
  },
@@ -662,6 +667,40 @@ Proves animation evidence appeared in the effect log or runtime observation. **U
662
667
  }
663
668
  ```
664
669
 
670
+ ### `audio`
671
+
672
+ Proves which labelled audio cues the game actually played, and how often. Every other audio check
673
+ is about the *file* — it exists, it decodes, it is inside its budget — and all of them stay green
674
+ while a one-shot line sounds a second time mid-match. **Use when** that is the thing the scenario
675
+ must prove.
676
+
677
+ Label a cue by passing a cue name to the audio bus when the game plays it; unlabelled sounds are never counted.
678
+ When it fails, `observations.json/runtimeObservations/gameplay/audio/recentCues` says when each
679
+ play happened.
680
+
681
+ - **Supported on:** web, desktop · **Requires:** runtime.audio
682
+
683
+ | Field | Type | Required |
684
+ | --- | --- | --- |
685
+ | `cue` | string | yes |
686
+ | `minPlays` | non-negative integer (defaults to 1) | no |
687
+ | `maxPlays` | non-negative integer; 0 proves silence | no |
688
+ | `minGapMs` | non-negative integer; fewest ms since the line before it | no |
689
+
690
+
691
+ ```json
692
+ {
693
+ "audio": [
694
+ {
695
+ "cue": "speech:p01",
696
+ "minPlays": 1,
697
+ "maxPlays": 1,
698
+ "minGapMs": 500
699
+ }
700
+ ]
701
+ }
702
+ ```
703
+
665
704
  ### `scene`
666
705
 
667
706
  Bounds the room the game is played in — the lights, materials, fog and camera framing the renderer was handed. Fails closed on a bridge that does not report the scene. **Use when** that is the thing the scenario must prove.