@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
|
+
---
|
|
2
|
+
paths:
|
|
3
|
+
- "public/scenes/**"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Scene JSON — things that fail silently
|
|
7
|
+
|
|
8
|
+
Format reference lives in
|
|
9
|
+
`.claude/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
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=d507943047667757a27a1b58cff203b0e3d1bdc646b0f5998cf0851840dde550 name=scene-json.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
---
|
|
2
|
+
paths:
|
|
3
|
+
- "public/ui/**"
|
|
4
|
+
---
|
|
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
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=101e26d6362ef8867f020086e5edae81ae70c45a11e53339171da8591f41f1a6 name=uikitml.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json.schemastore.org/claude-code-settings.json",
|
|
3
|
+
"permissions": {
|
|
4
|
+
"allow": [
|
|
5
|
+
"mcp__iwsdk-runtime__*",
|
|
6
|
+
"mcp__iwsdk-reference__*",
|
|
7
|
+
"mcp__metavr__*",
|
|
8
|
+
"Skill(iwsdk-build-model)",
|
|
9
|
+
"Skill(iwsdk-compose-scene)",
|
|
10
|
+
"Skill(iwsdk-debug)",
|
|
11
|
+
"Skill(iwsdk-depth-occlusion)",
|
|
12
|
+
"Skill(iwsdk-dev)",
|
|
13
|
+
"Skill(iwsdk-glasses-test)",
|
|
14
|
+
"Skill(iwsdk-grab)",
|
|
15
|
+
"Skill(iwsdk-hosting)",
|
|
16
|
+
"Skill(iwsdk-native-xr-test)",
|
|
17
|
+
"Skill(iwsdk-offline)",
|
|
18
|
+
"Skill(iwsdk-physics)",
|
|
19
|
+
"Skill(iwsdk-pwa-packaging)",
|
|
20
|
+
"Skill(iwsdk-ray)",
|
|
21
|
+
"Skill(iwsdk-ui)",
|
|
22
|
+
"Skill(iwsdk-upgrade)"
|
|
23
|
+
]
|
|
24
|
+
},
|
|
25
|
+
"enabledMcpjsonServers": [
|
|
26
|
+
"iwsdk-runtime",
|
|
27
|
+
"iwsdk-reference",
|
|
28
|
+
"metavr"
|
|
29
|
+
]
|
|
30
|
+
}
|
|
@@ -0,0 +1,312 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-build-model
|
|
3
|
+
description: Build or materially repair one reusable IWSDK 3D model as a glTF or deterministic parentless Three.js Object3D, including geometry, surface-relative detail, materials, semantic hierarchy, isolated inspection, and focused refinement. Does not arrange scenes, lighting, environment, or cameras; use iwsdk-compose-scene for those.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# IWSDK Build Model
|
|
7
|
+
|
|
8
|
+
Create one reusable model, prove that it works from multiple viewpoints, and hand a
|
|
9
|
+
stable manifest asset to `iwsdk-compose-scene`. This skill owns object-local geometry,
|
|
10
|
+
materials, hierarchy, proportions, and detail. It does not own scene JSON or the
|
|
11
|
+
placement of one asset relative to another. When a scene needs several new models,
|
|
12
|
+
finish each one under this skill before beginning composition; support assets such as
|
|
13
|
+
display stands, architecture, and set dressing are still models.
|
|
14
|
+
|
|
15
|
+
UIKitML panels belong to `iwsdk-ui`, not this skill.
|
|
16
|
+
|
|
17
|
+
## Fixed Boundaries
|
|
18
|
+
|
|
19
|
+
- Geometry and materials live in glTF or `src/scene-assets/*.scene-asset.ts`, never in
|
|
20
|
+
scene JSON.
|
|
21
|
+
- Register the result in the configured `src/assets.ts` default manifest export.
|
|
22
|
+
- A procedural export is a deterministic, parentless `Object3D` prototype. The editor
|
|
23
|
+
and application evaluate the manifest in separate realms, so do not use a `World`,
|
|
24
|
+
DOM state, timers, or shared object identity while defining it.
|
|
25
|
+
- Import Three.js classes from `@iwsdk/core`, never directly from `three`.
|
|
26
|
+
- For a new multi-file model, do not start `iwsdk dev up` until the first complete
|
|
27
|
+
asset module and manifest registration pass `npm run --if-present typecheck`. A live browser
|
|
28
|
+
evaluating half-written imports can leave HMR connected but not command-ready.
|
|
29
|
+
- Repetition inside one model belongs here. Repetition of placed manifest assets
|
|
30
|
+
belongs to `iwsdk-compose-scene` through prefabs or patterns.
|
|
31
|
+
- Use meters and keep the asset origin, forward axis, floor/contact plane, size
|
|
32
|
+
envelope, and attachment anchors explicit.
|
|
33
|
+
|
|
34
|
+
## 1. Define The Model Contract
|
|
35
|
+
|
|
36
|
+
Turn the request into a short checklist before editing:
|
|
37
|
+
|
|
38
|
+
- silhouette and overall proportions;
|
|
39
|
+
- primary masses, secondary forms, and tertiary surface detail;
|
|
40
|
+
- required articulated or independently readable parts;
|
|
41
|
+
- negative spaces, support contacts, and plausible attachment points;
|
|
42
|
+
- material families and their visual separation;
|
|
43
|
+
- canonical front, back, side, top, and quarter views;
|
|
44
|
+
- exact named parts that merit focused inspection.
|
|
45
|
+
|
|
46
|
+
A single reference image proves only what is visible. Mark hidden geometry as an
|
|
47
|
+
assumption instead of pretending it is specified.
|
|
48
|
+
|
|
49
|
+
## 2. Choose The Representation
|
|
50
|
+
|
|
51
|
+
Prefer, in order:
|
|
52
|
+
|
|
53
|
+
1. an existing suitable manifest asset;
|
|
54
|
+
2. a project-owned glTF with an inspectable hierarchy;
|
|
55
|
+
3. an installable reusable asset or template;
|
|
56
|
+
4. a deterministic procedural `Object3D` when controllable dimensions, semantic
|
|
57
|
+
subparts, articulation, or repeatable code-driven variation matter.
|
|
58
|
+
|
|
59
|
+
MetaVR and Drawcall Market can supply starting assets, but do not assume downloaded
|
|
60
|
+
models contain useful semantic parts. Inspect finalists before adopting them and copy
|
|
61
|
+
selected files into project-owned storage rather than persisting a transient CDN URL.
|
|
62
|
+
|
|
63
|
+
For substantial procedural work, keep a small construction library beside the model:
|
|
64
|
+
lofts/extrusions, bevelled primitives, mirrored duplication, surface frames, repeated
|
|
65
|
+
detail, and material factories. Build semantic named groups such as `Hull`, `Wing`,
|
|
66
|
+
`Nacelle`, `VentRow`, and `LandingGear`; unnamed meshes cannot be focused reliably.
|
|
67
|
+
|
|
68
|
+
## 3. Build From Large To Small
|
|
69
|
+
|
|
70
|
+
Build in this order:
|
|
71
|
+
|
|
72
|
+
1. silhouette and primary masses;
|
|
73
|
+
2. proportion-defining secondary forms and negative spaces;
|
|
74
|
+
3. joints, seams, supports, and functional connections;
|
|
75
|
+
4. repeated tertiary detail;
|
|
76
|
+
5. material separation and restrained finish.
|
|
77
|
+
|
|
78
|
+
Do not use tertiary detail to hide unresolved primary geometry. Reuse geometries and
|
|
79
|
+
materials where practical, but preserve names on inspection-critical groups.
|
|
80
|
+
|
|
81
|
+
### Pass the clay-form gate before detailing
|
|
82
|
+
|
|
83
|
+
- Build continuous designed forms with lofted sections, tapered plates, or bevelled
|
|
84
|
+
transitions. Do not approximate a vehicle hull, nacelle, limb, or other dominant
|
|
85
|
+
form as an exposed pile of stock boxes and cylinders.
|
|
86
|
+
- A primitive is appropriate for an intentionally manufactured subpart such as a
|
|
87
|
+
bearing, fastener, pipe, hub, or recessed mechanism. Where a large secondary mass
|
|
88
|
+
meets the primary form, add a collar, root, socket, fillet-like fairing, overlap, or
|
|
89
|
+
other visible load path instead of letting the pieces merely intersect or hover.
|
|
90
|
+
- In the clay rows of the first complete preview, judge the primary and secondary forms
|
|
91
|
+
before accepting tertiary detail as finish. From front, side, top, and quarter views,
|
|
92
|
+
the silhouette, thickness changes, and transitions must remain intentional without
|
|
93
|
+
color, emission, or tiny greebles.
|
|
94
|
+
- Treat obvious primitive profiles, floating slabs, paper-thin structural plates,
|
|
95
|
+
unexplained gaps, and abrupt tangencies as correction-worthy model defects even
|
|
96
|
+
when the material preview looks polished.
|
|
97
|
+
- Detail quality is not object count. For one hero-scale asset, treat roughly 700
|
|
98
|
+
meshes or 100,000 rendered triangles as a review trigger rather than a target. Before
|
|
99
|
+
exceeding it, remove repeated micro-plates, bolts, or seams that do not improve the
|
|
100
|
+
silhouette, material boundary, or construction story. Spend geometry on continuous
|
|
101
|
+
profiles, root fairings, joints, and thickness changes that remain legible in clay.
|
|
102
|
+
- In the single correction round, fix the weakest primary transition, attachment, or
|
|
103
|
+
support first. Do not answer a merely sparse-looking render by multiplying tertiary
|
|
104
|
+
greebles; fewer well-integrated details beat dense primitive noise.
|
|
105
|
+
|
|
106
|
+
### Keep iteration bounded
|
|
107
|
+
|
|
108
|
+
- Reuse the bundled construction library instead of emitting another geometry-helper
|
|
109
|
+
file into the conversation.
|
|
110
|
+
- Prefer two to six authored modules for a substantial model: shared materials/detail,
|
|
111
|
+
primary form, secondary assemblies, and a small root module. Split only at a real
|
|
112
|
+
ownership boundary or before a file grows past roughly 500 lines; do not create one
|
|
113
|
+
file and one tool round-trip per visible part.
|
|
114
|
+
- Once module boundaries are chosen, emit independent files together rather than
|
|
115
|
+
narrating and waiting between assemblies. Run one initial `npm run --if-present typecheck` after
|
|
116
|
+
all model modules and manifest registration exist; rerun it only after correcting
|
|
117
|
+
an actual error or before final delivery.
|
|
118
|
+
- In Claude Code, `Write` echoes the complete source back into the transcript. Use it
|
|
119
|
+
only for short files (roughly 80 lines or 8 KB). For longer new modules, use Bash
|
|
120
|
+
commands with single-quoted heredocs (`<<'EOF'`) so template literals, `$`, and
|
|
121
|
+
backticks remain literal and the success result stays short. Treat 100 source lines
|
|
122
|
+
or 10 KB as a hard transport limit for one tool call: create the file with `>` and
|
|
123
|
+
append later sections with `>>` in separate calls. End each call at the heredoc
|
|
124
|
+
delimiter; do not append command substitutions or validation to that same command.
|
|
125
|
+
A single logical correction may use several sequential tool calls—never combine
|
|
126
|
+
large replacements across multiple modules into one oversized patch script. Do not
|
|
127
|
+
put TypeScript template literals inside `node -e` or another shell-quoted one-liner.
|
|
128
|
+
Duplicated source payloads and quoting recovery waste context.
|
|
129
|
+
- After a write or edit succeeds, do not read the whole file back. Apply narrow edits;
|
|
130
|
+
avoid whole-file rewrites after initial creation.
|
|
131
|
+
- Claude Code's `Edit` result can retain the complete original file in the transcript.
|
|
132
|
+
Do not use `Edit` on a source file above roughly 120 lines. Use a narrowly scoped
|
|
133
|
+
scripted replacement that asserts exactly one match, writes the file once, and
|
|
134
|
+
prints only a short confirmation. This keeps a one-line correction from reloading
|
|
135
|
+
hundreds of source lines into context and every later cache read.
|
|
136
|
+
- Keep every agent-loop model preview at 640×480 or smaller. If a defect needs closer
|
|
137
|
+
inspection, use `focus` at the same pixel budget instead of raising the resolution.
|
|
138
|
+
Prefer the MCP preview, which persists the image and returns `screenshotPath`. Read
|
|
139
|
+
that file only when visual inspection is needed. Use one contact sheet rather than
|
|
140
|
+
several redundant views; use smaller sheets for support assets. Delivery and
|
|
141
|
+
benchmark captures may be larger, but do not feed duplicate high-resolution images
|
|
142
|
+
back into the model context.
|
|
143
|
+
|
|
144
|
+
### Surface-relative detail is mandatory
|
|
145
|
+
|
|
146
|
+
For vents, plates, grilles, bolts, fins, decals, struts, or greebles attached to a
|
|
147
|
+
sloped or curved surface, establish one local frame:
|
|
148
|
+
|
|
149
|
+
For substantial procedural work, copy this skill's bundled starter library into the
|
|
150
|
+
project without reading or rewriting it:
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
model_kit="$(find .claude/skills .agents/skills -path '*/iwsdk-build-model/assets/hardsurface.ts.template' -print -quit)"
|
|
154
|
+
mkdir -p src/scene-assets/lib
|
|
155
|
+
cp "$model_kit" src/scene-assets/lib/hardsurface.ts
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Do not `Read`, print, page through, or search the copied implementation. This public
|
|
159
|
+
surface is complete:
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
surfaceFrame(origin: Vector3, normal: Vector3, tangentHint: Vector3): SurfaceFrame
|
|
163
|
+
placeOnSurface(object: Object3D, frame: SurfaceFrame, normalOffset?: number): void
|
|
164
|
+
mirrorSurfaceFrameX(frame: SurfaceFrame): SurfaceFrame
|
|
165
|
+
orientBasis(object: Object3D, xDir: Vector3, yDir: Vector3): void
|
|
166
|
+
alignSpan(object: Object3D, a: Vector3, b: Vector3, upHint?: Vector3): number
|
|
167
|
+
ensureOutwardWinding(geometry: BufferGeometry): BufferGeometry
|
|
168
|
+
mirrorGeometryX(geometry: BufferGeometry): BufferGeometry
|
|
169
|
+
bevelBox(width, height, depth, bevel?, cornerRadius?, curveSegments?): BufferGeometry
|
|
170
|
+
taperPlate(lengthX, widthYFront, widthYBack, thickness, bevel?): BufferGeometry
|
|
171
|
+
LoftSurface.tube(sections: TubeSection[]): LoftSurface
|
|
172
|
+
LoftSurface.blade(stations: BladeStation[]): LoftSurface
|
|
173
|
+
surface.point(along: number, theta: number): Vector3
|
|
174
|
+
surface.frame(along: number, theta: number): SurfaceFrame
|
|
175
|
+
surface.frameToward(along: number, outwardDirection: Vector3, samples?: number): SurfaceFrame
|
|
176
|
+
surface.build(
|
|
177
|
+
alongs: number[],
|
|
178
|
+
segments?: number,
|
|
179
|
+
caps?: boolean | {start?: boolean; end?: boolean},
|
|
180
|
+
): BufferGeometry
|
|
181
|
+
sampleRange(from: number, to: number, count: number): number[]
|
|
182
|
+
makeRandom(seed: number): () => number
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
The exact section shapes are
|
|
186
|
+
`{z, halfW, hUp, hDown?, cx?, cy?, power?}` for `TubeSection` and
|
|
187
|
+
`{x, leadZ, trailZ, thickUp, thickDown?, y?, power?}` for `BladeStation`.
|
|
188
|
+
`point`, `frame`, `frameToward`, and `build` take the same absolute `z` or `x`
|
|
189
|
+
coordinates supplied in those sections; do not normalize the sweep range. Passing
|
|
190
|
+
`true` as `caps` closes both ends and `false` leaves both open. `alignSpan()` assumes
|
|
191
|
+
a Y-up primitive, places it midway between `a` and `b`, aligns local +Y to that span,
|
|
192
|
+
and returns the span length; it does not resize the geometry.
|
|
193
|
+
|
|
194
|
+
It exports deterministic lofted tube/blade surfaces, matching surface frames,
|
|
195
|
+
bevelled blocks and plates, span/basis placement, mirrored winding repair, and seeded
|
|
196
|
+
randomness. Import the needed helpers instead of reimplementing that geometry layer.
|
|
197
|
+
|
|
198
|
+
`SurfaceFrame` has a fixed object-space mapping: `tangent` becomes local +X,
|
|
199
|
+
`bitangent` becomes local +Y, and `normal` becomes local +Z. For lofts, `frame()`
|
|
200
|
+
keeps the tangent along the sweep and `frameToward()` only chooses the sample whose
|
|
201
|
+
normal most closely faces the requested direction. `placeOnSurface()` sets both the
|
|
202
|
+
object position and quaternion. To rotate a mounted detail within the tangent plane,
|
|
203
|
+
place a wrapper on the frame and rotate the detail child around local Z; do not apply
|
|
204
|
+
an Euler rotation to the frame-aligned wrapper itself. These conventions are the
|
|
205
|
+
complete orientation contract; do not inspect the bundled implementation to infer
|
|
206
|
+
them.
|
|
207
|
+
|
|
208
|
+
Author the detail so local X/Y lie in the surface plane and local +Z is thickness.
|
|
209
|
+
Offset by `thickness / 2 - embedDepth` so the detail visibly contacts the surface.
|
|
210
|
+
Once a local parent frame is established, vary rows and columns in tangent/bitangent
|
|
211
|
+
coordinates.
|
|
212
|
+
|
|
213
|
+
Free `rotation.set(...)`, `rotation.x = ...`, or guessed Euler angles on an individual
|
|
214
|
+
surface detail are a defect unless the detail already lives under a correctly aligned
|
|
215
|
+
surface-frame parent. This rule prevents the common failure where a vent intended to
|
|
216
|
+
lie against a hull becomes a standing fin.
|
|
217
|
+
|
|
218
|
+
Mirror with complete matrices or mirrored local frames, not position-only copies.
|
|
219
|
+
Recalculate or validate winding and normals after custom indexed/non-indexed geometry.
|
|
220
|
+
|
|
221
|
+
## 4. Validate The Asset
|
|
222
|
+
|
|
223
|
+
After the initial model and manifest pass typecheck, start the managed editor and use
|
|
224
|
+
the isolated model preview when it is command-ready. If valid source has
|
|
225
|
+
`browserConnected: true` but
|
|
226
|
+
`browserCommandReady: false` after an HMR error, call `browser_reload_page` once and
|
|
227
|
+
recheck before deeper diagnosis.
|
|
228
|
+
|
|
229
|
+
```text
|
|
230
|
+
asset_render_preview
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
npx @iwsdk/cli asset render-preview \
|
|
235
|
+
--input-json '{"assetId":"ship","mode":"material"}' \
|
|
236
|
+
--output-file artifacts/ship-material.png
|
|
237
|
+
npx @iwsdk/cli asset render-preview \
|
|
238
|
+
--input-json '{"assetId":"ship","mode":"clay"}' \
|
|
239
|
+
--output-file artifacts/ship-clay.png
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
The command renders one bounded contact sheet. Its default views are front, back,
|
|
243
|
+
right, top, and quarter. It also returns prototype-local bounds, framing bounds,
|
|
244
|
+
object/mesh/geometry/material counts, rendered triangles, named-part bounds, and
|
|
245
|
+
deterministic warnings for missing geometry or normals, invalid indices, non-finite
|
|
246
|
+
data, degenerate triangles, unnamed meshes, and unusual material sides.
|
|
247
|
+
|
|
248
|
+
The MCP response caps named-part paths and warning examples, reports full counts per
|
|
249
|
+
warning code, and omits part bounds to avoid flooding model context. Use CLI JSON when
|
|
250
|
+
complete named-part bounds or warning paths are required.
|
|
251
|
+
|
|
252
|
+
Visible transparent/additive effects are rendered but excluded from automatic framing.
|
|
253
|
+
Set `object.userData.iwsdkPreviewBounds = 'exclude'` for another visible effect that
|
|
254
|
+
must not determine the camera fit.
|
|
255
|
+
|
|
256
|
+
Always inspect the primary model. For simple support assets whose bounds and contact
|
|
257
|
+
plane are explicit, defer a separate preview when the first composed-scene render
|
|
258
|
+
will show them clearly; do not spend one model-render round-trip per trivial stand,
|
|
259
|
+
wall, or floor piece.
|
|
260
|
+
|
|
261
|
+
If any part looks implausible, frame it directly:
|
|
262
|
+
|
|
263
|
+
```bash
|
|
264
|
+
npx @iwsdk/cli asset render-preview \
|
|
265
|
+
--input-json '{"assetId":"ship","mode":"clay","focus":"Ship/Hull/VentRow"}' \
|
|
266
|
+
--output-file artifacts/ship-vent-row.png
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Use the clay pass to separate geometry/attachment defects from lighting or authored
|
|
270
|
+
material response. A defect visible in clay belongs here. A defect that appears only
|
|
271
|
+
after scene lighting is applied routes to `iwsdk-compose-scene` for exposure/light
|
|
272
|
+
diagnosis first; return here only if the material assignment itself is wrong.
|
|
273
|
+
|
|
274
|
+
## 5. Review And Refine
|
|
275
|
+
|
|
276
|
+
Review both material and clay rows for every substantial new or repaired model. Clay
|
|
277
|
+
is optional only for a simple support asset whose form and contact are already obvious
|
|
278
|
+
in the composed-scene render. Check:
|
|
279
|
+
|
|
280
|
+
1. silhouette;
|
|
281
|
+
2. proportions;
|
|
282
|
+
3. continuous primary and secondary form transitions in clay;
|
|
283
|
+
4. required parts;
|
|
284
|
+
5. negative space;
|
|
285
|
+
6. contacts, thickness, and surface attachment;
|
|
286
|
+
7. material response and separation.
|
|
287
|
+
|
|
288
|
+
Inspect suspicious named subtrees with `focus`. Fix the highest-impact defect in the
|
|
289
|
+
owning asset module and rerun the preview. Default to at most two focused correction
|
|
290
|
+
rounds after the first complete model. Stop earlier on repeated defects, oscillation,
|
|
291
|
+
diagnostic plateau, missing source evidence, or a representation ceiling.
|
|
292
|
+
|
|
293
|
+
## 6. Hand Off To Scene Composition
|
|
294
|
+
|
|
295
|
+
Before switching skills, inventory every visible element required by the requested
|
|
296
|
+
scene. Existing manifest assets may pass through unchanged; every missing or materially
|
|
297
|
+
changed model, including support and environment geometry, must complete this workflow
|
|
298
|
+
and have a stable manifest id. Do not leave asset-module authoring for the composition
|
|
299
|
+
phase.
|
|
300
|
+
|
|
301
|
+
Hand `iwsdk-compose-scene`:
|
|
302
|
+
|
|
303
|
+
- the stable manifest asset id;
|
|
304
|
+
- local origin, forward/up axes, and size envelope;
|
|
305
|
+
- floor/contact plane and named attachment anchors;
|
|
306
|
+
- intentional transparent/additive bounds exclusions;
|
|
307
|
+
- passing material and clay preview evidence;
|
|
308
|
+
- remaining assumptions or accepted gaps.
|
|
309
|
+
|
|
310
|
+
Do not compensate for a model-local defect with a scene transform. Do not start scene
|
|
311
|
+
lighting or camera iteration until the model passes isolated review.
|
|
312
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=95fc72ddf1f3915aa71a839558a3ce051b803214b25ad8c594e882068a3d7917 name=iwsdk-build-model (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|