@iwsdk/cli 1.1.0 → 1.2.0-rc.1
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 +106 -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 +1532 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +96 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +267 -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 +179 -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-offline/SKILL.md +217 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -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 +102 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +309 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +230 -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 +208 -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 +335 -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 +30 -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 +1532 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +96 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +267 -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 +179 -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-offline/SKILL.md +217 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -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 +102 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +309 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +230 -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 +208 -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 +335 -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 +954 -0
- package/dist/agent-guidance.d.ts +140 -0
- package/dist/agent-guidance.d.ts.map +1 -0
- package/dist/agent-guidance.js +3612 -0
- package/dist/agent-guidance.js.map +1 -0
- package/dist/cli.js +4010 -750
- 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 +138 -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 +53 -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 +6114 -508
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/metavr-telemetry.d.ts +6 -0
- package/dist/metavr-telemetry.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 +34 -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 +1506 -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,72 @@
|
|
|
1
|
+
<!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.1 sha256=4451a5b98ba38a835cca3fc49666cbe62ba77353f6b8d0ed7d46b691d35067c1 -->
|
|
2
|
+
# IWSDK scoped project guidance
|
|
3
|
+
|
|
4
|
+
This file augments the repository-root `AGENTS.md` for files in this directory.
|
|
5
|
+
|
|
6
|
+
# Scene JSON — things that fail silently
|
|
7
|
+
|
|
8
|
+
Format reference lives in
|
|
9
|
+
`.agents/skills/iwsdk-compose-scene/references/scene-format.md`: the document
|
|
10
|
+
boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
|
|
11
|
+
it for imports, prefabs, patterns, or a schema detail not covered by active
|
|
12
|
+
guidance. For ordinary flat node, component, and authored-view edits, this rule,
|
|
13
|
+
the existing scene, and the active specialist are sufficient. This file is only
|
|
14
|
+
the short list of behaviours that produce 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/cli 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
|
+
`ContactShadow` and `ShadowCatcher` meshes take no rays, so a node whose only
|
|
43
|
+
content is one of them is never listed; check the object it grounds instead.
|
|
44
|
+
|
|
45
|
+
## Component keys come in two forms
|
|
46
|
+
|
|
47
|
+
Root-level components use the namespaced form
|
|
48
|
+
(`com.iwsdk.components.DomeGradient`). Node-level components accept the bare name
|
|
49
|
+
(`RayInteractable`, `LocomotionEnvironment`). **The editor writes the namespaced
|
|
50
|
+
form on nodes**, so a file touched by both hands contains both. Match whatever the
|
|
51
|
+
node already uses instead of normalising.
|
|
52
|
+
|
|
53
|
+
`LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
|
|
54
|
+
|
|
55
|
+
## Browser hero views and XR spawn framing are distinct
|
|
56
|
+
|
|
57
|
+
Outside immersive XR, the hero authoring view supersedes `world.render.camera`
|
|
58
|
+
from `iwsdk.config.json` once the level initialises. While XR is presenting,
|
|
59
|
+
the tracked player rig owns the camera and the hero view is intentionally not
|
|
60
|
+
applied. Use the hero view for editor/browser framing, and validate important
|
|
61
|
+
content from the authored `player.transform` spawn (or the default standing
|
|
62
|
+
view near `[0, 1.6, 0]`) before accepting XR framing.
|
|
63
|
+
|
|
64
|
+
## Validation
|
|
65
|
+
|
|
66
|
+
`scene_render_file` validates, composes, lowers and renders without touching the
|
|
67
|
+
open document. A result is usable only when `valid: true` **and** a PNG comes
|
|
68
|
+
back. Render each changed module before the root.
|
|
69
|
+
|
|
70
|
+
For composing a scene rather than editing one, use the `iwsdk-compose-scene`
|
|
71
|
+
skill — it owns the intake, review and stop-rule procedure this file does not.
|
|
72
|
+
<!-- END iwsdk-agent-guidance -->
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
<!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.1 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.1 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 -->
|