@iwsdk/cli 1.1.0 → 1.2.0-rc.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -2
- package/dist/agent-adapters.d.ts +12 -1
- package/dist/agent-adapters.d.ts.map +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
- package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
- package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
- package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
- package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
- package/dist/agent-guidance/files/.claude/settings.json +29 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
- package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
- package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
- package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
- package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
- package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
- package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
- package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
- package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
- package/dist/agent-guidance/files/CLAUDE.md +3 -0
- package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
- package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
- package/dist/agent-guidance/files/src/AGENTS.md +153 -0
- package/dist/agent-guidance/manifest.json +854 -0
- package/dist/agent-guidance.d.ts +113 -0
- package/dist/agent-guidance.d.ts.map +1 -0
- package/dist/agent-guidance.js +3403 -0
- package/dist/agent-guidance.js.map +1 -0
- package/dist/cli.js +2407 -144
- package/dist/cli.js.map +1 -1
- package/dist/commands/adapter.d.ts +1 -0
- package/dist/commands/adapter.d.ts.map +1 -1
- package/dist/commands/agents.d.ts +11 -0
- package/dist/commands/agents.d.ts.map +1 -0
- package/dist/commands/browser.d.ts +11 -0
- package/dist/commands/browser.d.ts.map +1 -1
- package/dist/commands/dev.d.ts +1 -0
- package/dist/commands/dev.d.ts.map +1 -1
- package/dist/commands/reference.d.ts +15 -1
- package/dist/commands/reference.d.ts.map +1 -1
- package/dist/commands/runtime.d.ts.map +1 -1
- package/dist/commands/upgrade.d.ts +51 -0
- package/dist/commands/upgrade.d.ts.map +1 -0
- package/dist/contract.js +32 -0
- package/dist/contract.js.map +1 -1
- package/dist/guidance-refresh.d.ts +33 -0
- package/dist/guidance-refresh.d.ts.map +1 -0
- package/dist/help.d.ts +2 -0
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4744 -135
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
- package/dist/migrations.d.ts +36 -0
- package/dist/migrations.d.ts.map +1 -0
- package/dist/package-manager.d.ts +28 -0
- package/dist/package-manager.d.ts.map +1 -0
- package/dist/release-notes.d.ts +28 -0
- package/dist/release-notes.d.ts.map +1 -0
- package/dist/release-notes.json +1374 -0
- package/dist/runtime-contract.d.ts +8 -0
- package/dist/runtime-contract.d.ts.map +1 -1
- package/dist/runtime-telemetry.d.ts +8 -1
- package/dist/runtime-telemetry.d.ts.map +1 -1
- package/dist/version.d.ts +1 -1
- package/package.json +9 -3
package/README.md
CHANGED
|
@@ -7,8 +7,7 @@ It owns:
|
|
|
7
7
|
|
|
8
8
|
- dev server lifecycle commands
|
|
9
9
|
- adapter sync and status
|
|
10
|
-
- reference status and
|
|
11
|
-
the shared cache automatically)
|
|
10
|
+
- reference status and queries against the installed `@iwsdk/reference`
|
|
12
11
|
- runtime-resolved MCP stdio access
|
|
13
12
|
- direct runtime control commands
|
|
14
13
|
|
|
@@ -36,6 +35,84 @@ supports repository-scoped permissions, sync preapproves only IWSDK-managed MCP
|
|
|
36
35
|
namespaces and skill loading. Copilot tool approval remains an explicit VS Code
|
|
37
36
|
action because it has no supported repository config for that choice.
|
|
38
37
|
|
|
38
|
+
`adapter sync` also installs the project's agent guidance (below).
|
|
39
|
+
|
|
40
|
+
## Agent guidance
|
|
41
|
+
|
|
42
|
+
`@iwsdk/core` ships the coding-agent guidance for its release: a managed block in
|
|
43
|
+
`AGENTS.md`, the IWSDK skills, path-scoped rules, and the project code-review
|
|
44
|
+
subagent. `iwsdk agents sync` installs it from the installed `@iwsdk/core`, so the
|
|
45
|
+
guidance always matches the IWSDK version in `node_modules`. Run it after
|
|
46
|
+
upgrading IWSDK, or in a project that added IWSDK by hand.
|
|
47
|
+
|
|
48
|
+
- Files IWSDK wrote and nobody edited are replaced; each carries a stamp with the
|
|
49
|
+
release and a content hash. Retired IWSDK skills and rules are removed.
|
|
50
|
+
- Files a developer edited, and same-named files IWSDK did not write, are reported
|
|
51
|
+
and left alone. `--force` replaces them.
|
|
52
|
+
- An existing `AGENTS.md` keeps its own text; IWSDK guidance lives between
|
|
53
|
+
`<!-- BEGIN iwsdk-agent-guidance -->` and `<!-- END iwsdk-agent-guidance -->`.
|
|
54
|
+
`CLAUDE.md` gets an `@AGENTS.md` import.
|
|
55
|
+
- Guidance written by releases before stamps is recognized by hash and upgraded.
|
|
56
|
+
- Each file is replaced as a whole, through a temporary copy, so an interrupted
|
|
57
|
+
sync never leaves a half-updated skill. Files written by a newer IWSDK release
|
|
58
|
+
are never rolled back, and an `AGENTS.md` whose markers are broken is left for
|
|
59
|
+
you to fix.
|
|
60
|
+
- A project that lists `@iwsdk/core` must have it installed; otherwise the
|
|
61
|
+
command asks you to install dependencies first. A project that does not list
|
|
62
|
+
it yet gets the copy bundled with the CLI.
|
|
63
|
+
- Without `--tools`, a project keeps the coding tools it already has guidance
|
|
64
|
+
for (a project with none gets all five). `--tools claude,codex` picks them.
|
|
65
|
+
- `iwsdk agents check` writes nothing and exits 1 when sync would change files,
|
|
66
|
+
for CI. Edited files are reported but are not drift.
|
|
67
|
+
- Run it as `npx @iwsdk/cli@latest agents sync` in apps whose installed
|
|
68
|
+
`@iwsdk/cli` predates the command.
|
|
69
|
+
|
|
70
|
+
The command prints a short notice on stderr naming the entry skill and every
|
|
71
|
+
skill path, so a coding agent can read the guidance in the same session that
|
|
72
|
+
installed it.
|
|
73
|
+
|
|
74
|
+
`iwsdk dev up` and `dev restart` keep the guidance current after an upgrade:
|
|
75
|
+
when the installed `@iwsdk/core` ships different guidance than the project has,
|
|
76
|
+
they refresh the files nobody edited and print what changed. They only report,
|
|
77
|
+
without writing, when `CI` is set, when `node_modules` holds a different
|
|
78
|
+
`@iwsdk/core` than the lockfile resolves (for example after switching branches
|
|
79
|
+
without installing), or when `iwsdk.config.json` sets
|
|
80
|
+
`"dev": { "agentGuidance": "warn" }`. `"off"` (or `IWSDK_AGENT_GUIDANCE=off`)
|
|
81
|
+
disables the check. They never install guidance into a project that has none.
|
|
82
|
+
|
|
83
|
+
For dependency bots, run the sync after the bump with dependencies installed,
|
|
84
|
+
for example with Renovate (self-hosted Renovate must also allow the commands):
|
|
85
|
+
|
|
86
|
+
```json
|
|
87
|
+
{
|
|
88
|
+
"postUpgradeTasks": {
|
|
89
|
+
"commands": ["npm ci", "npx @iwsdk/cli@latest agents sync"],
|
|
90
|
+
"fileFilters": ["**/*"]
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Use your package manager's install in place of `npm ci`
|
|
96
|
+
(`pnpm install --frozen-lockfile`, `yarn install --immutable`).
|
|
97
|
+
|
|
98
|
+
## Upgrading IWSDK
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
npx @iwsdk/cli@latest upgrade [--to <version>] [--dry-run] [--no-install]
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`upgrade` sets every `@iwsdk/*` dependency in the release group to the CLI's
|
|
105
|
+
release (or `--to`), keeping `^` and `~` ranges and leaving `workspace:`,
|
|
106
|
+
`file:` and `catalog:` specs alone. It installs with the package manager found
|
|
107
|
+
from the nearest lockfile, aligns the `three` alias (in `package.json` or
|
|
108
|
+
`pnpm-workspace.yaml`) with the one `@iwsdk/core` uses, refreshes the agent
|
|
109
|
+
guidance the project already has, and checks `iwsdk.config.json` against the
|
|
110
|
+
new release. It writes to `.iwsdk/migrations/` (gitignored) the migration guide
|
|
111
|
+
for each release boundary crossed and `release-notes.md` with every change in
|
|
112
|
+
between, and names them in its output. Use `@latest`: migration guides and
|
|
113
|
+
release notes ship with the CLI, so the newest CLI covers every release,
|
|
114
|
+
whatever version the project starts from.
|
|
115
|
+
|
|
39
116
|
- `iwsdk adapter status` reports MCP, instruction, and permission state.
|
|
40
117
|
- `iwsdk adapter prune` removes managed MCP/permission entries and preserves
|
|
41
118
|
editable instruction files.
|
package/dist/agent-adapters.d.ts
CHANGED
|
@@ -22,11 +22,22 @@ export interface SyncAgentAdaptersOptions {
|
|
|
22
22
|
command?: string;
|
|
23
23
|
args?: string[];
|
|
24
24
|
}
|
|
25
|
+
export type AdapterGuidanceResult = {
|
|
26
|
+
status: 'synced';
|
|
27
|
+
version: string;
|
|
28
|
+
origin: string;
|
|
29
|
+
changed: boolean;
|
|
30
|
+
skipped: string[];
|
|
31
|
+
} | {
|
|
32
|
+
status: 'unavailable';
|
|
33
|
+
code: string;
|
|
34
|
+
message: string;
|
|
35
|
+
};
|
|
25
36
|
export declare function syncAgentAdapters({ workspaceRoot, tools, command, args, }: SyncAgentAdaptersOptions): Promise<{
|
|
26
37
|
workspaceRoot: string;
|
|
27
38
|
tools: AiTool[];
|
|
28
39
|
serverNames: string[];
|
|
29
|
-
|
|
40
|
+
guidance: AdapterGuidanceResult;
|
|
30
41
|
}>;
|
|
31
42
|
export declare function pruneAgentAdapters({ workspaceRoot, tools, }: {
|
|
32
43
|
workspaceRoot: string;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"agent-adapters.d.ts","sourceRoot":"","sources":["../src/agent-adapters.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;
|
|
1
|
+
{"version":3,"file":"agent-adapters.d.ts","sourceRoot":"","sources":["../src/agent-adapters.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH,OAAO,EAAsB,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAaxE,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC;KAClC,CAAC;IACF,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,MAAM,EAAE,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;QAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAoVD,MAAM,MAAM,qBAAqB,GAC7B;IACE,MAAM,EAAE,QAAQ,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,GACD;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,wBAAsB,iBAAiB,CAAC,EACtC,aAAa,EACb,KAAK,EACL,OAAO,EACP,IAAI,GACL,EAAE,wBAAwB,GAAG,OAAO,CAAC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,qBAAqB,CAAC;CACjC,CAAC,CA6BD;AAED,wBAAsB,kBAAkB,CAAC,EACvC,aAAa,EACb,KAAK,GACN,EAAE;IACD,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhB;AA8FD,wBAAsB,uBAAuB,CAC3C,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EAAE,GACpB,OAAO,CAAC,oBAAoB,CAAC,CA0C/B;AAED,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA0BvE"}
|
|
@@ -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.0 sha256=95fc72ddf1f3915aa71a839558a3ce051b803214b25ad8c594e882068a3d7917 name=iwsdk-build-model (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|