@iwsdk/cli 1.1.0 → 1.2.0-rc.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -2
- package/dist/agent-adapters.d.ts +12 -1
- package/dist/agent-adapters.d.ts.map +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
- package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
- package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
- package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
- package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
- package/dist/agent-guidance/files/.claude/settings.json +29 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
- package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
- package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
- package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
- package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
- package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
- package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
- package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
- package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
- package/dist/agent-guidance/files/CLAUDE.md +3 -0
- package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
- package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
- package/dist/agent-guidance/files/src/AGENTS.md +153 -0
- package/dist/agent-guidance/manifest.json +854 -0
- package/dist/agent-guidance.d.ts +113 -0
- package/dist/agent-guidance.d.ts.map +1 -0
- package/dist/agent-guidance.js +3403 -0
- package/dist/agent-guidance.js.map +1 -0
- package/dist/cli.js +2407 -144
- package/dist/cli.js.map +1 -1
- package/dist/commands/adapter.d.ts +1 -0
- package/dist/commands/adapter.d.ts.map +1 -1
- package/dist/commands/agents.d.ts +11 -0
- package/dist/commands/agents.d.ts.map +1 -0
- package/dist/commands/browser.d.ts +11 -0
- package/dist/commands/browser.d.ts.map +1 -1
- package/dist/commands/dev.d.ts +1 -0
- package/dist/commands/dev.d.ts.map +1 -1
- package/dist/commands/reference.d.ts +15 -1
- package/dist/commands/reference.d.ts.map +1 -1
- package/dist/commands/runtime.d.ts.map +1 -1
- package/dist/commands/upgrade.d.ts +51 -0
- package/dist/commands/upgrade.d.ts.map +1 -0
- package/dist/contract.js +32 -0
- package/dist/contract.js.map +1 -1
- package/dist/guidance-refresh.d.ts +33 -0
- package/dist/guidance-refresh.d.ts.map +1 -0
- package/dist/help.d.ts +2 -0
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4744 -135
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
- package/dist/migrations.d.ts +36 -0
- package/dist/migrations.d.ts.map +1 -0
- package/dist/package-manager.d.ts +28 -0
- package/dist/package-manager.d.ts.map +1 -0
- package/dist/release-notes.d.ts +28 -0
- package/dist/release-notes.d.ts.map +1 -0
- package/dist/release-notes.json +1374 -0
- package/dist/runtime-contract.d.ts +8 -0
- package/dist/runtime-contract.d.ts.map +1 -1
- package/dist/runtime-telemetry.d.ts +8 -1
- package/dist/runtime-telemetry.d.ts.map +1 -1
- package/dist/version.d.ts +1 -1
- package/package.json +9 -3
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
<!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.0 sha256=abe74e27fdcd33f9fbdfa6fef5b11cd1427fe15c66fec1a0b884f3a09b750266 -->
|
|
2
|
+
# IWSDK scoped project guidance
|
|
3
|
+
|
|
4
|
+
This file augments the repository-root `AGENTS.md` for files in this directory.
|
|
5
|
+
|
|
6
|
+
# UIKitML panels
|
|
7
|
+
|
|
8
|
+
HTML/CSS-shaped, not a browser engine. Validate rather than assume support.
|
|
9
|
+
|
|
10
|
+
**Numeric sizes are UIKit units (centimetres), not pixels.** `width: 95` is a
|
|
11
|
+
0.95 m panel. Font sizes follow the same scale: `font-size: 3` is 3 cm tall.
|
|
12
|
+
|
|
13
|
+
**Panels are single-sided and face +Z.** To aim one at a camera, yaw by
|
|
14
|
+
`atan2(dx, dz)` toward it — there is no 180° term. A back-facing panel renders
|
|
15
|
+
nothing, reports no error, and still returns `valid: true` from
|
|
16
|
+
`scene_render_file`; the only signal is its absence from
|
|
17
|
+
`renderStats.visibleNodeIds`.
|
|
18
|
+
|
|
19
|
+
Verified working: `display: flex`, `flex-direction`, `align-items`,
|
|
20
|
+
`justify-content: space-between`, `gap`, `margin-*`, `padding-*`, `width`,
|
|
21
|
+
`height`, `background-color`, `border-color`, `border-width`, `border-radius`,
|
|
22
|
+
`font-size`, `font-weight`, `color`, `text-align`, `cursor`. Tags `div`, `span`,
|
|
23
|
+
`button` all work.
|
|
24
|
+
|
|
25
|
+
Expand shorthands (`padding: 12 18` → four properties), use unitless
|
|
26
|
+
line-height multipliers, and prefer uniform `border-color`/`border-width` over
|
|
27
|
+
directional variants. Parser errors include source locations.
|
|
28
|
+
|
|
29
|
+
**Production builds drop unused Lucide icons.** They keep only icons named in
|
|
30
|
+
`public/**/*.uikitml`. Icons named only by UIKitML built at runtime or loaded
|
|
31
|
+
from elsewhere must be listed in `iwsdkDev({ bundle: { icons: [...] } })`, or
|
|
32
|
+
they fail after `npm run build`.
|
|
33
|
+
|
|
34
|
+
## Runtime API
|
|
35
|
+
|
|
36
|
+
Resolve the placed panel by **scene node id**, then elements by their `id`
|
|
37
|
+
attribute:
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
const panel = world.getSceneObject<UIKitMLAsset>('config-panel');
|
|
41
|
+
const chip = panel?.getElementById<UIKit.Text>('finish-gold');
|
|
42
|
+
chip?.addEventListener('click', onClick);
|
|
43
|
+
chip?.setProperties({ backgroundColor: '#d8e6f5', color: '#0e1116' });
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
`setProperties` updates both text (`{ text }`) and style
|
|
47
|
+
(`backgroundColor`, `color`, `borderColor`, `display`) — style changes do apply,
|
|
48
|
+
including over class-based styles from the `<style>` block. `UIKit.Text` is the
|
|
49
|
+
public element type; no deep import from `@pmndrs/uikit` is needed.
|
|
50
|
+
|
|
51
|
+
Three distinct identities, don't conflate them: the **manifest ID** names the
|
|
52
|
+
reusable asset, the **scene node ID** names the placed instance, and the element
|
|
53
|
+
`id` names a field inside it. Never depend on a transient entity index.
|
|
54
|
+
|
|
55
|
+
Give the panel node `RayInteractable` so clicks land.
|
|
56
|
+
|
|
57
|
+
The editor render does not run application systems, so `scene_screenshot` can
|
|
58
|
+
never prove a panel *behaves* — only `browser_screenshot`, against the runtime,
|
|
59
|
+
can.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
For the authoring procedure — isolated preview, placement, editing, wiring
|
|
64
|
+
runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
|
|
65
|
+
than improvising. This file is the format reference it relies on.
|
|
66
|
+
<!-- END iwsdk-agent-guidance -->
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
<!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.0 sha256=b60c812e637c6f5bd8f4480f83d7c28a93e042abac20fee504238e8981fa2b6f -->
|
|
2
|
+
# IWSDK scoped project guidance
|
|
3
|
+
|
|
4
|
+
This file augments the repository-root `AGENTS.md` for files in this directory.
|
|
5
|
+
|
|
6
|
+
# ECS API reference
|
|
7
|
+
|
|
8
|
+
## Field types
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
Types.Float32 Float64 Int8 Int16 Int32 Boolean String FilePath
|
|
12
|
+
Types.Vec2 Vec3 Vec4 Color(RGBA) Entity Enum
|
|
13
|
+
Types.Object // avoid — not optimised
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Component
|
|
17
|
+
|
|
18
|
+
Declare in a system-free module, then list it in `src/components.ts` via
|
|
19
|
+
`defineComponents()` or the editor cannot author it.
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
export const MyComponent = createComponent('MyComponent', {
|
|
23
|
+
speed: { type: Types.Float32, default: 1 },
|
|
24
|
+
tint: { type: Types.Color, default: [1, 1, 1, 1] }, // RGBA
|
|
25
|
+
});
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Optional metadata per field — `label`, `step`, `min`, `max`, `enum`, `help`,
|
|
29
|
+
`widget` — drives the editor inspector.
|
|
30
|
+
|
|
31
|
+
## System
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
export class MySystem extends createSystem(
|
|
35
|
+
{
|
|
36
|
+
items: { required: [MyComponent] },
|
|
37
|
+
active: { required: [MyComponent], excluded: [Grabbed] },
|
|
38
|
+
},
|
|
39
|
+
{ speed: { type: Types.Float32, default: 1 } }, // optional config
|
|
40
|
+
) {
|
|
41
|
+
private temp!: Vector3;
|
|
42
|
+
|
|
43
|
+
init() {
|
|
44
|
+
this.temp = new Vector3();
|
|
45
|
+
this.queries.items.subscribe('qualify', (entity) => { /* matched */ });
|
|
46
|
+
this.cleanupFuncs.push(this.config.speed.subscribe((v) => { /* … */ }));
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
update(delta: number, time: number) {
|
|
50
|
+
for (const entity of this.queries.active.entities) { /* no allocations */ }
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Queries take `required`, `excluded` and `where` (value predicates via `eq`, `ne`,
|
|
56
|
+
`lt`, `le`, `gt`, `ge`, `isin`, `nin`). `excluded` is the clean way to skip
|
|
57
|
+
entities in a transient state — e.g. excluding `Grabbed` so a held object is left
|
|
58
|
+
alone.
|
|
59
|
+
|
|
60
|
+
Register explicitly in `src/index.ts` with `world.registerSystem(MySystem)`.
|
|
61
|
+
|
|
62
|
+
Read fields with `entity.getValue(Component, 'field')`. For vector fields use
|
|
63
|
+
`entity.getVectorView(Component, 'field')` — it returns a `Float32Array` view with
|
|
64
|
+
no allocation, and `setValue` **throws** on vector fields in elics 3.4.x.
|
|
65
|
+
|
|
66
|
+
## Interaction components
|
|
67
|
+
|
|
68
|
+
`RayInteractable` plus `Hovered`/`Pressed` covers both mouse/touch canvas input
|
|
69
|
+
and XR rays. Grab components: `OneHandGrabbable` and `TwoHandsGrabbable` are
|
|
70
|
+
proximity-based and respond to **squeeze**, while `DistanceGrabbable` is
|
|
71
|
+
ray-based and responds to **trigger**. `Grabbed` is a transient tag managed by
|
|
72
|
+
`GrabSystem` — read it, never add or remove it. `GrabSystem.useHandPinchForGrab`
|
|
73
|
+
defaults to **true**, so a hand pinch grabs; set it to `false` to require squeeze.
|
|
74
|
+
|
|
75
|
+
`DistanceGrabbable` fields: `movementMode` (`MoveTowardsTarget`, `MoveFromTarget`,
|
|
76
|
+
`MoveAtSource`, `RotateAtSource`), `returnToOrigin`, `moveSpeedFactor`,
|
|
77
|
+
`detachOnGrab`, `translate`, `rotate`, `scale`, `targetPositionOffset`,
|
|
78
|
+
`targetQuaternionOffset`. `returnToOrigin: true` gives spring-back on release with
|
|
79
|
+
no custom code.
|
|
80
|
+
|
|
81
|
+
For a held object use `GrabSystem`'s public methods — `forceRelease(entity)`,
|
|
82
|
+
`getHolderHand(entity)` — never deep-import `Handle`.
|
|
83
|
+
|
|
84
|
+
## XR input
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
const pad = this.input.xr.gamepads.right;
|
|
88
|
+
pad?.getButtonDown(InputComponent.Trigger); // just pressed
|
|
89
|
+
pad?.getAxesValues(InputComponent.Thumbstick);
|
|
90
|
+
this.player.head; this.player.raySpaces.left; this.player.gripSpaces.right;
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Prefer `world.input.actions` for reusable intent (`locomotion.move`) over raw
|
|
94
|
+
buttons. Browser controls live at `world.input.keyboard` and
|
|
95
|
+
`world.input.browserGamepads`.
|
|
96
|
+
|
|
97
|
+
## Lifecycle
|
|
98
|
+
|
|
99
|
+
`world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
|
|
100
|
+
pause simulation on blur. `world.camera.position` is local to `world.player`; use
|
|
101
|
+
`getWorldPosition()` when logic needs the true viewer position.
|
|
102
|
+
|
|
103
|
+
# Asset manifest contract
|
|
104
|
+
|
|
105
|
+
`src/assets.ts` is imported **independently by the app runtime and the editor**,
|
|
106
|
+
in separate JS realms. It must therefore be deterministic and self-contained:
|
|
107
|
+
|
|
108
|
+
- no `World`, scene, iframe, editor object or DOM access
|
|
109
|
+
- no timers, no fetching ambient state
|
|
110
|
+
- no reliance on singleton object identity across realms
|
|
111
|
+
- prototypes immutable after registration, and never parented
|
|
112
|
+
|
|
113
|
+
A manifest entry is either a URL descriptor (`{ url, type, name?, priority? }`)
|
|
114
|
+
or a bare parentless `Object3D`. `AssetType` covers `GLTF`, `Audio`, `Texture`,
|
|
115
|
+
`HDRTexture`, `UIKitML`. Only glTF, UIKitML and `Object3D` entries are placeable
|
|
116
|
+
as scene content; audio/texture/HDR are for application systems.
|
|
117
|
+
|
|
118
|
+
Build public URLs from `import.meta.env.BASE_URL` so runtime, editor and subpath
|
|
119
|
+
builds resolve identically. A file in `public/` is **not** available to a scene
|
|
120
|
+
until it is registered here.
|
|
121
|
+
|
|
122
|
+
## Procedural assets
|
|
123
|
+
|
|
124
|
+
Export a parentless `Object3D` from `src/scene-assets/*.scene-asset.ts` and
|
|
125
|
+
register it under a stable ID. The registry rejects an already-parented
|
|
126
|
+
prototype.
|
|
127
|
+
|
|
128
|
+
Every placement is a distinct hierarchy clone, but **geometry and materials stay
|
|
129
|
+
shared**. Never dispose them from a placed clone; world teardown owns their
|
|
130
|
+
lifetime. Reassigning `mesh.material` on a clone is fine and is how you restyle
|
|
131
|
+
one instance — mutating the shared material in place changes every instance.
|
|
132
|
+
|
|
133
|
+
Bounds come from `Box3` over the instantiated asset and drive placement,
|
|
134
|
+
selection, framing and scatter collision. Put the origin where composition wants
|
|
135
|
+
it (usually floor contact, or the object's own pivot), keep transforms finite,
|
|
136
|
+
and don't let invisible helpers inflate bounds.
|
|
137
|
+
|
|
138
|
+
## Cost
|
|
139
|
+
|
|
140
|
+
Split tessellation by viewing distance rather than using one budget everywhere: a
|
|
141
|
+
close-range hero model and coarser display copies of the same form are two
|
|
142
|
+
prototypes from one factory function. Sphere/lathe segment counts dominate small
|
|
143
|
+
repeated detail more than people expect — check `renderStats.triangles` rather
|
|
144
|
+
than guessing.
|
|
145
|
+
|
|
146
|
+
Reuse material instances within a module. Prefer prefabs plus a deterministic
|
|
147
|
+
pattern for repetition; a pattern whose prefab resolves to a single component-free
|
|
148
|
+
mesh lowers to one `InstancedMesh`.
|
|
149
|
+
|
|
150
|
+
Start assets at `castShadow: false` and opt in only for grounded focal masses.
|
|
151
|
+
Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
|
|
152
|
+
`ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
|
|
153
|
+
<!-- END iwsdk-agent-guidance -->
|