@iwsdk/create 0.4.1 → 0.5.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 +103 -41
- package/dist/cli.js +1003 -3418
- package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +96 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +129 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/component-reference.md +154 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +364 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/api-reference.md +1489 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +241 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +101 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +176 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +156 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +199 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +159 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +255 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +208 -0
- package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +450 -0
- package/dist/guidance/claude/.claude/rules/assets-and-manifest.md +55 -0
- package/dist/guidance/claude/.claude/rules/ecs-api.md +102 -0
- package/dist/guidance/claude/.claude/rules/scene-json.md +64 -0
- package/dist/guidance/claude/.claude/rules/uikitml.md +60 -0
- package/dist/guidance/claude/.claude/settings.json +19 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +96 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +129 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/component-reference.md +154 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +364 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/api-reference.md +1489 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +241 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +101 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +176 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +156 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +199 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +159 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +255 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +208 -0
- package/dist/guidance/claude/CLAUDE.md +142 -0
- package/dist/guidance/codex/.codex/config.toml +2 -0
- package/dist/guidance/common/AGENTS.md +151 -0
- package/dist/guidance/copilot/.github/instructions/assets-and-manifest.instructions.md +52 -0
- package/dist/guidance/copilot/.github/instructions/ecs-api.instructions.md +100 -0
- package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +63 -0
- package/dist/guidance/copilot/.github/instructions/uikitml.instructions.md +59 -0
- package/dist/guidance/cursor/.cursor/rules/assets-and-manifest.mdc +57 -0
- package/dist/guidance/cursor/.cursor/rules/ecs-api.mdc +104 -0
- package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +66 -0
- package/dist/guidance/cursor/.cursor/rules/uikitml.mdc +62 -0
- package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +63 -0
- package/dist/guidance/scoped-agents/public/ui/AGENTS.md +59 -0
- package/dist/guidance/scoped-agents/src/AGENTS.md +149 -0
- package/dist/template/common/README.md +13 -0
- package/dist/template/common/gitignore.template +45 -0
- package/dist/template/common/index.html +16 -0
- package/dist/template/common/nvmrc.template +1 -0
- package/dist/template/common/public/audio/chime.mp3 +0 -0
- package/dist/template/common/public/gltf/webxr-banner/banner.gltf +68 -0
- package/dist/template/common/public/textures/webxr.png +0 -0
- package/dist/template/common/public/ui/welcome.uikitml +98 -0
- package/dist/template/common/src/assets.ts +54 -0
- package/dist/template/common/src/components.ts +11 -0
- package/dist/template/common/src/index.ts +19 -0
- package/dist/template/common/src/panel.ts +38 -0
- package/dist/template/common/src/robot-component.ts +10 -0
- package/dist/template/common/src/robot.ts +38 -0
- package/dist/template/common/src/vite-env.d.ts +2 -0
- package/dist/template/common/tsconfig.json +15 -0
- package/dist/template/common/vite.config.ts +27 -0
- package/dist/template/common-js/README.md +13 -0
- package/dist/template/common-js/gitignore.template +45 -0
- package/dist/template/common-js/index.html +16 -0
- package/dist/template/common-js/nvmrc.template +1 -0
- package/dist/template/common-js/public/audio/chime.mp3 +0 -0
- package/dist/template/common-js/public/gltf/webxr-banner/banner.gltf +68 -0
- package/dist/template/common-js/public/textures/webxr.png +0 -0
- package/dist/template/common-js/public/ui/welcome.uikitml +98 -0
- package/dist/template/common-js/src/assets.js +45 -0
- package/dist/template/common-js/src/components.js +9 -0
- package/dist/template/common-js/src/index.js +14 -0
- package/dist/template/common-js/src/panel.js +31 -0
- package/dist/template/common-js/src/robot-component.js +8 -0
- package/dist/template/common-js/src/robot.js +37 -0
- package/dist/template/common-js/vite.config.js +25 -0
- package/dist/template/scenes/ar.iwsdk.scene.json +96 -0
- package/dist/template/scenes/immersive.iwsdk.scene.json +109 -0
- package/package.json +23 -17
- package/scripts/verify-release-ready.mjs +76 -0
- package/LICENSE +0 -21
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
---
|
|
2
|
+
applyTo: "public/scenes/**"
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Scene JSON — things that fail silently
|
|
6
|
+
|
|
7
|
+
Format reference lives in
|
|
8
|
+
`.agents/skills/iwsdk-scene-composer/references/scene-format.md`: the document
|
|
9
|
+
boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
|
|
10
|
+
it before composing. This file is only the short list of behaviours that produce
|
|
11
|
+
no error when you get them wrong.
|
|
12
|
+
|
|
13
|
+
Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
|
|
14
|
+
closed — an unknown field fails validation.
|
|
15
|
+
|
|
16
|
+
## Imports stop at the authoring boundary
|
|
17
|
+
|
|
18
|
+
Authoring tools can validate and render a root with `imports`, so modular scratch
|
|
19
|
+
scenes remain useful for composition. The editable scene session and application
|
|
20
|
+
runtime deliberately reject imports. Run `scene_flatten_file` or
|
|
21
|
+
`npx iwsdk scene flatten` once, verify the source and output runtime hashes match,
|
|
22
|
+
then make the flat output the sole editable source of truth. Never re-flatten over
|
|
23
|
+
later human editor changes.
|
|
24
|
+
|
|
25
|
+
## The player materialises at the scene origin
|
|
26
|
+
|
|
27
|
+
`0,0,0` unless the document authors `player.transform`. Nothing warns you. A
|
|
28
|
+
scene can pass every authored camera view and still spawn the player inside the
|
|
29
|
+
geometry, because review cameras are not the viewpoint that ships. Keep that
|
|
30
|
+
volume clear or place the player deliberately, and author a diagnostic view at
|
|
31
|
+
player eye height to prove it.
|
|
32
|
+
|
|
33
|
+
## `visibleNodeIds` is the silent-failure detector
|
|
34
|
+
|
|
35
|
+
`renderStats.visibleNodeIds` lists what actually rendered. A node missing from it
|
|
36
|
+
did not appear — even when the image looks plausible and `valid` is `true`. Check
|
|
37
|
+
it against what you expect rather than trusting the picture. Single-sided
|
|
38
|
+
surfaces facing away from the camera are the usual cause, and they report nothing.
|
|
39
|
+
|
|
40
|
+
## Component keys come in two forms
|
|
41
|
+
|
|
42
|
+
Root-level components use the namespaced form
|
|
43
|
+
(`com.iwsdk.components.DomeGradient`). Node-level components accept the bare name
|
|
44
|
+
(`RayInteractable`, `LocomotionEnvironment`). **The editor writes the namespaced
|
|
45
|
+
form on nodes**, so a file touched by both hands contains both. Match whatever the
|
|
46
|
+
node already uses instead of normalising.
|
|
47
|
+
|
|
48
|
+
`LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
|
|
49
|
+
|
|
50
|
+
## The scene owns the runtime camera
|
|
51
|
+
|
|
52
|
+
The hero authoring view supersedes `world.render.camera` from
|
|
53
|
+
`iwsdk.config.json` once the level initialises. Changing the config camera to fix
|
|
54
|
+
runtime framing will appear to do nothing — change the hero view instead.
|
|
55
|
+
|
|
56
|
+
## Validation
|
|
57
|
+
|
|
58
|
+
`scene_render_file` validates, composes, lowers and renders without touching the
|
|
59
|
+
open document. A result is usable only when `valid: true` **and** a PNG comes
|
|
60
|
+
back. Render each changed module before the root.
|
|
61
|
+
|
|
62
|
+
For composing a scene rather than editing one, use the `iwsdk-scene-composer`
|
|
63
|
+
skill — it owns the intake, review and stop-rule procedure this file does not.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
---
|
|
2
|
+
applyTo: "public/ui/**"
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# UIKitML panels
|
|
6
|
+
|
|
7
|
+
HTML/CSS-shaped, not a browser engine. Validate rather than assume support.
|
|
8
|
+
|
|
9
|
+
**Numeric sizes are UIKit units (centimetres), not pixels.** `width: 95` is a
|
|
10
|
+
0.95 m panel. Font sizes follow the same scale: `font-size: 3` is 3 cm tall.
|
|
11
|
+
|
|
12
|
+
**Panels are single-sided and face +Z.** To aim one at a camera, yaw by
|
|
13
|
+
`atan2(dx, dz)` toward it — there is no 180° term. A back-facing panel renders
|
|
14
|
+
nothing, reports no error, and still returns `valid: true` from
|
|
15
|
+
`scene_render_file`; the only signal is its absence from
|
|
16
|
+
`renderStats.visibleNodeIds`.
|
|
17
|
+
|
|
18
|
+
Verified working: `display: flex`, `flex-direction`, `align-items`,
|
|
19
|
+
`justify-content: space-between`, `gap`, `margin-*`, `padding-*`, `width`,
|
|
20
|
+
`height`, `background-color`, `border-color`, `border-width`, `border-radius`,
|
|
21
|
+
`font-size`, `font-weight`, `color`, `text-align`, `cursor`. Tags `div`, `span`,
|
|
22
|
+
`button` all work.
|
|
23
|
+
|
|
24
|
+
Expand shorthands (`padding: 12 18` → four properties), use unitless
|
|
25
|
+
line-height multipliers, and prefer uniform `border-color`/`border-width` over
|
|
26
|
+
directional variants. Parser errors include source locations.
|
|
27
|
+
|
|
28
|
+
## Runtime API
|
|
29
|
+
|
|
30
|
+
Resolve the placed panel by **scene node id**, then elements by their `id`
|
|
31
|
+
attribute:
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
const panel = world.getSceneObject<UIKitMLAsset>('config-panel');
|
|
35
|
+
const chip = panel?.getElementById<UIKit.Text>('finish-gold');
|
|
36
|
+
chip?.addEventListener('click', onClick);
|
|
37
|
+
chip?.setProperties({ backgroundColor: '#d8e6f5', color: '#0e1116' });
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
`setProperties` updates both text (`{ text }`) and style
|
|
41
|
+
(`backgroundColor`, `color`, `borderColor`, `display`) — style changes do apply,
|
|
42
|
+
including over class-based styles from the `<style>` block. `UIKit.Text` is the
|
|
43
|
+
public element type; no deep import from `@pmndrs/uikit` is needed.
|
|
44
|
+
|
|
45
|
+
Three distinct identities, don't conflate them: the **manifest ID** names the
|
|
46
|
+
reusable asset, the **scene node ID** names the placed instance, and the element
|
|
47
|
+
`id` names a field inside it. Never depend on a transient entity index.
|
|
48
|
+
|
|
49
|
+
Give the panel node `RayInteractable` so clicks land.
|
|
50
|
+
|
|
51
|
+
The editor render does not run application systems, so `scene_screenshot` can
|
|
52
|
+
never prove a panel *behaves* — only `browser_screenshot`, against the runtime,
|
|
53
|
+
can.
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
For the authoring procedure — isolated preview, placement, editing, wiring
|
|
58
|
+
runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
|
|
59
|
+
than improvising. This file is the format reference it relies on.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "Asset manifest contract"
|
|
3
|
+
globs:
|
|
4
|
+
- "src/assets.ts"
|
|
5
|
+
- "src/assets.js"
|
|
6
|
+
- "src/scene-assets/**"
|
|
7
|
+
alwaysApply: false
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Asset manifest contract
|
|
11
|
+
|
|
12
|
+
`src/assets.ts` is imported **independently by the app runtime and the editor**,
|
|
13
|
+
in separate JS realms. It must therefore be deterministic and self-contained:
|
|
14
|
+
|
|
15
|
+
- no `World`, scene, iframe, editor object or DOM access
|
|
16
|
+
- no timers, no fetching ambient state
|
|
17
|
+
- no reliance on singleton object identity across realms
|
|
18
|
+
- prototypes immutable after registration, and never parented
|
|
19
|
+
|
|
20
|
+
A manifest entry is either a URL descriptor (`{ url, type, name?, priority? }`)
|
|
21
|
+
or a bare parentless `Object3D`. `AssetType` covers `GLTF`, `Audio`, `Texture`,
|
|
22
|
+
`HDRTexture`, `UIKitML`. Only glTF, UIKitML and `Object3D` entries are placeable
|
|
23
|
+
as scene content; audio/texture/HDR are for application systems.
|
|
24
|
+
|
|
25
|
+
Build public URLs from `import.meta.env.BASE_URL` so runtime, editor and subpath
|
|
26
|
+
builds resolve identically. A file in `public/` is **not** available to a scene
|
|
27
|
+
until it is registered here.
|
|
28
|
+
|
|
29
|
+
## Procedural assets
|
|
30
|
+
|
|
31
|
+
Export a parentless `Object3D` from `src/scene-assets/*.scene-asset.ts` and
|
|
32
|
+
register it under a stable ID. The registry rejects an already-parented
|
|
33
|
+
prototype.
|
|
34
|
+
|
|
35
|
+
Every placement is a distinct hierarchy clone, but **geometry and materials stay
|
|
36
|
+
shared**. Never dispose them from a placed clone; world teardown owns their
|
|
37
|
+
lifetime. Reassigning `mesh.material` on a clone is fine and is how you restyle
|
|
38
|
+
one instance — mutating the shared material in place changes every instance.
|
|
39
|
+
|
|
40
|
+
Bounds come from `Box3` over the instantiated asset and drive placement,
|
|
41
|
+
selection, framing and scatter collision. Put the origin where composition wants
|
|
42
|
+
it (usually floor contact, or the object's own pivot), keep transforms finite,
|
|
43
|
+
and don't let invisible helpers inflate bounds.
|
|
44
|
+
|
|
45
|
+
## Cost
|
|
46
|
+
|
|
47
|
+
Split tessellation by viewing distance rather than using one budget everywhere: a
|
|
48
|
+
close-range hero model and coarser display copies of the same form are two
|
|
49
|
+
prototypes from one factory function. Sphere/lathe segment counts dominate small
|
|
50
|
+
repeated detail more than people expect — check `renderStats.triangles` rather
|
|
51
|
+
than guessing.
|
|
52
|
+
|
|
53
|
+
Reuse material instances within a module. Prefer prefabs plus a deterministic
|
|
54
|
+
pattern for repetition; a pattern whose prefab resolves to a single component-free
|
|
55
|
+
mesh lowers to one `InstancedMesh`.
|
|
56
|
+
|
|
57
|
+
Start assets at `castShadow: false` and opt in only for grounded focal masses.
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "ECS API reference"
|
|
3
|
+
globs:
|
|
4
|
+
- "src/**/*.ts"
|
|
5
|
+
- "src/**/*.js"
|
|
6
|
+
alwaysApply: false
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# ECS API reference
|
|
10
|
+
|
|
11
|
+
## Field types
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
Types.Float32 Float64 Int8 Int16 Int32 Boolean String FilePath
|
|
15
|
+
Types.Vec2 Vec3 Vec4 Color(RGBA) Entity Enum
|
|
16
|
+
Types.Object // avoid — not optimised
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Component
|
|
20
|
+
|
|
21
|
+
Declare in a system-free module, then list it in `src/components.ts` via
|
|
22
|
+
`defineComponents()` or the editor cannot author it.
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
export const MyComponent = createComponent('MyComponent', {
|
|
26
|
+
speed: { type: Types.Float32, default: 1 },
|
|
27
|
+
tint: { type: Types.Color, default: [1, 1, 1, 1] }, // RGBA
|
|
28
|
+
});
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Optional metadata per field — `label`, `step`, `min`, `max`, `enum`, `help`,
|
|
32
|
+
`widget` — drives the editor inspector.
|
|
33
|
+
|
|
34
|
+
## System
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
export class MySystem extends createSystem(
|
|
38
|
+
{
|
|
39
|
+
items: { required: [MyComponent] },
|
|
40
|
+
active: { required: [MyComponent], excluded: [Grabbed] },
|
|
41
|
+
},
|
|
42
|
+
{ speed: { type: Types.Float32, default: 1 } }, // optional config
|
|
43
|
+
) {
|
|
44
|
+
private temp!: Vector3;
|
|
45
|
+
|
|
46
|
+
init() {
|
|
47
|
+
this.temp = new Vector3();
|
|
48
|
+
this.queries.items.subscribe('qualify', (entity) => { /* matched */ });
|
|
49
|
+
this.cleanupFuncs.push(this.config.speed.subscribe((v) => { /* … */ }));
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
update(delta: number, time: number) {
|
|
53
|
+
for (const entity of this.queries.active.entities) { /* no allocations */ }
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Queries take `required`, `excluded` and `where` (value predicates via `eq`, `ne`,
|
|
59
|
+
`lt`, `le`, `gt`, `ge`, `isin`, `nin`). `excluded` is the clean way to skip
|
|
60
|
+
entities in a transient state — e.g. excluding `Grabbed` so a held object is left
|
|
61
|
+
alone.
|
|
62
|
+
|
|
63
|
+
Register explicitly in `src/index.ts` with `world.registerSystem(MySystem)`.
|
|
64
|
+
|
|
65
|
+
Read fields with `entity.getValue(Component, 'field')`. For vector fields use
|
|
66
|
+
`entity.getVectorView(Component, 'field')` — it returns a `Float32Array` view with
|
|
67
|
+
no allocation, and `setValue` **throws** on vector fields in elics 3.4.x.
|
|
68
|
+
|
|
69
|
+
## Interaction components
|
|
70
|
+
|
|
71
|
+
`RayInteractable` plus `Hovered`/`Pressed` covers both mouse/touch canvas input
|
|
72
|
+
and XR rays. Grab components: `OneHandGrabbable` and `TwoHandsGrabbable` are
|
|
73
|
+
proximity-based and respond to **squeeze**, while `DistanceGrabbable` is
|
|
74
|
+
ray-based and responds to **trigger**. `Grabbed` is a transient tag managed by
|
|
75
|
+
`GrabSystem` — read it, never add or remove it. `GrabSystem.useHandPinchForGrab`
|
|
76
|
+
defaults to **false**, so hand pinch does not grab unless you enable it.
|
|
77
|
+
|
|
78
|
+
`DistanceGrabbable` fields: `movementMode` (`MoveTowardsTarget`, `MoveFromTarget`,
|
|
79
|
+
`MoveAtSource`, `RotateAtSource`), `returnToOrigin`, `moveSpeedFactor`,
|
|
80
|
+
`detachOnGrab`, `translate`, `rotate`, `scale`, `targetPositionOffset`,
|
|
81
|
+
`targetQuaternionOffset`. `returnToOrigin: true` gives spring-back on release with
|
|
82
|
+
no custom code.
|
|
83
|
+
|
|
84
|
+
For a held object use `GrabSystem`'s public methods — `forceRelease(entity)`,
|
|
85
|
+
`getHolderHand(entity)` — never deep-import `Handle`.
|
|
86
|
+
|
|
87
|
+
## XR input
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
const pad = this.input.xr.gamepads.right;
|
|
91
|
+
pad?.getButtonDown(InputComponent.Trigger); // just pressed
|
|
92
|
+
pad?.getAxesValues(InputComponent.Thumbstick);
|
|
93
|
+
this.player.head; this.player.raySpaces.left; this.player.gripSpaces.right;
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Prefer `world.input.actions` for reusable intent (`locomotion.move`) over raw
|
|
97
|
+
buttons. Browser controls live at `world.input.keyboard` and
|
|
98
|
+
`world.input.browserGamepads`.
|
|
99
|
+
|
|
100
|
+
## Lifecycle
|
|
101
|
+
|
|
102
|
+
`world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
|
|
103
|
+
pause simulation on blur. `world.camera.position` is local to `world.player`; use
|
|
104
|
+
`getWorldPosition()` when logic needs the true viewer position.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "Scene JSON — things that fail silently"
|
|
3
|
+
globs:
|
|
4
|
+
- "public/scenes/**"
|
|
5
|
+
alwaysApply: false
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Scene JSON — things that fail silently
|
|
9
|
+
|
|
10
|
+
Format reference lives in
|
|
11
|
+
`.agents/skills/iwsdk-scene-composer/references/scene-format.md`: the document
|
|
12
|
+
boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
|
|
13
|
+
it before composing. This file is only the short list of behaviours that produce
|
|
14
|
+
no error when you get them wrong.
|
|
15
|
+
|
|
16
|
+
Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
|
|
17
|
+
closed — an unknown field fails validation.
|
|
18
|
+
|
|
19
|
+
## Imports stop at the authoring boundary
|
|
20
|
+
|
|
21
|
+
Authoring tools can validate and render a root with `imports`, so modular scratch
|
|
22
|
+
scenes remain useful for composition. The editable scene session and application
|
|
23
|
+
runtime deliberately reject imports. Run `scene_flatten_file` or
|
|
24
|
+
`npx iwsdk scene flatten` once, verify the source and output runtime hashes match,
|
|
25
|
+
then make the flat output the sole editable source of truth. Never re-flatten over
|
|
26
|
+
later human editor changes.
|
|
27
|
+
|
|
28
|
+
## The player materialises at the scene origin
|
|
29
|
+
|
|
30
|
+
`0,0,0` unless the document authors `player.transform`. Nothing warns you. A
|
|
31
|
+
scene can pass every authored camera view and still spawn the player inside the
|
|
32
|
+
geometry, because review cameras are not the viewpoint that ships. Keep that
|
|
33
|
+
volume clear or place the player deliberately, and author a diagnostic view at
|
|
34
|
+
player eye height to prove it.
|
|
35
|
+
|
|
36
|
+
## `visibleNodeIds` is the silent-failure detector
|
|
37
|
+
|
|
38
|
+
`renderStats.visibleNodeIds` lists what actually rendered. A node missing from it
|
|
39
|
+
did not appear — even when the image looks plausible and `valid` is `true`. Check
|
|
40
|
+
it against what you expect rather than trusting the picture. Single-sided
|
|
41
|
+
surfaces facing away from the camera are the usual cause, and they report nothing.
|
|
42
|
+
|
|
43
|
+
## Component keys come in two forms
|
|
44
|
+
|
|
45
|
+
Root-level components use the namespaced form
|
|
46
|
+
(`com.iwsdk.components.DomeGradient`). Node-level components accept the bare name
|
|
47
|
+
(`RayInteractable`, `LocomotionEnvironment`). **The editor writes the namespaced
|
|
48
|
+
form on nodes**, so a file touched by both hands contains both. Match whatever the
|
|
49
|
+
node already uses instead of normalising.
|
|
50
|
+
|
|
51
|
+
`LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
|
|
52
|
+
|
|
53
|
+
## The scene owns the runtime camera
|
|
54
|
+
|
|
55
|
+
The hero authoring view supersedes `world.render.camera` from
|
|
56
|
+
`iwsdk.config.json` once the level initialises. Changing the config camera to fix
|
|
57
|
+
runtime framing will appear to do nothing — change the hero view instead.
|
|
58
|
+
|
|
59
|
+
## Validation
|
|
60
|
+
|
|
61
|
+
`scene_render_file` validates, composes, lowers and renders without touching the
|
|
62
|
+
open document. A result is usable only when `valid: true` **and** a PNG comes
|
|
63
|
+
back. Render each changed module before the root.
|
|
64
|
+
|
|
65
|
+
For composing a scene rather than editing one, use the `iwsdk-scene-composer`
|
|
66
|
+
skill — it owns the intake, review and stop-rule procedure this file does not.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "UIKitML panels"
|
|
3
|
+
globs:
|
|
4
|
+
- "public/ui/**"
|
|
5
|
+
alwaysApply: false
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# UIKitML panels
|
|
9
|
+
|
|
10
|
+
HTML/CSS-shaped, not a browser engine. Validate rather than assume support.
|
|
11
|
+
|
|
12
|
+
**Numeric sizes are UIKit units (centimetres), not pixels.** `width: 95` is a
|
|
13
|
+
0.95 m panel. Font sizes follow the same scale: `font-size: 3` is 3 cm tall.
|
|
14
|
+
|
|
15
|
+
**Panels are single-sided and face +Z.** To aim one at a camera, yaw by
|
|
16
|
+
`atan2(dx, dz)` toward it — there is no 180° term. A back-facing panel renders
|
|
17
|
+
nothing, reports no error, and still returns `valid: true` from
|
|
18
|
+
`scene_render_file`; the only signal is its absence from
|
|
19
|
+
`renderStats.visibleNodeIds`.
|
|
20
|
+
|
|
21
|
+
Verified working: `display: flex`, `flex-direction`, `align-items`,
|
|
22
|
+
`justify-content: space-between`, `gap`, `margin-*`, `padding-*`, `width`,
|
|
23
|
+
`height`, `background-color`, `border-color`, `border-width`, `border-radius`,
|
|
24
|
+
`font-size`, `font-weight`, `color`, `text-align`, `cursor`. Tags `div`, `span`,
|
|
25
|
+
`button` all work.
|
|
26
|
+
|
|
27
|
+
Expand shorthands (`padding: 12 18` → four properties), use unitless
|
|
28
|
+
line-height multipliers, and prefer uniform `border-color`/`border-width` over
|
|
29
|
+
directional variants. Parser errors include source locations.
|
|
30
|
+
|
|
31
|
+
## Runtime API
|
|
32
|
+
|
|
33
|
+
Resolve the placed panel by **scene node id**, then elements by their `id`
|
|
34
|
+
attribute:
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
const panel = world.getSceneObject<UIKitMLAsset>('config-panel');
|
|
38
|
+
const chip = panel?.getElementById<UIKit.Text>('finish-gold');
|
|
39
|
+
chip?.addEventListener('click', onClick);
|
|
40
|
+
chip?.setProperties({ backgroundColor: '#d8e6f5', color: '#0e1116' });
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`setProperties` updates both text (`{ text }`) and style
|
|
44
|
+
(`backgroundColor`, `color`, `borderColor`, `display`) — style changes do apply,
|
|
45
|
+
including over class-based styles from the `<style>` block. `UIKit.Text` is the
|
|
46
|
+
public element type; no deep import from `@pmndrs/uikit` is needed.
|
|
47
|
+
|
|
48
|
+
Three distinct identities, don't conflate them: the **manifest ID** names the
|
|
49
|
+
reusable asset, the **scene node ID** names the placed instance, and the element
|
|
50
|
+
`id` names a field inside it. Never depend on a transient entity index.
|
|
51
|
+
|
|
52
|
+
Give the panel node `RayInteractable` so clicks land.
|
|
53
|
+
|
|
54
|
+
The editor render does not run application systems, so `scene_screenshot` can
|
|
55
|
+
never prove a panel *behaves* — only `browser_screenshot`, against the runtime,
|
|
56
|
+
can.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
For the authoring procedure — isolated preview, placement, editing, wiring
|
|
61
|
+
runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
|
|
62
|
+
than improvising. This file is the format reference it relies on.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# IWSDK scoped project guidance
|
|
2
|
+
|
|
3
|
+
This file augments the repository-root `AGENTS.md` for files in this directory.
|
|
4
|
+
|
|
5
|
+
# Scene JSON — things that fail silently
|
|
6
|
+
|
|
7
|
+
Format reference lives in
|
|
8
|
+
`.agents/skills/iwsdk-scene-composer/references/scene-format.md`: the document
|
|
9
|
+
boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
|
|
10
|
+
it before composing. This file is only the short list of behaviours that produce
|
|
11
|
+
no error when you get them wrong.
|
|
12
|
+
|
|
13
|
+
Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
|
|
14
|
+
closed — an unknown field fails validation.
|
|
15
|
+
|
|
16
|
+
## Imports stop at the authoring boundary
|
|
17
|
+
|
|
18
|
+
Authoring tools can validate and render a root with `imports`, so modular scratch
|
|
19
|
+
scenes remain useful for composition. The editable scene session and application
|
|
20
|
+
runtime deliberately reject imports. Run `scene_flatten_file` or
|
|
21
|
+
`npx iwsdk scene flatten` once, verify the source and output runtime hashes match,
|
|
22
|
+
then make the flat output the sole editable source of truth. Never re-flatten over
|
|
23
|
+
later human editor changes.
|
|
24
|
+
|
|
25
|
+
## The player materialises at the scene origin
|
|
26
|
+
|
|
27
|
+
`0,0,0` unless the document authors `player.transform`. Nothing warns you. A
|
|
28
|
+
scene can pass every authored camera view and still spawn the player inside the
|
|
29
|
+
geometry, because review cameras are not the viewpoint that ships. Keep that
|
|
30
|
+
volume clear or place the player deliberately, and author a diagnostic view at
|
|
31
|
+
player eye height to prove it.
|
|
32
|
+
|
|
33
|
+
## `visibleNodeIds` is the silent-failure detector
|
|
34
|
+
|
|
35
|
+
`renderStats.visibleNodeIds` lists what actually rendered. A node missing from it
|
|
36
|
+
did not appear — even when the image looks plausible and `valid` is `true`. Check
|
|
37
|
+
it against what you expect rather than trusting the picture. Single-sided
|
|
38
|
+
surfaces facing away from the camera are the usual cause, and they report nothing.
|
|
39
|
+
|
|
40
|
+
## Component keys come in two forms
|
|
41
|
+
|
|
42
|
+
Root-level components use the namespaced form
|
|
43
|
+
(`com.iwsdk.components.DomeGradient`). Node-level components accept the bare name
|
|
44
|
+
(`RayInteractable`, `LocomotionEnvironment`). **The editor writes the namespaced
|
|
45
|
+
form on nodes**, so a file touched by both hands contains both. Match whatever the
|
|
46
|
+
node already uses instead of normalising.
|
|
47
|
+
|
|
48
|
+
`LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
|
|
49
|
+
|
|
50
|
+
## The scene owns the runtime camera
|
|
51
|
+
|
|
52
|
+
The hero authoring view supersedes `world.render.camera` from
|
|
53
|
+
`iwsdk.config.json` once the level initialises. Changing the config camera to fix
|
|
54
|
+
runtime framing will appear to do nothing — change the hero view instead.
|
|
55
|
+
|
|
56
|
+
## Validation
|
|
57
|
+
|
|
58
|
+
`scene_render_file` validates, composes, lowers and renders without touching the
|
|
59
|
+
open document. A result is usable only when `valid: true` **and** a PNG comes
|
|
60
|
+
back. Render each changed module before the root.
|
|
61
|
+
|
|
62
|
+
For composing a scene rather than editing one, use the `iwsdk-scene-composer`
|
|
63
|
+
skill — it owns the intake, review and stop-rule procedure this file does not.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# IWSDK scoped project guidance
|
|
2
|
+
|
|
3
|
+
This file augments the repository-root `AGENTS.md` for files in this directory.
|
|
4
|
+
|
|
5
|
+
# UIKitML panels
|
|
6
|
+
|
|
7
|
+
HTML/CSS-shaped, not a browser engine. Validate rather than assume support.
|
|
8
|
+
|
|
9
|
+
**Numeric sizes are UIKit units (centimetres), not pixels.** `width: 95` is a
|
|
10
|
+
0.95 m panel. Font sizes follow the same scale: `font-size: 3` is 3 cm tall.
|
|
11
|
+
|
|
12
|
+
**Panels are single-sided and face +Z.** To aim one at a camera, yaw by
|
|
13
|
+
`atan2(dx, dz)` toward it — there is no 180° term. A back-facing panel renders
|
|
14
|
+
nothing, reports no error, and still returns `valid: true` from
|
|
15
|
+
`scene_render_file`; the only signal is its absence from
|
|
16
|
+
`renderStats.visibleNodeIds`.
|
|
17
|
+
|
|
18
|
+
Verified working: `display: flex`, `flex-direction`, `align-items`,
|
|
19
|
+
`justify-content: space-between`, `gap`, `margin-*`, `padding-*`, `width`,
|
|
20
|
+
`height`, `background-color`, `border-color`, `border-width`, `border-radius`,
|
|
21
|
+
`font-size`, `font-weight`, `color`, `text-align`, `cursor`. Tags `div`, `span`,
|
|
22
|
+
`button` all work.
|
|
23
|
+
|
|
24
|
+
Expand shorthands (`padding: 12 18` → four properties), use unitless
|
|
25
|
+
line-height multipliers, and prefer uniform `border-color`/`border-width` over
|
|
26
|
+
directional variants. Parser errors include source locations.
|
|
27
|
+
|
|
28
|
+
## Runtime API
|
|
29
|
+
|
|
30
|
+
Resolve the placed panel by **scene node id**, then elements by their `id`
|
|
31
|
+
attribute:
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
const panel = world.getSceneObject<UIKitMLAsset>('config-panel');
|
|
35
|
+
const chip = panel?.getElementById<UIKit.Text>('finish-gold');
|
|
36
|
+
chip?.addEventListener('click', onClick);
|
|
37
|
+
chip?.setProperties({ backgroundColor: '#d8e6f5', color: '#0e1116' });
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
`setProperties` updates both text (`{ text }`) and style
|
|
41
|
+
(`backgroundColor`, `color`, `borderColor`, `display`) — style changes do apply,
|
|
42
|
+
including over class-based styles from the `<style>` block. `UIKit.Text` is the
|
|
43
|
+
public element type; no deep import from `@pmndrs/uikit` is needed.
|
|
44
|
+
|
|
45
|
+
Three distinct identities, don't conflate them: the **manifest ID** names the
|
|
46
|
+
reusable asset, the **scene node ID** names the placed instance, and the element
|
|
47
|
+
`id` names a field inside it. Never depend on a transient entity index.
|
|
48
|
+
|
|
49
|
+
Give the panel node `RayInteractable` so clicks land.
|
|
50
|
+
|
|
51
|
+
The editor render does not run application systems, so `scene_screenshot` can
|
|
52
|
+
never prove a panel *behaves* — only `browser_screenshot`, against the runtime,
|
|
53
|
+
can.
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
For the authoring procedure — isolated preview, placement, editing, wiring
|
|
58
|
+
runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
|
|
59
|
+
than improvising. This file is the format reference it relies on.
|