create-threenative 0.2.1 → 0.2.3
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/LICENSE +21 -0
- package/README.md +10 -2
- package/agent-docs/asset-mcp-loop.md +33 -0
- package/agent-docs/ctx-surface.md +69 -0
- package/agent-docs/engine-capabilities.md +4 -0
- package/agent-docs/framework-blocks-you.md +60 -0
- package/agent-docs/look-at-it-and-budget-the-look.md +27 -0
- package/agent-docs/performance-default.md +42 -0
- package/agent-docs/pixel-budget.md +20 -0
- package/agent-docs/playtest-fail-closed.md +23 -0
- package/agent-docs/references/assertion-reference.md +652 -0
- package/agent-docs/references/capability-reference.md +3279 -0
- package/agent-docs/references/capture-the-frame.md +53 -0
- package/agent-docs/references/ctx-cookbook.md +51 -0
- package/agent-docs/references/debug-surface.md +63 -0
- package/agent-docs/references/finding-assets.md +147 -0
- package/agent-docs/references/gameplay-recipes.md +54 -0
- package/agent-docs/references/menu-screens.md +69 -0
- package/agent-docs/references/mobile-memory-budget.md +87 -0
- package/agent-docs/references/sculpt-from-a-reference.md +39 -0
- package/agent-docs/references/visual-baseline.md +133 -0
- package/agent-docs/references/webview-ui.md +113 -0
- package/agent-docs/sculpt-loop.md +16 -0
- package/agent-files/.agents/skills/threenative-builder/SKILL.md +7 -0
- package/agent-files/.agents/skills/threenative-verifier/SKILL.md +7 -0
- package/agent-files/.claude/agents/threenative-builder.md +7 -0
- package/agent-files/.claude/agents/threenative-verifier.md +7 -0
- package/agent-files/.threenative/agents/builder.md +32 -0
- package/agent-files/.threenative/agents/verifier.md +31 -0
- package/agent-files/AGENT-ROLES.md +26 -0
- package/capabilities.json +3542 -0
- package/dist/index.d.ts +191 -3
- package/dist/index.js +1707 -73
- package/dist/threenative.d.ts +9 -2
- package/dist/threenative.js +1825 -148
- package/package.json +30 -6
- package/template-assets/loading.ts +315 -0
- package/template-assets/patches/three@0.185.1.patch +287 -0
- package/templates/action-rpg/.codex/config.toml +15 -0
- package/templates/action-rpg/.mcp.json +6 -2
- package/templates/action-rpg/AGENTS.md +370 -6
- package/templates/action-rpg/CLAUDE.md +370 -6
- package/templates/action-rpg/index.html +0 -1
- package/templates/action-rpg/package.json +15 -11
- package/templates/action-rpg/playtests/combat.playtest.json +23 -9
- package/templates/action-rpg/playtests/fail.playtest.json +3 -3
- package/templates/action-rpg/playtests/inventory.playtest.json +16 -10
- package/templates/action-rpg/playtests/performance.playtest.json +22 -0
- package/templates/action-rpg/playtests/progress.playtest.json +18 -13
- package/templates/action-rpg/playtests/win.playtest.json +10 -4
- package/templates/action-rpg/public/icon.png +0 -0
- package/templates/action-rpg/src/entities/Enemy.ts +14 -4
- package/templates/action-rpg/src/game.ts +21 -0
- package/templates/action-rpg/src/render/lighting.ts +6 -1
- package/templates/action-rpg/src/render/loading.ts +267 -42
- package/templates/action-rpg/src/render/postprocessing.ts +68 -15
- package/templates/action-rpg/src/render/worldEnvironment.ts +583 -0
- package/templates/action-rpg/src/scenes/Play.ts +49 -19
- package/templates/action-rpg/src/state.ts +4 -0
- package/templates/action-rpg/src/style.css +45 -1
- package/templates/action-rpg/src/ui/AbilityBar.tsx +9 -7
- package/templates/action-rpg/src/ui/App.tsx +9 -8
- package/templates/action-rpg/src/ui/CharacterPanel.tsx +10 -8
- package/templates/action-rpg/src/ui/GameUi.tsx +24 -0
- package/templates/action-rpg/src/ui/Hud.tsx +10 -8
- package/templates/action-rpg/src/ui/InventoryPanel.tsx +9 -7
- package/templates/action-rpg/src/ui/main.tsx +14 -0
- package/templates/action-rpg/threenative.config.ts +21 -8
- package/templates/action-rpg/vite.config.ts +32 -2
- package/templates/defense/.codex/config.toml +15 -0
- package/templates/defense/.mcp.json +6 -2
- package/templates/defense/AGENTS.md +371 -8
- package/templates/defense/CLAUDE.md +371 -8
- package/templates/defense/README.md +2 -1
- package/templates/defense/index.html +0 -1
- package/templates/defense/package.json +16 -12
- package/templates/defense/playtests/leak.playtest.json +9 -4
- package/templates/defense/playtests/performance.playtest.json +22 -0
- package/templates/defense/playtests/placement.playtest.json +5 -5
- package/templates/defense/playtests/pointer-placement.playtest.json +89 -0
- package/templates/defense/playtests/scan.playtest.json +3 -3
- package/templates/defense/playtests/survive.playtest.json +11 -6
- package/templates/defense/public/icon.png +0 -0
- package/templates/defense/src/attackers/Attacker.ts +28 -12
- package/templates/defense/src/game.ts +24 -2
- package/templates/defense/src/render/lighting.ts +6 -1
- package/templates/defense/src/render/loading.ts +263 -37
- package/templates/defense/src/render/postprocessing.ts +70 -13
- package/templates/defense/src/render/shapes.ts +38 -0
- package/templates/defense/src/render/worldEnvironment.ts +583 -0
- package/templates/defense/src/scenes/Defense.ts +109 -50
- package/templates/defense/src/state.ts +6 -0
- package/templates/defense/src/style.css +45 -1
- package/templates/defense/src/ui/App.tsx +9 -4
- package/templates/defense/src/ui/GameUi.tsx +20 -0
- package/templates/defense/src/ui/Hud.tsx +6 -5
- package/templates/defense/src/ui/main.tsx +14 -0
- package/templates/defense/threenative.config.ts +21 -8
- package/templates/defense/vite.config.ts +34 -1
- package/templates/minimal/.codex/config.toml +15 -0
- package/templates/minimal/.mcp.json +6 -2
- package/templates/minimal/AGENTS.md +360 -255
- package/templates/minimal/CLAUDE.md +360 -255
- package/templates/minimal/index.html +0 -1
- package/templates/minimal/package.json +14 -11
- package/templates/minimal/playtests/atmosphere.playtest.json +32 -0
- package/templates/minimal/playtests/play.playtest.json +17 -5
- package/templates/minimal/public/icon.png +0 -0
- package/templates/minimal/src/game.ts +1 -0
- package/templates/minimal/src/render/camera.ts +1 -1
- package/templates/minimal/src/render/hud.ts +24 -8
- package/templates/minimal/src/render/lighting.ts +23 -2
- package/templates/minimal/src/render/loading.ts +23 -103
- package/templates/minimal/src/render/postprocessing.ts +92 -14
- package/templates/minimal/src/render/sky.ts +37 -32
- package/templates/minimal/src/render/worldEnvironment.ts +583 -0
- package/templates/minimal/src/scenes/Play.ts +91 -13
- package/templates/minimal/src/state.ts +8 -1
- package/templates/minimal/threenative.config.ts +15 -10
- package/templates/minimal/vite.config.ts +28 -1
- package/templates/platformer/.codex/config.toml +15 -0
- package/templates/platformer/.mcp.json +6 -2
- package/templates/platformer/AGENTS.md +385 -130
- package/templates/platformer/CLAUDE.md +385 -130
- package/templates/platformer/index.html +0 -1
- package/templates/platformer/package.json +17 -14
- package/templates/platformer/playtests/avoidance.playtest.json +6 -1
- package/templates/platformer/playtests/branding.playtest.json +29 -0
- package/templates/platformer/playtests/buffer.playtest.json +1 -1
- package/templates/platformer/playtests/collect.playtest.json +1 -1
- package/templates/platformer/playtests/collision-layers.playtest.json +2 -2
- package/templates/platformer/playtests/coyote.playtest.json +42 -8
- package/templates/platformer/playtests/damage.playtest.json +4 -1
- package/templates/platformer/playtests/dash.playtest.json +2 -2
- package/templates/platformer/playtests/jump.playtest.json +2 -3
- package/templates/platformer/playtests/native/touch-controls.playtest.json +33 -0
- package/templates/platformer/playtests/oneway.playtest.json +1 -1
- package/templates/platformer/playtests/performance.playtest.json +6 -5
- package/templates/platformer/playtests/respawn.playtest.json +2 -2
- package/templates/platformer/playtests/stomp-rise.playtest.json +17 -3
- package/templates/platformer/playtests/stomp.playtest.json +11 -3
- package/templates/platformer/playtests/terminal-loop-fail.playtest.json +13 -4
- package/templates/platformer/playtests/terminal-loop-win.playtest.json +3 -3
- package/templates/platformer/playtests/touch-controls-web.playtest.json +46 -0
- package/templates/platformer/public/icon.png +0 -0
- package/templates/platformer/src/entities/Character.ts +16 -10
- package/templates/platformer/src/entities/Patrol.ts +5 -0
- package/templates/platformer/src/game.ts +24 -1
- package/templates/platformer/src/render/lighting.ts +6 -1
- package/templates/platformer/src/render/loading.ts +270 -61
- package/templates/platformer/src/render/postprocessing.ts +68 -15
- package/templates/platformer/src/render/touch-controls.ts +54 -36
- package/templates/platformer/src/render/worldEnvironment.ts +583 -0
- package/templates/platformer/src/scenes/Level.ts +47 -22
- package/templates/platformer/src/state.ts +4 -0
- package/templates/platformer/src/style.css +45 -1
- package/templates/platformer/src/ui/App.tsx +9 -4
- package/templates/platformer/src/ui/GameUi.tsx +20 -0
- package/templates/platformer/src/ui/Hud.tsx +6 -5
- package/templates/platformer/src/ui/main.tsx +14 -0
- package/templates/platformer/threenative.config.ts +20 -10
- package/templates/platformer/vite.config.ts +34 -1
- package/templates/racing/.codex/config.toml +15 -0
- package/templates/racing/.mcp.json +6 -2
- package/templates/racing/AGENTS.md +370 -6
- package/templates/racing/CLAUDE.md +370 -6
- package/templates/racing/index.html +0 -1
- package/templates/racing/package.json +16 -12
- package/templates/racing/playtests/boost.playtest.json +5 -5
- package/templates/racing/playtests/outcome.playtest.json +14 -4
- package/templates/racing/playtests/performance.playtest.json +22 -0
- package/templates/racing/playtests/ranking.playtest.json +2 -2
- package/templates/racing/playtests/rescue.playtest.json +12 -6
- package/templates/racing/playtests/reverse.playtest.json +3 -3
- package/templates/racing/playtests/shortcut.playtest.json +3 -3
- package/templates/racing/public/icon.png +0 -0
- package/templates/racing/src/game.ts +24 -1
- package/templates/racing/src/render/camera.ts +10 -6
- package/templates/racing/src/render/lighting.ts +6 -1
- package/templates/racing/src/render/loading.ts +291 -34
- package/templates/racing/src/render/postprocessing.ts +70 -13
- package/templates/racing/src/render/worldEnvironment.ts +583 -0
- package/templates/racing/src/scenes/Race.ts +68 -36
- package/templates/racing/src/state.ts +4 -0
- package/templates/racing/src/style.css +45 -1
- package/templates/racing/src/track/Lap.ts +20 -9
- package/templates/racing/src/track/Ranking.ts +53 -14
- package/templates/racing/src/track/Track.ts +29 -16
- package/templates/racing/src/track/TrackSector.ts +14 -4
- package/templates/racing/src/ui/App.tsx +9 -4
- package/templates/racing/src/ui/GameUi.tsx +20 -0
- package/templates/racing/src/ui/Hud.tsx +6 -5
- package/templates/racing/src/ui/main.tsx +14 -0
- package/templates/racing/threenative.config.ts +21 -8
- package/templates/racing/vite.config.ts +34 -1
- package/templates/sailing/.codex/config.toml +15 -0
- package/templates/sailing/.mcp.json +20 -0
- package/templates/sailing/AGENTS.md +388 -0
- package/templates/sailing/CLAUDE.md +390 -0
- package/templates/sailing/README.md +25 -0
- package/templates/sailing/index.html +12 -0
- package/templates/sailing/kit.json +7 -0
- package/templates/sailing/native-playtests/survives.playtest.json +21 -0
- package/templates/sailing/package.json +52 -0
- package/templates/sailing/playtests/fail.playtest.json +24 -0
- package/templates/sailing/playtests/performance.playtest.json +21 -0
- package/templates/sailing/playtests/survives.playtest.json +38 -0
- package/templates/sailing/playtests/win.playtest.json +31 -0
- package/templates/sailing/public/favicon.svg +5 -0
- package/templates/sailing/public/icon.png +0 -0
- package/templates/sailing/src/entities/Ship.ts +96 -0
- package/templates/sailing/src/game.ts +40 -0
- package/templates/sailing/src/main.ts +15 -0
- package/templates/sailing/src/render/camera.ts +21 -0
- package/templates/sailing/src/render/lighting.ts +36 -0
- package/templates/sailing/src/render/loading.ts +315 -0
- package/templates/sailing/src/render/materials.ts +28 -0
- package/templates/sailing/src/render/palette.ts +24 -0
- package/templates/sailing/src/render/postprocessing.ts +33 -0
- package/templates/sailing/src/render/props.ts +52 -0
- package/templates/sailing/src/render/sky.ts +32 -0
- package/templates/sailing/src/render/water-material.ts +14 -0
- package/templates/sailing/src/render/water-shaders.ts +12 -0
- package/templates/sailing/src/render/wave-nodes.ts +10 -0
- package/templates/sailing/src/render/worldEnvironment.ts +590 -0
- package/templates/sailing/src/scenes/Boot.ts +12 -0
- package/templates/sailing/src/scenes/Sailing.ts +106 -0
- package/templates/sailing/src/state.ts +10 -0
- package/templates/sailing/src/style.css +61 -0
- package/templates/sailing/src/ui/App.tsx +15 -0
- package/templates/sailing/src/ui/GameUi.tsx +12 -0
- package/templates/sailing/src/ui/Hud.tsx +55 -0
- package/templates/sailing/src/ui/Menu.tsx +30 -0
- package/templates/sailing/src/ui/main.tsx +7 -0
- package/templates/sailing/tailwind.config.ts +2 -0
- package/templates/sailing/threenative.config.ts +34 -0
- package/templates/sailing/tsconfig.json +17 -0
- package/templates/sailing/vite.config.ts +34 -0
- package/templates/shooter/.codex/config.toml +15 -0
- package/templates/shooter/.mcp.json +6 -2
- package/templates/shooter/AGENTS.md +373 -7
- package/templates/shooter/CLAUDE.md +373 -7
- package/templates/shooter/index.html +0 -1
- package/templates/shooter/package.json +16 -11
- package/templates/shooter/playtests/fail.playtest.json +5 -4
- package/templates/shooter/playtests/input-control.playtest.json +131 -0
- package/templates/shooter/playtests/per-item.playtest.json +59 -0
- package/templates/shooter/playtests/performance.playtest.json +22 -0
- package/templates/shooter/playtests/shooter.playtest.json +22 -18
- package/templates/shooter/playtests/survives.playtest.json +1 -1
- package/templates/shooter/public/favicon.svg +1 -1
- package/templates/shooter/public/icon.png +0 -0
- package/templates/shooter/src/game.ts +24 -1
- package/templates/shooter/src/main.ts +3 -13
- package/templates/shooter/src/render/camera.ts +62 -12
- package/templates/shooter/src/render/lighting.ts +6 -1
- package/templates/shooter/src/render/loading.ts +262 -33
- package/templates/shooter/src/render/palette.ts +1 -1
- package/templates/shooter/src/render/postprocessing.ts +68 -16
- package/templates/shooter/src/render/shapes.ts +178 -0
- package/templates/shooter/src/render/ui.css +34 -1
- package/templates/shooter/src/render/worldEnvironment.ts +583 -0
- package/templates/shooter/src/scenes/Play.ts +246 -73
- package/templates/shooter/src/state.ts +13 -0
- package/templates/shooter/src/style.css +26 -0
- package/templates/shooter/src/ui/App.tsx +10 -12
- package/templates/shooter/src/ui/GameUi.tsx +20 -0
- package/templates/shooter/src/ui/Hud.tsx +8 -10
- package/templates/shooter/src/ui/Menu.tsx +24 -9
- package/templates/shooter/src/ui/main.tsx +15 -0
- package/templates/shooter/src/weapons/Projectile.ts +21 -10
- package/templates/shooter/threenative.config.ts +21 -8
- package/templates/shooter/vite.config.ts +32 -2
- package/templates/starter/.codex/config.toml +15 -0
- package/templates/starter/.mcp.json +6 -2
- package/templates/starter/AGENTS.md +429 -326
- package/templates/starter/CLAUDE.md +429 -326
- package/templates/starter/assets/pickup.wav +0 -0
- package/templates/starter/gitignore +4 -0
- package/templates/starter/index.html +0 -1
- package/templates/starter/native-playtests/react-hud.playtest.json +20 -0
- package/templates/starter/native-playtests/render-chain.playtest.json +12 -0
- package/templates/starter/package.json +16 -12
- package/templates/starter/playtests/assets.playtest.json +65 -0
- package/templates/starter/playtests/buffer.playtest.json +59 -9
- package/templates/starter/playtests/cloth.playtest.json +113 -0
- package/templates/starter/playtests/coyote.playtest.json +60 -8
- package/templates/starter/playtests/forward.playtest.json +29 -4
- package/templates/starter/playtests/gameover.playtest.json +66 -0
- package/templates/starter/playtests/goal.playtest.json +67 -0
- package/templates/starter/playtests/hot-reload.playtest.json +48 -8
- package/templates/starter/playtests/look.playtest.json +34 -6
- package/templates/starter/playtests/models-baseline.png +0 -0
- package/templates/starter/playtests/models.playtest.json +74 -0
- package/templates/starter/playtests/monitoring.playtest.json +38 -7
- package/templates/starter/playtests/odometer.playtest.json +54 -0
- package/templates/starter/playtests/pause.playtest.json +27 -4
- package/templates/starter/playtests/play.playtest.json +43 -7
- package/templates/starter/playtests/respawn.playtest.json +46 -6
- package/templates/starter/playtests/restart.playtest.json +65 -10
- package/templates/starter/playtests/seed.playtest.json +44 -8
- package/templates/starter/playtests/survives.playtest.json +27 -4
- package/templates/starter/playtests/textures-baseline.png +0 -0
- package/templates/starter/playtests/textures.playtest.json +74 -0
- package/templates/starter/playtests/zoom-pinch.playtest.json +86 -0
- package/templates/starter/playtests/zoom-wheel.playtest.json +59 -0
- package/templates/starter/public/icon.png +0 -0
- package/templates/starter/src/entities/Goal.ts +122 -0
- package/templates/starter/src/entities/Player.ts +40 -2
- package/templates/starter/src/game.ts +25 -0
- package/templates/starter/src/render/camera.ts +31 -5
- package/templates/starter/src/render/easing.ts +5 -0
- package/templates/starter/src/render/effects/gradualBackground.ts +48 -0
- package/templates/starter/src/render/effects/lensDistortion.ts +43 -0
- package/templates/starter/src/render/effects/sparkle.ts +49 -0
- package/templates/starter/src/render/lighting.ts +6 -1
- package/templates/starter/src/render/loading.ts +315 -0
- package/templates/starter/src/render/materials.ts +17 -1
- package/templates/starter/src/render/pennant.ts +54 -0
- package/templates/starter/src/render/postprocessing.ts +46 -15
- package/templates/starter/src/render/scenery.ts +83 -0
- package/templates/starter/src/render/shapes.ts +9 -21
- package/templates/starter/src/render/worldEnvironment.ts +583 -0
- package/templates/starter/src/scenes/Play.ts +146 -36
- package/templates/starter/src/state.ts +12 -0
- package/templates/starter/src/style.css +45 -1
- package/templates/starter/src/ui/App.tsx +9 -6
- package/templates/starter/src/ui/GameUi.tsx +20 -0
- package/templates/starter/src/ui/Hud.tsx +52 -29
- package/templates/starter/src/ui/Menu.tsx +25 -23
- package/templates/starter/src/ui/main.tsx +14 -0
- package/templates/starter/threenative.config.ts +27 -9
- package/templates/starter/tools/look.mjs +109 -0
- package/templates/starter/vite.config.ts +32 -2
- package/templates/minimal/assets/.gitkeep +0 -0
- package/templates/minimal/public/.gitkeep +0 -0
- package/templates/platformer/assets/.gitkeep +0 -0
- package/templates/platformer/public/.gitkeep +0 -0
- package/templates/starter/assets/.gitkeep +0 -0
- package/templates/starter/public/.gitkeep +0 -0
- package/templates/starter/public/pickup.ogg +0 -0
- /package/templates/starter/{public → assets}/native-proof.glb +0 -0
- /package/templates/starter/{public → assets}/native-proof.png +0 -0
|
@@ -0,0 +1,3279 @@
|
|
|
1
|
+
<!-- Generated by scripts/generate-capability-reference.ts from capabilities.json — do not hand-edit. -->
|
|
2
|
+
<!-- Regenerate: pnpm build -->
|
|
3
|
+
|
|
4
|
+
# Capability reference
|
|
5
|
+
|
|
6
|
+
Every public class and function export of `@threenative/core` and `@threenative/physics`,
|
|
7
|
+
generated from the doc tags the engine itself compiles, so this page cannot disagree with
|
|
8
|
+
the code. Look here before writing a replacement; ask `engine_search_capabilities` when an
|
|
9
|
+
MCP server is available.
|
|
10
|
+
|
|
11
|
+
## `@threenative/core`
|
|
12
|
+
|
|
13
|
+
### `AnimationPlayer`
|
|
14
|
+
|
|
15
|
+
`class` — Play a skinned or sprite animation from game code. A travelling clip's playback rate is matched to the ground the body actually covers, so feet do not skate or spin — on by default, `strideSync: false` to keep the authored rate, and `player.stride` reports the measurement either way. Name the body a game moves as `strideRoot` when the rig is a child of it.
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
export class AnimationPlayer { … }
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
- **Use when:** play an animation on a character · switch a character between idle and attack clips · stop a walking character's feet from sliding or spinning · match a walk or run cycle to how fast a character is moving
|
|
22
|
+
- **Constraints:** name the body a game moves as strideRoot when the animated rig is a child of it · a one-shot clip always plays at its authored rate; the matched rate re-times loops only
|
|
23
|
+
- **Overrides:** strideSync controls whether the matched rate is applied while stride is still measured
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
const player = new AnimationPlayer({ clips, root: rig, strideRoot: body });
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### `Atmosphere`
|
|
30
|
+
|
|
31
|
+
`class` — Own the compute lifetime and expose only parameter-driven atmosphere nodes. The class deliberately creates no mesh, material, or scene light. A template chooses all of those, and the same object remains useful when a game supplies a completely different look.
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
export class Atmosphere extends Group implements IComputeDriven { … }
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
- **Use when:** render a sunrise that changes as time and place change · add distance haze from the depth of a scene pass
|
|
38
|
+
- **Constraints:** supply rayleigh, mie, ozone, planetRadius, and atmosphereRadius; there is no Earth fallback · the game creates the sky object, surface, and sun from the returned nodes
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
const atmosphere = new Atmosphere({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
|
|
42
|
+
ctx.add(atmosphere);
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### `AtmosphereLuts`
|
|
46
|
+
|
|
47
|
+
`class` — Own the transmittance, multi-scattering, and sky-view compute lookup textures.
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
export class AtmosphereLuts { … }
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
- **Use when:** bake the three atmosphere LUTs once before a game shows its world
|
|
54
|
+
- **Constraints:** supply all physical parameters; this class creates no scene appearance
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
const luts = new AtmosphereLuts({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### `attachToBone`
|
|
61
|
+
|
|
62
|
+
`function` — Attach a game-owned object to a named skeleton bone.
|
|
63
|
+
|
|
64
|
+
```ts
|
|
65
|
+
export function attachToBone(root: Object3D, boneName: string, child: Object3D): Object3D { … }
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- **Use when:** put a weapon in a character's hand · hold a rifle in a character's right hand · add an enemy that patrols the level, chases the player when it sees them, and holds a rifle in its right hand · attach an accessory to a skinned model · equip crew with swords and pistols · put a sword or pistol in a crew member's hand
|
|
69
|
+
- **Constraints:** when a request is to hold or attach a weapon to a hand, import and call `attachToBone` from `@threenative/core`; do not manually parent, position, or rotate the rifle · if a stock visual has no skeleton, add a portable Three.js Bone named `RightHand` under the character, then call `attachToBone`; do not replace the helper with manual parenting
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import { attachToBone } from "@threenative/core";
|
|
73
|
+
attachToBone(character, "RightHand", rifle);
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### `AudioBus`
|
|
77
|
+
|
|
78
|
+
`class` — Route effects through a named audio bus.
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
export class AudioBus { … }
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
- **Use when:** play a sound effect with a volume bus · mute or adjust a category of game audio · keep a gunshot audible at 20 metres by tuning positional falloff · play cannon, wave, and ship sound effects
|
|
85
|
+
- **Constraints:** create buses before playing clips and dispose them with the game · refDistance and rolloffFactor tune positional falloff and apply to playAt only
|
|
86
|
+
- **Supersedes (writing this fails `pnpm budgets`):** new Audio(
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
const effects = new AudioBus({ camera });
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### `Billboard3D`
|
|
93
|
+
|
|
94
|
+
`class` — Face a game-owned object toward a perspective or orthographic camera.
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
export class Billboard3D { … }
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
- **Use when:** keep a world-space marker or nameplate facing the camera · billboard a tree, label, or effect under a rotated parent
|
|
101
|
+
- **Constraints:** call update from the owning scene; no global scene scan is installed · orthographic cameras use their forward direction, and lockAxis restricts world rotation
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
const billboard = new Billboard3D(label, { camera });
|
|
105
|
+
billboard.update();
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### `CameraShake`
|
|
109
|
+
|
|
110
|
+
`class` — Produce a game-authored camera shake offset for a template-owned camera rig.
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
export class CameraShake { … }
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
- **Use when:** add a hit, explosion, or landing shake to a camera · compose a transient camera offset after camera damping
|
|
117
|
+
- **Constraints:** amplitude, rotationAmplitude, frequency, decay, and curve are required game choices · update returns an offset and never writes to a camera
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
const shake = new CameraShake({ amplitude, rotationAmplitude, frequency, decay, curve });
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### `CanvasLayer`
|
|
124
|
+
|
|
125
|
+
`class` — Manage a camera or screen-facing canvas layer.
|
|
126
|
+
|
|
127
|
+
```ts
|
|
128
|
+
export class CanvasLayer { … }
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
- **Use when:** place a HUD layer above the Three.js scene · attach a canvas layer to a camera
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
const hud = new CanvasLayer({ camera });
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### `ClusteredBatch`
|
|
138
|
+
|
|
139
|
+
`class` — Draw many copies of one over-detailed body, each at the detail its own distance earns. `InstancedBatch` collapses repeated props into one draw and gives every copy the same triangles. This gives a copy two hundred metres away a coarser cut than one twelve metres away, and still submits one draw per distance group rather than one per copy — which is what makes four hundred scanned boulders affordable. The shape, the surface and every transform stay the game's.
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
export class ClusteredBatch { … }
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
- **Use when:** draw hundreds of copies of a scanned or sculpted body without hundreds of draw calls · stop distant copies of a dense prop from costing their full triangle count
|
|
146
|
+
- **Constraints:** the body's geometry must carry a cluster table from `assets.models.virtual` · every copy is placed before build(); place() after build() throws
|
|
147
|
+
- **Overrides:** distanceRatio sets how wide one distance group is, default 1.25 · errorPixels sets the screen-space error budget, default 1 pixel
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
const boulders = new ClusteredBatch({ geometry, material, table });
|
|
151
|
+
boulders.place({ position: [x, y, z], rotation: [0, angle, 0] });
|
|
152
|
+
boulders.build({ name: "boulders", parent: ctx.scene });
|
|
153
|
+
// in the scene's update, before the render:
|
|
154
|
+
boulders.update(ctx.camera, ctx.renderer.domElement.height);
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### `ClusteredMesh`
|
|
158
|
+
|
|
159
|
+
`class` — Draw a model too detailed for the screen to resolve, without submitting the part it cannot. **This is on, and a game does not call it.** Any primitive of 65,536 triangles or more bakes to a cluster DAG in the asset pipeline, the loader returns a `ClusteredMesh` for it, and the engine takes the cut every frame before it renders. Each frame the mesh submits one draw holding only the clusters whose error projects to fewer than `errorPixels` screen pixels; a mesh nothing has cut yet draws in full, so the worst case is an ordinary `Mesh`. Geometry, surface and every appearance parameter stay the game's.
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
export class ClusteredMesh extends Mesh { … }
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
- **Use when:** draw a model too detailed for the screen to resolve · import a scanned or sculpted mesh of millions of triangles and still hold the frame · stop a dense rock face or terrain body from costing its full triangle count up close
|
|
166
|
+
- **Constraints:** the bake happens in the asset pipeline, never at run time — there is no runtime flag · the payload costs about 3-4x a baked primitive's bytes; `assets.models.virtual: "none"` opts out and `minSourceTriangles` moves the 65,536 line · needs a perspective camera; a screen-space error has no meaning without one · one shadow cut is chosen at load and does not follow a shadow camera
|
|
167
|
+
- **Overrides:** errorPixels sets the screen-space error budget, default 1 pixel · recutDistance sets how far the camera moves before the cut is retaken, default a thousandth of the mesh's radius
|
|
168
|
+
|
|
169
|
+
```ts
|
|
170
|
+
// Nothing to call: the loader returns one of these and the engine cuts it every frame.
|
|
171
|
+
const face = await ctx.assets.model("quarry-face.glb");
|
|
172
|
+
ctx.scene.add(face.scene);
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### `ComputeDrivenRegistry`
|
|
176
|
+
|
|
177
|
+
`class` — Register game-owned IComputeDriven objects with the shared compute lifetime.
|
|
178
|
+
|
|
179
|
+
```ts
|
|
180
|
+
export class ComputeDrivenRegistry { … }
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
- **Use when:** use IComputeDriven for a cloth, fluid, boid, or other GPU simulation · run a cloth or fluid simulation with ordered GPU passes · keep IComputeDriven kernels warm before the first visible frame
|
|
184
|
+
- **Constraints:** add the object through ctx.add so it attaches, dispatches, and releases with its scene
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
class Cloth extends Mesh implements IComputeDriven { ... }
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### `createAssetLoader`
|
|
191
|
+
|
|
192
|
+
`function` — Create the portable asset loader a scene also receives as `ctx.assets`.
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
export function createAssetLoader(options: IAssetLoaderOptions = { … }
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
- **Use when:** preload models, textures, or audio before a scene enters · load assets from a nonstandard base path or a compiled asset manifest
|
|
199
|
+
- **Constraints:** reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches
|
|
200
|
+
|
|
201
|
+
```ts
|
|
202
|
+
const assets = createAssetLoader({ basePath: "/assets" });
|
|
203
|
+
const rock = await assets.texture("rock.png");
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
### `createRandom`
|
|
207
|
+
|
|
208
|
+
`function` — Create a deterministic random source for portable gameplay.
|
|
209
|
+
|
|
210
|
+
```ts
|
|
211
|
+
export function createRandom(seed?: number): IRandom { … }
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
- **Use when:** seed enemy patrol choices · reproduce the same procedural level in a playtest
|
|
215
|
+
- **Constraints:** use the returned source instead of Math.random for replayable behavior
|
|
216
|
+
- **Supersedes (writing this fails `pnpm budgets`):** Math.random(
|
|
217
|
+
|
|
218
|
+
```ts
|
|
219
|
+
const random = createRandom(42);
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
### `createReplayDriver`
|
|
223
|
+
|
|
224
|
+
`function` — Record or replay deterministic game input and state.
|
|
225
|
+
|
|
226
|
+
```ts
|
|
227
|
+
export function createReplayDriver( recording: Recording, target: EventTarget, pointerTarget = target, ) { … }
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
- **Use when:** reproduce a gameplay bug from recorded input · run a deterministic replay in a playtest
|
|
231
|
+
- **Constraints:** use a seeded random source and fixed-step simulation for meaningful replays
|
|
232
|
+
|
|
233
|
+
```ts
|
|
234
|
+
const driver = createReplayDriver({ recording });
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
### `defineGame`
|
|
238
|
+
|
|
239
|
+
`function` — Define the portable game entry shared by web and native.
|
|
240
|
+
|
|
241
|
+
```ts
|
|
242
|
+
export function defineGame<TState extends Record<string, unknown>, TPhysics = undefined>( config: IGameConfig<TState, TPhysics>, ): IGame<TState, TPhysics> { … }
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
- **Use when:** start a ThreeNative game from src/game.ts · register physics and gameplay plugins · let the player zoom the camera with a wheel, pinch, or gamepad axis
|
|
246
|
+
- **Constraints:** keep DOM and React mounting in src/main.ts · bind scroll or pinch and read the intent with ctx.input.axis(name); do not add a window wheel listener · scroll: true uses the DOM wheel sign on browser and native: negative deltaY toward the user is positive intent
|
|
247
|
+
|
|
248
|
+
```ts
|
|
249
|
+
const game = defineGame({ input: { zoom: { scroll: true, pinch: true } }, scenes: { Play } });
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
### `directionalTransmittance`
|
|
253
|
+
|
|
254
|
+
`function` — Approximate direct transmittance for a ray leaving the game surface.
|
|
255
|
+
|
|
256
|
+
```ts
|
|
257
|
+
export function directionalTransmittance( parameters: IAtmosphereParameters | IResolvedAtmosphereParameters, direction: Vector3, ): Vector3 { … }
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
- **Use when:** colour a game-owned sun from atmosphere extinction
|
|
261
|
+
- **Constraints:** pass a non-zero direction; coefficients and radii come from the game
|
|
262
|
+
|
|
263
|
+
```ts
|
|
264
|
+
const transmittance = directionalTransmittance(parameters, sunDirection);
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
### `directionFromSolarPosition`
|
|
268
|
+
|
|
269
|
+
`function` — Convert solar elevation and azimuth degrees into a normalized Three.js direction.
|
|
270
|
+
|
|
271
|
+
```ts
|
|
272
|
+
export function directionFromSolarPosition(elevation: number, azimuth: number): Vector3 { … }
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
- **Use when:** aim a template's sun from solarPosition output
|
|
276
|
+
- **Constraints:** elevation and azimuth must be finite degrees
|
|
277
|
+
|
|
278
|
+
```ts
|
|
279
|
+
const direction = directionFromSolarPosition(sun.elevation, sun.azimuth);
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
### `ensureVelocityOutput`
|
|
283
|
+
|
|
284
|
+
`function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
|
|
285
|
+
|
|
286
|
+
```ts
|
|
287
|
+
export function ensureVelocityOutput(pass: IVelocityRenderPass): MRTNode { … }
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
- **Use when:** keep a skinned character or instanced crowd stable in a temporal stage · add the velocity output to a Three.js scene pass · add a velocity target before a temporal stage consumes a scene pass
|
|
291
|
+
- **Constraints:** call `VelocityTracker.update()` before the render and `commit()` after it · a pass is only given a velocity target when a temporal stage consumes it · call only when a temporal stage is active
|
|
292
|
+
|
|
293
|
+
```ts
|
|
294
|
+
const scenePass = pass(scene, camera);
|
|
295
|
+
ensureVelocityOutput(scenePass);
|
|
296
|
+
renderer.setOutputNode(scenePass);
|
|
297
|
+
const tracker = new VelocityTracker();
|
|
298
|
+
tracker.update(scene);
|
|
299
|
+
renderer.render(scene, camera);
|
|
300
|
+
tracker.commit(scene);
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
### `FluidField2D`
|
|
304
|
+
|
|
305
|
+
`class` — Simulate a deterministic 2D velocity-and-dye field on the GPU while exposing its data to game-owned rendering.
|
|
306
|
+
|
|
307
|
+
```ts
|
|
308
|
+
export class FluidField2D extends Group { … }
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
- **Use when:** simulate smoke, fire, fog, wind, or fluid response on a grid · inject a touch, pointer, or gameplay impulse into a fluid field · sample fluid dye or velocity in a game-owned render node · simulate ocean currents and wind affecting a sailing ship · simulate ocean fluid dynamics and currents that affect a ship
|
|
312
|
+
- **Constraints:** add the field through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic · `dye` and `velocity` are numeric samplers; appearance stays in the game's `src/render/` code · the conformance sample measures mean absolute velocity divergence at 0.001732 after four 32² steps with pressureIterations 2, below the 0.0025 threshold
|
|
313
|
+
- **Overrides:** pressureIterations, viscosity, vorticity, and splatRadius tune the solver without changing its pass order
|
|
314
|
+
|
|
315
|
+
```ts
|
|
316
|
+
const field = new FluidField2D({ resolution: 256, pressureIterations: 20 });
|
|
317
|
+
ctx.add(field);
|
|
318
|
+
field.splat({ x: 0.5, y: 0.5 }, { x: 0.2, y: 0 }, 1);
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
### `FrameBudget`
|
|
322
|
+
|
|
323
|
+
`class` — Read where the frame's milliseconds went, per presented frame, on any platform.
|
|
324
|
+
|
|
325
|
+
```ts
|
|
326
|
+
export class FrameBudget { … }
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
- **Use when:** find out why a game runs slowly on a phone · attribute a frame to present wait, simulation, three.js render, or overlay
|
|
330
|
+
- **Constraints:** on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement
|
|
331
|
+
|
|
332
|
+
```ts
|
|
333
|
+
defineGame({ frameBudget: { reportEvery: 120 }, scenes: { Play } });
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
### `getPlatform`
|
|
337
|
+
|
|
338
|
+
`function` — Read the host platform without reaching for browser globals.
|
|
339
|
+
|
|
340
|
+
```ts
|
|
341
|
+
export function getPlatform(): Readonly<IPlatformInfo> { … }
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
345
|
+
- **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
|
|
346
|
+
|
|
347
|
+
```ts
|
|
348
|
+
if (isMobile()) showTouchControls();
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
### `GPUParticles3D`
|
|
352
|
+
|
|
353
|
+
`class` — Dispatch a game-owned particle surface and process function through a pooled system.
|
|
354
|
+
|
|
355
|
+
```ts
|
|
356
|
+
export class GPUParticles3D extends Sprite implements IComputeDriven { … }
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
- **Use when:** emit sparks, smoke, or other transient effects · update many small visual particles · emit cannon smoke and muzzle flash particles · fire a cannonball projectile with cannon smoke particles
|
|
360
|
+
- **Constraints:** geometry, color, and timing remain supplied by the game
|
|
361
|
+
|
|
362
|
+
```ts
|
|
363
|
+
const particles = new GPUParticles3D(particleOptions);
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
### `GPUReadback`
|
|
367
|
+
|
|
368
|
+
`class` — Copy a GPU buffer back to the CPU on a throttle, and report how old each sample is.
|
|
369
|
+
|
|
370
|
+
```ts
|
|
371
|
+
export class GPUReadback { … }
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
- **Use when:** read a GPU simulation on the CPU without stalling the frame · float a body on a wave field whose height only exists on the GPU · count GPU-side survivors for a diagnostic without blocking drawing · keep a ship floating on simulated ocean waves
|
|
375
|
+
- **Constraints:** the copy is asynchronous, so every sample carries staleFrames and is never this frame · WebGPU only; the seam throws on a WebGL2 renderer rather than returning nothing · one copy is in flight at a time and requests made during one are dropped, not queued
|
|
376
|
+
|
|
377
|
+
```ts
|
|
378
|
+
const heights = new GPUReadback({ attribute: field.value, everyFrames: 4 });
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
### `GPUSceneBVH`
|
|
382
|
+
|
|
383
|
+
`class` — Pack a selected static scene into TSL storage nodes for an upstream BVH ray query.
|
|
384
|
+
|
|
385
|
+
```ts
|
|
386
|
+
export class GPUSceneBVH extends Group implements IComputeDriven { … }
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
- **Use when:** trace thousands of scene rays inside a TSL kernel · build a contact-occlusion or visibility query over loaded meshes
|
|
390
|
+
- **Constraints:** call rebuild() after a scene transform or geometry change; the snapshot is static by default · rebuild() is an explicit CPU SAH build proportional to selected triangles; process() is a no-op, and the game pays upstream traversal per shader ray
|
|
391
|
+
|
|
392
|
+
```ts
|
|
393
|
+
const bvh = ctx.add(new GPUSceneBVH(ctx.scene, { include: (object) => object.userData.traceable === true }));
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
### `GroundSnap`
|
|
397
|
+
|
|
398
|
+
`class` — Keep a rendered model's feet on a surface while preserving an auditable override.
|
|
399
|
+
|
|
400
|
+
```ts
|
|
401
|
+
export class GroundSnap { … }
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
- **Use when:** keep a character's feet on the floor · correct visual grounding after an animation update
|
|
405
|
+
- **Constraints:** import from `@threenative/core`; this moves the rendered model, not its physics collider
|
|
406
|
+
- **Overrides:** enabled controls whether correction is applied while clearance is still measured
|
|
407
|
+
|
|
408
|
+
```ts
|
|
409
|
+
import { GroundSnap } from "@threenative/core";
|
|
410
|
+
const snap = new GroundSnap(character, { enabled: true });
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
### `InstancedBatch`
|
|
414
|
+
|
|
415
|
+
`class` — Collapse many copies of one game-authored shape into a single draw, without counting them first. `new InstancedMesh(geometry, material, count)` needs the count before anything is placed, so a procedural builder ends up walking its layout twice or over-allocating. Place as you go and `build()` once; the shape, the surface and every transform stay the game's, and the built mesh is returned so instances can still be animated by the index `place` and `span` hand back.
|
|
416
|
+
|
|
417
|
+
```ts
|
|
418
|
+
export class InstancedBatch { … }
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
- **Use when:** draw hundreds of repeated props without hundreds of draw calls · place repeated props when the count is not known until the layout has been walked · build a chain, railing, cable, or tie rod out of point-to-point segments
|
|
422
|
+
- **Constraints:** geometry and material are required and come from the game; the batch chooses neither · span stretches along +Y, so its geometry must be unit-height and centred on the origin · placing after build() throws, and build() returns undefined when nothing was placed
|
|
423
|
+
- **Overrides:** castShadow and receiveShadow pass through to the built mesh and default to Three.js's own false
|
|
424
|
+
|
|
425
|
+
```ts
|
|
426
|
+
const curbs = new InstancedBatch({ geometry: new BoxGeometry(1, 1, 1), material });
|
|
427
|
+
curbs.place({ position: [x, 0.08, z], rotation: [0, angle, 0], scale: [length, 0.18, 0.42] });
|
|
428
|
+
curbs.build({ castShadow: true, name: "curbs", parent: ctx.scene });
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
### `isMobile`
|
|
432
|
+
|
|
433
|
+
`function` — Read the host platform without reaching for browser globals.
|
|
434
|
+
|
|
435
|
+
```ts
|
|
436
|
+
export function isMobile(): boolean { … }
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
440
|
+
- **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
|
|
441
|
+
|
|
442
|
+
```ts
|
|
443
|
+
if (isMobile()) showTouchControls();
|
|
444
|
+
```
|
|
445
|
+
|
|
446
|
+
### `isNative`
|
|
447
|
+
|
|
448
|
+
`function` — Read the host platform without reaching for browser globals.
|
|
449
|
+
|
|
450
|
+
```ts
|
|
451
|
+
export function isNative(): boolean { … }
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
455
|
+
- **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
|
|
456
|
+
|
|
457
|
+
```ts
|
|
458
|
+
if (isMobile()) showTouchControls();
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
### `isTouchscreenAvailable`
|
|
462
|
+
|
|
463
|
+
`function` — Read the host platform without reaching for browser globals.
|
|
464
|
+
|
|
465
|
+
```ts
|
|
466
|
+
export function isTouchscreenAvailable(): boolean { … }
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
470
|
+
- **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
|
|
471
|
+
|
|
472
|
+
```ts
|
|
473
|
+
if (isMobile()) showTouchControls();
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
### `isWeb`
|
|
477
|
+
|
|
478
|
+
`function` — Read the host platform without reaching for browser globals.
|
|
479
|
+
|
|
480
|
+
```ts
|
|
481
|
+
export function isWeb(): boolean { … }
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
485
|
+
- **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
|
|
486
|
+
|
|
487
|
+
```ts
|
|
488
|
+
if (isMobile()) showTouchControls();
|
|
489
|
+
```
|
|
490
|
+
|
|
491
|
+
### `measureThreePose`
|
|
492
|
+
|
|
493
|
+
`function` — Measure a Three.js pose for grounded or attachment-aware checks.
|
|
494
|
+
|
|
495
|
+
```ts
|
|
496
|
+
export function measureThreePose( object: Object3D, options: IMeasureThreePoseOptions = { … }
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
- **Use when:** inspect a skinned model's posed bounds · verify a character's visual pose
|
|
500
|
+
- **Constraints:** precise per-vertex measurement is opt-in and not for frame loops
|
|
501
|
+
|
|
502
|
+
```ts
|
|
503
|
+
const measurement = measureThreePose(model);
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
### `normaliseToMetres`
|
|
507
|
+
|
|
508
|
+
`function` — Scale an asset to a real-world measurement and return the applied factor.
|
|
509
|
+
|
|
510
|
+
```ts
|
|
511
|
+
export function normaliseToMetres(object: Object3D, options: INormaliseToMetresOptions): number { … }
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
- **Use when:** make a character exactly 1.8 metres tall · normalize a prop or weapon to a known longest axis
|
|
515
|
+
- **Constraints:** skinned height uses a crown bone; game-specific asset expectations stay in render code
|
|
516
|
+
- **Supersedes (writing this fails `pnpm budgets`):** new Box3().setFromObject(
|
|
517
|
+
|
|
518
|
+
```ts
|
|
519
|
+
normaliseToMetres(character, { metres: 1.8, axis: "height" });
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
### `parseReplayRecording`
|
|
523
|
+
|
|
524
|
+
`function` — Validate and parse a replay recording file.
|
|
525
|
+
|
|
526
|
+
```ts
|
|
527
|
+
export function parseReplayRecording(value: unknown): IReplayRecording { … }
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
- **Use when:** validate a recording before replaying it in another host
|
|
531
|
+
- **Constraints:** recordings are version 1; the parser fails closed with TN_REPLAY_* codes
|
|
532
|
+
|
|
533
|
+
```ts
|
|
534
|
+
const recording = parseReplayRecording(rawRecording);
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
### `PathFollow3D`
|
|
538
|
+
|
|
539
|
+
`class` — Move an object along a Three.js curve with Godot-style path following.
|
|
540
|
+
|
|
541
|
+
```ts
|
|
542
|
+
export class PathFollow3D { … }
|
|
543
|
+
```
|
|
544
|
+
|
|
545
|
+
- **Use when:** move an enemy or prop along a patrol path · sample a racing line from a curve
|
|
546
|
+
|
|
547
|
+
```ts
|
|
548
|
+
const follower = new PathFollow3D(curve, { loop: true });
|
|
549
|
+
```
|
|
550
|
+
|
|
551
|
+
### `PointerEvents3D`
|
|
552
|
+
|
|
553
|
+
`class` — Dispatch portable pointer events from the game surface to registered Three.js objects.
|
|
554
|
+
|
|
555
|
+
```ts
|
|
556
|
+
export class PointerEvents3D implements IPointerEvents3D { … }
|
|
557
|
+
```
|
|
558
|
+
|
|
559
|
+
- **Use when:** let the player click on a thing in the world · show a 3D object while a pointer hovers over it · handle touch and mouse taps on a loaded model without naming its child meshes
|
|
560
|
+
- **Constraints:** listeners are side-table registrations; Three.js prototypes are never patched · one raycast serves each active pointer and no raycast runs when nothing is registered
|
|
561
|
+
|
|
562
|
+
```ts
|
|
563
|
+
ctx.pointer.on(tile, "tapped", (event) => place(event.point));
|
|
564
|
+
```
|
|
565
|
+
|
|
566
|
+
### `posedBounds`
|
|
567
|
+
|
|
568
|
+
`function` — Measure a Three.js pose for grounded or attachment-aware checks.
|
|
569
|
+
|
|
570
|
+
```ts
|
|
571
|
+
export function posedBounds(root: Object3D, meshes?: readonly Object3D[]): IThreePoseBounds { … }
|
|
572
|
+
```
|
|
573
|
+
|
|
574
|
+
- **Use when:** inspect a skinned model's posed bounds · verify a character's visual pose
|
|
575
|
+
- **Constraints:** precise per-vertex measurement is opt-in and not for frame loops
|
|
576
|
+
|
|
577
|
+
```ts
|
|
578
|
+
const measurement = measureThreePose(model);
|
|
579
|
+
```
|
|
580
|
+
|
|
581
|
+
### `prewarm`
|
|
582
|
+
|
|
583
|
+
`function` — Keep transient render surfaces in the renderer's pipeline cache before first use.
|
|
584
|
+
|
|
585
|
+
```ts
|
|
586
|
+
export function prewarm(object: Object3D | readonly Object3D[]): void { … }
|
|
587
|
+
```
|
|
588
|
+
|
|
589
|
+
- **Use when:** prewarm a projectile, tracer, particle, or other transient effect · avoid a long first-use frame for a newly visible effect
|
|
590
|
+
- **Constraints:** keep the surface visible with zero opacity; do not hide it with `visible = false`
|
|
591
|
+
- **Supersedes (writing this fails `pnpm budgets`):** .visible = false
|
|
592
|
+
|
|
593
|
+
```ts
|
|
594
|
+
prewarm(tracerPool);
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
### `ProbeVolume`
|
|
598
|
+
|
|
599
|
+
`class` — Bake static diffuse irradiance that reaches surfaces from outside the camera view.
|
|
600
|
+
|
|
601
|
+
```ts
|
|
602
|
+
export class ProbeVolume extends Object3D implements IComputeDriven { … }
|
|
603
|
+
```
|
|
604
|
+
|
|
605
|
+
- **Use when:** light bouncing from a room I cannot see · light a wall with an off-screen emitter
|
|
606
|
+
- **Constraints:** request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting · add the volume with ctx.add() so its incremental work is measured in the render phase · call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour
|
|
607
|
+
- **Overrides:** density, bounds, bakeBudgetMs, and bounces are game-owned choices
|
|
608
|
+
|
|
609
|
+
```ts
|
|
610
|
+
const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);
|
|
611
|
+
```
|
|
612
|
+
|
|
613
|
+
### `readProbeVolumeObservation`
|
|
614
|
+
|
|
615
|
+
`function` — Bake static diffuse irradiance that reaches surfaces from outside the camera view.
|
|
616
|
+
|
|
617
|
+
```ts
|
|
618
|
+
export function readProbeVolumeObservation(value: unknown): IProbeVolumeObservation | undefined { … }
|
|
619
|
+
```
|
|
620
|
+
|
|
621
|
+
- **Use when:** light bouncing from a room I cannot see · light a wall with an off-screen emitter
|
|
622
|
+
- **Constraints:** request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting · add the volume with ctx.add() so its incremental work is measured in the render phase · call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour
|
|
623
|
+
- **Overrides:** density, bounds, bakeBudgetMs, and bounces are game-owned choices
|
|
624
|
+
|
|
625
|
+
```ts
|
|
626
|
+
const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);
|
|
627
|
+
```
|
|
628
|
+
|
|
629
|
+
### `readRenderChainObservation`
|
|
630
|
+
|
|
631
|
+
`function` — Compose game-provided render nodes in a measured, fail-closed chain.
|
|
632
|
+
|
|
633
|
+
```ts
|
|
634
|
+
export function readRenderChainObservation( renderer: unknown, ): IRenderChainMarker["applied"] | undefined { … }
|
|
635
|
+
```
|
|
636
|
+
|
|
637
|
+
- **Use when:** compose screen-space effects in a canonical order · report which render tier and velocity route actually ran
|
|
638
|
+
- **Constraints:** stage factories own colour, strength, and all other appearance choices
|
|
639
|
+
|
|
640
|
+
```ts
|
|
641
|
+
const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
|
|
642
|
+
```
|
|
643
|
+
|
|
644
|
+
### `readRenderChainReport`
|
|
645
|
+
|
|
646
|
+
`function` — Compose game-provided render nodes in a measured, fail-closed chain.
|
|
647
|
+
|
|
648
|
+
```ts
|
|
649
|
+
export function readRenderChainReport(renderer: unknown): IRenderChainMarker | undefined { … }
|
|
650
|
+
```
|
|
651
|
+
|
|
652
|
+
- **Use when:** compose screen-space effects in a canonical order · report which render tier and velocity route actually ran · expose the render tier and dropped-stage reasons to a playtest · inspect whether a temporal pass received velocity
|
|
653
|
+
- **Constraints:** stage factories own colour, strength, and all other appearance choices · an absent value means no chain was installed and must fail a chain assertion
|
|
654
|
+
|
|
655
|
+
```ts
|
|
656
|
+
const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
|
|
657
|
+
```
|
|
658
|
+
|
|
659
|
+
### `readVelocityPreviousBoneMatrices`
|
|
660
|
+
|
|
661
|
+
`function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
|
|
662
|
+
|
|
663
|
+
```ts
|
|
664
|
+
export function readVelocityPreviousBoneMatrices(object: Object3D): Float32Array | undefined { … }
|
|
665
|
+
```
|
|
666
|
+
|
|
667
|
+
- **Use when:** keep a skinned character or instanced crowd stable in a temporal stage · add the velocity output to a Three.js scene pass · inspect the previous skinned pose at a renderer adapter boundary
|
|
668
|
+
- **Constraints:** call `VelocityTracker.update()` before the render and `commit()` after it · a pass is only given a velocity target when a temporal stage consumes it
|
|
669
|
+
|
|
670
|
+
```ts
|
|
671
|
+
const scenePass = pass(scene, camera);
|
|
672
|
+
ensureVelocityOutput(scenePass);
|
|
673
|
+
renderer.setOutputNode(scenePass);
|
|
674
|
+
const tracker = new VelocityTracker();
|
|
675
|
+
tracker.update(scene);
|
|
676
|
+
renderer.render(scene, camera);
|
|
677
|
+
tracker.commit(scene);
|
|
678
|
+
```
|
|
679
|
+
|
|
680
|
+
### `readVelocityPreviousMatrices`
|
|
681
|
+
|
|
682
|
+
`function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
|
|
683
|
+
|
|
684
|
+
```ts
|
|
685
|
+
export function readVelocityPreviousMatrices(object: Object3D): Float32Array | undefined { … }
|
|
686
|
+
```
|
|
687
|
+
|
|
688
|
+
- **Use when:** keep a skinned character or instanced crowd stable in a temporal stage · add the velocity output to a Three.js scene pass · inspect the previous instance frame at a renderer adapter boundary
|
|
689
|
+
- **Constraints:** call `VelocityTracker.update()` before the render and `commit()` after it · a pass is only given a velocity target when a temporal stage consumes it
|
|
690
|
+
|
|
691
|
+
```ts
|
|
692
|
+
const scenePass = pass(scene, camera);
|
|
693
|
+
ensureVelocityOutput(scenePass);
|
|
694
|
+
renderer.setOutputNode(scenePass);
|
|
695
|
+
const tracker = new VelocityTracker();
|
|
696
|
+
tracker.update(scene);
|
|
697
|
+
renderer.render(scene, camera);
|
|
698
|
+
tracker.commit(scene);
|
|
699
|
+
```
|
|
700
|
+
|
|
701
|
+
### `readVelocityPreviousWorldMatrix`
|
|
702
|
+
|
|
703
|
+
`function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
|
|
704
|
+
|
|
705
|
+
```ts
|
|
706
|
+
export function readVelocityPreviousWorldMatrix(object: Object3D): Matrix4 | undefined { … }
|
|
707
|
+
```
|
|
708
|
+
|
|
709
|
+
- **Use when:** keep a skinned character or instanced crowd stable in a temporal stage · add the velocity output to a Three.js scene pass · inspect the previous rigid transform at a renderer adapter boundary
|
|
710
|
+
- **Constraints:** call `VelocityTracker.update()` before the render and `commit()` after it · a pass is only given a velocity target when a temporal stage consumes it
|
|
711
|
+
|
|
712
|
+
```ts
|
|
713
|
+
const scenePass = pass(scene, camera);
|
|
714
|
+
ensureVelocityOutput(scenePass);
|
|
715
|
+
renderer.setOutputNode(scenePass);
|
|
716
|
+
const tracker = new VelocityTracker();
|
|
717
|
+
tracker.update(scene);
|
|
718
|
+
renderer.render(scene, camera);
|
|
719
|
+
tracker.commit(scene);
|
|
720
|
+
```
|
|
721
|
+
|
|
722
|
+
### `RenderChain`
|
|
723
|
+
|
|
724
|
+
`class` — Compose game-provided render nodes in a measured, fail-closed chain.
|
|
725
|
+
|
|
726
|
+
```ts
|
|
727
|
+
export class RenderChain { … }
|
|
728
|
+
```
|
|
729
|
+
|
|
730
|
+
- **Use when:** compose screen-space effects in a canonical order · report which render tier and velocity route actually ran
|
|
731
|
+
- **Constraints:** stage factories own colour, strength, and all other appearance choices
|
|
732
|
+
|
|
733
|
+
```ts
|
|
734
|
+
const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
|
|
735
|
+
```
|
|
736
|
+
|
|
737
|
+
### `replay`
|
|
738
|
+
|
|
739
|
+
`function` — Record or replay deterministic game input and state.
|
|
740
|
+
|
|
741
|
+
```ts
|
|
742
|
+
export function replay< TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined, >(options: IReplayOptions = { … }
|
|
743
|
+
```
|
|
744
|
+
|
|
745
|
+
- **Use when:** reproduce a gameplay bug from recorded input · run a deterministic replay in a playtest
|
|
746
|
+
- **Constraints:** use a seeded random source and fixed-step simulation for meaningful replays
|
|
747
|
+
|
|
748
|
+
```ts
|
|
749
|
+
const driver = createReplayDriver({ recording });
|
|
750
|
+
```
|
|
751
|
+
|
|
752
|
+
### `resolveAtmosphereLutResolutions`
|
|
753
|
+
|
|
754
|
+
`function` — Resolve the three LUT dimensions, allowing a game to trade startup cost for resolution.
|
|
755
|
+
|
|
756
|
+
```ts
|
|
757
|
+
export function resolveAtmosphereLutResolutions( resolutions: Partial<IAtmosphereLutResolutions> | undefined, ): IAtmosphereLutResolutions { … }
|
|
758
|
+
```
|
|
759
|
+
|
|
760
|
+
- **Use when:** choose atmosphere LUT dimensions for a measured startup budget
|
|
761
|
+
- **Constraints:** every width and height must be a positive integer; the dimensions are not a named fidelity tier
|
|
762
|
+
|
|
763
|
+
```ts
|
|
764
|
+
const resolutions = resolveAtmosphereLutResolutions({ skyView: { width: 128, height: 72 } });
|
|
765
|
+
```
|
|
766
|
+
|
|
767
|
+
### `resolveAtmosphereParameters`
|
|
768
|
+
|
|
769
|
+
`function` — Validate and clone game-owned atmosphere coefficients.
|
|
770
|
+
|
|
771
|
+
```ts
|
|
772
|
+
export function resolveAtmosphereParameters( options: IAtmosphereParameters, ): IResolvedAtmosphereParameters { … }
|
|
773
|
+
```
|
|
774
|
+
|
|
775
|
+
- **Use when:** validate atmosphere coefficients before a game creates its sky
|
|
776
|
+
- **Constraints:** provide all three coefficient vectors and both radii; omitted fields are errors
|
|
777
|
+
|
|
778
|
+
```ts
|
|
779
|
+
const parameters = resolveAtmosphereParameters({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
|
|
780
|
+
```
|
|
781
|
+
|
|
782
|
+
### `Scene`
|
|
783
|
+
|
|
784
|
+
`class` — Implement a portable Godot-shaped game scene lifecycle.
|
|
785
|
+
|
|
786
|
+
```ts
|
|
787
|
+
export abstract class Scene< TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined, > { … }
|
|
788
|
+
```
|
|
789
|
+
|
|
790
|
+
- **Use when:** add a playable level or menu scene · move scene setup and per-frame gameplay out of the entry point
|
|
791
|
+
- **Constraints:** scene code must stay portable across web and native
|
|
792
|
+
|
|
793
|
+
```ts
|
|
794
|
+
class Play extends Scene { update(ctx, dt) {} }
|
|
795
|
+
```
|
|
796
|
+
|
|
797
|
+
### `ScenePicker`
|
|
798
|
+
|
|
799
|
+
`class` — Raycast the game scene using the framework's picker.
|
|
800
|
+
|
|
801
|
+
```ts
|
|
802
|
+
export class ScenePicker { … }
|
|
803
|
+
```
|
|
804
|
+
|
|
805
|
+
- **Use when:** select an object under the pointer · interact with the first collider or mesh hit
|
|
806
|
+
- **Supersedes (writing this fails `pnpm budgets`):** new Raycaster(
|
|
807
|
+
|
|
808
|
+
```ts
|
|
809
|
+
const picker = new ScenePicker({ camera, scene });
|
|
810
|
+
```
|
|
811
|
+
|
|
812
|
+
### `Scheduler`
|
|
813
|
+
|
|
814
|
+
`class` — Schedule delayed and repeating callbacks or tween numeric properties with game-owned cleanup.
|
|
815
|
+
|
|
816
|
+
```ts
|
|
817
|
+
export class Scheduler { … }
|
|
818
|
+
```
|
|
819
|
+
|
|
820
|
+
- **Use when:** delay an enemy patrol transition · run a callback every simulation tick · tween a numeric property with a game-owned curve
|
|
821
|
+
- **Constraints:** dispose returned handles when the owning scene exits · ease receives progress in the range 0 to 1 and its return value is the interpolation factor
|
|
822
|
+
|
|
823
|
+
```ts
|
|
824
|
+
const door = { y: 0 };
|
|
825
|
+
await ctx.tween(door, { y: 2.4 }, 0.5, { ease: (t) => 1 - (1 - t) ** 3 });
|
|
826
|
+
```
|
|
827
|
+
|
|
828
|
+
### `skeletonBones`
|
|
829
|
+
|
|
830
|
+
`function` — List the names of every bone in a character hierarchy.
|
|
831
|
+
|
|
832
|
+
```ts
|
|
833
|
+
export function skeletonBones(root: Object3D): readonly string[] { … }
|
|
834
|
+
```
|
|
835
|
+
|
|
836
|
+
- **Use when:** inspect the available bones before attaching a game-owned object · debug a missing skeleton bone name
|
|
837
|
+
|
|
838
|
+
```ts
|
|
839
|
+
import { skeletonBones } from "@threenative/core";
|
|
840
|
+
const bones = skeletonBones(character);
|
|
841
|
+
```
|
|
842
|
+
|
|
843
|
+
### `SoftBody3D`
|
|
844
|
+
|
|
845
|
+
`class` — Simulate an ordinary game-authored triangle mesh as cloth on the existing fixed-step GPU lane. The mesh supplies every visible choice. This class welds exporter duplicates, owns spring and position buffers, and replaces only the cloned material's position node. It adds no material, colour, texture, wind, stiffness, damping, or pinning default.
|
|
846
|
+
|
|
847
|
+
```ts
|
|
848
|
+
export class SoftBody3D extends Mesh<BufferGeometry, NodeMaterial> implements IComputeDriven { … }
|
|
849
|
+
```
|
|
850
|
+
|
|
851
|
+
- **Use when:** make a flag, cape, or curtain move as cloth · simulate a deforming surface while keeping one edge pinned · simulate cloth sails blowing in the wind · make cloth sails billow in wind on a ship
|
|
852
|
+
- **Constraints:** the mesh must use one Three.js node material and contain complete triangles · pinned, stiffness, damping, gravity, and wind are required game-owned inputs · Pixel 8 steady upper bound for the shipped 45-vertex pennant with readback every two frames: whole-starter update p95 4.66 ms, render p95 3.56 ms, and GPU timer 0.05 ms across three 300-frame final-rung windows at 552x248 with 4x MSAA; these whole-scene numbers are not isolated solver cost
|
|
853
|
+
- **Overrides:** timeStep follows the engine 1/60-second convention unless the game overrides it · readbackEveryFrames enables an explicitly stale CPU position sample; zero disables it
|
|
854
|
+
|
|
855
|
+
```ts
|
|
856
|
+
const flag = new SoftBody3D(flagMesh, { pinned: topEdge, stiffness: 35, damping: 1.8, gravity: [0, -9.81, 0], wind: [1.5, 0, 0.4] });
|
|
857
|
+
```
|
|
858
|
+
|
|
859
|
+
### `softCircleDataTexture`
|
|
860
|
+
|
|
861
|
+
`function` — Build a soft round sprite as pixel data instead of painting a canvas.
|
|
862
|
+
|
|
863
|
+
```ts
|
|
864
|
+
export function softCircleDataTexture(size = 64, hardness = 0.25): DataTexture { … }
|
|
865
|
+
```
|
|
866
|
+
|
|
867
|
+
- **Use when:** give smoke, flash, or glow sprites a radial alpha falloff · generate sprite images that render identically under every backend
|
|
868
|
+
- **Constraints:** canvas-painted images sample black under WebGPURenderer; write sprites as pixel data there
|
|
869
|
+
|
|
870
|
+
```ts
|
|
871
|
+
const puff = softCircleDataTexture(64, 0.25);
|
|
872
|
+
```
|
|
873
|
+
|
|
874
|
+
### `solarPosition`
|
|
875
|
+
|
|
876
|
+
`function` — Calculate solar elevation and azimuth from time, latitude, and longitude.
|
|
877
|
+
|
|
878
|
+
```ts
|
|
879
|
+
export function solarPosition(input: ISolarPositionInput, target?: ISolarPosition): ISolarPosition;
|
|
880
|
+
```
|
|
881
|
+
|
|
882
|
+
- **Use when:** move a sun across a real day at a game's latitude and longitude
|
|
883
|
+
- **Constraints:** dates are interpreted as UTC unless utcOffset is supplied; no fixed sun direction is assumed · pass a mutable { azimuth, elevation } target to reuse the result object in a steady frame loop
|
|
884
|
+
|
|
885
|
+
```ts
|
|
886
|
+
const sun = solarPosition({ date, latitude: 49.28, longitude: -123.12, utcOffset: -8 });
|
|
887
|
+
```
|
|
888
|
+
|
|
889
|
+
### `solarPositionAt`
|
|
890
|
+
|
|
891
|
+
`function` — Calculate solar elevation and azimuth for one UTC date.
|
|
892
|
+
|
|
893
|
+
```ts
|
|
894
|
+
export function solarPositionAt( date: Date | string, latitude: number, longitude: number, ): ISolarPosition { … }
|
|
895
|
+
```
|
|
896
|
+
|
|
897
|
+
- **Use when:** calculate a sun direction from a timestamp and a game location
|
|
898
|
+
- **Constraints:** dates are interpreted as UTC; use solarPosition for an explicit local offset
|
|
899
|
+
|
|
900
|
+
```ts
|
|
901
|
+
const sun = solarPositionAt(new Date(), 49.28, -123.12);
|
|
902
|
+
```
|
|
903
|
+
|
|
904
|
+
### `SpectralOcean`
|
|
905
|
+
|
|
906
|
+
`class` — Simulate a spectral ocean — cascaded wave spectra inverse-transformed on the GPU each frame.
|
|
907
|
+
|
|
908
|
+
```ts
|
|
909
|
+
export class SpectralOcean extends Object3D implements IComputeDriven { … }
|
|
910
|
+
```
|
|
911
|
+
|
|
912
|
+
- **Use when:** make an ocean whose surface is the view rather than a background · float a boat on waves the GPU is drawing · drive a water material from a wave simulation without writing an FFT · sail a ship on simulated ocean waves with buoyancy
|
|
913
|
+
- **Constraints:** it draws nothing; the game supplies the mesh, the material and every colour · CPU height is a throttled copy carrying staleFrames, never this frame and never exact · an exact free CPU height needs an analytic wave field instead; that is a different contract · cascades are ordered largest patchSize first and every tuning number is required
|
|
914
|
+
|
|
915
|
+
```ts
|
|
916
|
+
const sea = ctx.add(new SpectralOcean(oceanOptions));
|
|
917
|
+
```
|
|
918
|
+
|
|
919
|
+
### `SpriteAnimator3D`
|
|
920
|
+
|
|
921
|
+
`class` — Advance a game-owned non-uniform sprite atlas on the fixed step.
|
|
922
|
+
|
|
923
|
+
```ts
|
|
924
|
+
export class SpriteAnimator3D { … }
|
|
925
|
+
```
|
|
926
|
+
|
|
927
|
+
- **Use when:** play an animated pickup or sprite-sheet effect · sequence atlas frames with different authored durations
|
|
928
|
+
- **Constraints:** the game supplies the atlas texture, surface, filtering, layout, and every frame duration · update is driven by the scene fixed step; no wall clock or default frame rate is used
|
|
929
|
+
|
|
930
|
+
```ts
|
|
931
|
+
const animator = new SpriteAnimator3D({ texture: atlas, frames, mode: "pingPong" });
|
|
932
|
+
```
|
|
933
|
+
|
|
934
|
+
### `TracerPool3D`
|
|
935
|
+
|
|
936
|
+
`class` — Pool travelling bullet-streak meshes for hitscan shots.
|
|
937
|
+
|
|
938
|
+
```ts
|
|
939
|
+
export class TracerPool3D { … }
|
|
940
|
+
```
|
|
941
|
+
|
|
942
|
+
- **Use when:** show where a hitscan round went · draw incoming fire without spawning projectiles
|
|
943
|
+
- **Constraints:** the surface comes from the game; pooling, travel, and fading belong to the engine · update once per frame and dispose with the owning scene
|
|
944
|
+
|
|
945
|
+
```ts
|
|
946
|
+
const tracers = new TracerPool3D(ctx.scene, tracerOptions);
|
|
947
|
+
tracers.spawn(muzzle, shotDirection, hit.distance);
|
|
948
|
+
```
|
|
949
|
+
|
|
950
|
+
### `updateAtmosphereParameters`
|
|
951
|
+
|
|
952
|
+
`function` — Apply a partial game-owned atmosphere change while preserving validation.
|
|
953
|
+
|
|
954
|
+
```ts
|
|
955
|
+
export function updateAtmosphereParameters( current: IResolvedAtmosphereParameters, patch: IAtmosphereParameterPatch, ): IResolvedAtmosphereParameters { … }
|
|
956
|
+
```
|
|
957
|
+
|
|
958
|
+
- **Use when:** change scattering coefficients and rebake an atmosphere
|
|
959
|
+
- **Constraints:** patches cannot introduce omitted, negative, or non-finite physical values
|
|
960
|
+
|
|
961
|
+
```ts
|
|
962
|
+
atmosphere.setAtmosphere({ rayleigh: [0.008, 0.016, 0.04] });
|
|
963
|
+
```
|
|
964
|
+
|
|
965
|
+
### `updateClusteredMeshes`
|
|
966
|
+
|
|
967
|
+
`function` — Take every clustered mesh under a root through this frame's cut, before the render. The engine already does this for the scene it renders; reach for it only to cut a subtree the engine does not render, such as one staged for a camera of your own.
|
|
968
|
+
|
|
969
|
+
```ts
|
|
970
|
+
export function updateClusteredMeshes( root: { … }
|
|
971
|
+
```
|
|
972
|
+
|
|
973
|
+
- **Use when:** cut a virtual-geometry subtree the engine does not render itself
|
|
974
|
+
|
|
975
|
+
```ts
|
|
976
|
+
updateClusteredMeshes(stagedRoot, myCamera, ctx.renderer.domElement.height);
|
|
977
|
+
```
|
|
978
|
+
|
|
979
|
+
### `velocityTexture`
|
|
980
|
+
|
|
981
|
+
`function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
|
|
982
|
+
|
|
983
|
+
```ts
|
|
984
|
+
export function velocityTexture(pass: IVelocityRenderPass): Node { … }
|
|
985
|
+
```
|
|
986
|
+
|
|
987
|
+
- **Use when:** keep a skinned character or instanced crowd stable in a temporal stage · add the velocity output to a Three.js scene pass · read screen-space motion for a temporal stage
|
|
988
|
+
- **Constraints:** call `VelocityTracker.update()` before the render and `commit()` after it · a pass is only given a velocity target when a temporal stage consumes it
|
|
989
|
+
|
|
990
|
+
```ts
|
|
991
|
+
const scenePass = pass(scene, camera);
|
|
992
|
+
ensureVelocityOutput(scenePass);
|
|
993
|
+
renderer.setOutputNode(scenePass);
|
|
994
|
+
const tracker = new VelocityTracker();
|
|
995
|
+
tracker.update(scene);
|
|
996
|
+
renderer.render(scene, camera);
|
|
997
|
+
tracker.commit(scene);
|
|
998
|
+
```
|
|
999
|
+
|
|
1000
|
+
### `VelocityTracker`
|
|
1001
|
+
|
|
1002
|
+
`class` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
|
|
1003
|
+
|
|
1004
|
+
```ts
|
|
1005
|
+
export class VelocityTracker { … }
|
|
1006
|
+
```
|
|
1007
|
+
|
|
1008
|
+
- **Use when:** keep a skinned character or instanced crowd stable in a temporal stage · add the velocity output to a Three.js scene pass · retain previous transforms for animated and instanced renderables
|
|
1009
|
+
- **Constraints:** call `VelocityTracker.update()` before the render and `commit()` after it · a pass is only given a velocity target when a temporal stage consumes it · call `update()` after gameplay writes and `commit()` after the render
|
|
1010
|
+
|
|
1011
|
+
```ts
|
|
1012
|
+
const scenePass = pass(scene, camera);
|
|
1013
|
+
ensureVelocityOutput(scenePass);
|
|
1014
|
+
renderer.setOutputNode(scenePass);
|
|
1015
|
+
const tracker = new VelocityTracker();
|
|
1016
|
+
tracker.update(scene);
|
|
1017
|
+
renderer.render(scene, camera);
|
|
1018
|
+
tracker.commit(scene);
|
|
1019
|
+
```
|
|
1020
|
+
|
|
1021
|
+
### `warmUpScene`
|
|
1022
|
+
|
|
1023
|
+
`function` — Warms up `scene` for `camera`, in slices, presenting a frame between each. Fail closed on a nonsensical slice size rather than quietly choosing one: a zero or negative slice would loop forever, and a caller that passed it has a bug worth seeing now.
|
|
1024
|
+
|
|
1025
|
+
```ts
|
|
1026
|
+
export async function warmUpScene( renderer: IWarmUpRenderer, scene: Object3D, camera: Camera, options: IWarmUpOptions = { … }
|
|
1027
|
+
```
|
|
1028
|
+
|
|
1029
|
+
- **Use when:** compile a scene's shaders during the loading screen instead of on the first frame · stop a native launch freezing for seconds inside its first rendered frame
|
|
1030
|
+
|
|
1031
|
+
```ts
|
|
1032
|
+
await warmUpScene(renderer, scene, camera, { onProgress: (p) => setLoading(p) });
|
|
1033
|
+
```
|
|
1034
|
+
|
|
1035
|
+
### `WaveField`
|
|
1036
|
+
|
|
1037
|
+
`class` — Evaluate analytic waves on CPU and displace game-owned vertices with the matching TSL graph.
|
|
1038
|
+
|
|
1039
|
+
```ts
|
|
1040
|
+
export class WaveField { … }
|
|
1041
|
+
```
|
|
1042
|
+
|
|
1043
|
+
- **Use when:** float a boat on waves · make water move · find the water surface height at a point
|
|
1044
|
+
- **Constraints:** supply every wave amplitude, wavelength, direction, speed and warp value · call setTime for the default graph clock when the game advances its own time
|
|
1045
|
+
|
|
1046
|
+
```ts
|
|
1047
|
+
const field = new WaveField({ waves });
|
|
1048
|
+
const { height, normal } = field.sample(x, z, elapsed);
|
|
1049
|
+
```
|
|
1050
|
+
|
|
1051
|
+
### `withVelocityContext`
|
|
1052
|
+
|
|
1053
|
+
`function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
|
|
1054
|
+
|
|
1055
|
+
```ts
|
|
1056
|
+
export function withVelocityContext<T>(node: T, source: Node): T { … }
|
|
1057
|
+
```
|
|
1058
|
+
|
|
1059
|
+
- **Use when:** keep a skinned character or instanced crowd stable in a temporal stage · add the velocity output to a Three.js scene pass · hand the provisioned velocity source through a composed temporal graph
|
|
1060
|
+
- **Constraints:** call `VelocityTracker.update()` before the render and `commit()` after it · a pass is only given a velocity target when a temporal stage consumes it
|
|
1061
|
+
|
|
1062
|
+
```ts
|
|
1063
|
+
const scenePass = pass(scene, camera);
|
|
1064
|
+
ensureVelocityOutput(scenePass);
|
|
1065
|
+
renderer.setOutputNode(scenePass);
|
|
1066
|
+
const tracker = new VelocityTracker();
|
|
1067
|
+
tracker.update(scene);
|
|
1068
|
+
renderer.render(scene, camera);
|
|
1069
|
+
tracker.commit(scene);
|
|
1070
|
+
```
|
|
1071
|
+
|
|
1072
|
+
### `zenithTransmittance`
|
|
1073
|
+
|
|
1074
|
+
`function` — Return direct vertical transmittance for the supplied atmosphere.
|
|
1075
|
+
|
|
1076
|
+
```ts
|
|
1077
|
+
export function zenithTransmittance( parameters: IAtmosphereParameters | IResolvedAtmosphereParameters, ): AtmosphereRgb { … }
|
|
1078
|
+
```
|
|
1079
|
+
|
|
1080
|
+
- **Use when:** check a supplied atmosphere's direct vertical transmittance
|
|
1081
|
+
- **Constraints:** use the returned value as a validation oracle; the rendered path samples the LUT
|
|
1082
|
+
|
|
1083
|
+
```ts
|
|
1084
|
+
const zenith = zenithTransmittance({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
|
|
1085
|
+
```
|
|
1086
|
+
|
|
1087
|
+
## `@threenative/core/hot`
|
|
1088
|
+
|
|
1089
|
+
### `acceptHotUpdate`
|
|
1090
|
+
|
|
1091
|
+
`function` — Register hot-reload state preservation for a game.
|
|
1092
|
+
|
|
1093
|
+
```ts
|
|
1094
|
+
export function acceptHotUpdate<TState extends Record<string, unknown>, TPhysics>( game: IGame<TState, TPhysics>, hot: IImportMeta["hot"], ): void { … }
|
|
1095
|
+
```
|
|
1096
|
+
|
|
1097
|
+
- **Use when:** keep game state while editing source in development · diagnose state shape changes during hot reload
|
|
1098
|
+
- **Constraints:** use only in the web development entry
|
|
1099
|
+
|
|
1100
|
+
```ts
|
|
1101
|
+
acceptHotUpdate(game, import.meta.hot);
|
|
1102
|
+
```
|
|
1103
|
+
|
|
1104
|
+
### `assertPortableState`
|
|
1105
|
+
|
|
1106
|
+
`function` — Validate that hot-reload state can cross the Vite boundary.
|
|
1107
|
+
|
|
1108
|
+
```ts
|
|
1109
|
+
export function assertPortableState(state: unknown): void { … }
|
|
1110
|
+
```
|
|
1111
|
+
|
|
1112
|
+
- **Use when:** preserve JSON-shaped state during hot reload · reject a non-portable game state before reload
|
|
1113
|
+
- **Constraints:** state must contain finite numbers and plain objects only
|
|
1114
|
+
|
|
1115
|
+
```ts
|
|
1116
|
+
assertPortableState(game.state.getState());
|
|
1117
|
+
```
|
|
1118
|
+
|
|
1119
|
+
## `@threenative/core/playtest`
|
|
1120
|
+
|
|
1121
|
+
### `playtest`
|
|
1122
|
+
|
|
1123
|
+
`function` — Install the playtest bridge into a portable game.
|
|
1124
|
+
|
|
1125
|
+
```ts
|
|
1126
|
+
export function playtest< TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined, >(options: IPlaytestOptions = { … }
|
|
1127
|
+
```
|
|
1128
|
+
|
|
1129
|
+
- **Use when:** expose movement and world observations to a playtest · connect a game to the ThreeNative scenario runner
|
|
1130
|
+
- **Constraints:** install once in the game's plugin list
|
|
1131
|
+
|
|
1132
|
+
```ts
|
|
1133
|
+
const game = defineGame({ plugins: [playtest()] });
|
|
1134
|
+
```
|
|
1135
|
+
|
|
1136
|
+
## `@threenative/core/react`
|
|
1137
|
+
|
|
1138
|
+
### `createReactOverlay`
|
|
1139
|
+
|
|
1140
|
+
`function` — `@threenative/core/react` — React that renders on a phone, with no DOM and no WebView. A subpath on purpose. `react` and `react-reconciler` are **optional** peers, and nothing in `@threenative/core`'s main entry imports either of them, so a game that never mounts a React overlay pays nothing and core stays consumable from React Three Fiber. Importing this module is the opt-in. The element vocabulary is two components, borrowed from React Native rather than invented: {@link View} is a rectangle, {@link Text} is a run of glyphs. They are components and not lowercase intrinsics because `view` and `text` are already SVG tags in `@types/react`, and a HUD element that silently means `<svg:text>` on one platform is exactly the kind of quiet divergence this path exists to end.
|
|
1141
|
+
|
|
1142
|
+
```ts
|
|
1143
|
+
export function createReactOverlay(options: IReactOverlayOptions): IReactOverlay { … }
|
|
1144
|
+
```
|
|
1145
|
+
|
|
1146
|
+
- **Use when:** render a React HUD on Android or iOS without a WebView · show the same React component on web and on a phone · show a React HUD on Android, iOS or desktop native · render the same React component on web and on a phone without a WebView
|
|
1147
|
+
- **Constraints:** styling is the `style` prop; Tailwind class names are CSS and cannot cross · import `react`, never `react-dom`, from the portable native entry · import `react`, never `react-dom`, from a native entry
|
|
1148
|
+
|
|
1149
|
+
```ts
|
|
1150
|
+
const overlay = createReactOverlay({ canvasLayer: ctx.canvasLayer });
|
|
1151
|
+
```
|
|
1152
|
+
|
|
1153
|
+
### `measureText`
|
|
1154
|
+
|
|
1155
|
+
`function` — Width in pixels of a glyph run at a given cell height.
|
|
1156
|
+
|
|
1157
|
+
```ts
|
|
1158
|
+
export function measureText(text: string, fontSize: number, letterSpacing = 0): number { … }
|
|
1159
|
+
```
|
|
1160
|
+
|
|
1161
|
+
- **Use when:** measure native React HUD text before laying it out
|
|
1162
|
+
|
|
1163
|
+
```ts
|
|
1164
|
+
const scoreWidth = measureText("SCORE 10", 24)
|
|
1165
|
+
```
|
|
1166
|
+
|
|
1167
|
+
### `supportedGlyphs`
|
|
1168
|
+
|
|
1169
|
+
`function` — Every character this glyph set can draw, for error messages and for the templates' AGENTS.md.
|
|
1170
|
+
|
|
1171
|
+
```ts
|
|
1172
|
+
export function supportedGlyphs(): string { … }
|
|
1173
|
+
```
|
|
1174
|
+
|
|
1175
|
+
- **Use when:** discover which characters a native React HUD can draw
|
|
1176
|
+
|
|
1177
|
+
```ts
|
|
1178
|
+
supportedGlyphs().includes("A")
|
|
1179
|
+
```
|
|
1180
|
+
|
|
1181
|
+
### `supportedStyleKeys`
|
|
1182
|
+
|
|
1183
|
+
`function` — Every style key the overlay implements, for the templates' AGENTS.md and for error messages.
|
|
1184
|
+
|
|
1185
|
+
```ts
|
|
1186
|
+
export function supportedStyleKeys(): readonly string[] { … }
|
|
1187
|
+
```
|
|
1188
|
+
|
|
1189
|
+
- **Use when:** discover which React HUD style properties work on native
|
|
1190
|
+
|
|
1191
|
+
```ts
|
|
1192
|
+
supportedStyleKeys().includes("centerX")
|
|
1193
|
+
```
|
|
1194
|
+
|
|
1195
|
+
### `Text`
|
|
1196
|
+
|
|
1197
|
+
`function` — A run of bitmap glyphs, drawn as one instanced quad per lit pixel.
|
|
1198
|
+
|
|
1199
|
+
```ts
|
|
1200
|
+
export function Text(props: ITextProps): ReactNode { … }
|
|
1201
|
+
```
|
|
1202
|
+
|
|
1203
|
+
- **Use when:** show text in a native React HUD without a DOM
|
|
1204
|
+
|
|
1205
|
+
```ts
|
|
1206
|
+
<Text style={{ color: "#ffffff", fontSize: 24 }}>SCORE 10</Text>
|
|
1207
|
+
```
|
|
1208
|
+
|
|
1209
|
+
### `View`
|
|
1210
|
+
|
|
1211
|
+
`function` — A rectangle. Paints when its style has a `background`; otherwise it only positions children.
|
|
1212
|
+
|
|
1213
|
+
```ts
|
|
1214
|
+
export function View(props: IViewProps): ReactNode { … }
|
|
1215
|
+
```
|
|
1216
|
+
|
|
1217
|
+
- **Use when:** group and position native React HUD elements
|
|
1218
|
+
|
|
1219
|
+
```ts
|
|
1220
|
+
<View style={{ centerX: 0, top: 24 }}><Text>READY</Text></View>
|
|
1221
|
+
```
|
|
1222
|
+
|
|
1223
|
+
## `@threenative/core/ui-layer`
|
|
1224
|
+
|
|
1225
|
+
### `connectUiBridge`
|
|
1226
|
+
|
|
1227
|
+
`function` — Open the message channel between a game and its UI, whatever host is underneath.
|
|
1228
|
+
|
|
1229
|
+
```ts
|
|
1230
|
+
export function connectUiBridge(options: IConnectOptions): IUiBridge { … }
|
|
1231
|
+
```
|
|
1232
|
+
|
|
1233
|
+
- **Use when:** write a UI that talks to the game on web and on a phone alike · send a message from a HUD rendered over the game surface · connect game code to a platform-owned UI realm · share one UI bridge implementation across web, Android, iOS, and desktop
|
|
1234
|
+
- **Constraints:** the transport is discovered, never configured; no game names the web view
|
|
1235
|
+
|
|
1236
|
+
```ts
|
|
1237
|
+
const bridge = connectUiBridge({ end: "ui" });
|
|
1238
|
+
```
|
|
1239
|
+
|
|
1240
|
+
### `onUiIntent`
|
|
1241
|
+
|
|
1242
|
+
`function` — Handle the actions a UI sends back to the game.
|
|
1243
|
+
|
|
1244
|
+
```ts
|
|
1245
|
+
export function onUiIntent( bridge: IUiBridge, listener: (intent: string, payload: unknown) => void, ): () => void { … }
|
|
1246
|
+
```
|
|
1247
|
+
|
|
1248
|
+
- **Use when:** restart or pause a game from a button in its HUD · handle a HUD button action in game code · route native and web UI commands through one listener
|
|
1249
|
+
- **Constraints:** prefer game.ui.onIntent, which connects the bridge for you
|
|
1250
|
+
|
|
1251
|
+
```ts
|
|
1252
|
+
onUiIntent(bridge, (intent) => { if (intent === "restart") game.goto("Play"); });
|
|
1253
|
+
```
|
|
1254
|
+
|
|
1255
|
+
### `publishHitRegions`
|
|
1256
|
+
|
|
1257
|
+
`function` — Tell the native input host where a UI's touchable controls are.
|
|
1258
|
+
|
|
1259
|
+
```ts
|
|
1260
|
+
export function publishHitRegions(options: IRegistryOptions): IHitRegionRegistry { … }
|
|
1261
|
+
```
|
|
1262
|
+
|
|
1263
|
+
- **Use when:** let a touch on empty HUD space reach the game instead of the UI · make a HUD button receive taps on a phone · give native input hosts the rectangles claimed by UI controls · keep touch hit testing aligned with a moving web or native HUD
|
|
1264
|
+
- **Constraints:** mark controls with data-tn-interactive; pointer-events is not the mechanism
|
|
1265
|
+
|
|
1266
|
+
```ts
|
|
1267
|
+
publishHitRegions({ bridge });
|
|
1268
|
+
```
|
|
1269
|
+
|
|
1270
|
+
### `publishUiState`
|
|
1271
|
+
|
|
1272
|
+
`function` — Publish the game's state so a UI in another process can mirror it.
|
|
1273
|
+
|
|
1274
|
+
```ts
|
|
1275
|
+
export function publishUiState<T>( bridge: IUiBridge, store: IPublishableStore<T>, options: IPublishOptions = { … }
|
|
1276
|
+
```
|
|
1277
|
+
|
|
1278
|
+
- **Use when:** show score or health in a UI rendered over the game surface · keep a HUD in step with the game without re-rendering on the loop · publish game state to a HUD in another realm · keep a web and native UI mirror on the same throttled state stream
|
|
1279
|
+
- **Constraints:** publishes at the store's throttled cadence, and not at all with no UI listening
|
|
1280
|
+
|
|
1281
|
+
```ts
|
|
1282
|
+
publishUiState(bridge, game.state);
|
|
1283
|
+
```
|
|
1284
|
+
|
|
1285
|
+
### `sendUiIntent`
|
|
1286
|
+
|
|
1287
|
+
`function` — Send a player action from the UI back to the game.
|
|
1288
|
+
|
|
1289
|
+
```ts
|
|
1290
|
+
export function sendUiIntent(bridge: IUiBridge, intent: string, payload?: unknown): void { … }
|
|
1291
|
+
```
|
|
1292
|
+
|
|
1293
|
+
- **Use when:** wire a Restart button in a HUD to the running game · pause a game from a menu drawn over its surface · send a button or menu action from a UI HUD to game code · keep UI input portable across web and native hosts
|
|
1294
|
+
- **Constraints:** one-way; the game decides what each name means and may ignore one
|
|
1295
|
+
|
|
1296
|
+
```ts
|
|
1297
|
+
sendUiIntent(bridge, "restart");
|
|
1298
|
+
```
|
|
1299
|
+
|
|
1300
|
+
### `subscribeUiState`
|
|
1301
|
+
|
|
1302
|
+
`function` — Mirror the game's published state on the UI side.
|
|
1303
|
+
|
|
1304
|
+
```ts
|
|
1305
|
+
export function subscribeUiState<T>(bridge: IUiBridge): IUiStateMirror<T> { … }
|
|
1306
|
+
```
|
|
1307
|
+
|
|
1308
|
+
- **Use when:** read game state from a HUD that runs in the platform's web view · read published game state from a UI HUD · subscribe a web or native UI to the game's mirrored state
|
|
1309
|
+
- **Constraints:** returns undefined until the game publishes its first state
|
|
1310
|
+
|
|
1311
|
+
```ts
|
|
1312
|
+
const mirror = subscribeUiState(bridge);
|
|
1313
|
+
```
|
|
1314
|
+
|
|
1315
|
+
## `@threenative/core/world`
|
|
1316
|
+
|
|
1317
|
+
### `Heightfield`
|
|
1318
|
+
|
|
1319
|
+
`class` — One height buffer shared by world queries, rendered geometry, and a physics heightfield. The game supplies every value, so changing the terrain's shape never requires a package edit. `fromSampler` evaluates that game function exactly once at each vertex and retains only the resulting numbers. Queries interpolate those same numbers instead of evaluating the function again.
|
|
1320
|
+
|
|
1321
|
+
```ts
|
|
1322
|
+
export class Heightfield { … }
|
|
1323
|
+
```
|
|
1324
|
+
|
|
1325
|
+
- **Use when:** build terrain geometry and collision from one game-authored height function · query the same ground height or normal that a player sees and collides with · build islands and coastlines from terrain
|
|
1326
|
+
- **Constraints:** sampleHeight owns the terrain shape and stays in game source; the framework stores and interpolates its output · rows and columns are vertex counts; geometry is row-major z-then-x and collider export transposes once into Rapier's column-major matrix order
|
|
1327
|
+
- **Overrides:** rows, columns, width, depth, origin, and sampleHeight are explicit on every field
|
|
1328
|
+
|
|
1329
|
+
```ts
|
|
1330
|
+
const field = Heightfield.fromSampler({ rows: 65, columns: 65, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: terrainHeight });
|
|
1331
|
+
```
|
|
1332
|
+
|
|
1333
|
+
## `@threenative/physics`
|
|
1334
|
+
|
|
1335
|
+
### `Area3D`
|
|
1336
|
+
|
|
1337
|
+
`class` — Detect overlaps without turning the body into a moving collider.
|
|
1338
|
+
|
|
1339
|
+
```ts
|
|
1340
|
+
export class Area3D { … }
|
|
1341
|
+
```
|
|
1342
|
+
|
|
1343
|
+
- **Use when:** detect when an enemy enters a trigger area · react to a player entering a zone
|
|
1344
|
+
- **Constraints:** add the area to the physics context before stepping the world
|
|
1345
|
+
|
|
1346
|
+
```ts
|
|
1347
|
+
const area = new Area3D({ context, shape });
|
|
1348
|
+
```
|
|
1349
|
+
|
|
1350
|
+
### `Buoyancy3D`
|
|
1351
|
+
|
|
1352
|
+
`class` — Float a rigid body on a game-owned height source with fixed-step force ordering.
|
|
1353
|
+
|
|
1354
|
+
```ts
|
|
1355
|
+
export class Buoyancy3D { … }
|
|
1356
|
+
```
|
|
1357
|
+
|
|
1358
|
+
- **Use when:** float a boat on waves · keep a hull above a moving water surface
|
|
1359
|
+
- **Constraints:** supply hull points, density, drag, and the height source
|
|
1360
|
+
- **Overrides:** buoyancy disables force application while submergedFraction remains measured
|
|
1361
|
+
|
|
1362
|
+
```ts
|
|
1363
|
+
new Buoyancy3D({ body, surface: field, hullPoints, density: 1_000, drag: 4 });
|
|
1364
|
+
```
|
|
1365
|
+
|
|
1366
|
+
### `CharacterBody3D`
|
|
1367
|
+
|
|
1368
|
+
`class` — Move a character body with collision-aware sliding.
|
|
1369
|
+
|
|
1370
|
+
```ts
|
|
1371
|
+
export class CharacterBody3D { … }
|
|
1372
|
+
```
|
|
1373
|
+
|
|
1374
|
+
- **Use when:** move an enemy or player through a level · keep a character from walking through walls
|
|
1375
|
+
- **Constraints:** use moveAndSlide inside the physics update
|
|
1376
|
+
|
|
1377
|
+
```ts
|
|
1378
|
+
const body = new CharacterBody3D({ context, object });
|
|
1379
|
+
```
|
|
1380
|
+
|
|
1381
|
+
### `CollisionShape3D`
|
|
1382
|
+
|
|
1383
|
+
`class` — Give a physics body a Three.js collision shape.
|
|
1384
|
+
|
|
1385
|
+
```ts
|
|
1386
|
+
export class CollisionShape3D { … }
|
|
1387
|
+
```
|
|
1388
|
+
|
|
1389
|
+
- **Use when:** add a capsule or box collider to a character · configure the shape used by a rigid body
|
|
1390
|
+
- **Constraints:** create shapes through the owning physics context
|
|
1391
|
+
|
|
1392
|
+
```ts
|
|
1393
|
+
const shape = new CollisionShape3D({ context, shape: "capsule" });
|
|
1394
|
+
```
|
|
1395
|
+
|
|
1396
|
+
### `interactionGroups`
|
|
1397
|
+
|
|
1398
|
+
`function` — Encode collision layers and masks for Rapier groups.
|
|
1399
|
+
|
|
1400
|
+
```ts
|
|
1401
|
+
export function interactionGroups(layer: number, mask: number): number { … }
|
|
1402
|
+
```
|
|
1403
|
+
|
|
1404
|
+
- **Use when:** make an enemy collide with the world but not pickups · configure which physics layers interact
|
|
1405
|
+
|
|
1406
|
+
```ts
|
|
1407
|
+
const groups = interactionGroups(1, 3);
|
|
1408
|
+
```
|
|
1409
|
+
|
|
1410
|
+
### `Joint3D`
|
|
1411
|
+
|
|
1412
|
+
`class` — Connect two physics bodies with a Godot-style joint.
|
|
1413
|
+
|
|
1414
|
+
```ts
|
|
1415
|
+
export class Joint3D { … }
|
|
1416
|
+
```
|
|
1417
|
+
|
|
1418
|
+
- **Use when:** constrain a rigid body to another body · build a hinge or pin mechanism
|
|
1419
|
+
- **Constraints:** both bodies must belong to the same physics context
|
|
1420
|
+
|
|
1421
|
+
```ts
|
|
1422
|
+
const joint = new Joint3D({ context, kind: "hinge" });
|
|
1423
|
+
```
|
|
1424
|
+
|
|
1425
|
+
### `PhysicsDirectSpaceState3D`
|
|
1426
|
+
|
|
1427
|
+
`class` — Query the physics world without creating a body.
|
|
1428
|
+
|
|
1429
|
+
```ts
|
|
1430
|
+
export class PhysicsDirectSpaceState3D { … }
|
|
1431
|
+
```
|
|
1432
|
+
|
|
1433
|
+
- **Use when:** raycast for visibility or aiming · find bodies inside a shape or point query
|
|
1434
|
+
- **Constraints:** query results are bounded by the configured result limit
|
|
1435
|
+
|
|
1436
|
+
```ts
|
|
1437
|
+
const space = new PhysicsDirectSpaceState3D(context);
|
|
1438
|
+
```
|
|
1439
|
+
|
|
1440
|
+
### `rapier`
|
|
1441
|
+
|
|
1442
|
+
`function` — Install the Rapier physics plugin and simulation backend.
|
|
1443
|
+
|
|
1444
|
+
```ts
|
|
1445
|
+
export function rapier(options: IPhysicsOptions = { … }
|
|
1446
|
+
```
|
|
1447
|
+
|
|
1448
|
+
- **Use when:** add physics to a portable game · provide the context used by character and rigid bodies
|
|
1449
|
+
- **Constraints:** place rapier() before recast() in the plugin list
|
|
1450
|
+
|
|
1451
|
+
```ts
|
|
1452
|
+
const game = defineGame({ plugins: [rapier()] });
|
|
1453
|
+
```
|
|
1454
|
+
|
|
1455
|
+
### `RigidBody3D`
|
|
1456
|
+
|
|
1457
|
+
`class` — Simulate a dynamic or static rigid body.
|
|
1458
|
+
|
|
1459
|
+
```ts
|
|
1460
|
+
export class RigidBody3D { … }
|
|
1461
|
+
```
|
|
1462
|
+
|
|
1463
|
+
- **Use when:** give a crate or prop physical motion · create a body that collides with a character · fire physical cannonballs that collide with ships or scenery · fire a cannonball projectile with cannon smoke particles
|
|
1464
|
+
- **Constraints:** register rapier() in the game plugin list before using bodies
|
|
1465
|
+
|
|
1466
|
+
```ts
|
|
1467
|
+
const crate = new RigidBody3D({ context, object, mode: "dynamic" });
|
|
1468
|
+
```
|
|
1469
|
+
|
|
1470
|
+
### `softBodyCollision`
|
|
1471
|
+
|
|
1472
|
+
`function` — Feed existing rigid-body boxes into `SoftBody3D` without inventing a second collider API.
|
|
1473
|
+
|
|
1474
|
+
```ts
|
|
1475
|
+
export function softBodyCollision(...bodies: readonly RigidBody3D[]): ISoftBodyCollision { … }
|
|
1476
|
+
```
|
|
1477
|
+
|
|
1478
|
+
- **Use when:** stop a cloth flag, cape, or curtain at an existing physics wall · collide SoftBody3D with fixed box bodies
|
|
1479
|
+
- **Constraints:** every body must use CollisionShape3D.box and retain its Three.js object transform · rotated boxes become conservative cloth-local axis-aligned bounds
|
|
1480
|
+
|
|
1481
|
+
```ts
|
|
1482
|
+
const cloth = new SoftBody3D(mesh, { ...options, collision: softBodyCollision(wall) });
|
|
1483
|
+
```
|
|
1484
|
+
|
|
1485
|
+
## `@threenative/physics/navigation`
|
|
1486
|
+
|
|
1487
|
+
### `NavigationAgent3D`
|
|
1488
|
+
|
|
1489
|
+
`class` — Move an agent along a baked navmesh toward a target.
|
|
1490
|
+
|
|
1491
|
+
```ts
|
|
1492
|
+
export class NavigationAgent3D { … }
|
|
1493
|
+
```
|
|
1494
|
+
|
|
1495
|
+
- **Use when:** enemy walks around a wall · enemy patrols a level and chases the player · enemy walks around a patrol path and chases the player when it sees them · enemy patrols and chases while avoiding obstacles · enemy chases the player with line of sight and obstacle avoidance · NPC walks to a destination · move crew around a ship deck
|
|
1496
|
+
- **Constraints:** import NavigationAgent3D from exactly `@threenative/physics/navigation`; `@threenative/physics` is not a valid import for this symbol; use this capability instead of hand-written A*; requires recast() after rapier(), plus a baked NavigationRegion3D
|
|
1497
|
+
|
|
1498
|
+
```ts
|
|
1499
|
+
import { NavigationAgent3D } from "@threenative/physics/navigation";
|
|
1500
|
+
import { Vector3 } from "three";
|
|
1501
|
+
const agent = new NavigationAgent3D({ navigation, object });
|
|
1502
|
+
agent.setTargetPosition(player.position);
|
|
1503
|
+
const reusableTarget = new Vector3();
|
|
1504
|
+
const next = agent.getNextPathPosition(reusableTarget);
|
|
1505
|
+
```
|
|
1506
|
+
|
|
1507
|
+
### `NavigationObstacle3D`
|
|
1508
|
+
|
|
1509
|
+
`class` — Add a non-moving crowd obstacle to a navmesh.
|
|
1510
|
+
|
|
1511
|
+
```ts
|
|
1512
|
+
export class NavigationObstacle3D { … }
|
|
1513
|
+
```
|
|
1514
|
+
|
|
1515
|
+
- **Use when:** keep navigation agents away from a blocking prop · make a stationary character affect crowd avoidance
|
|
1516
|
+
- **Constraints:** create it after recast() and dispose it with the scene
|
|
1517
|
+
|
|
1518
|
+
```ts
|
|
1519
|
+
const obstacle = new NavigationObstacle3D({ navigation, object });
|
|
1520
|
+
```
|
|
1521
|
+
|
|
1522
|
+
### `NavigationRegion3D`
|
|
1523
|
+
|
|
1524
|
+
`class` — Bake walkable Three.js geometry into a navigation region.
|
|
1525
|
+
|
|
1526
|
+
```ts
|
|
1527
|
+
export class NavigationRegion3D { … }
|
|
1528
|
+
```
|
|
1529
|
+
|
|
1530
|
+
- **Use when:** let enemies walk around level geometry · create the baked navmesh required by NavigationAgent3D
|
|
1531
|
+
- **Constraints:** bake before creating agents or obstacles
|
|
1532
|
+
|
|
1533
|
+
```ts
|
|
1534
|
+
const region = new NavigationRegion3D({ navigation, meshes: [floor] });
|
|
1535
|
+
```
|
|
1536
|
+
|
|
1537
|
+
### `recast`
|
|
1538
|
+
|
|
1539
|
+
`function` — Install navmesh pathfinding and crowd avoidance.
|
|
1540
|
+
|
|
1541
|
+
```ts
|
|
1542
|
+
export function recast(): NavigationPlugin { … }
|
|
1543
|
+
```
|
|
1544
|
+
|
|
1545
|
+
- **Use when:** enemy walks around a wall · NPC patrols a level and chases a player
|
|
1546
|
+
- **Constraints:** requires rapier() earlier in the plugins array
|
|
1547
|
+
|
|
1548
|
+
```ts
|
|
1549
|
+
const game = defineGame({ plugins: [rapier(), recast()] });
|
|
1550
|
+
```
|
|
1551
|
+
|
|
1552
|
+
## `@threenative/playtest`
|
|
1553
|
+
|
|
1554
|
+
### `assertJsonSafe`
|
|
1555
|
+
|
|
1556
|
+
`function` — Validate JSON-safe bridge messages and protocol sizes.
|
|
1557
|
+
|
|
1558
|
+
```ts
|
|
1559
|
+
export function assertJsonSafe(value: unknown, path = "$"): asserts value is JsonValue { … }
|
|
1560
|
+
```
|
|
1561
|
+
|
|
1562
|
+
- **Use when:** send a safe observation over the playtest bridge · reject an oversized or cyclic playtest payload · validate entity components and gameplay observations before crossing the bridge
|
|
1563
|
+
- **Constraints:** bridge values must be JSON-shaped · throws instead of silently dropping the offending field
|
|
1564
|
+
|
|
1565
|
+
```ts
|
|
1566
|
+
assertJsonSafe({ score: 10 });
|
|
1567
|
+
```
|
|
1568
|
+
|
|
1569
|
+
### `DeviceMetricsError`
|
|
1570
|
+
|
|
1571
|
+
`class` — Measure and judge device thermal, power and battery state around a device playtest run.
|
|
1572
|
+
|
|
1573
|
+
```ts
|
|
1574
|
+
export class DeviceMetricsError extends Error { … }
|
|
1575
|
+
```
|
|
1576
|
+
|
|
1577
|
+
- **Use when:** find out whether an Android run was throttled or started hot · read battery temperature, current draw or per-rail power for a run
|
|
1578
|
+
- **Constraints:** a reading the device does not expose reports unavailable, never zero · a run that started hot or whose thermal status rose is flagged as confounded
|
|
1579
|
+
|
|
1580
|
+
```ts
|
|
1581
|
+
const verdict = summarizeDeviceMetrics(observation.samples);
|
|
1582
|
+
```
|
|
1583
|
+
|
|
1584
|
+
### `DeviceMetricsRecorder`
|
|
1585
|
+
|
|
1586
|
+
`class` — Measure and judge device thermal, power and battery state around a device playtest run.
|
|
1587
|
+
|
|
1588
|
+
```ts
|
|
1589
|
+
export class DeviceMetricsRecorder { … }
|
|
1590
|
+
```
|
|
1591
|
+
|
|
1592
|
+
- **Use when:** find out whether an Android run was throttled or started hot · read battery temperature, current draw or per-rail power for a run
|
|
1593
|
+
- **Constraints:** a reading the device does not expose reports unavailable, never zero · a run that started hot or whose thermal status rose is flagged as confounded
|
|
1594
|
+
|
|
1595
|
+
```ts
|
|
1596
|
+
const verdict = summarizeDeviceMetrics(observation.samples);
|
|
1597
|
+
```
|
|
1598
|
+
|
|
1599
|
+
### `evaluateRichPlaytestAssertions`
|
|
1600
|
+
|
|
1601
|
+
`function` — Evaluate rich semantic assertions against captured observations.
|
|
1602
|
+
|
|
1603
|
+
```ts
|
|
1604
|
+
export function evaluateRichPlaytestAssertions(input: { … }
|
|
1605
|
+
```
|
|
1606
|
+
|
|
1607
|
+
- **Use when:** assert movement, visibility, or diagnostics in a playtest · turn a scenario observation into a pass or failure
|
|
1608
|
+
- **Constraints:** malformed or empty assertions fail closed
|
|
1609
|
+
|
|
1610
|
+
```ts
|
|
1611
|
+
const result = evaluateRichPlaytestAssertions(input);
|
|
1612
|
+
```
|
|
1613
|
+
|
|
1614
|
+
### `invalidScenario`
|
|
1615
|
+
|
|
1616
|
+
`function` — Load and validate a scenario, then control its tick steps.
|
|
1617
|
+
|
|
1618
|
+
```ts
|
|
1619
|
+
export function invalidScenario(scenarioPath: string, message: string): PlaytestScenarioError { … }
|
|
1620
|
+
```
|
|
1621
|
+
|
|
1622
|
+
- **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
|
|
1623
|
+
- **Constraints:** unknown scenario keys fail closed
|
|
1624
|
+
|
|
1625
|
+
```ts
|
|
1626
|
+
const scenario = await loadPlaytestScenario(project, file);
|
|
1627
|
+
```
|
|
1628
|
+
|
|
1629
|
+
### `jsonByteLength`
|
|
1630
|
+
|
|
1631
|
+
`function` — Validate JSON-safe bridge messages and protocol sizes.
|
|
1632
|
+
|
|
1633
|
+
```ts
|
|
1634
|
+
export function jsonByteLength(value: JsonValue): number { … }
|
|
1635
|
+
```
|
|
1636
|
+
|
|
1637
|
+
- **Use when:** send a safe observation over the playtest bridge · reject an oversized or cyclic playtest payload · check a runtime observation against the protocol payload limit before sampling
|
|
1638
|
+
- **Constraints:** bridge values must be JSON-shaped
|
|
1639
|
+
|
|
1640
|
+
```ts
|
|
1641
|
+
assertJsonSafe({ score: 10 });
|
|
1642
|
+
```
|
|
1643
|
+
|
|
1644
|
+
### `loadPlaytestScenario`
|
|
1645
|
+
|
|
1646
|
+
`function` — Load and validate a scenario, then control its tick steps.
|
|
1647
|
+
|
|
1648
|
+
```ts
|
|
1649
|
+
export async function loadPlaytestScenario(projectPath: string, scenarioPath: string): Promise<IPlaytestScenario> { … }
|
|
1650
|
+
```
|
|
1651
|
+
|
|
1652
|
+
- **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
|
|
1653
|
+
- **Constraints:** unknown scenario keys fail closed
|
|
1654
|
+
|
|
1655
|
+
```ts
|
|
1656
|
+
const scenario = await loadPlaytestScenario(project, file);
|
|
1657
|
+
```
|
|
1658
|
+
|
|
1659
|
+
### `missingPlaytestCapabilities`
|
|
1660
|
+
|
|
1661
|
+
`function` — Validate and inspect playtest capability declarations.
|
|
1662
|
+
|
|
1663
|
+
```ts
|
|
1664
|
+
export function missingPlaytestCapabilities(required: readonly string[], available: readonly string[]): string[] { … }
|
|
1665
|
+
```
|
|
1666
|
+
|
|
1667
|
+
- **Use when:** check whether a scenario's required capabilities are installed · report unknown or missing playtest capabilities
|
|
1668
|
+
|
|
1669
|
+
```ts
|
|
1670
|
+
const missing = missingPlaytestCapabilities(required, available);
|
|
1671
|
+
```
|
|
1672
|
+
|
|
1673
|
+
### `parseDeviceBattery`
|
|
1674
|
+
|
|
1675
|
+
`function` — Measure and judge device thermal, power and battery state around a device playtest run.
|
|
1676
|
+
|
|
1677
|
+
```ts
|
|
1678
|
+
export function parseDeviceBattery(output: string): IPlaytestDeviceBattery { … }
|
|
1679
|
+
```
|
|
1680
|
+
|
|
1681
|
+
- **Use when:** find out whether an Android run was throttled or started hot · read battery temperature, current draw or per-rail power for a run
|
|
1682
|
+
- **Constraints:** a reading the device does not expose reports unavailable, never zero · a run that started hot or whose thermal status rose is flagged as confounded
|
|
1683
|
+
|
|
1684
|
+
```ts
|
|
1685
|
+
const verdict = summarizeDeviceMetrics(observation.samples);
|
|
1686
|
+
```
|
|
1687
|
+
|
|
1688
|
+
### `parseDeviceCurrent`
|
|
1689
|
+
|
|
1690
|
+
`function` — Measure and judge device thermal, power and battery state around a device playtest run.
|
|
1691
|
+
|
|
1692
|
+
```ts
|
|
1693
|
+
export function parseDeviceCurrent(output: string): PlaytestDeviceMeasurement<number> { … }
|
|
1694
|
+
```
|
|
1695
|
+
|
|
1696
|
+
- **Use when:** find out whether an Android run was throttled or started hot · read battery temperature, current draw or per-rail power for a run
|
|
1697
|
+
- **Constraints:** a reading the device does not expose reports unavailable, never zero · a run that started hot or whose thermal status rose is flagged as confounded
|
|
1698
|
+
|
|
1699
|
+
```ts
|
|
1700
|
+
const verdict = summarizeDeviceMetrics(observation.samples);
|
|
1701
|
+
```
|
|
1702
|
+
|
|
1703
|
+
### `parseDevicePowerRails`
|
|
1704
|
+
|
|
1705
|
+
`function` — Measure and judge device thermal, power and battery state around a device playtest run.
|
|
1706
|
+
|
|
1707
|
+
```ts
|
|
1708
|
+
export function parseDevicePowerRails(output: string): PlaytestDevicePowerRails { … }
|
|
1709
|
+
```
|
|
1710
|
+
|
|
1711
|
+
- **Use when:** find out whether an Android run was throttled or started hot · read battery temperature, current draw or per-rail power for a run
|
|
1712
|
+
- **Constraints:** a reading the device does not expose reports unavailable, never zero · a run that started hot or whose thermal status rose is flagged as confounded
|
|
1713
|
+
|
|
1714
|
+
```ts
|
|
1715
|
+
const verdict = summarizeDeviceMetrics(observation.samples);
|
|
1716
|
+
```
|
|
1717
|
+
|
|
1718
|
+
### `parseDeviceThermal`
|
|
1719
|
+
|
|
1720
|
+
`function` — Measure and judge device thermal, power and battery state around a device playtest run.
|
|
1721
|
+
|
|
1722
|
+
```ts
|
|
1723
|
+
export function parseDeviceThermal(output: string): IPlaytestDeviceThermal { … }
|
|
1724
|
+
```
|
|
1725
|
+
|
|
1726
|
+
- **Use when:** find out whether an Android run was throttled or started hot · read battery temperature, current draw or per-rail power for a run
|
|
1727
|
+
- **Constraints:** a reading the device does not expose reports unavailable, never zero · a run that started hot or whose thermal status rose is flagged as confounded
|
|
1728
|
+
|
|
1729
|
+
```ts
|
|
1730
|
+
const verdict = summarizeDeviceMetrics(observation.samples);
|
|
1731
|
+
```
|
|
1732
|
+
|
|
1733
|
+
### `playtestDiagnostic`
|
|
1734
|
+
|
|
1735
|
+
`function` — Create a structured playtest diagnostic.
|
|
1736
|
+
|
|
1737
|
+
```ts
|
|
1738
|
+
export function playtestDiagnostic( code: PlaytestDiagnosticCode, message: string, instruction: string, details: Pick<IPlaytestProtocolDiagnostic, "capability" | "path"> & { … }
|
|
1739
|
+
```
|
|
1740
|
+
|
|
1741
|
+
- **Use when:** report a named runtime diagnostic to a scenario · explain why a playtest assertion cannot pass
|
|
1742
|
+
|
|
1743
|
+
```ts
|
|
1744
|
+
playtestDiagnostic("physics", "body missing");
|
|
1745
|
+
```
|
|
1746
|
+
|
|
1747
|
+
### `PlaytestScenarioError`
|
|
1748
|
+
|
|
1749
|
+
`class` — Load and validate a scenario, then control its tick steps.
|
|
1750
|
+
|
|
1751
|
+
```ts
|
|
1752
|
+
export class PlaytestScenarioError extends Error { … }
|
|
1753
|
+
```
|
|
1754
|
+
|
|
1755
|
+
- **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
|
|
1756
|
+
- **Constraints:** unknown scenario keys fail closed
|
|
1757
|
+
|
|
1758
|
+
```ts
|
|
1759
|
+
const scenario = await loadPlaytestScenario(project, file);
|
|
1760
|
+
```
|
|
1761
|
+
|
|
1762
|
+
### `playtestStepHoldTicks`
|
|
1763
|
+
|
|
1764
|
+
`function` — Load and validate a scenario, then control its tick steps.
|
|
1765
|
+
|
|
1766
|
+
```ts
|
|
1767
|
+
export function playtestStepHoldTicks(step: IPlaytestStep, fallback = 1): number { … }
|
|
1768
|
+
```
|
|
1769
|
+
|
|
1770
|
+
- **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
|
|
1771
|
+
- **Constraints:** unknown scenario keys fail closed
|
|
1772
|
+
|
|
1773
|
+
```ts
|
|
1774
|
+
const scenario = await loadPlaytestScenario(project, file);
|
|
1775
|
+
```
|
|
1776
|
+
|
|
1777
|
+
### `playtestStepWaitTicks`
|
|
1778
|
+
|
|
1779
|
+
`function` — Load and validate a scenario, then control its tick steps.
|
|
1780
|
+
|
|
1781
|
+
```ts
|
|
1782
|
+
export function playtestStepWaitTicks(step: IPlaytestStep): number { … }
|
|
1783
|
+
```
|
|
1784
|
+
|
|
1785
|
+
- **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
|
|
1786
|
+
- **Constraints:** unknown scenario keys fail closed
|
|
1787
|
+
|
|
1788
|
+
```ts
|
|
1789
|
+
const scenario = await loadPlaytestScenario(project, file);
|
|
1790
|
+
```
|
|
1791
|
+
|
|
1792
|
+
### `rejectUnknownKeys`
|
|
1793
|
+
|
|
1794
|
+
`function` — Load and validate a scenario, then control its tick steps.
|
|
1795
|
+
|
|
1796
|
+
```ts
|
|
1797
|
+
export function rejectUnknownKeys( value: Record<string, unknown>, allowedKeys: readonly string[], scenarioPath: string, objectPath: string, ): void { … }
|
|
1798
|
+
```
|
|
1799
|
+
|
|
1800
|
+
- **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
|
|
1801
|
+
- **Constraints:** unknown scenario keys fail closed
|
|
1802
|
+
|
|
1803
|
+
```ts
|
|
1804
|
+
const scenario = await loadPlaytestScenario(project, file);
|
|
1805
|
+
```
|
|
1806
|
+
|
|
1807
|
+
### `requiredPlaytestCapabilities`
|
|
1808
|
+
|
|
1809
|
+
`function` — Evaluate rich semantic assertions against captured observations.
|
|
1810
|
+
|
|
1811
|
+
```ts
|
|
1812
|
+
export function requiredPlaytestCapabilities(scenario: IPlaytestScenario): PlaytestCapability[] { … }
|
|
1813
|
+
```
|
|
1814
|
+
|
|
1815
|
+
- **Use when:** assert movement, visibility, or diagnostics in a playtest · turn a scenario observation into a pass or failure
|
|
1816
|
+
- **Constraints:** malformed or empty assertions fail closed
|
|
1817
|
+
|
|
1818
|
+
```ts
|
|
1819
|
+
const result = evaluateRichPlaytestAssertions(input);
|
|
1820
|
+
```
|
|
1821
|
+
|
|
1822
|
+
### `resolveDiagnosticsPolicy`
|
|
1823
|
+
|
|
1824
|
+
`function` — Resolve the effective diagnostics policy for a run, with fail-closed defaults applied.
|
|
1825
|
+
|
|
1826
|
+
```ts
|
|
1827
|
+
export function resolveDiagnosticsPolicy( policy: IPlaytestDiagnosticsAssertion | undefined, ): IPlaytestDiagnosticsPolicy { … }
|
|
1828
|
+
```
|
|
1829
|
+
|
|
1830
|
+
- **Use when:** judge captured console, network, or runtime diagnostics for a playtest
|
|
1831
|
+
- **Constraints:** absent policy fields default to rejecting errors
|
|
1832
|
+
|
|
1833
|
+
```ts
|
|
1834
|
+
const policy = resolveDiagnosticsPolicy(scenario.assert?.diagnostics);
|
|
1835
|
+
```
|
|
1836
|
+
|
|
1837
|
+
### `summarizeDeviceMetrics`
|
|
1838
|
+
|
|
1839
|
+
`function` — Measure and judge device thermal, power and battery state around a device playtest run.
|
|
1840
|
+
|
|
1841
|
+
```ts
|
|
1842
|
+
export function summarizeDeviceMetrics( samples: readonly IPlaytestDeviceMetricsSample[], ): IPlaytestDeviceMetricsVerdict { … }
|
|
1843
|
+
```
|
|
1844
|
+
|
|
1845
|
+
- **Use when:** find out whether an Android run was throttled or started hot · read battery temperature, current draw or per-rail power for a run
|
|
1846
|
+
- **Constraints:** a reading the device does not expose reports unavailable, never zero · a run that started hot or whose thermal status rose is flagged as confounded
|
|
1847
|
+
|
|
1848
|
+
```ts
|
|
1849
|
+
const verdict = summarizeDeviceMetrics(observation.samples);
|
|
1850
|
+
```
|
|
1851
|
+
|
|
1852
|
+
### `unknownPlaytestCapabilities`
|
|
1853
|
+
|
|
1854
|
+
`function` — Validate and inspect playtest capability declarations.
|
|
1855
|
+
|
|
1856
|
+
```ts
|
|
1857
|
+
export function unknownPlaytestCapabilities(capabilities: readonly string[]): string[] { … }
|
|
1858
|
+
```
|
|
1859
|
+
|
|
1860
|
+
- **Use when:** check whether a scenario's required capabilities are installed · report unknown or missing playtest capabilities
|
|
1861
|
+
|
|
1862
|
+
```ts
|
|
1863
|
+
const missing = missingPlaytestCapabilities(required, available);
|
|
1864
|
+
```
|
|
1865
|
+
|
|
1866
|
+
## `@threenative/playtest/capture`
|
|
1867
|
+
|
|
1868
|
+
### `assertCaptureNotBlank`
|
|
1869
|
+
|
|
1870
|
+
`function` — Fail closed when a screenshot is blank or uniform.
|
|
1871
|
+
|
|
1872
|
+
```ts
|
|
1873
|
+
export function assertCaptureNotBlank(png: Buffer, label: string): ICaptureFrameStats { … }
|
|
1874
|
+
```
|
|
1875
|
+
|
|
1876
|
+
- **Use when:** guard a visual playtest against a blank frame · prove a screenshot contains more than a loading surface
|
|
1877
|
+
- **Constraints:** the assertion throws instead of returning a false pass
|
|
1878
|
+
|
|
1879
|
+
```ts
|
|
1880
|
+
assertCaptureNotBlank(png, "first frame");
|
|
1881
|
+
```
|
|
1882
|
+
|
|
1883
|
+
### `CaptureGuardError`
|
|
1884
|
+
|
|
1885
|
+
`class` — Explain why a captured frame failed the non-blank guard.
|
|
1886
|
+
|
|
1887
|
+
```ts
|
|
1888
|
+
export class CaptureGuardError extends Error { … }
|
|
1889
|
+
```
|
|
1890
|
+
|
|
1891
|
+
- **Use when:** fail a visual test when the rendered frame is blank · include capture statistics in a playtest error
|
|
1892
|
+
|
|
1893
|
+
```ts
|
|
1894
|
+
throw new CaptureGuardError("menu", "no bright pixels");
|
|
1895
|
+
```
|
|
1896
|
+
|
|
1897
|
+
### `inspectFrame`
|
|
1898
|
+
|
|
1899
|
+
`function` — Inspect a PNG frame for visible pixels and luminance variation.
|
|
1900
|
+
|
|
1901
|
+
```ts
|
|
1902
|
+
export function inspectFrame(png: Buffer): ICaptureFrameStats { … }
|
|
1903
|
+
```
|
|
1904
|
+
|
|
1905
|
+
- **Use when:** measure whether a screenshot contains a rendered game · diagnose a uniform or blank capture
|
|
1906
|
+
|
|
1907
|
+
```ts
|
|
1908
|
+
const stats = inspectFrame(png);
|
|
1909
|
+
```
|
|
1910
|
+
|
|
1911
|
+
## `@threenative/playtest/protocol`
|
|
1912
|
+
|
|
1913
|
+
### `assertJsonSafe`
|
|
1914
|
+
|
|
1915
|
+
`function` — Reject any value that would not survive JSON serialization.
|
|
1916
|
+
|
|
1917
|
+
```ts
|
|
1918
|
+
export function assertJsonSafe(value: unknown, path = "$"): asserts value is JsonValue { … }
|
|
1919
|
+
```
|
|
1920
|
+
|
|
1921
|
+
- **Use when:** validate entity components and gameplay observations before crossing the bridge
|
|
1922
|
+
- **Constraints:** throws instead of silently dropping the offending field
|
|
1923
|
+
|
|
1924
|
+
```ts
|
|
1925
|
+
assertJsonSafe(snapshot, "$.components");
|
|
1926
|
+
```
|
|
1927
|
+
|
|
1928
|
+
### `jsonByteLength`
|
|
1929
|
+
|
|
1930
|
+
`function` — Measure a payload's wire size in bytes.
|
|
1931
|
+
|
|
1932
|
+
```ts
|
|
1933
|
+
export function jsonByteLength(value: JsonValue): number { … }
|
|
1934
|
+
```
|
|
1935
|
+
|
|
1936
|
+
- **Use when:** check a runtime observation against the protocol payload limit before sampling
|
|
1937
|
+
|
|
1938
|
+
```ts
|
|
1939
|
+
const bytes = jsonByteLength(observation);
|
|
1940
|
+
```
|
|
1941
|
+
|
|
1942
|
+
## `@threenative/playtest/runner`
|
|
1943
|
+
|
|
1944
|
+
### `AdbAndroidDriver`
|
|
1945
|
+
|
|
1946
|
+
`class` — Drive and inspect Android playtest transport.
|
|
1947
|
+
|
|
1948
|
+
```ts
|
|
1949
|
+
export class AdbAndroidDriver implements IAndroidDriver { … }
|
|
1950
|
+
```
|
|
1951
|
+
|
|
1952
|
+
- **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
|
|
1953
|
+
- **Constraints:** Android evidence must name its target and transport
|
|
1954
|
+
|
|
1955
|
+
```ts
|
|
1956
|
+
const adb = discoverAdb(process.env);
|
|
1957
|
+
```
|
|
1958
|
+
|
|
1959
|
+
### `advanceFixedStep`
|
|
1960
|
+
|
|
1961
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
1962
|
+
|
|
1963
|
+
```ts
|
|
1964
|
+
export async function advanceFixedStep( page: Page, bridge: Pick<IPlaytestBridgeClient, "advance">, ticks: number, ): Promise<void> { … }
|
|
1965
|
+
```
|
|
1966
|
+
|
|
1967
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
1968
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
1969
|
+
|
|
1970
|
+
```ts
|
|
1971
|
+
const report = await runStandalonePlaytest(options);
|
|
1972
|
+
```
|
|
1973
|
+
|
|
1974
|
+
### `advanceTimeoutMs`
|
|
1975
|
+
|
|
1976
|
+
`function` — Connect a Playwright page to a playtest bridge.
|
|
1977
|
+
|
|
1978
|
+
```ts
|
|
1979
|
+
export function advanceTimeoutMs( ticks: number, perTickMs: number = PLAYTEST_ADVANCE_TICK_BUDGET_MS, ): number { … }
|
|
1980
|
+
```
|
|
1981
|
+
|
|
1982
|
+
- **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
|
|
1983
|
+
- **Constraints:** the bridge must answer the handshake or the run fails
|
|
1984
|
+
|
|
1985
|
+
```ts
|
|
1986
|
+
const bridge = await connectPlaytestBridge(page);
|
|
1987
|
+
```
|
|
1988
|
+
|
|
1989
|
+
### `androidMailboxPaths`
|
|
1990
|
+
|
|
1991
|
+
`function` — Resolve a native device transport and its mailbox paths.
|
|
1992
|
+
|
|
1993
|
+
```ts
|
|
1994
|
+
export function androidMailboxPaths( packageName: string, root = `/sdcard/Android/data/$ { … }
|
|
1995
|
+
```
|
|
1996
|
+
|
|
1997
|
+
- **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
|
|
1998
|
+
- **Constraints:** paths stay inside the managed artifact directory
|
|
1999
|
+
|
|
2000
|
+
```ts
|
|
2001
|
+
const paths = deviceMailboxPaths(projectRoot);
|
|
2002
|
+
```
|
|
2003
|
+
|
|
2004
|
+
### `androidTouchBatches`
|
|
2005
|
+
|
|
2006
|
+
`function` — Drive and inspect Android playtest transport.
|
|
2007
|
+
|
|
2008
|
+
```ts
|
|
2009
|
+
export function androidTouchBatches( identity: readonly string[], positions: readonly string[], ): string[][] { … }
|
|
2010
|
+
```
|
|
2011
|
+
|
|
2012
|
+
- **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
|
|
2013
|
+
- **Constraints:** Android evidence must name its target and transport
|
|
2014
|
+
|
|
2015
|
+
```ts
|
|
2016
|
+
const adb = discoverAdb(process.env);
|
|
2017
|
+
```
|
|
2018
|
+
|
|
2019
|
+
### `batchArtifactDirectory`
|
|
2020
|
+
|
|
2021
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2022
|
+
|
|
2023
|
+
```ts
|
|
2024
|
+
export function batchArtifactDirectory(base: string, scenarioPath: string, index: number): string { … }
|
|
2025
|
+
```
|
|
2026
|
+
|
|
2027
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2028
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2029
|
+
|
|
2030
|
+
```ts
|
|
2031
|
+
const report = await runStandalonePlaytest(options);
|
|
2032
|
+
```
|
|
2033
|
+
|
|
2034
|
+
### `boundedTeardownStep`
|
|
2035
|
+
|
|
2036
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2037
|
+
|
|
2038
|
+
```ts
|
|
2039
|
+
export async function boundedTeardownStep( step: Promise<unknown> | undefined, timeoutMs: number, ): Promise<boolean> { … }
|
|
2040
|
+
```
|
|
2041
|
+
|
|
2042
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2043
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2044
|
+
|
|
2045
|
+
```ts
|
|
2046
|
+
const report = await runStandalonePlaytest(options);
|
|
2047
|
+
```
|
|
2048
|
+
|
|
2049
|
+
### `bridgeWaitTimeoutMs`
|
|
2050
|
+
|
|
2051
|
+
`function` — Connect a Playwright page to a playtest bridge.
|
|
2052
|
+
|
|
2053
|
+
```ts
|
|
2054
|
+
export function bridgeWaitTimeoutMs( operationMs: number = PLAYTEST_PROTOCOL_LIMITS.operationTimeoutMs, ): number { … }
|
|
2055
|
+
```
|
|
2056
|
+
|
|
2057
|
+
- **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
|
|
2058
|
+
- **Constraints:** the bridge must answer the handshake or the run fails
|
|
2059
|
+
|
|
2060
|
+
```ts
|
|
2061
|
+
const bridge = await connectPlaytestBridge(page);
|
|
2062
|
+
```
|
|
2063
|
+
|
|
2064
|
+
### `buildReport`
|
|
2065
|
+
|
|
2066
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2067
|
+
|
|
2068
|
+
```ts
|
|
2069
|
+
export function buildReport( config: IStandalonePlaytestConfig, scenario: IPlaytestScenario, beforeSnapshot: IPlaytestObservationSnapshot | undefined, afterSnapshot: IPlaytestObservationSnapshot | undefined, consoleEntries: IRunnerConsoleEntry[], networkEntries: Array< { … }
|
|
2070
|
+
```
|
|
2071
|
+
|
|
2072
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2073
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2074
|
+
|
|
2075
|
+
```ts
|
|
2076
|
+
const report = await runStandalonePlaytest(options);
|
|
2077
|
+
```
|
|
2078
|
+
|
|
2079
|
+
### `captureVisualSurface`
|
|
2080
|
+
|
|
2081
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2082
|
+
|
|
2083
|
+
```ts
|
|
2084
|
+
export async function captureVisualSurface( page: Page, artifactPath?: string, ): Promise<Buffer | undefined> { … }
|
|
2085
|
+
```
|
|
2086
|
+
|
|
2087
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2088
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2089
|
+
|
|
2090
|
+
```ts
|
|
2091
|
+
const report = await runStandalonePlaytest(options);
|
|
2092
|
+
```
|
|
2093
|
+
|
|
2094
|
+
### `connectPlaytestBridge`
|
|
2095
|
+
|
|
2096
|
+
`function` — Connect a Playwright page to a playtest bridge.
|
|
2097
|
+
|
|
2098
|
+
```ts
|
|
2099
|
+
export async function connectPlaytestBridge( page: Page, scenario: IPlaytestScenario, timeoutMs: number = PLAYTEST_PROTOCOL_LIMITS.operationTimeoutMs, ): Promise<IPlaytestBridgeClient | undefined> { … }
|
|
2100
|
+
```
|
|
2101
|
+
|
|
2102
|
+
- **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
|
|
2103
|
+
- **Constraints:** the bridge must answer the handshake or the run fails
|
|
2104
|
+
|
|
2105
|
+
```ts
|
|
2106
|
+
const bridge = await connectPlaytestBridge(page);
|
|
2107
|
+
```
|
|
2108
|
+
|
|
2109
|
+
### `connectPlaytestBridgeTransport`
|
|
2110
|
+
|
|
2111
|
+
`function` — Connect a Playwright page to a playtest bridge.
|
|
2112
|
+
|
|
2113
|
+
```ts
|
|
2114
|
+
export async function connectPlaytestBridgeTransport( transport: IBridgeTransport, scenario: IPlaytestScenario, timeoutMs: number = bridgeWaitTimeoutMs(), ): Promise<IPlaytestBridgeClient | undefined> { … }
|
|
2115
|
+
```
|
|
2116
|
+
|
|
2117
|
+
- **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
|
|
2118
|
+
- **Constraints:** the bridge must answer the handshake or the run fails
|
|
2119
|
+
|
|
2120
|
+
```ts
|
|
2121
|
+
const bridge = await connectPlaytestBridge(page);
|
|
2122
|
+
```
|
|
2123
|
+
|
|
2124
|
+
### `DesktopPlaytestDriver`
|
|
2125
|
+
|
|
2126
|
+
`class` — Drive a local desktop playtest mailbox.
|
|
2127
|
+
|
|
2128
|
+
```ts
|
|
2129
|
+
export class DesktopPlaytestDriver implements IDevicePlaytestDriver { … }
|
|
2130
|
+
```
|
|
2131
|
+
|
|
2132
|
+
- **Use when:** run a desktop target through the playtest protocol · exchange observations with a native desktop host
|
|
2133
|
+
- **Constraints:** the mailbox lifecycle must be disposed after the run
|
|
2134
|
+
|
|
2135
|
+
```ts
|
|
2136
|
+
const driver = new DesktopPlaytestDriver(options);
|
|
2137
|
+
```
|
|
2138
|
+
|
|
2139
|
+
### `DeviceBridgeTransport`
|
|
2140
|
+
|
|
2141
|
+
`class` — Resolve a native device transport and its mailbox paths.
|
|
2142
|
+
|
|
2143
|
+
```ts
|
|
2144
|
+
export class DeviceBridgeTransport implements IDevicePlaytestTransport { … }
|
|
2145
|
+
```
|
|
2146
|
+
|
|
2147
|
+
- **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
|
|
2148
|
+
- **Constraints:** paths stay inside the managed artifact directory
|
|
2149
|
+
|
|
2150
|
+
```ts
|
|
2151
|
+
const paths = deviceMailboxPaths(projectRoot);
|
|
2152
|
+
```
|
|
2153
|
+
|
|
2154
|
+
### `deviceMailboxPaths`
|
|
2155
|
+
|
|
2156
|
+
`function` — Resolve a native device transport and its mailbox paths.
|
|
2157
|
+
|
|
2158
|
+
```ts
|
|
2159
|
+
export function deviceMailboxPaths(root: string): IDeviceMailboxPaths { … }
|
|
2160
|
+
```
|
|
2161
|
+
|
|
2162
|
+
- **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
|
|
2163
|
+
- **Constraints:** paths stay inside the managed artifact directory
|
|
2164
|
+
|
|
2165
|
+
```ts
|
|
2166
|
+
const paths = deviceMailboxPaths(projectRoot);
|
|
2167
|
+
```
|
|
2168
|
+
|
|
2169
|
+
### `DeviceMailboxTransport`
|
|
2170
|
+
|
|
2171
|
+
`class` — Resolve a native device transport and its mailbox paths.
|
|
2172
|
+
|
|
2173
|
+
```ts
|
|
2174
|
+
export class DeviceMailboxTransport implements IDevicePlaytestTransport { … }
|
|
2175
|
+
```
|
|
2176
|
+
|
|
2177
|
+
- **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
|
|
2178
|
+
- **Constraints:** paths stay inside the managed artifact directory
|
|
2179
|
+
|
|
2180
|
+
```ts
|
|
2181
|
+
const paths = deviceMailboxPaths(projectRoot);
|
|
2182
|
+
```
|
|
2183
|
+
|
|
2184
|
+
### `deviceTimeoutDiagnostic`
|
|
2185
|
+
|
|
2186
|
+
`function` — Resolve a native device transport and its mailbox paths.
|
|
2187
|
+
|
|
2188
|
+
```ts
|
|
2189
|
+
export function deviceTimeoutDiagnostic( diagnostic: IPlaytestProtocolDiagnostic, hostAlive: boolean | undefined, lastConsoleLines: readonly string[], ): IPlaytestProtocolDiagnostic { … }
|
|
2190
|
+
```
|
|
2191
|
+
|
|
2192
|
+
- **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
|
|
2193
|
+
- **Constraints:** paths stay inside the managed artifact directory
|
|
2194
|
+
|
|
2195
|
+
```ts
|
|
2196
|
+
const paths = deviceMailboxPaths(projectRoot);
|
|
2197
|
+
```
|
|
2198
|
+
|
|
2199
|
+
### `discoverAdb`
|
|
2200
|
+
|
|
2201
|
+
`function` — Drive and inspect Android playtest transport.
|
|
2202
|
+
|
|
2203
|
+
```ts
|
|
2204
|
+
export function discoverAdb(environment: NodeJS.ProcessEnv = process.env): string { … }
|
|
2205
|
+
```
|
|
2206
|
+
|
|
2207
|
+
- **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
|
|
2208
|
+
- **Constraints:** Android evidence must name its target and transport
|
|
2209
|
+
|
|
2210
|
+
```ts
|
|
2211
|
+
const adb = discoverAdb(process.env);
|
|
2212
|
+
```
|
|
2213
|
+
|
|
2214
|
+
### `failedDiagnosticsAssertion`
|
|
2215
|
+
|
|
2216
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2217
|
+
|
|
2218
|
+
```ts
|
|
2219
|
+
export function failedDiagnosticsAssertion(policy: IPlaytestDiagnosticsPolicy): IPlaytestAssertionResult { … }
|
|
2220
|
+
```
|
|
2221
|
+
|
|
2222
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2223
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2224
|
+
|
|
2225
|
+
```ts
|
|
2226
|
+
const report = await runStandalonePlaytest(options);
|
|
2227
|
+
```
|
|
2228
|
+
|
|
2229
|
+
### `formatUsage`
|
|
2230
|
+
|
|
2231
|
+
`function` — Parse standalone playtest runner configuration.
|
|
2232
|
+
|
|
2233
|
+
```ts
|
|
2234
|
+
export function formatUsage(): string { … }
|
|
2235
|
+
```
|
|
2236
|
+
|
|
2237
|
+
- **Use when:** invoke the playtest CLI from a scaffold · validate runner flags before launching a browser
|
|
2238
|
+
- **Constraints:** invalid flags throw a named usage error
|
|
2239
|
+
|
|
2240
|
+
```ts
|
|
2241
|
+
const config = parseStandalonePlaytestArgs(argv);
|
|
2242
|
+
```
|
|
2243
|
+
|
|
2244
|
+
### `handlePlaytestSignal`
|
|
2245
|
+
|
|
2246
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2247
|
+
|
|
2248
|
+
```ts
|
|
2249
|
+
export async function handlePlaytestSignal( teardown: (stopManagedServer: boolean) => Promise<void>, setExitCode: (code: number) => void = (code) => { … }
|
|
2250
|
+
```
|
|
2251
|
+
|
|
2252
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2253
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2254
|
+
|
|
2255
|
+
```ts
|
|
2256
|
+
const report = await runStandalonePlaytest(options);
|
|
2257
|
+
```
|
|
2258
|
+
|
|
2259
|
+
### `initStandalonePlaytest`
|
|
2260
|
+
|
|
2261
|
+
`function` — Initialize the standalone playtest files for a project.
|
|
2262
|
+
|
|
2263
|
+
```ts
|
|
2264
|
+
export async function initStandalonePlaytest(projectPath = process.cwd()): Promise< { … }
|
|
2265
|
+
```
|
|
2266
|
+
|
|
2267
|
+
- **Use when:** add the runner contract to a new game · create a starter scenario fixture
|
|
2268
|
+
- **Constraints:** generated scenarios must contain real assertions
|
|
2269
|
+
|
|
2270
|
+
```ts
|
|
2271
|
+
await initStandalonePlaytest(projectPath);
|
|
2272
|
+
```
|
|
2273
|
+
|
|
2274
|
+
### `isRuntimeReadout`
|
|
2275
|
+
|
|
2276
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2277
|
+
|
|
2278
|
+
```ts
|
|
2279
|
+
export function isRuntimeReadout(entry: unknown): boolean { … }
|
|
2280
|
+
```
|
|
2281
|
+
|
|
2282
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2283
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2284
|
+
|
|
2285
|
+
```ts
|
|
2286
|
+
const report = await runStandalonePlaytest(options);
|
|
2287
|
+
```
|
|
2288
|
+
|
|
2289
|
+
### `keyboardIsShown`
|
|
2290
|
+
|
|
2291
|
+
`function` — Drive and inspect Android playtest transport.
|
|
2292
|
+
|
|
2293
|
+
```ts
|
|
2294
|
+
export function keyboardIsShown(dump: string): boolean { … }
|
|
2295
|
+
```
|
|
2296
|
+
|
|
2297
|
+
- **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
|
|
2298
|
+
- **Constraints:** Android evidence must name its target and transport
|
|
2299
|
+
|
|
2300
|
+
```ts
|
|
2301
|
+
const adb = discoverAdb(process.env);
|
|
2302
|
+
```
|
|
2303
|
+
|
|
2304
|
+
### `LocalDeviceMailbox`
|
|
2305
|
+
|
|
2306
|
+
`class` — Drive a local desktop playtest mailbox.
|
|
2307
|
+
|
|
2308
|
+
```ts
|
|
2309
|
+
export class LocalDeviceMailbox { … }
|
|
2310
|
+
```
|
|
2311
|
+
|
|
2312
|
+
- **Use when:** run a desktop target through the playtest protocol · exchange observations with a native desktop host
|
|
2313
|
+
- **Constraints:** the mailbox lifecycle must be disposed after the run
|
|
2314
|
+
|
|
2315
|
+
```ts
|
|
2316
|
+
const driver = new DesktopPlaytestDriver(options);
|
|
2317
|
+
```
|
|
2318
|
+
|
|
2319
|
+
### `ManagedServerError`
|
|
2320
|
+
|
|
2321
|
+
`class` — Execute scenario steps, assertions, and evidence capture.
|
|
2322
|
+
|
|
2323
|
+
```ts
|
|
2324
|
+
export class ManagedServerError extends Error { … }
|
|
2325
|
+
```
|
|
2326
|
+
|
|
2327
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2328
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2329
|
+
|
|
2330
|
+
```ts
|
|
2331
|
+
const report = await runStandalonePlaytest(options);
|
|
2332
|
+
```
|
|
2333
|
+
|
|
2334
|
+
### `openPageAndConnectBridge`
|
|
2335
|
+
|
|
2336
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2337
|
+
|
|
2338
|
+
```ts
|
|
2339
|
+
export async function openPageAndConnectBridge( page: Page, config: IStandalonePlaytestConfig, scenario: IPlaytestScenario, ): Promise<IPlaytestBridgeClient | undefined> { … }
|
|
2340
|
+
```
|
|
2341
|
+
|
|
2342
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2343
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2344
|
+
|
|
2345
|
+
```ts
|
|
2346
|
+
const report = await runStandalonePlaytest(options);
|
|
2347
|
+
```
|
|
2348
|
+
|
|
2349
|
+
### `pageLifecycleDiagnostic`
|
|
2350
|
+
|
|
2351
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2352
|
+
|
|
2353
|
+
```ts
|
|
2354
|
+
export function pageLifecycleDiagnostic( error: unknown, lifecycle: IPageLifecycle, url: string, ): IPlaytestProtocolDiagnostic | undefined { … }
|
|
2355
|
+
```
|
|
2356
|
+
|
|
2357
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2358
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2359
|
+
|
|
2360
|
+
```ts
|
|
2361
|
+
const report = await runStandalonePlaytest(options);
|
|
2362
|
+
```
|
|
2363
|
+
|
|
2364
|
+
### `parseAndroidConsole`
|
|
2365
|
+
|
|
2366
|
+
`function` — Drive and inspect Android playtest transport.
|
|
2367
|
+
|
|
2368
|
+
```ts
|
|
2369
|
+
export function parseAndroidConsole(output: string): Array< { … }
|
|
2370
|
+
```
|
|
2371
|
+
|
|
2372
|
+
- **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
|
|
2373
|
+
- **Constraints:** Android evidence must name its target and transport
|
|
2374
|
+
|
|
2375
|
+
```ts
|
|
2376
|
+
const adb = discoverAdb(process.env);
|
|
2377
|
+
```
|
|
2378
|
+
|
|
2379
|
+
### `parseLaunchedPid`
|
|
2380
|
+
|
|
2381
|
+
`function` — Drive and inspect iOS simulator playtest transport.
|
|
2382
|
+
|
|
2383
|
+
```ts
|
|
2384
|
+
export function parseLaunchedPid(output: string): string { … }
|
|
2385
|
+
```
|
|
2386
|
+
|
|
2387
|
+
- **Use when:** run a scenario on the iOS simulator · parse the launched native process identifier
|
|
2388
|
+
- **Constraints:** simulator evidence does not claim physical-device proof
|
|
2389
|
+
|
|
2390
|
+
```ts
|
|
2391
|
+
const driver = new XcrunIosDriver(options);
|
|
2392
|
+
```
|
|
2393
|
+
|
|
2394
|
+
### `parseStandalonePlaytestArgs`
|
|
2395
|
+
|
|
2396
|
+
`function` — Parse standalone playtest runner configuration.
|
|
2397
|
+
|
|
2398
|
+
```ts
|
|
2399
|
+
export function parseStandalonePlaytestArgs(argv: readonly string[], cwd = process.cwd()): IStandalonePlaytestConfig { … }
|
|
2400
|
+
```
|
|
2401
|
+
|
|
2402
|
+
- **Use when:** invoke the playtest CLI from a scaffold · validate runner flags before launching a browser
|
|
2403
|
+
- **Constraints:** invalid flags throw a named usage error
|
|
2404
|
+
|
|
2405
|
+
```ts
|
|
2406
|
+
const config = parseStandalonePlaytestArgs(argv);
|
|
2407
|
+
```
|
|
2408
|
+
|
|
2409
|
+
### `PlaytestBridgeError`
|
|
2410
|
+
|
|
2411
|
+
`class` — Connect a Playwright page to a playtest bridge.
|
|
2412
|
+
|
|
2413
|
+
```ts
|
|
2414
|
+
export class PlaytestBridgeError extends Error { … }
|
|
2415
|
+
```
|
|
2416
|
+
|
|
2417
|
+
- **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
|
|
2418
|
+
- **Constraints:** the bridge must answer the handshake or the run fails
|
|
2419
|
+
|
|
2420
|
+
```ts
|
|
2421
|
+
const bridge = await connectPlaytestBridge(page);
|
|
2422
|
+
```
|
|
2423
|
+
|
|
2424
|
+
### `PlaytestCliUsageError`
|
|
2425
|
+
|
|
2426
|
+
`class` — Parse standalone playtest runner configuration.
|
|
2427
|
+
|
|
2428
|
+
```ts
|
|
2429
|
+
export class PlaytestCliUsageError extends Error { … }
|
|
2430
|
+
```
|
|
2431
|
+
|
|
2432
|
+
- **Use when:** invoke the playtest CLI from a scaffold · validate runner flags before launching a browser
|
|
2433
|
+
- **Constraints:** invalid flags throw a named usage error
|
|
2434
|
+
|
|
2435
|
+
```ts
|
|
2436
|
+
const config = parseStandalonePlaytestArgs(argv);
|
|
2437
|
+
```
|
|
2438
|
+
|
|
2439
|
+
### `playtestStepDrivesMovement`
|
|
2440
|
+
|
|
2441
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2442
|
+
|
|
2443
|
+
```ts
|
|
2444
|
+
export function playtestStepDrivesMovement( step: IPlaytestScenario["steps"][number], hasHeldInput: boolean, ): boolean { … }
|
|
2445
|
+
```
|
|
2446
|
+
|
|
2447
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2448
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2449
|
+
|
|
2450
|
+
```ts
|
|
2451
|
+
const report = await runStandalonePlaytest(options);
|
|
2452
|
+
```
|
|
2453
|
+
|
|
2454
|
+
### `PlaywrightTransport`
|
|
2455
|
+
|
|
2456
|
+
`class` — Connect a Playwright page to a playtest bridge.
|
|
2457
|
+
|
|
2458
|
+
```ts
|
|
2459
|
+
export class PlaywrightTransport implements IBridgeTransport { … }
|
|
2460
|
+
```
|
|
2461
|
+
|
|
2462
|
+
- **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
|
|
2463
|
+
- **Constraints:** the bridge must answer the handshake or the run fails
|
|
2464
|
+
|
|
2465
|
+
```ts
|
|
2466
|
+
const bridge = await connectPlaytestBridge(page);
|
|
2467
|
+
```
|
|
2468
|
+
|
|
2469
|
+
### `preflightDisplay`
|
|
2470
|
+
|
|
2471
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2472
|
+
|
|
2473
|
+
```ts
|
|
2474
|
+
export function preflightDisplay( config: Pick<IStandalonePlaytestConfig, "headless">, scenario: Pick<IPlaytestScenario, "artifacts" | "assert" | "steps">, environment: NodeJS.ProcessEnv = process.env, platform = process.platform, ): IPlaytestDiagnostic | undefined { … }
|
|
2475
|
+
```
|
|
2476
|
+
|
|
2477
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2478
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2479
|
+
|
|
2480
|
+
```ts
|
|
2481
|
+
const report = await runStandalonePlaytest(options);
|
|
2482
|
+
```
|
|
2483
|
+
|
|
2484
|
+
### `reconcileBrowserPointers`
|
|
2485
|
+
|
|
2486
|
+
`function` — Select safe Chromium arguments for WebGPU playtests.
|
|
2487
|
+
|
|
2488
|
+
```ts
|
|
2489
|
+
export function reconcileBrowserPointers( previous: ReadonlyMap<number, Required<IPlaytestPointer>>, next: readonly IPlaytestPointer[], ): IBrowserPointerChange[] { … }
|
|
2490
|
+
```
|
|
2491
|
+
|
|
2492
|
+
- **Use when:** run a browser playtest with Vulkan WebGPU · reject a SwiftShader adapter as evidence
|
|
2493
|
+
- **Constraints:** inspect the adapter name before claiming GPU proof
|
|
2494
|
+
|
|
2495
|
+
```ts
|
|
2496
|
+
const args = resolveBrowserArguments(undefined);
|
|
2497
|
+
```
|
|
2498
|
+
|
|
2499
|
+
### `recordToScenario`
|
|
2500
|
+
|
|
2501
|
+
`function` — Convert captured runner observations into a replay scenario.
|
|
2502
|
+
|
|
2503
|
+
```ts
|
|
2504
|
+
export function recordToScenario( value: unknown, scenarioPath = "recording.json", oracleValue?: unknown, ): IPlaytestScenario { … }
|
|
2505
|
+
```
|
|
2506
|
+
|
|
2507
|
+
- **Use when:** preserve a failing playtest as a replay fixture · require assertions before recording a scenario
|
|
2508
|
+
- **Constraints:** an empty assertion set is a failure
|
|
2509
|
+
|
|
2510
|
+
```ts
|
|
2511
|
+
const scenario = recordToScenario(recording);
|
|
2512
|
+
```
|
|
2513
|
+
|
|
2514
|
+
### `requireAssertions`
|
|
2515
|
+
|
|
2516
|
+
`function` — Convert captured runner observations into a replay scenario.
|
|
2517
|
+
|
|
2518
|
+
```ts
|
|
2519
|
+
export function requireAssertions( value: IPlaytestScenario["assert"], scenarioPath: string, ): NonNullable<IPlaytestScenario["assert"]> { … }
|
|
2520
|
+
```
|
|
2521
|
+
|
|
2522
|
+
- **Use when:** preserve a failing playtest as a replay fixture · require assertions before recording a scenario
|
|
2523
|
+
- **Constraints:** an empty assertion set is a failure
|
|
2524
|
+
|
|
2525
|
+
```ts
|
|
2526
|
+
const scenario = recordToScenario(recording);
|
|
2527
|
+
```
|
|
2528
|
+
|
|
2529
|
+
### `resolveBrowserArguments`
|
|
2530
|
+
|
|
2531
|
+
`function` — Select safe Chromium arguments for WebGPU playtests.
|
|
2532
|
+
|
|
2533
|
+
```ts
|
|
2534
|
+
export function resolveBrowserArguments(browserArgs: readonly string[] | undefined): string[] { … }
|
|
2535
|
+
```
|
|
2536
|
+
|
|
2537
|
+
- **Use when:** run a browser playtest with Vulkan WebGPU · reject a SwiftShader adapter as evidence
|
|
2538
|
+
- **Constraints:** inspect the adapter name before claiming GPU proof
|
|
2539
|
+
|
|
2540
|
+
```ts
|
|
2541
|
+
const args = resolveBrowserArguments(undefined);
|
|
2542
|
+
```
|
|
2543
|
+
|
|
2544
|
+
### `resolveManagedServerCommand`
|
|
2545
|
+
|
|
2546
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2547
|
+
|
|
2548
|
+
```ts
|
|
2549
|
+
export function resolveManagedServerCommand( config: IStandalonePlaytestConfig, dynamicPort?: number, ): string { … }
|
|
2550
|
+
```
|
|
2551
|
+
|
|
2552
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2553
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2554
|
+
|
|
2555
|
+
```ts
|
|
2556
|
+
const report = await runStandalonePlaytest(options);
|
|
2557
|
+
```
|
|
2558
|
+
|
|
2559
|
+
### `resolveManagedServerConfig`
|
|
2560
|
+
|
|
2561
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2562
|
+
|
|
2563
|
+
```ts
|
|
2564
|
+
export async function resolveManagedServerConfig( config: IStandalonePlaytestConfig, ): Promise<IStandalonePlaytestConfig> { … }
|
|
2565
|
+
```
|
|
2566
|
+
|
|
2567
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2568
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2569
|
+
|
|
2570
|
+
```ts
|
|
2571
|
+
const report = await runStandalonePlaytest(options);
|
|
2572
|
+
```
|
|
2573
|
+
|
|
2574
|
+
### `rotatedTouchPosition`
|
|
2575
|
+
|
|
2576
|
+
`function` — Drive and inspect Android playtest transport.
|
|
2577
|
+
|
|
2578
|
+
```ts
|
|
2579
|
+
export function rotatedTouchPosition(x: number, y: number, rotation: number): [number, number] { … }
|
|
2580
|
+
```
|
|
2581
|
+
|
|
2582
|
+
- **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
|
|
2583
|
+
- **Constraints:** Android evidence must name its target and transport
|
|
2584
|
+
|
|
2585
|
+
```ts
|
|
2586
|
+
const adb = discoverAdb(process.env);
|
|
2587
|
+
```
|
|
2588
|
+
|
|
2589
|
+
### `runAndroidPlaytest`
|
|
2590
|
+
|
|
2591
|
+
`function` — Run a playtest on Android through the configured device transport.
|
|
2592
|
+
|
|
2593
|
+
```ts
|
|
2594
|
+
export async function runAndroidPlaytest( config: IStandalonePlaytestConfig, dependencies: IAndroidPlaytestDependencies = { … }
|
|
2595
|
+
```
|
|
2596
|
+
|
|
2597
|
+
- **Use when:** execute a scenario on an Android target · collect Android playtest artifacts
|
|
2598
|
+
- **Constraints:** the app bundle and device transport must be prepared
|
|
2599
|
+
|
|
2600
|
+
```ts
|
|
2601
|
+
await runAndroidPlaytest(options);
|
|
2602
|
+
```
|
|
2603
|
+
|
|
2604
|
+
### `runDesktopPlaytest`
|
|
2605
|
+
|
|
2606
|
+
`function` — Run a desktop playtest and collect its report.
|
|
2607
|
+
|
|
2608
|
+
```ts
|
|
2609
|
+
export async function runDesktopPlaytest( config: IStandalonePlaytestConfig, dependencies: IDesktopPlaytestDependencies = { … }
|
|
2610
|
+
```
|
|
2611
|
+
|
|
2612
|
+
- **Use when:** execute a scenario against the desktop host · verify native desktop behavior from the same scenario
|
|
2613
|
+
- **Constraints:** the desktop host must be built before launching
|
|
2614
|
+
|
|
2615
|
+
```ts
|
|
2616
|
+
await runDesktopPlaytest(options);
|
|
2617
|
+
```
|
|
2618
|
+
|
|
2619
|
+
### `runDevicePlaytest`
|
|
2620
|
+
|
|
2621
|
+
`function` — Run a playtest on Android through the configured device transport.
|
|
2622
|
+
|
|
2623
|
+
```ts
|
|
2624
|
+
export async function runDevicePlaytest( config: IStandalonePlaytestConfig, target: IDevicePlaytestTarget, ): Promise<IStandalonePlaytestReport> { … }
|
|
2625
|
+
```
|
|
2626
|
+
|
|
2627
|
+
- **Use when:** execute a scenario on an Android target · collect Android playtest artifacts
|
|
2628
|
+
- **Constraints:** the app bundle and device transport must be prepared
|
|
2629
|
+
|
|
2630
|
+
```ts
|
|
2631
|
+
await runAndroidPlaytest(options);
|
|
2632
|
+
```
|
|
2633
|
+
|
|
2634
|
+
### `runIosPlaytest`
|
|
2635
|
+
|
|
2636
|
+
`function` — Run a playtest on the iOS simulator or device transport.
|
|
2637
|
+
|
|
2638
|
+
```ts
|
|
2639
|
+
export async function runIosPlaytest( config: IStandalonePlaytestConfig, dependencies: IIosPlaytestDependencies = { … }
|
|
2640
|
+
```
|
|
2641
|
+
|
|
2642
|
+
- **Use when:** execute a scenario on an iOS target · collect iOS playtest artifacts
|
|
2643
|
+
- **Constraints:** identify simulator versus physical transport in evidence
|
|
2644
|
+
|
|
2645
|
+
```ts
|
|
2646
|
+
await runIosPlaytest(options);
|
|
2647
|
+
```
|
|
2648
|
+
|
|
2649
|
+
### `runStandalonePlaytest`
|
|
2650
|
+
|
|
2651
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2652
|
+
|
|
2653
|
+
```ts
|
|
2654
|
+
export async function runStandalonePlaytest( config: IStandalonePlaytestConfig, options: IStandalonePlaytestRunOptions = { … }
|
|
2655
|
+
```
|
|
2656
|
+
|
|
2657
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2658
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2659
|
+
|
|
2660
|
+
```ts
|
|
2661
|
+
const report = await runStandalonePlaytest(options);
|
|
2662
|
+
```
|
|
2663
|
+
|
|
2664
|
+
### `runStandalonePlaytests`
|
|
2665
|
+
|
|
2666
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2667
|
+
|
|
2668
|
+
```ts
|
|
2669
|
+
export async function runStandalonePlaytests( config: IStandalonePlaytestConfig, ): Promise<readonly IStandalonePlaytestReport[]> { … }
|
|
2670
|
+
```
|
|
2671
|
+
|
|
2672
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2673
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2674
|
+
|
|
2675
|
+
```ts
|
|
2676
|
+
const report = await runStandalonePlaytest(options);
|
|
2677
|
+
```
|
|
2678
|
+
|
|
2679
|
+
### `softwareAdapterName`
|
|
2680
|
+
|
|
2681
|
+
`function` — Select safe Chromium arguments for WebGPU playtests.
|
|
2682
|
+
|
|
2683
|
+
```ts
|
|
2684
|
+
export function softwareAdapterName(adapter: Readonly<Record<string, string>> | undefined): string | undefined { … }
|
|
2685
|
+
```
|
|
2686
|
+
|
|
2687
|
+
- **Use when:** run a browser playtest with Vulkan WebGPU · reject a SwiftShader adapter as evidence
|
|
2688
|
+
- **Constraints:** inspect the adapter name before claiming GPU proof
|
|
2689
|
+
|
|
2690
|
+
```ts
|
|
2691
|
+
const args = resolveBrowserArguments(undefined);
|
|
2692
|
+
```
|
|
2693
|
+
|
|
2694
|
+
### `substituteManagedPort`
|
|
2695
|
+
|
|
2696
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2697
|
+
|
|
2698
|
+
```ts
|
|
2699
|
+
export function substituteManagedPort(command: string, port: number): string { … }
|
|
2700
|
+
```
|
|
2701
|
+
|
|
2702
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2703
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2704
|
+
|
|
2705
|
+
```ts
|
|
2706
|
+
const report = await runStandalonePlaytest(options);
|
|
2707
|
+
```
|
|
2708
|
+
|
|
2709
|
+
### `tapCommand`
|
|
2710
|
+
|
|
2711
|
+
`function` — Drive and inspect Android playtest transport.
|
|
2712
|
+
|
|
2713
|
+
```ts
|
|
2714
|
+
export function tapCommand(x: number, y: number): string[] { … }
|
|
2715
|
+
```
|
|
2716
|
+
|
|
2717
|
+
- **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
|
|
2718
|
+
- **Constraints:** Android evidence must name its target and transport
|
|
2719
|
+
|
|
2720
|
+
```ts
|
|
2721
|
+
const adb = discoverAdb(process.env);
|
|
2722
|
+
```
|
|
2723
|
+
|
|
2724
|
+
### `touchRotationFromWindowDump`
|
|
2725
|
+
|
|
2726
|
+
`function` — Drive and inspect Android playtest transport.
|
|
2727
|
+
|
|
2728
|
+
```ts
|
|
2729
|
+
export function touchRotationFromWindowDump(dump: string): number | undefined { … }
|
|
2730
|
+
```
|
|
2731
|
+
|
|
2732
|
+
- **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
|
|
2733
|
+
- **Constraints:** Android evidence must name its target and transport
|
|
2734
|
+
|
|
2735
|
+
```ts
|
|
2736
|
+
const adb = discoverAdb(process.env);
|
|
2737
|
+
```
|
|
2738
|
+
|
|
2739
|
+
### `validateDeviceEndpoint`
|
|
2740
|
+
|
|
2741
|
+
`function` — Resolve a native device transport and its mailbox paths.
|
|
2742
|
+
|
|
2743
|
+
```ts
|
|
2744
|
+
export function validateDeviceEndpoint(value: string): URL { … }
|
|
2745
|
+
```
|
|
2746
|
+
|
|
2747
|
+
- **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
|
|
2748
|
+
- **Constraints:** paths stay inside the managed artifact directory
|
|
2749
|
+
|
|
2750
|
+
```ts
|
|
2751
|
+
const paths = deviceMailboxPaths(projectRoot);
|
|
2752
|
+
```
|
|
2753
|
+
|
|
2754
|
+
### `viewportPresentationCommands`
|
|
2755
|
+
|
|
2756
|
+
`function` — Drive and inspect Android playtest transport.
|
|
2757
|
+
|
|
2758
|
+
```ts
|
|
2759
|
+
export function viewportPresentationCommands( viewport: { … }
|
|
2760
|
+
```
|
|
2761
|
+
|
|
2762
|
+
- **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
|
|
2763
|
+
- **Constraints:** Android evidence must name its target and transport
|
|
2764
|
+
|
|
2765
|
+
```ts
|
|
2766
|
+
const adb = discoverAdb(process.env);
|
|
2767
|
+
```
|
|
2768
|
+
|
|
2769
|
+
### `viewportRestoreCommands`
|
|
2770
|
+
|
|
2771
|
+
`function` — Drive and inspect Android playtest transport.
|
|
2772
|
+
|
|
2773
|
+
```ts
|
|
2774
|
+
export function viewportRestoreCommands(): string[][] { … }
|
|
2775
|
+
```
|
|
2776
|
+
|
|
2777
|
+
- **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
|
|
2778
|
+
- **Constraints:** Android evidence must name its target and transport
|
|
2779
|
+
|
|
2780
|
+
```ts
|
|
2781
|
+
const adb = discoverAdb(process.env);
|
|
2782
|
+
```
|
|
2783
|
+
|
|
2784
|
+
### `writeCaptureProvenance`
|
|
2785
|
+
|
|
2786
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2787
|
+
|
|
2788
|
+
```ts
|
|
2789
|
+
export async function writeCaptureProvenance( artifactDirectory: string, provenance: IPlaytestCaptureProvenance, ): Promise<void> { … }
|
|
2790
|
+
```
|
|
2791
|
+
|
|
2792
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2793
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2794
|
+
|
|
2795
|
+
```ts
|
|
2796
|
+
const report = await runStandalonePlaytest(options);
|
|
2797
|
+
```
|
|
2798
|
+
|
|
2799
|
+
### `writeObservationArtifacts`
|
|
2800
|
+
|
|
2801
|
+
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
2802
|
+
|
|
2803
|
+
```ts
|
|
2804
|
+
export async function writeObservationArtifacts( artifactDirectory: string, requested: IPlaytestArtifactRequest | undefined, observations: { … }
|
|
2805
|
+
```
|
|
2806
|
+
|
|
2807
|
+
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
2808
|
+
- **Constraints:** missing observations and malformed assertions fail closed
|
|
2809
|
+
|
|
2810
|
+
```ts
|
|
2811
|
+
const report = await runStandalonePlaytest(options);
|
|
2812
|
+
```
|
|
2813
|
+
|
|
2814
|
+
### `XcrunIosDriver`
|
|
2815
|
+
|
|
2816
|
+
`class` — Drive and inspect iOS simulator playtest transport.
|
|
2817
|
+
|
|
2818
|
+
```ts
|
|
2819
|
+
export class XcrunIosDriver implements IDevicePlaytestDriver { … }
|
|
2820
|
+
```
|
|
2821
|
+
|
|
2822
|
+
- **Use when:** run a scenario on the iOS simulator · parse the launched native process identifier
|
|
2823
|
+
- **Constraints:** simulator evidence does not claim physical-device proof
|
|
2824
|
+
|
|
2825
|
+
```ts
|
|
2826
|
+
const driver = new XcrunIosDriver(options);
|
|
2827
|
+
```
|
|
2828
|
+
|
|
2829
|
+
## `@threenative/playtest/three`
|
|
2830
|
+
|
|
2831
|
+
### `adviseThreeRenderWorkload`
|
|
2832
|
+
|
|
2833
|
+
`function` — Explain which render workloads should be collapsed or retained.
|
|
2834
|
+
|
|
2835
|
+
```ts
|
|
2836
|
+
export function adviseThreeRenderWorkload(input: IRenderAdvisorInput): IRenderAdvisorReport { … }
|
|
2837
|
+
```
|
|
2838
|
+
|
|
2839
|
+
- **Use when:** diagnose a slow Three.js scene · choose a render optimization from observed workload data
|
|
2840
|
+
- **Constraints:** use measured input rather than visual guesses
|
|
2841
|
+
|
|
2842
|
+
```ts
|
|
2843
|
+
const advice = adviseThreeRenderWorkload(input);
|
|
2844
|
+
```
|
|
2845
|
+
|
|
2846
|
+
### `connectDevicePlaytestBridge`
|
|
2847
|
+
|
|
2848
|
+
`function` — Connect a device-hosted game to the playtest bridge.
|
|
2849
|
+
|
|
2850
|
+
```ts
|
|
2851
|
+
export function connectDevicePlaytestBridge( bridge: IPlaytestBridgeV1, endpoint: string, ): IDeviceBridgeInstallation { … }
|
|
2852
|
+
```
|
|
2853
|
+
|
|
2854
|
+
- **Use when:** run the same playtest on an Android or iOS target · read the device bridge endpoint
|
|
2855
|
+
- **Constraints:** use the device transport selected by the runner
|
|
2856
|
+
|
|
2857
|
+
```ts
|
|
2858
|
+
const connection = await connectDevicePlaytestBridge();
|
|
2859
|
+
```
|
|
2860
|
+
|
|
2861
|
+
### `installThreePlaytestBridge`
|
|
2862
|
+
|
|
2863
|
+
`function` — Install the playtest observation bridge for a plain Three.js game.
|
|
2864
|
+
|
|
2865
|
+
```ts
|
|
2866
|
+
export function installThreePlaytestBridge(options: IThreePlaytestBridgeOptions): IThreePlaytestBridgeInstallation { … }
|
|
2867
|
+
```
|
|
2868
|
+
|
|
2869
|
+
- **Use when:** expose a non-ThreeNative game to the scenario runner · add semantic observations to a browser playtest
|
|
2870
|
+
- **Constraints:** install once before the runner connects
|
|
2871
|
+
|
|
2872
|
+
```ts
|
|
2873
|
+
const bridge = installThreePlaytestBridge(options);
|
|
2874
|
+
```
|
|
2875
|
+
|
|
2876
|
+
### `readPlaytestEndpoint`
|
|
2877
|
+
|
|
2878
|
+
`function` — Connect a device-hosted game to the playtest bridge.
|
|
2879
|
+
|
|
2880
|
+
```ts
|
|
2881
|
+
export function readPlaytestEndpoint(): string | undefined { … }
|
|
2882
|
+
```
|
|
2883
|
+
|
|
2884
|
+
- **Use when:** run the same playtest on an Android or iOS target · read the device bridge endpoint
|
|
2885
|
+
- **Constraints:** use the device transport selected by the runner
|
|
2886
|
+
|
|
2887
|
+
```ts
|
|
2888
|
+
const connection = await connectDevicePlaytestBridge();
|
|
2889
|
+
```
|
|
2890
|
+
|
|
2891
|
+
### `ThreePlaytestPhysicsRecorder`
|
|
2892
|
+
|
|
2893
|
+
`class` — Record Three.js physics bodies for playtest observations.
|
|
2894
|
+
|
|
2895
|
+
```ts
|
|
2896
|
+
export class ThreePlaytestPhysicsRecorder { … }
|
|
2897
|
+
```
|
|
2898
|
+
|
|
2899
|
+
- **Use when:** assert physics contacts in a plain Three.js game · capture bounded body state for a scenario
|
|
2900
|
+
- **Constraints:** keep recorder limits within the documented caps
|
|
2901
|
+
|
|
2902
|
+
```ts
|
|
2903
|
+
const physics = new ThreePlaytestPhysicsRecorder();
|
|
2904
|
+
```
|
|
2905
|
+
|
|
2906
|
+
## `@threenative/template/starter/src/render/effects/gradualBackground`
|
|
2907
|
+
|
|
2908
|
+
### `gradualBackground`
|
|
2909
|
+
|
|
2910
|
+
`function` — ThreeNative equivalent for realism-effects gradualBackground.
|
|
2911
|
+
|
|
2912
|
+
```ts
|
|
2913
|
+
function gradualBackground
|
|
2914
|
+
```
|
|
2915
|
+
|
|
2916
|
+
- **Use when:** grade a background by distance
|
|
2917
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
2918
|
+
|
|
2919
|
+
```ts
|
|
2920
|
+
gradualBackground(...)
|
|
2921
|
+
```
|
|
2922
|
+
|
|
2923
|
+
## `@threenative/template/starter/src/render/effects/lensDistortion`
|
|
2924
|
+
|
|
2925
|
+
### `lensDistortion`
|
|
2926
|
+
|
|
2927
|
+
`function` — ThreeNative equivalent for realism-effects lensDistortion.
|
|
2928
|
+
|
|
2929
|
+
```ts
|
|
2930
|
+
function lensDistortion
|
|
2931
|
+
```
|
|
2932
|
+
|
|
2933
|
+
- **Use when:** warp the image with radial lens distortion
|
|
2934
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
2935
|
+
|
|
2936
|
+
```ts
|
|
2937
|
+
lensDistortion(...)
|
|
2938
|
+
```
|
|
2939
|
+
|
|
2940
|
+
## `@threenative/template/starter/src/render/effects/sparkle`
|
|
2941
|
+
|
|
2942
|
+
### `sparkle`
|
|
2943
|
+
|
|
2944
|
+
`function` — ThreeNative equivalent for realism-effects sparkle.
|
|
2945
|
+
|
|
2946
|
+
```ts
|
|
2947
|
+
function sparkle
|
|
2948
|
+
```
|
|
2949
|
+
|
|
2950
|
+
- **Use when:** add glints to bright highlights
|
|
2951
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
2952
|
+
|
|
2953
|
+
```ts
|
|
2954
|
+
sparkle(...)
|
|
2955
|
+
```
|
|
2956
|
+
|
|
2957
|
+
## `@threenative/ui`
|
|
2958
|
+
|
|
2959
|
+
### `DebugOverlay`
|
|
2960
|
+
|
|
2961
|
+
`function` — Show framework diagnostics while developing a game.
|
|
2962
|
+
|
|
2963
|
+
```ts
|
|
2964
|
+
export function DebugOverlay() { … }
|
|
2965
|
+
```
|
|
2966
|
+
|
|
2967
|
+
- **Use when:** display runtime and playtest diagnostics in a React HUD · inspect a game without changing its scene
|
|
2968
|
+
|
|
2969
|
+
```ts
|
|
2970
|
+
<DebugOverlay game={game} />
|
|
2971
|
+
```
|
|
2972
|
+
|
|
2973
|
+
### `GameCanvas`
|
|
2974
|
+
|
|
2975
|
+
`function` — Mount a ThreeNative game in a React canvas.
|
|
2976
|
+
|
|
2977
|
+
```ts
|
|
2978
|
+
export function GameCanvas<TState extends Record<string, unknown>, TPhysics>( { … }
|
|
2979
|
+
```
|
|
2980
|
+
|
|
2981
|
+
- **Use when:** add a game viewport to a React application · connect a game canvas to the web UI shell
|
|
2982
|
+
- **Constraints:** keep the portable game entry free of React DOM code
|
|
2983
|
+
|
|
2984
|
+
```ts
|
|
2985
|
+
<GameCanvas game={game} />
|
|
2986
|
+
```
|
|
2987
|
+
|
|
2988
|
+
### `UiLayer`
|
|
2989
|
+
|
|
2990
|
+
`function` — Render a game's UI so the same source runs on web and on every native target.
|
|
2991
|
+
|
|
2992
|
+
```ts
|
|
2993
|
+
export function UiLayer( { … }
|
|
2994
|
+
```
|
|
2995
|
+
|
|
2996
|
+
- **Use when:** write one HUD that looks the same on the web build and on a phone · mount a React UI over the game surface on Android or iOS
|
|
2997
|
+
- **Constraints:** mark every control the player touches with data-tn-interactive
|
|
2998
|
+
|
|
2999
|
+
```ts
|
|
3000
|
+
<UiLayer><Hud /></UiLayer>
|
|
3001
|
+
```
|
|
3002
|
+
|
|
3003
|
+
### `useGameState`
|
|
3004
|
+
|
|
3005
|
+
`function` — Read throttled game state from React.
|
|
3006
|
+
|
|
3007
|
+
```ts
|
|
3008
|
+
export function useGameState<TState extends Record<string, unknown>, TPhysics, TSelected>( game: IGame<TState, TPhysics>, selector: GameSelector<TState, TSelected>, ): TSelected;
|
|
3009
|
+
```
|
|
3010
|
+
|
|
3011
|
+
- **Use when:** bind a HUD component to game state · select a slice of state for a React panel
|
|
3012
|
+
- **Constraints:** use this hook only from the web UI entry
|
|
3013
|
+
|
|
3014
|
+
```ts
|
|
3015
|
+
const score = useGameState(game, (state) => state.score);
|
|
3016
|
+
```
|
|
3017
|
+
|
|
3018
|
+
### `useUiIntent`
|
|
3019
|
+
|
|
3020
|
+
`function` — Send a player action from the UI back to the game.
|
|
3021
|
+
|
|
3022
|
+
```ts
|
|
3023
|
+
export function useUiIntent(): (intent: string, payload?: unknown) => void { … }
|
|
3024
|
+
```
|
|
3025
|
+
|
|
3026
|
+
- **Use when:** wire a Restart button in a HUD to the running game · pause a game from a menu rendered over its surface
|
|
3027
|
+
- **Constraints:** the game decides what each intent name means; it may ignore one
|
|
3028
|
+
|
|
3029
|
+
```ts
|
|
3030
|
+
const send = useUiIntent(); send("restart");
|
|
3031
|
+
```
|
|
3032
|
+
|
|
3033
|
+
### `useUiState`
|
|
3034
|
+
|
|
3035
|
+
`function` — Read the game's published state from a UI that may be in another process.
|
|
3036
|
+
|
|
3037
|
+
```ts
|
|
3038
|
+
export function useUiState<TState extends object>(): TState | undefined;
|
|
3039
|
+
```
|
|
3040
|
+
|
|
3041
|
+
- **Use when:** bind a HUD to game state on web and native alike · show score or health in a UI rendered over the game surface
|
|
3042
|
+
- **Constraints:** returns undefined until the game publishes its first state
|
|
3043
|
+
|
|
3044
|
+
```ts
|
|
3045
|
+
const score = useUiState((state) => state.score);
|
|
3046
|
+
```
|
|
3047
|
+
|
|
3048
|
+
## `three/addons/tsl/display/DenoiseNode.js`
|
|
3049
|
+
|
|
3050
|
+
### `DenoiseNode`
|
|
3051
|
+
|
|
3052
|
+
`class` — ThreeNative equivalent for realism-effects DenoiseNode.
|
|
3053
|
+
|
|
3054
|
+
```ts
|
|
3055
|
+
class DenoiseNode
|
|
3056
|
+
```
|
|
3057
|
+
|
|
3058
|
+
- **Use when:** denoise a noisy screen-space pass
|
|
3059
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
3060
|
+
|
|
3061
|
+
```ts
|
|
3062
|
+
DenoiseNode(...)
|
|
3063
|
+
```
|
|
3064
|
+
|
|
3065
|
+
## `three/addons/tsl/display/MotionBlur.js`
|
|
3066
|
+
|
|
3067
|
+
### `motionBlur`
|
|
3068
|
+
|
|
3069
|
+
`function` — ThreeNative equivalent for realism-effects motionBlur.
|
|
3070
|
+
|
|
3071
|
+
```ts
|
|
3072
|
+
function motionBlur
|
|
3073
|
+
```
|
|
3074
|
+
|
|
3075
|
+
- **Use when:** blur motion using a velocity buffer
|
|
3076
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
3077
|
+
|
|
3078
|
+
```ts
|
|
3079
|
+
motionBlur(...)
|
|
3080
|
+
```
|
|
3081
|
+
|
|
3082
|
+
## `three/addons/tsl/display/RecurrentDenoiseNode.js`
|
|
3083
|
+
|
|
3084
|
+
### `RecurrentDenoiseNode`
|
|
3085
|
+
|
|
3086
|
+
`class` — ThreeNative equivalent for realism-effects RecurrentDenoiseNode.
|
|
3087
|
+
|
|
3088
|
+
```ts
|
|
3089
|
+
class RecurrentDenoiseNode
|
|
3090
|
+
```
|
|
3091
|
+
|
|
3092
|
+
- **Use when:** denoise a noisy screen-space pass
|
|
3093
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
3094
|
+
|
|
3095
|
+
```ts
|
|
3096
|
+
RecurrentDenoiseNode(...)
|
|
3097
|
+
```
|
|
3098
|
+
|
|
3099
|
+
## `three/addons/tsl/display/SharpenNode.js`
|
|
3100
|
+
|
|
3101
|
+
### `SharpenNode`
|
|
3102
|
+
|
|
3103
|
+
`class` — ThreeNative equivalent for realism-effects SharpenNode.
|
|
3104
|
+
|
|
3105
|
+
```ts
|
|
3106
|
+
class SharpenNode
|
|
3107
|
+
```
|
|
3108
|
+
|
|
3109
|
+
- **Use when:** make the image sharper
|
|
3110
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
3111
|
+
|
|
3112
|
+
```ts
|
|
3113
|
+
SharpenNode(...)
|
|
3114
|
+
```
|
|
3115
|
+
|
|
3116
|
+
## `three/addons/tsl/display/SSAAPassNode.js`
|
|
3117
|
+
|
|
3118
|
+
### `SSAAPassNode`
|
|
3119
|
+
|
|
3120
|
+
`class` — ThreeNative equivalent for realism-effects SSAAPassNode.
|
|
3121
|
+
|
|
3122
|
+
```ts
|
|
3123
|
+
class SSAAPassNode
|
|
3124
|
+
```
|
|
3125
|
+
|
|
3126
|
+
- **Use when:** anti-alias still and moving scenes
|
|
3127
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
3128
|
+
|
|
3129
|
+
```ts
|
|
3130
|
+
SSAAPassNode(...)
|
|
3131
|
+
```
|
|
3132
|
+
|
|
3133
|
+
## `three/addons/tsl/display/SSGINode.js`
|
|
3134
|
+
|
|
3135
|
+
### `SSGINode`
|
|
3136
|
+
|
|
3137
|
+
`class` — ThreeNative equivalent for realism-effects SSGINode.
|
|
3138
|
+
|
|
3139
|
+
```ts
|
|
3140
|
+
class SSGINode
|
|
3141
|
+
```
|
|
3142
|
+
|
|
3143
|
+
- **Use when:** add screen-space global illumination
|
|
3144
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
3145
|
+
|
|
3146
|
+
```ts
|
|
3147
|
+
SSGINode(...)
|
|
3148
|
+
```
|
|
3149
|
+
|
|
3150
|
+
## `three/addons/tsl/display/SSRNode.js`
|
|
3151
|
+
|
|
3152
|
+
### `SSRNode`
|
|
3153
|
+
|
|
3154
|
+
`class` — ThreeNative equivalent for realism-effects SSRNode.
|
|
3155
|
+
|
|
3156
|
+
```ts
|
|
3157
|
+
class SSRNode
|
|
3158
|
+
```
|
|
3159
|
+
|
|
3160
|
+
- **Use when:** add screen-space reflections
|
|
3161
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
3162
|
+
|
|
3163
|
+
```ts
|
|
3164
|
+
SSRNode(...)
|
|
3165
|
+
```
|
|
3166
|
+
|
|
3167
|
+
## `three/addons/tsl/display/TemporalReprojectNode.js`
|
|
3168
|
+
|
|
3169
|
+
### `TemporalReprojectNode`
|
|
3170
|
+
|
|
3171
|
+
`class` — ThreeNative equivalent for realism-effects TemporalReprojectNode.
|
|
3172
|
+
|
|
3173
|
+
```ts
|
|
3174
|
+
class TemporalReprojectNode
|
|
3175
|
+
```
|
|
3176
|
+
|
|
3177
|
+
- **Use when:** reproject a temporal history
|
|
3178
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
3179
|
+
|
|
3180
|
+
```ts
|
|
3181
|
+
TemporalReprojectNode(...)
|
|
3182
|
+
```
|
|
3183
|
+
|
|
3184
|
+
## `three/addons/tsl/display/TRAANode.js`
|
|
3185
|
+
|
|
3186
|
+
### `TRAANode`
|
|
3187
|
+
|
|
3188
|
+
`class` — ThreeNative equivalent for realism-effects TRAANode.
|
|
3189
|
+
|
|
3190
|
+
```ts
|
|
3191
|
+
class TRAANode
|
|
3192
|
+
```
|
|
3193
|
+
|
|
3194
|
+
- **Use when:** temporally resolve a moving image
|
|
3195
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
3196
|
+
|
|
3197
|
+
```ts
|
|
3198
|
+
TRAANode(...)
|
|
3199
|
+
```
|
|
3200
|
+
|
|
3201
|
+
## `three/tsl`
|
|
3202
|
+
|
|
3203
|
+
### `depth`
|
|
3204
|
+
|
|
3205
|
+
`function` — ThreeNative equivalent for realism-effects depth.
|
|
3206
|
+
|
|
3207
|
+
```ts
|
|
3208
|
+
function depth
|
|
3209
|
+
```
|
|
3210
|
+
|
|
3211
|
+
- **Use when:** provide depth to screen-space effects
|
|
3212
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
3213
|
+
|
|
3214
|
+
```ts
|
|
3215
|
+
depth(...)
|
|
3216
|
+
```
|
|
3217
|
+
|
|
3218
|
+
### `mrt`
|
|
3219
|
+
|
|
3220
|
+
`function` — ThreeNative equivalent for realism-effects mrt.
|
|
3221
|
+
|
|
3222
|
+
```ts
|
|
3223
|
+
function mrt
|
|
3224
|
+
```
|
|
3225
|
+
|
|
3226
|
+
- **Use when:** provision velocity, normal, and depth render targets
|
|
3227
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
3228
|
+
|
|
3229
|
+
```ts
|
|
3230
|
+
mrt(...)
|
|
3231
|
+
```
|
|
3232
|
+
|
|
3233
|
+
### `normal`
|
|
3234
|
+
|
|
3235
|
+
`function` — ThreeNative equivalent for realism-effects normal.
|
|
3236
|
+
|
|
3237
|
+
```ts
|
|
3238
|
+
function normal
|
|
3239
|
+
```
|
|
3240
|
+
|
|
3241
|
+
- **Use when:** provide normals to screen-space effects
|
|
3242
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
3243
|
+
|
|
3244
|
+
```ts
|
|
3245
|
+
normal(...)
|
|
3246
|
+
```
|
|
3247
|
+
|
|
3248
|
+
### `velocity`
|
|
3249
|
+
|
|
3250
|
+
`function` — ThreeNative equivalent for realism-effects velocity.
|
|
3251
|
+
|
|
3252
|
+
```ts
|
|
3253
|
+
function velocity
|
|
3254
|
+
```
|
|
3255
|
+
|
|
3256
|
+
- **Use when:** provide motion vectors to temporal effects
|
|
3257
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
3258
|
+
|
|
3259
|
+
```ts
|
|
3260
|
+
velocity(...)
|
|
3261
|
+
```
|
|
3262
|
+
|
|
3263
|
+
## `three/webgpu`
|
|
3264
|
+
|
|
3265
|
+
### `VelocityNode`
|
|
3266
|
+
|
|
3267
|
+
`class` — ThreeNative equivalent for realism-effects VelocityNode.
|
|
3268
|
+
|
|
3269
|
+
```ts
|
|
3270
|
+
class VelocityNode
|
|
3271
|
+
```
|
|
3272
|
+
|
|
3273
|
+
- **Use when:** provide motion vectors to temporal effects
|
|
3274
|
+
- **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
|
|
3275
|
+
|
|
3276
|
+
```ts
|
|
3277
|
+
VelocityNode(...)
|
|
3278
|
+
```
|
|
3279
|
+
|