@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,309 @@
|
|
|
1
|
+
## Common Workflows
|
|
2
|
+
|
|
3
|
+
### Creating a Dynamic Physics Object
|
|
4
|
+
|
|
5
|
+
```typescript
|
|
6
|
+
import {
|
|
7
|
+
Mesh,
|
|
8
|
+
SphereGeometry,
|
|
9
|
+
MeshStandardMaterial,
|
|
10
|
+
Color,
|
|
11
|
+
FrontSide,
|
|
12
|
+
} from 'three';
|
|
13
|
+
import {
|
|
14
|
+
PhysicsShape,
|
|
15
|
+
PhysicsShapeType,
|
|
16
|
+
PhysicsBody,
|
|
17
|
+
PhysicsState,
|
|
18
|
+
PhysicsManipulation,
|
|
19
|
+
} from '@iwsdk/core';
|
|
20
|
+
|
|
21
|
+
// 1. Create Three.js mesh
|
|
22
|
+
const ball = new Mesh(
|
|
23
|
+
new SphereGeometry(0.2),
|
|
24
|
+
new MeshStandardMaterial({ color: new Color(0xff4444), side: FrontSide }),
|
|
25
|
+
);
|
|
26
|
+
ball.position.set(0, 2, -1);
|
|
27
|
+
|
|
28
|
+
// 2. Wrap as ECS entity
|
|
29
|
+
const entity = world.createTransformEntity(ball);
|
|
30
|
+
|
|
31
|
+
// 3. Add physics components
|
|
32
|
+
entity.addComponent(PhysicsShape, {
|
|
33
|
+
shape: PhysicsShapeType.Sphere,
|
|
34
|
+
dimensions: [0.2, 0, 0],
|
|
35
|
+
restitution: 0.6, // Bouncy
|
|
36
|
+
});
|
|
37
|
+
entity.addComponent(PhysicsBody, { state: PhysicsState.Dynamic });
|
|
38
|
+
|
|
39
|
+
// 4. Optional: apply initial impulse
|
|
40
|
+
entity.addComponent(PhysicsManipulation, { force: [5, 2, 0] });
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### Creating a Static Environment Collider
|
|
44
|
+
|
|
45
|
+
For walls, floors, and fixed scenery that block dynamic objects but never move:
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
// Ground plane
|
|
49
|
+
const ground = new Mesh(
|
|
50
|
+
new BoxGeometry(10, 0.1, 10),
|
|
51
|
+
new MeshStandardMaterial({ color: 0x888888 }),
|
|
52
|
+
);
|
|
53
|
+
ground.position.set(0, -0.05, 0);
|
|
54
|
+
|
|
55
|
+
const groundEntity = world.createTransformEntity(ground);
|
|
56
|
+
groundEntity.addComponent(PhysicsShape, {
|
|
57
|
+
shape: PhysicsShapeType.Box,
|
|
58
|
+
dimensions: [10, 0.1, 10],
|
|
59
|
+
friction: 0.8,
|
|
60
|
+
});
|
|
61
|
+
groundEntity.addComponent(PhysicsBody, { state: PhysicsState.Static });
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
For complex static geometry (GLTF environments), use `TriMesh` for exact collision:
|
|
65
|
+
|
|
66
|
+
```typescript
|
|
67
|
+
envEntity.addComponent(PhysicsShape, { shape: PhysicsShapeType.TriMesh });
|
|
68
|
+
envEntity.addComponent(PhysicsBody, { state: PhysicsState.Static });
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### Creating a Kinematic Moving Platform
|
|
72
|
+
|
|
73
|
+
Kinematic bodies follow their Object3D: move it from a system and the body sweeps
|
|
74
|
+
there over the next physics steps, pushing dynamic objects and carrying anything
|
|
75
|
+
resting on it. When the Object3D stops, the body stops with it. Don't apply
|
|
76
|
+
`PhysicsManipulation` to a kinematic body; it is ignored with a warning.
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
// Setup
|
|
80
|
+
const platform = new Mesh(
|
|
81
|
+
new BoxGeometry(3, 0.2, 3),
|
|
82
|
+
new MeshStandardMaterial({ color: 0x4488ff }),
|
|
83
|
+
);
|
|
84
|
+
|
|
85
|
+
const platformEntity = world.createTransformEntity(platform);
|
|
86
|
+
platformEntity.addComponent(PhysicsShape, {
|
|
87
|
+
shape: PhysicsShapeType.Box,
|
|
88
|
+
dimensions: [3, 0.2, 3],
|
|
89
|
+
});
|
|
90
|
+
platformEntity.addComponent(PhysicsBody, { state: PhysicsState.Kinematic });
|
|
91
|
+
|
|
92
|
+
// In a system's update loop, move it:
|
|
93
|
+
update(delta, time) {
|
|
94
|
+
for (const entity of this.queries.platforms.entities) {
|
|
95
|
+
entity.object3D.position.y = 1 + Math.sin(time) * 2;
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### Resetting or Teleporting an Existing Body
|
|
101
|
+
|
|
102
|
+
Do not remove/re-add physics components or write only to the Object3D of a dynamic
|
|
103
|
+
body. Use the live physics system so Havok and the render transform update together:
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
import { PhysicsSystem } from '@iwsdk/core';
|
|
107
|
+
|
|
108
|
+
const physics = world.getSystem(PhysicsSystem);
|
|
109
|
+
physics.setBodyTransform(entity, {
|
|
110
|
+
position: homePosition,
|
|
111
|
+
quaternion: homeQuaternion,
|
|
112
|
+
});
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Velocity is cleared by default. Pass `{ resetVelocity: false }` only when a teleport
|
|
116
|
+
must preserve motion. The pose is relative to the entity's parent, like
|
|
117
|
+
`object3D.position`; pass `{ space: 'world' }` for a world-space pose. Physics
|
|
118
|
+
simulates in world space, so bodies may live under a moved level root or another
|
|
119
|
+
entity. `gravityFactor`, `linearDamping`, and `angularDamping` can be
|
|
120
|
+
changed reactively with `entity.setValue`; changing motion state or shape requires
|
|
121
|
+
deliberate body lifecycle handling.
|
|
122
|
+
|
|
123
|
+
### Making an Object Grabbable with Physics
|
|
124
|
+
|
|
125
|
+
Combine grab components with physics for throwable objects:
|
|
126
|
+
|
|
127
|
+
```typescript
|
|
128
|
+
import {
|
|
129
|
+
RayInteractable,
|
|
130
|
+
OneHandGrabbable,
|
|
131
|
+
DistanceGrabbable,
|
|
132
|
+
} from '@iwsdk/core';
|
|
133
|
+
|
|
134
|
+
// Physics components
|
|
135
|
+
entity.addComponent(PhysicsShape, { shape: PhysicsShapeType.Auto });
|
|
136
|
+
entity.addComponent(PhysicsBody, { state: PhysicsState.Dynamic });
|
|
137
|
+
|
|
138
|
+
// Grab components
|
|
139
|
+
entity.addComponent(RayInteractable);
|
|
140
|
+
entity.addComponent(OneHandGrabbable);
|
|
141
|
+
|
|
142
|
+
// Optional: allow grabbing from a distance
|
|
143
|
+
entity.addComponent(DistanceGrabbable, {
|
|
144
|
+
rotate: true,
|
|
145
|
+
translate: true,
|
|
146
|
+
});
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
When grabbed, the `PhysicsSystem` makes a dynamic body kinematic and drives it toward the hand pose, so it pushes other bodies without being knocked out of the hand. A pose jump faster than a hand can move, such as an emulator controller teleport, moves the held body without sweeping it through its neighbours. On release, the body is dynamic again and leaves with the hand's recent velocity, smoothed over about 50 ms and capped at 10 m/s. Note: near-field grabs do not add `Hovered`/`Pressed` tags — assert grab behavior with ECS snapshot/diff, not tag queries.
|
|
150
|
+
|
|
151
|
+
### Reading Velocity for Game Logic
|
|
152
|
+
|
|
153
|
+
```typescript
|
|
154
|
+
const velocity = entity.getVectorView(PhysicsBody, '_linearVelocity');
|
|
155
|
+
const speed = Math.sqrt(velocity[0] ** 2 + velocity[1] ** 2 + velocity[2] ** 2);
|
|
156
|
+
|
|
157
|
+
if (speed > 5.0) {
|
|
158
|
+
// High-speed impact logic
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### Explosion Pattern (Radial Force)
|
|
163
|
+
|
|
164
|
+
Apply outward force to all nearby physics objects:
|
|
165
|
+
|
|
166
|
+
```typescript
|
|
167
|
+
const explosionPos = bomb.object3D.position;
|
|
168
|
+
const radius = 5.0;
|
|
169
|
+
const force = 50.0;
|
|
170
|
+
|
|
171
|
+
for (const target of this.queries.physicsObjects.entities) {
|
|
172
|
+
const dist = target.object3D.position.distanceTo(explosionPos);
|
|
173
|
+
if (dist < radius && dist > 0) {
|
|
174
|
+
const direction = target.object3D.position
|
|
175
|
+
.clone()
|
|
176
|
+
.sub(explosionPos)
|
|
177
|
+
.normalize();
|
|
178
|
+
const strength = force * (1 - dist / radius);
|
|
179
|
+
target.addComponent(PhysicsManipulation, {
|
|
180
|
+
force: direction.multiplyScalar(strength).toArray(),
|
|
181
|
+
});
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## Custom Physics System Pattern
|
|
187
|
+
|
|
188
|
+
Create domain-specific components that interact with the physics system:
|
|
189
|
+
|
|
190
|
+
```typescript
|
|
191
|
+
import {
|
|
192
|
+
createComponent,
|
|
193
|
+
createSystem,
|
|
194
|
+
Types,
|
|
195
|
+
PhysicsBody,
|
|
196
|
+
PhysicsManipulation,
|
|
197
|
+
} from '@iwsdk/core';
|
|
198
|
+
|
|
199
|
+
// 1. Define custom component
|
|
200
|
+
export const Buoyancy = createComponent('Buoyancy', {
|
|
201
|
+
waterLevel: { type: Types.Float32, default: 0.0 },
|
|
202
|
+
buoyancyForce: { type: Types.Float32, default: 15.0 },
|
|
203
|
+
});
|
|
204
|
+
|
|
205
|
+
// 2. Create system that applies physics forces
|
|
206
|
+
export class BuoyancySystem extends createSystem({
|
|
207
|
+
floaters: { required: [Buoyancy, PhysicsBody] },
|
|
208
|
+
}) {
|
|
209
|
+
update(delta) {
|
|
210
|
+
for (const entity of this.queries.floaters.entities) {
|
|
211
|
+
const waterLevel = entity.getValue(Buoyancy, 'waterLevel');
|
|
212
|
+
const force = entity.getValue(Buoyancy, 'buoyancyForce');
|
|
213
|
+
const y = entity.object3D.position.y;
|
|
214
|
+
|
|
215
|
+
if (y < waterLevel) {
|
|
216
|
+
const submersion = Math.min(1, (waterLevel - y) / 0.5);
|
|
217
|
+
if (!entity.hasComponent(PhysicsManipulation)) {
|
|
218
|
+
entity.addComponent(PhysicsManipulation, {
|
|
219
|
+
force: [0, force * submersion * delta, 0],
|
|
220
|
+
});
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
// 3. Register with world
|
|
228
|
+
world.registerComponent(Buoyancy);
|
|
229
|
+
world.registerSystem(BuoyancySystem, { priority: 5 });
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
## Complete Example: Physics Playground
|
|
234
|
+
|
|
235
|
+
```typescript
|
|
236
|
+
import {
|
|
237
|
+
World,
|
|
238
|
+
PhysicsShape,
|
|
239
|
+
PhysicsShapeType,
|
|
240
|
+
PhysicsBody,
|
|
241
|
+
PhysicsState,
|
|
242
|
+
PhysicsManipulation,
|
|
243
|
+
RayInteractable,
|
|
244
|
+
OneHandGrabbable,
|
|
245
|
+
} from '@iwsdk/core';
|
|
246
|
+
import projectOptions from 'virtual:iwsdk-project';
|
|
247
|
+
import {
|
|
248
|
+
Mesh,
|
|
249
|
+
BoxGeometry,
|
|
250
|
+
SphereGeometry,
|
|
251
|
+
MeshStandardMaterial,
|
|
252
|
+
Color,
|
|
253
|
+
FrontSide,
|
|
254
|
+
} from 'three';
|
|
255
|
+
|
|
256
|
+
World.create(
|
|
257
|
+
document.getElementById('scene-container'),
|
|
258
|
+
projectOptions,
|
|
259
|
+
).then((world) => {
|
|
260
|
+
// Static floor
|
|
261
|
+
const floor = new Mesh(
|
|
262
|
+
new BoxGeometry(10, 0.1, 10),
|
|
263
|
+
new MeshStandardMaterial({ color: 0x555555 }),
|
|
264
|
+
);
|
|
265
|
+
floor.position.set(0, -0.05, 0);
|
|
266
|
+
const floorEntity = world.createTransformEntity(floor);
|
|
267
|
+
floorEntity.addComponent(PhysicsShape, {
|
|
268
|
+
shape: PhysicsShapeType.Box,
|
|
269
|
+
dimensions: [10, 0.1, 10],
|
|
270
|
+
friction: 0.8,
|
|
271
|
+
});
|
|
272
|
+
floorEntity.addComponent(PhysicsBody, { state: PhysicsState.Static });
|
|
273
|
+
|
|
274
|
+
// Dynamic bouncy ball (grabbable)
|
|
275
|
+
const ball = new Mesh(
|
|
276
|
+
new SphereGeometry(0.15),
|
|
277
|
+
new MeshStandardMaterial({ color: new Color(0xff4444), side: FrontSide }),
|
|
278
|
+
);
|
|
279
|
+
ball.position.set(0, 1.5, -1);
|
|
280
|
+
const ballEntity = world.createTransformEntity(ball);
|
|
281
|
+
ballEntity.addComponent(PhysicsShape, {
|
|
282
|
+
shape: PhysicsShapeType.Sphere,
|
|
283
|
+
dimensions: [0.15, 0, 0],
|
|
284
|
+
restitution: 0.8,
|
|
285
|
+
friction: 0.5,
|
|
286
|
+
});
|
|
287
|
+
ballEntity.addComponent(PhysicsBody, { state: PhysicsState.Dynamic });
|
|
288
|
+
ballEntity.addComponent(RayInteractable);
|
|
289
|
+
ballEntity.addComponent(OneHandGrabbable);
|
|
290
|
+
|
|
291
|
+
// Dynamic box with initial impulse
|
|
292
|
+
const box = new Mesh(
|
|
293
|
+
new BoxGeometry(0.3, 0.3, 0.3),
|
|
294
|
+
new MeshStandardMaterial({ color: new Color(0x4488ff), side: FrontSide }),
|
|
295
|
+
);
|
|
296
|
+
box.position.set(0.5, 2, -1);
|
|
297
|
+
const boxEntity = world.createTransformEntity(box);
|
|
298
|
+
boxEntity.addComponent(PhysicsShape, {
|
|
299
|
+
shape: PhysicsShapeType.Box,
|
|
300
|
+
dimensions: [0.3, 0.3, 0.3],
|
|
301
|
+
restitution: 0.3,
|
|
302
|
+
});
|
|
303
|
+
boxEntity.addComponent(PhysicsBody, {
|
|
304
|
+
state: PhysicsState.Dynamic,
|
|
305
|
+
linearDamping: 0.1,
|
|
306
|
+
});
|
|
307
|
+
boxEntity.addComponent(PhysicsManipulation, { force: [-3, 5, 0] });
|
|
308
|
+
});
|
|
309
|
+
```
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-pwa-packaging
|
|
3
|
+
description: Ship an IWSDK app to Meta Quest and the Horizon Store as a PWA/TWA — both immersive WebXR and 2D windowed panel modes. Use for PWA packaging, web app manifest and icons, auto-enter-XR on launch, bubblewrap APK builds, signing keystores, Digital Asset Links, sideloading, and Horizon Store upload. Also use when a packaged app is stuck loading, shows a URL bar, or will not launch.
|
|
4
|
+
argument-hint: '[packaging goal, e.g. "ship to the store" or "build an APK"]'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# PWA Packaging for Meta Horizon
|
|
8
|
+
|
|
9
|
+
Turn a built IWSDK app into a signed Quest APK and get it on the Store. The app
|
|
10
|
+
runs from a live URL inside a Trusted Web Activity — the APK is a thin native
|
|
11
|
+
wrapper, not a bundle of your files. That single fact explains most of the
|
|
12
|
+
pipeline: the origin must be live before packaging, and web fixes ship by
|
|
13
|
+
redeploying rather than rebuilding.
|
|
14
|
+
|
|
15
|
+
User request is in `$ARGUMENTS`.
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
0. Pick app mode → immersive WebXR vs 2D panel (decides steps 1 and 4)
|
|
19
|
+
1. Prepare the app → auto-enter XR (immersive only) + manifest link
|
|
20
|
+
2. Get it hosted → public HTTPS origin = <DOMAIN> [iwsdk-hosting]
|
|
21
|
+
3. Manifest + icons → installable PWA, live on <DOMAIN>
|
|
22
|
+
4. Package the APK → keystore, twa-manifest.json, build, asset links
|
|
23
|
+
5. Upload to Store → ovr-platform-util
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Do not reorder these. Step 4 fetches from `<DOMAIN>`, and asset links in step 4
|
|
27
|
+
need a second publish through step 2 — so hosting is a dependency, not a
|
|
28
|
+
finishing touch.
|
|
29
|
+
|
|
30
|
+
## Step 0 — Pick the app mode first
|
|
31
|
+
|
|
32
|
+
One decision, made once, that changes exactly two things downstream. Ask the
|
|
33
|
+
developer if it is not obvious from the project.
|
|
34
|
+
|
|
35
|
+
| | **Immersive WebXR** | **2D panel** |
|
|
36
|
+
| --- | --- | --- |
|
|
37
|
+
| Runs as | full VR/WebXR session | windowed 2D panel with a Library entry |
|
|
38
|
+
| Auto-enter session (step 1) | **yes** | **no — must not be added** |
|
|
39
|
+
| `horizonOSAppMode` (step 4) | `"immersive"` | `"2D"` |
|
|
40
|
+
|
|
41
|
+
An IWSDK app scaffolded with `--mode vr` or `--mode ar` is immersive. A wrong
|
|
42
|
+
value here is the classic failure: a 2D app marked `immersive` hangs on a
|
|
43
|
+
loading screen, and an immersive app marked `2D` opens with a browser URL bar.
|
|
44
|
+
Details and the AR/VR nuance: [`references/app-modes.md`](references/app-modes.md).
|
|
45
|
+
|
|
46
|
+
## Step 1 — Prepare the app
|
|
47
|
+
|
|
48
|
+
**Immersive only: auto-enter the XR session on launch.** An installed immersive
|
|
49
|
+
PWA has no 2D page to click, so nothing would ever call `requestSession` — the
|
|
50
|
+
app-icon tap is the user activation and the app must spend it itself. Gate on
|
|
51
|
+
`getDigitalGoodsService` so this fires only in the installed PWA and never in a
|
|
52
|
+
browser tab, which keeps its normal Enter-XR button.
|
|
53
|
+
|
|
54
|
+
In `src/index.ts`, inside the `World.create(...)` callback:
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
World.create(container, projectOptions).then((world) => {
|
|
58
|
+
// …system registration…
|
|
59
|
+
|
|
60
|
+
const nav = navigator as Navigator & {
|
|
61
|
+
xr?: { isSessionSupported?: (m: string) => Promise<boolean> };
|
|
62
|
+
};
|
|
63
|
+
if ('getDigitalGoodsService' in window && nav.xr?.isSessionSupported) {
|
|
64
|
+
nav.xr
|
|
65
|
+
.isSessionSupported('immersive-vr') // 'immersive-ar' for an AR app
|
|
66
|
+
.then((supported) => {
|
|
67
|
+
if (supported) world.launchXR();
|
|
68
|
+
})
|
|
69
|
+
.catch(() => {});
|
|
70
|
+
}
|
|
71
|
+
});
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
`world.launchXR()` is IWSDK's `requestSession` plus session setup — do not call
|
|
75
|
+
`navigator.xr.requestSession` directly. `getDigitalGoodsService` exists only on
|
|
76
|
+
device, so this path cannot be validated in a desktop browser or in IWER; verify
|
|
77
|
+
it on the headset after sideloading (step 4).
|
|
78
|
+
|
|
79
|
+
**Both modes:** link the manifest and icons in `index.html`. The scaffolded
|
|
80
|
+
`index.html` ships `<link rel="icon" href="data:," />` and no manifest link, so
|
|
81
|
+
the app is not installable until step 3 adds them.
|
|
82
|
+
|
|
83
|
+
**Optional: launch offline.** The TWA loads `<DOMAIN>` over the network, so with
|
|
84
|
+
no connection an installed app shows an error page instead of the app. If it
|
|
85
|
+
must launch offline, add an offline copy with the `iwsdk-offline` skill before
|
|
86
|
+
packaging: one online launch then keeps the release on the device. Keep the
|
|
87
|
+
manifest's `start_url` and `scope` inside the service worker's scope.
|
|
88
|
+
|
|
89
|
+
Then confirm the app itself is sound before wrapping it — `npm run --if-present typecheck`,
|
|
90
|
+
and `npm run build` producing a `dist/` you have actually loaded. Packaging a
|
|
91
|
+
broken build wastes a full round trip through hosting, signing, and upload.
|
|
92
|
+
|
|
93
|
+
## Step 2 — Get it hosted
|
|
94
|
+
|
|
95
|
+
**Invoke the `iwsdk-hosting` skill.** It asks whether hosting already exists,
|
|
96
|
+
recommends and runs Vercel if not, and — if the developer already has a host —
|
|
97
|
+
pauses with concrete upload steps instead of guessing at their pipeline.
|
|
98
|
+
|
|
99
|
+
Come back with a `<DOMAIN>` that passes the hosting contract: root, manifest,
|
|
100
|
+
and icons all 200, manifest served as `application/manifest+json`. Asset links
|
|
101
|
+
are still expected to 404 at this point; they arrive in step 4.
|
|
102
|
+
|
|
103
|
+
Do not substitute a localhost tunnel or a preview URL. `bubblewrap` bakes the
|
|
104
|
+
host into the APK, and a URL that later 401s or disappears produces an app that
|
|
105
|
+
installs and then shows nothing.
|
|
106
|
+
|
|
107
|
+
## Step 3 — Manifest and icons
|
|
108
|
+
|
|
109
|
+
Both modes need a valid installable manifest plus PNG icons, live on `<DOMAIN>`
|
|
110
|
+
before `bubblewrap update` runs — it fetches them over the network.
|
|
111
|
+
|
|
112
|
+
`public/manifest.webmanifest`:
|
|
113
|
+
|
|
114
|
+
```json
|
|
115
|
+
{
|
|
116
|
+
"name": "…", "short_name": "…", "description": "…",
|
|
117
|
+
"start_url": "/", "scope": "/",
|
|
118
|
+
"display": "standalone", "orientation": "landscape",
|
|
119
|
+
"background_color": "#06010f", "theme_color": "#0a0418",
|
|
120
|
+
"icons": [
|
|
121
|
+
{ "src": "/icons/icon-192.png", "type": "image/png", "sizes": "192x192", "purpose": "any" },
|
|
122
|
+
{ "src": "/icons/icon-512.png", "type": "image/png", "sizes": "512x512", "purpose": "any" },
|
|
123
|
+
{ "src": "/icons/icon-512-maskable.png", "type": "image/png", "sizes": "512x512", "purpose": "maskable" }
|
|
124
|
+
]
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Generate icons with `sharp` (`npm i -D sharp`; the scaffold already pins a
|
|
129
|
+
working version). The maskable icon must be full-bleed and opaque. Full manifest
|
|
130
|
+
reference, the icon script, and subpath/multi-origin cases:
|
|
131
|
+
[`references/manifest-and-icons.md`](references/manifest-and-icons.md).
|
|
132
|
+
|
|
133
|
+
Rebuild and publish — via `iwsdk-hosting` again if the developer owns the host —
|
|
134
|
+
then verify the manifest and both icon URLs return 200 before continuing.
|
|
135
|
+
|
|
136
|
+
## Step 4 — Package the APK with bubblewrap
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
npm i -g @meta-quest/bubblewrap-cli # bin: bubblewrap, needs Node >= 18
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
First run downloads a JDK 17 and the Android SDK into `~/.bubblewrap` behind
|
|
143
|
+
**interactive prompts** (including an SDK licence confirmation). An agent cannot
|
|
144
|
+
answer those — have the developer run `bubblewrap doctor` once in a real
|
|
145
|
+
terminal, then continue. Everything after that is scriptable.
|
|
146
|
+
|
|
147
|
+
`bubblewrap init` is also an interactive wizard with no value flags to bypass
|
|
148
|
+
it, so **use the scripted path**: hand-write `twa-manifest.json`, then `update`
|
|
149
|
+
and `build`.
|
|
150
|
+
|
|
151
|
+
Four things happen here, in order:
|
|
152
|
+
|
|
153
|
+
1. **Choose the signing key — pause and ask.** The key is permanent: every
|
|
154
|
+
future update must reuse the same keystore, alias, and `packageId`, and a
|
|
155
|
+
published listing is already bound to one. Reuse an existing keystore, or
|
|
156
|
+
generate a new one outside the deployable web tree so it never ships.
|
|
157
|
+
2. **Write `twa-manifest.json`**, with `isMetaQuest: true` and the
|
|
158
|
+
`horizonOSAppMode` chosen in step 0.
|
|
159
|
+
3. **Build** — `bubblewrap update && bubblewrap build`, passwords passed through
|
|
160
|
+
`BUBBLEWRAP_KEYSTORE_PASSWORD` / `BUBBLEWRAP_KEY_PASSWORD` (there are no
|
|
161
|
+
password CLI flags).
|
|
162
|
+
4. **Publish `public/.well-known/assetlinks.json`** with the package name and
|
|
163
|
+
the certificate SHA-256. Until it is live on `<DOMAIN>`, the TWA will not
|
|
164
|
+
launch. This is the second hosting handoff — go back through `iwsdk-hosting`
|
|
165
|
+
and verify the URL yourself.
|
|
166
|
+
|
|
167
|
+
Commands, the full manifest template, keystore handling, and build verification:
|
|
168
|
+
[`references/bubblewrap.md`](references/bubblewrap.md).
|
|
169
|
+
|
|
170
|
+
Sideload and test on device before uploading — `adb install -r
|
|
171
|
+
app-release-signed.apk`, or the `metavr` MCP server that scaffolded projects
|
|
172
|
+
register. This is the only place the immersive auto-enter path can be verified.
|
|
173
|
+
|
|
174
|
+
## Step 5 — Upload to the Horizon Store
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
./ovr-platform-util upload-quest-build \
|
|
178
|
+
--app-id <HORIZON_APP_ID> --app-secret <SECRET> \
|
|
179
|
+
--apk app-release-signed.apk \
|
|
180
|
+
--channel ALPHA --age-group MIXED_AGES \
|
|
181
|
+
--notes "…" --disable-progress-bar
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Same command for both modes. Channels: `ALPHA`/`BETA`/`RC` for testing, `STORE`
|
|
185
|
+
for production. Auth is the app's App Secret or a user token — ask the
|
|
186
|
+
developer, never invent one, and never write it into a file under `public/`.
|
|
187
|
+
|
|
188
|
+
Expect the first upload to fail with *"must first agree to our Developer
|
|
189
|
+
Distribution Agreement"*. Only an org admin can sign it, so pause, ask, and
|
|
190
|
+
retry the identical command. Tool download, auth, and flag reference:
|
|
191
|
+
[`references/store-upload.md`](references/store-upload.md).
|
|
192
|
+
|
|
193
|
+
## Redeploy vs rebuild
|
|
194
|
+
|
|
195
|
+
| Change | Action |
|
|
196
|
+
| ------ | ------ |
|
|
197
|
+
| App logic, assets, styling, manifest text, icons, asset links | republish `<DOMAIN>`; installed TWA picks it up next launch |
|
|
198
|
+
| Package id, app name, launcher icon, version, **app mode**, signing | rebuild the APK and re-upload |
|
|
199
|
+
|
|
200
|
+
With an offline copy (`iwsdk-offline`), a republished release installs in the
|
|
201
|
+
background during a launch and takes over when the app is idle, or on the
|
|
202
|
+
launch after that.
|
|
203
|
+
|
|
204
|
+
## Security
|
|
205
|
+
|
|
206
|
+
The keystore and the app secret never go near `public/` or `dist/`. After every
|
|
207
|
+
publish, confirm the keystore is not being served:
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
curl -s -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/android.keystore # want 404
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Back up the keystore somewhere durable. Losing it means the app can never be
|
|
214
|
+
updated — only replaced by a new Store entry.
|
|
215
|
+
|
|
216
|
+
## Reference Files
|
|
217
|
+
|
|
218
|
+
| File | Load when |
|
|
219
|
+
| ---- | --------- |
|
|
220
|
+
| [`references/app-modes.md`](references/app-modes.md) | Step 0 — choosing immersive vs 2D, and what each implies |
|
|
221
|
+
| [`references/manifest-and-icons.md`](references/manifest-and-icons.md) | Step 3 — manifest fields, icon generation, subpath and multi-origin |
|
|
222
|
+
| [`references/bubblewrap.md`](references/bubblewrap.md) | Step 4 — prereqs, keystore, `twa-manifest.json`, build, asset links |
|
|
223
|
+
| [`references/store-upload.md`](references/store-upload.md) | Step 5 — `ovr-platform-util`, auth, channels, the DDA blocker |
|
|
224
|
+
| [`references/troubleshooting.md`](references/troubleshooting.md) | Anything installed but misbehaving — stuck loading, URL bar, will-not-launch |
|
|
225
|
+
|
|
226
|
+
Getting the app online is the `iwsdk-hosting` skill, and keeping it working
|
|
227
|
+
offline is `iwsdk-offline`. Building the app itself is
|
|
228
|
+
`iwsdk-planner` and the other `iwsdk-*` skills — do not re-derive IWSDK
|
|
229
|
+
patterns here.
|
|
230
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=2fbb9b9e9245162fa8cdb51e0a1396dde89b3d459ad5bcc29b45b92ade7a0022 name=iwsdk-pwa-packaging (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# App Modes: Immersive WebXR vs 2D Panel
|
|
2
|
+
|
|
3
|
+
The first decision in the pipeline and the one most likely to be wrong. It is
|
|
4
|
+
made once, and it changes exactly two things:
|
|
5
|
+
|
|
6
|
+
1. Whether the app auto-enters a WebXR session on launch (immersive only).
|
|
7
|
+
2. The `horizonOSAppMode` value in `twa-manifest.json`.
|
|
8
|
+
|
|
9
|
+
Everything else — hosting, manifest, icons, keystore, asset links, Store upload
|
|
10
|
+
— is identical for both.
|
|
11
|
+
|
|
12
|
+
| | **Immersive WebXR** | **2D panel** |
|
|
13
|
+
| --- | --- | --- |
|
|
14
|
+
| Runs as | full VR/WebXR session on launch | windowed 2D panel with its own Library entry |
|
|
15
|
+
| Typical app | IWSDK scene, game, spatial tool | dashboard, companion app, store front, any responsive site |
|
|
16
|
+
| Web app requirement | must support `immersive-vr` / `immersive-ar` | any responsive PWA; IWSDK not required |
|
|
17
|
+
| Auto-enter `requestSession` | **yes — built into the app** | **no — must not be added** |
|
|
18
|
+
| `horizonOSAppMode` | `"immersive"` | `"2D"` |
|
|
19
|
+
|
|
20
|
+
## Choosing
|
|
21
|
+
|
|
22
|
+
An IWSDK app scaffolded with `--mode vr` or `--mode ar` is immersive; that is
|
|
23
|
+
the whole point of the scaffold. Pick 2D only when the experience is genuinely a
|
|
24
|
+
flat panel — a companion or admin surface next to an immersive app, or a web
|
|
25
|
+
property being brought to the headset unchanged.
|
|
26
|
+
|
|
27
|
+
If the same origin should be both, that is two Store apps with two `packageId`s
|
|
28
|
+
sharing one `<DOMAIN>`. The asset-links file lists both packages.
|
|
29
|
+
|
|
30
|
+
## The classic failure
|
|
31
|
+
|
|
32
|
+
`horizonOSAppMode` is validated against `['immersive', '2D']` and **defaults to
|
|
33
|
+
`immersive`** when absent or misspelled — so a 2D app whose manifest omits the
|
|
34
|
+
field inherits the wrong mode silently.
|
|
35
|
+
|
|
36
|
+
| Symptom on device | Cause | Fix |
|
|
37
|
+
| ----------------- | ----- | --- |
|
|
38
|
+
| 2D app stuck on a loading screen | mode is `immersive`; Horizon waits for a session that never starts | set `"2D"`, `bubblewrap update && bubblewrap build`, re-upload |
|
|
39
|
+
| Immersive app opens showing a browser URL bar | mode is `2D` | set `"immersive"`, rebuild, re-upload |
|
|
40
|
+
| Immersive app opens flat with no URL bar | mode is right, auto-enter code is missing or never fires | add/repair the auto-enter block, republish `<DOMAIN>` — no rebuild needed |
|
|
41
|
+
|
|
42
|
+
The third row is worth internalizing: a missing session call is a **web** bug,
|
|
43
|
+
fixed by a redeploy. A wrong mode is a **native** bug, fixed only by a new APK.
|
|
44
|
+
Check the mode in the built APK before blaming the app code:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
"$BT/aapt" dump badging app-release-signed.apk | grep -iE 'package:|APP_MODE|OCULUS'
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Auto-enter, in detail (immersive only)
|
|
51
|
+
|
|
52
|
+
An installed immersive PWA has no 2D page and no button to press. Horizon
|
|
53
|
+
launches it straight into a headset context, so if the app waits for a click it
|
|
54
|
+
waits forever. The app-icon tap counts as the user activation that
|
|
55
|
+
`requestSession` requires — but only if the app spends it immediately on load.
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
const nav = navigator as Navigator & {
|
|
59
|
+
xr?: { isSessionSupported?: (m: string) => Promise<boolean> };
|
|
60
|
+
};
|
|
61
|
+
if ('getDigitalGoodsService' in window && nav.xr?.isSessionSupported) {
|
|
62
|
+
nav.xr
|
|
63
|
+
.isSessionSupported('immersive-vr') // 'immersive-ar' for an AR app
|
|
64
|
+
.then((supported) => {
|
|
65
|
+
if (supported) world.launchXR();
|
|
66
|
+
})
|
|
67
|
+
.catch(() => {});
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Three things this code is doing deliberately:
|
|
72
|
+
|
|
73
|
+
- **`getDigitalGoodsService` as the install gate.** It is present in an
|
|
74
|
+
installed PWA and absent in a browser tab, so the same build keeps its normal
|
|
75
|
+
Enter-XR button on desktop and in IWER while auto-entering on device. Feature-
|
|
76
|
+
detecting the headset any other way (user agent, screen size) misfires.
|
|
77
|
+
- **`isSessionSupported` before `launchXR`.** Calling into an unsupported mode
|
|
78
|
+
throws and leaves the app on a black screen with nothing in the console.
|
|
79
|
+
- **`world.launchXR()`, not `navigator.xr.requestSession`.** `launchXR` is
|
|
80
|
+
IWSDK's session request plus the renderer, reference-space, and input wiring
|
|
81
|
+
that the world needs. A raw `requestSession` gets a session the world does not
|
|
82
|
+
know about.
|
|
83
|
+
|
|
84
|
+
Match the session mode to `iwsdk.config.json` — `world.xr.mode: "ar"` means
|
|
85
|
+
`isSessionSupported('immersive-ar')`. Querying the wrong mode returns `false`
|
|
86
|
+
and the app silently stays flat.
|
|
87
|
+
|
|
88
|
+
Because `getDigitalGoodsService` is device-only, this branch never runs on a
|
|
89
|
+
development machine. It can only be verified by sideloading the APK and
|
|
90
|
+
launching from the Library.
|
|
91
|
+
|
|
92
|
+
## 2D panel notes
|
|
93
|
+
|
|
94
|
+
A 2D app runs as a single-instance standalone panel. There is no tab or
|
|
95
|
+
navigation bar by default; `theme_color` / `theme_color_dark` in the web
|
|
96
|
+
manifest color the custom tab bar when one is shown. Cookies and storage are
|
|
97
|
+
shared with the Quest Browser.
|
|
98
|
+
|
|
99
|
+
Out-of-scope links open inside the panel unless targeted at a new tab or window.
|
|
100
|
+
If the app legitimately spans origins, add `additional_trusted_origins` to the
|
|
101
|
+
web manifest and host `/.well-known/assetlinks.json` on **every** listed origin
|
|
102
|
+
— a missing one silently drops that origin out of scope mid-session.
|
|
103
|
+
|
|
104
|
+
Do not add the auto-enter block to a 2D app under any circumstances.
|