@iwsdk/create 1.2.0-rc.1 → 1.2.0-rc.2
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 +1 -0
- package/dist/cli.js +121 -9
- package/dist/guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +1 -1
- package/dist/guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +1 -1
- package/dist/guidance/files/.agents/skills/iwsdk-debug/SKILL.md +1 -1
- package/dist/guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
- package/dist/guidance/files/.agents/skills/iwsdk-dev/SKILL.md +20 -1
- package/dist/guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +1 -1
- package/dist/guidance/files/.agents/skills/iwsdk-grab/SKILL.md +1 -1
- package/dist/guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +1 -1
- package/dist/guidance/files/.agents/skills/iwsdk-metavr-native/SKILL.md +216 -0
- package/dist/guidance/files/.agents/skills/iwsdk-metavr-native/assets/iwn-host.mjs +71 -0
- package/dist/guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +1 -1
- package/dist/guidance/files/.agents/skills/iwsdk-offline/SKILL.md +1 -1
- package/dist/guidance/files/.agents/skills/iwsdk-physics/SKILL.md +1 -1
- package/dist/guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +6 -2
- package/dist/guidance/files/.agents/skills/iwsdk-ray/SKILL.md +1 -1
- package/dist/guidance/files/.agents/skills/iwsdk-ui/SKILL.md +1 -1
- package/dist/guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +1 -1
- package/dist/guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +1 -1
- package/dist/guidance/files/.claude/rules/assets-and-manifest.md +1 -1
- package/dist/guidance/files/.claude/rules/ecs-api.md +1 -1
- package/dist/guidance/files/.claude/rules/scene-json.md +1 -1
- package/dist/guidance/files/.claude/rules/uikitml.md +1 -1
- package/dist/guidance/files/.claude/settings.json +1 -0
- package/dist/guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +1 -1
- package/dist/guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +1 -1
- package/dist/guidance/files/.claude/skills/iwsdk-debug/SKILL.md +1 -1
- package/dist/guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
- package/dist/guidance/files/.claude/skills/iwsdk-dev/SKILL.md +20 -1
- package/dist/guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -1
- package/dist/guidance/files/.claude/skills/iwsdk-grab/SKILL.md +1 -1
- package/dist/guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +1 -1
- package/dist/guidance/files/.claude/skills/iwsdk-metavr-native/SKILL.md +216 -0
- package/dist/guidance/files/.claude/skills/iwsdk-metavr-native/assets/iwn-host.mjs +71 -0
- package/dist/guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +1 -1
- package/dist/guidance/files/.claude/skills/iwsdk-offline/SKILL.md +1 -1
- package/dist/guidance/files/.claude/skills/iwsdk-physics/SKILL.md +1 -1
- package/dist/guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +6 -2
- package/dist/guidance/files/.claude/skills/iwsdk-ray/SKILL.md +1 -1
- package/dist/guidance/files/.claude/skills/iwsdk-ui/SKILL.md +1 -1
- package/dist/guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +1 -1
- package/dist/guidance/files/.cursor/rules/assets-and-manifest.mdc +1 -1
- package/dist/guidance/files/.cursor/rules/ecs-api.mdc +1 -1
- package/dist/guidance/files/.cursor/rules/scene-json.mdc +1 -1
- package/dist/guidance/files/.cursor/rules/uikitml.mdc +1 -1
- package/dist/guidance/files/.github/instructions/assets-and-manifest.instructions.md +1 -1
- package/dist/guidance/files/.github/instructions/ecs-api.instructions.md +1 -1
- package/dist/guidance/files/.github/instructions/scene-json.instructions.md +1 -1
- package/dist/guidance/files/.github/instructions/uikitml.instructions.md +1 -1
- package/dist/guidance/files/AGENTS.md +10 -1
- package/dist/guidance/files/public/scenes/AGENTS.md +1 -1
- package/dist/guidance/files/public/ui/AGENTS.md +1 -1
- package/dist/guidance/files/src/AGENTS.md +1 -1
- package/dist/guidance/manifest.json +36 -6
- package/dist/template/scenes/ar.iwsdk.scene.json +1 -0
- package/dist/template/scenes/immersive.iwsdk.scene.json +1 -0
- package/package.json +4 -4
- package/scripts/verify-release-ready.mjs +2 -2
package/README.md
CHANGED
|
@@ -182,6 +182,7 @@ the interactive setup controls language, features, Git, and installation.
|
|
|
182
182
|
| `--git` / `--no-git` | Initialize or skip a Git repository |
|
|
183
183
|
| `--canary` | Use the default canary SDK bundle |
|
|
184
184
|
| `--canary URL` | Use a custom HTTP(S) SDK bundle |
|
|
185
|
+
| `--metavr-native` | Alpha, VR or AR: add `npm run build:metavr`, a native Quest APK built with `@iwer/native` |
|
|
185
186
|
|
|
186
187
|
Automation and coding agents should map the requested experience to a target
|
|
187
188
|
and high-level feature flags before invoking Create, then pass those choices
|
package/dist/cli.js
CHANGED
|
@@ -20911,6 +20911,8 @@ const VITE_CONFIG_NAMES = [
|
|
|
20911
20911
|
const VITE_PEER_RANGE = '^7.0.0';
|
|
20912
20912
|
const SKELETON_DIRECTORY = 'src/iwsdk';
|
|
20913
20913
|
/** IWSDK's own .gitignore entries: runtime state and generated MCP configs. */
|
|
20914
|
+
/** Added with --metavr-native: native APK builds (npm run build:metavr). */
|
|
20915
|
+
const NATIVE_GITIGNORE_ENTRY = 'dist-metavr/';
|
|
20914
20916
|
const GITIGNORE_ENTRIES = [
|
|
20915
20917
|
'.iwsdk/',
|
|
20916
20918
|
'.mcp.json',
|
|
@@ -21494,6 +21496,13 @@ async function adoptExistingProject({ outDir, files, guidanceRoot, language, loc
|
|
|
21494
21496
|
if (existingViteConfig != null && !pluginFound) {
|
|
21495
21497
|
manualSteps.push(`If the app renders UIKitML panels, also dedupe \`three\` and the \`@pmndrs/uikit*\` packages in ${pluginConfig} (\`resolve.dedupe\`, \`optimizeDeps.include\`), as the IWSDK starter's Vite config does.`);
|
|
21496
21498
|
}
|
|
21499
|
+
const plannedManifestFile = files.find((file) => file.path === 'iwsdk.config.json');
|
|
21500
|
+
const plannedNative = plannedManifestFile
|
|
21501
|
+
? JSON.parse(textContents(plannedManifestFile)).native
|
|
21502
|
+
: undefined;
|
|
21503
|
+
const gitignoreEntries = plannedNative === undefined
|
|
21504
|
+
? GITIGNORE_ENTRIES
|
|
21505
|
+
: [...GITIGNORE_ENTRIES, NATIVE_GITIGNORE_ENTRY];
|
|
21497
21506
|
const gitignoreAdded = [];
|
|
21498
21507
|
if ((await writeTarget(outDir, '.gitignore')) !== 'blocked') {
|
|
21499
21508
|
const gitignorePath = path$5.join(outDir, '.gitignore');
|
|
@@ -21501,7 +21510,7 @@ async function adoptExistingProject({ outDir, files, guidanceRoot, language, loc
|
|
|
21501
21510
|
? await fsp.readFile(gitignorePath, 'utf8')
|
|
21502
21511
|
: '';
|
|
21503
21512
|
const present = new Set(current.split(/\r?\n/u).map((line) => line.trim()));
|
|
21504
|
-
gitignoreAdded.push(...
|
|
21513
|
+
gitignoreAdded.push(...gitignoreEntries.filter((line) => !present.has(line)));
|
|
21505
21514
|
if (gitignoreAdded.length > 0) {
|
|
21506
21515
|
const eol = current.includes('\r\n') ? '\r\n' : '\n';
|
|
21507
21516
|
await fsp.writeFile(gitignorePath, `${current}${current && !/\r?\n$/u.test(current) ? eol : ''}${current ? eol : ''}# IWSDK${eol}${gitignoreAdded.join(eol)}${eol}`);
|
|
@@ -21539,6 +21548,13 @@ async function adoptExistingProject({ outDir, files, guidanceRoot, language, loc
|
|
|
21539
21548
|
manualSteps.push(`Locomotion is on in iwsdk.config.json, but ${path$5.relative(outDir, sceneFile).split(path$5.sep).join('/')} has no \`LocomotionEnvironment\`: add it to the floor the player walks on, or set \`world.features.locomotion\` to \`false\`. Otherwise the player falls through the world.`);
|
|
21540
21549
|
}
|
|
21541
21550
|
}
|
|
21551
|
+
// --metavr-native over a project that already has iwsdk.config.json: the
|
|
21552
|
+
// manifest is kept, so build:metavr would stop at "no native section".
|
|
21553
|
+
if (plannedNative !== undefined &&
|
|
21554
|
+
isRecord$1(manifest) &&
|
|
21555
|
+
manifest.native === undefined) {
|
|
21556
|
+
manualSteps.push(`Add the native build target to iwsdk.config.json (your file was kept): \`"native": ${JSON.stringify(plannedNative)}\`. Replace the com.example package id before a store build. Until then \`npm run build:metavr\` stops at "no native section".`);
|
|
21557
|
+
}
|
|
21542
21558
|
const locomotionOff = created.includes('iwsdk.config.json') &&
|
|
21543
21559
|
created.some((file) => file.endsWith('.iwsdk.scene.json')) &&
|
|
21544
21560
|
!locomotion &&
|
|
@@ -22484,7 +22500,7 @@ crossSpawn.exports._enoent = enoent;
|
|
|
22484
22500
|
* LICENSE file in the root directory of this source tree.
|
|
22485
22501
|
*/
|
|
22486
22502
|
const BASE_OVERRIDES = {
|
|
22487
|
-
sharp: '0.35.
|
|
22503
|
+
sharp: '0.35.5',
|
|
22488
22504
|
three: 'npm:super-three@0.185.0',
|
|
22489
22505
|
};
|
|
22490
22506
|
const ONLY_BUILT_DEPENDENCIES = ['esbuild', 'protobufjs', 'sharp'];
|
|
@@ -22683,7 +22699,7 @@ function printMetavrNotice() {
|
|
|
22683
22699
|
console.log(`\n metavr collects essential usage data, as described in the Meta Platform Technologies SDK License (${MPT_SDK_LICENSE_URL}). If you don't want to use metavr, uninstall it from your project:`);
|
|
22684
22700
|
console.log(stdoutColor.gray(' npm uninstall @meta-quest/metavr'));
|
|
22685
22701
|
}
|
|
22686
|
-
function printNextSteps(appName, installed, actionItems = [], inPlace = false, xrEnabled = true) {
|
|
22702
|
+
function printNextSteps(appName, installed, actionItems = [], inPlace = false, xrEnabled = true, nativeAlpha = false) {
|
|
22687
22703
|
const startCmd = 'npm run dev';
|
|
22688
22704
|
printMetavrNotice();
|
|
22689
22705
|
console.log('\nNext steps:');
|
|
@@ -22713,6 +22729,12 @@ function printNextSteps(appName, installed, actionItems = [], inPlace = false, x
|
|
|
22713
22729
|
if (xrEnabled) {
|
|
22714
22730
|
console.log(stdoutColor.gray(` IWER controls: ${IWER_CONTROLS_URL}`));
|
|
22715
22731
|
}
|
|
22732
|
+
if (nativeAlpha) {
|
|
22733
|
+
console.log('\nNative Quest build (alpha):');
|
|
22734
|
+
console.log(stdoutColor.gray(' npx iwer-native doctor # adb, headset, native config'));
|
|
22735
|
+
console.log(stdoutColor.gray(' npm run build:metavr # writes dist-metavr/<appName>.apk'));
|
|
22736
|
+
console.log(stdoutColor.gray(' npx iwer-native install && npx iwer-native run'));
|
|
22737
|
+
}
|
|
22716
22738
|
}
|
|
22717
22739
|
function printPrerequisites(prereqs = []) {
|
|
22718
22740
|
if (!prereqs.length) {
|
|
@@ -22750,6 +22772,75 @@ function printPrerequisites(prereqs = []) {
|
|
|
22750
22772
|
}
|
|
22751
22773
|
}
|
|
22752
22774
|
|
|
22775
|
+
/**
|
|
22776
|
+
* Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
22777
|
+
*
|
|
22778
|
+
* This source code is licensed under the MIT license found in the
|
|
22779
|
+
* LICENSE file in the root directory of this source tree.
|
|
22780
|
+
*/
|
|
22781
|
+
/**
|
|
22782
|
+
* Alpha: `--metavr-native` (or IWSDK_CREATE_METAVR_NATIVE=1) adds the native
|
|
22783
|
+
* Quest build to a new VR or AR project. `npm run build:metavr` builds with Vite in
|
|
22784
|
+
* the `metavr` mode (the dev plugin then leaves the IWER emulator out) and packs
|
|
22785
|
+
* dist/ into dist-metavr/<appName>.apk with @iwer/native, which runs the app
|
|
22786
|
+
* without a browser. Off by default while @iwer/native is an alpha.
|
|
22787
|
+
*/
|
|
22788
|
+
const NATIVE_ALPHA_FLAG = '--metavr-native';
|
|
22789
|
+
const NATIVE_ALPHA_ENV = 'IWSDK_CREATE_METAVR_NATIVE';
|
|
22790
|
+
/** Pinned exactly: experimental releases may change commands and config keys. */
|
|
22791
|
+
const IWER_NATIVE_ALPHA_VERSION = '2.9.0';
|
|
22792
|
+
const BUILD_METAVR_SCRIPT = 'vite build --mode metavr && iwer-native pack';
|
|
22793
|
+
const NATIVE_ALPHA_GITIGNORE = '\n# Native Quest builds (npm run build:metavr)\ndist-metavr/\n';
|
|
22794
|
+
function nativeAlphaRequested(args, env = process.env) {
|
|
22795
|
+
return (args.includes(NATIVE_ALPHA_FLAG) ||
|
|
22796
|
+
env[NATIVE_ALPHA_ENV] === '1' ||
|
|
22797
|
+
env[NATIVE_ALPHA_ENV] === 'true');
|
|
22798
|
+
}
|
|
22799
|
+
/**
|
|
22800
|
+
* The native runtime runs immersive sessions only: immersive-vr, and
|
|
22801
|
+
* immersive-ar over passthrough, which pack declares from world.xr.mode "ar".
|
|
22802
|
+
* It has no 2D page, so the Desktop 3D starting point cannot be packed.
|
|
22803
|
+
*/
|
|
22804
|
+
function validateNativeAlphaTarget(target) {
|
|
22805
|
+
if (target !== 'vr' && target !== 'ar') {
|
|
22806
|
+
throw new Error(`${NATIVE_ALPHA_FLAG} is available for --target vr or ar only (the @iwer/native alpha runs immersive sessions, with no 2D page; got ${target}).`);
|
|
22807
|
+
}
|
|
22808
|
+
}
|
|
22809
|
+
// aapt2 rejects package segments that are Java keywords or literals.
|
|
22810
|
+
const JAVA_KEYWORDS = new Set('abstract assert boolean break byte case catch char class const continue default do double else enum extends final finally float for goto if implements import instanceof int interface long native new package private protected public return short static strictfp super switch synchronized this throw throws transient try void volatile while true false null _'.split(' '));
|
|
22811
|
+
/** Android application id from the project name: com.example.<name>, which the packer flags as a placeholder. */
|
|
22812
|
+
function nativePackageId(appName) {
|
|
22813
|
+
let segment = appName
|
|
22814
|
+
.replace(/^@[^/]+\//, '')
|
|
22815
|
+
.toLowerCase()
|
|
22816
|
+
.replace(/[^a-z0-9_]+/g, '_')
|
|
22817
|
+
.replace(/^_+|_+$/g, '');
|
|
22818
|
+
if (!/^[a-z]/.test(segment)) {
|
|
22819
|
+
segment = `app${segment ? `_${segment}` : ''}`;
|
|
22820
|
+
}
|
|
22821
|
+
if (JAVA_KEYWORDS.has(segment)) {
|
|
22822
|
+
segment = `${segment}_app`;
|
|
22823
|
+
}
|
|
22824
|
+
return `com.example.${segment}`;
|
|
22825
|
+
}
|
|
22826
|
+
/**
|
|
22827
|
+
* Origins the starter fetches from at run time. The native runtime refuses
|
|
22828
|
+
* every origin outside native.network.allow; the starter loads its controller
|
|
22829
|
+
* models from the WebXR input profiles on jsDelivr (@iwsdk/xr-input
|
|
22830
|
+
* DEFAULT_PROFILES_PATH), so without this entry controllers have no model.
|
|
22831
|
+
*/
|
|
22832
|
+
const NATIVE_ALPHA_NETWORK_ALLOW = [
|
|
22833
|
+
'https://cdn.jsdelivr.net',
|
|
22834
|
+
];
|
|
22835
|
+
/** The `native` section of iwsdk.config.json (validated by @iwer/native). */
|
|
22836
|
+
function createNativeTargetSection(appName) {
|
|
22837
|
+
return {
|
|
22838
|
+
packageId: nativePackageId(appName),
|
|
22839
|
+
appName: appName.replace(/^@[^/]+\//, ''),
|
|
22840
|
+
network: { allow: [...NATIVE_ALPHA_NETWORK_ALLOW] },
|
|
22841
|
+
};
|
|
22842
|
+
}
|
|
22843
|
+
|
|
22753
22844
|
/**
|
|
22754
22845
|
* Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
22755
22846
|
*
|
|
@@ -22820,7 +22911,7 @@ function createProjectManifest(configuration) {
|
|
|
22820
22911
|
};
|
|
22821
22912
|
}
|
|
22822
22913
|
|
|
22823
|
-
const VERSION = "1.2.0-rc.
|
|
22914
|
+
const VERSION = "1.2.0-rc.2";
|
|
22824
22915
|
const NODE_ENGINE = ">=20.19.0 <21.0.0-0 || >=22.12.0 <23.0.0-0 || >=24.0.0";
|
|
22825
22916
|
|
|
22826
22917
|
/**
|
|
@@ -22841,14 +22932,24 @@ async function buildStarterProjectFiles({ appName, configuration, language, pack
|
|
|
22841
22932
|
path: 'public/scenes/main.iwsdk.scene.json',
|
|
22842
22933
|
contents: await readFile$1(sceneSource),
|
|
22843
22934
|
});
|
|
22935
|
+
const manifest = createProjectManifest(configuration);
|
|
22936
|
+
if (configuration.nativeAlpha) {
|
|
22937
|
+
manifest.native = createNativeTargetSection(appName);
|
|
22938
|
+
}
|
|
22844
22939
|
files.push({
|
|
22845
22940
|
path: 'iwsdk.config.json',
|
|
22846
|
-
contents: `${JSON.stringify(
|
|
22941
|
+
contents: `${JSON.stringify(manifest, null, 2)}\n`,
|
|
22847
22942
|
});
|
|
22848
22943
|
files.push({
|
|
22849
22944
|
path: 'package.json',
|
|
22850
|
-
contents: `${JSON.stringify(createProjectPackageJson(appName, language, packageSource), null, 2)}\n`,
|
|
22945
|
+
contents: `${JSON.stringify(createProjectPackageJson(appName, language, packageSource, configuration.nativeAlpha === true), null, 2)}\n`,
|
|
22851
22946
|
});
|
|
22947
|
+
if (configuration.nativeAlpha) {
|
|
22948
|
+
const gitignore = files.find((file) => file.path === '.gitignore');
|
|
22949
|
+
if (gitignore != null && typeof gitignore.contents === 'string') {
|
|
22950
|
+
gitignore.contents = `${gitignore.contents.trimEnd()}\n${NATIVE_ALPHA_GITIGNORE}`;
|
|
22951
|
+
}
|
|
22952
|
+
}
|
|
22852
22953
|
files.push({
|
|
22853
22954
|
path: 'pnpm-workspace.yaml',
|
|
22854
22955
|
contents: createPnpmWorkspaceYaml(),
|
|
@@ -22859,7 +22960,7 @@ async function buildStarterProjectFiles({ appName, configuration, language, pack
|
|
|
22859
22960
|
}
|
|
22860
22961
|
return files.sort((left, right) => left.path.localeCompare(right.path));
|
|
22861
22962
|
}
|
|
22862
|
-
function createProjectPackageJson(appName, language, source) {
|
|
22963
|
+
function createProjectPackageJson(appName, language, source, nativeAlpha = false) {
|
|
22863
22964
|
const packageSpec = (name) => source.getPackageInstallSpec(name) ?? VERSION;
|
|
22864
22965
|
return {
|
|
22865
22966
|
name: appName,
|
|
@@ -22874,6 +22975,7 @@ function createProjectPackageJson(appName, language, source) {
|
|
|
22874
22975
|
'reference:status': 'iwsdk reference status',
|
|
22875
22976
|
...(language === 'ts' ? { typecheck: 'tsc --noEmit' } : {}),
|
|
22876
22977
|
build: 'vite build',
|
|
22978
|
+
...(nativeAlpha ? { 'build:metavr': BUILD_METAVR_SCRIPT } : {}),
|
|
22877
22979
|
preview: 'vite preview',
|
|
22878
22980
|
},
|
|
22879
22981
|
dependencies: {
|
|
@@ -22889,6 +22991,7 @@ function createProjectPackageJson(appName, language, source) {
|
|
|
22889
22991
|
'@iwsdk/reference': packageSpec('@iwsdk/reference'),
|
|
22890
22992
|
'@iwsdk/cli': packageSpec('@iwsdk/cli'),
|
|
22891
22993
|
'@iwsdk/vite-plugin-dev': packageSpec('@iwsdk/vite-plugin-dev'),
|
|
22994
|
+
...(nativeAlpha ? { '@iwer/native': IWER_NATIVE_ALPHA_VERSION } : {}),
|
|
22892
22995
|
'@meta-quest/metavr': '^1.8.1',
|
|
22893
22996
|
...(language === 'ts'
|
|
22894
22997
|
? { '@types/three': '^0.185.0', typescript: '^5.5.0' }
|
|
@@ -22896,7 +22999,7 @@ function createProjectPackageJson(appName, language, source) {
|
|
|
22896
22999
|
vite: '^7.1.4',
|
|
22897
23000
|
},
|
|
22898
23001
|
overrides: {
|
|
22899
|
-
sharp: '0.35.
|
|
23002
|
+
sharp: '0.35.5',
|
|
22900
23003
|
three: 'npm:super-three@0.185.0',
|
|
22901
23004
|
},
|
|
22902
23005
|
engines: {
|
|
@@ -29940,6 +30043,7 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
|
|
|
29940
30043
|
.option('--no-scene-understanding', 'Disable scene understanding')
|
|
29941
30044
|
.option('--environment-raycast', 'Enable environment raycast (AR mode)')
|
|
29942
30045
|
.option('--no-environment-raycast', 'Disable environment raycast')
|
|
30046
|
+
.option(NATIVE_ALPHA_FLAG, '(alpha) Add npm run build:metavr: a native Quest APK built with @iwer/native (VR or AR)')
|
|
29943
30047
|
.option('--skip-reference-warmup', 'No effect; kept for older scripts (@iwsdk/reference bundles its corpus)')
|
|
29944
30048
|
.action((n, opts) => {
|
|
29945
30049
|
nameArg = n;
|
|
@@ -30078,7 +30182,14 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
|
|
|
30078
30182
|
locomotionEnabled: false,
|
|
30079
30183
|
}));
|
|
30080
30184
|
}
|
|
30185
|
+
const nativeAlpha = nativeAlphaRequested(process.argv.slice(2));
|
|
30186
|
+
if (nativeAlpha) {
|
|
30187
|
+
validateNativeAlphaTarget(res.target);
|
|
30188
|
+
}
|
|
30081
30189
|
printConfigurationSummary(res, adopting);
|
|
30190
|
+
if (nativeAlpha) {
|
|
30191
|
+
console.log(` Native Quest build: npm run build:metavr (alpha, @iwer/native)`);
|
|
30192
|
+
}
|
|
30082
30193
|
const source = resolveSource(cliOpts.canary);
|
|
30083
30194
|
// Prepare source (downloads tgz files for remote bundles)
|
|
30084
30195
|
if (source.isBundleMode) {
|
|
@@ -30111,6 +30222,7 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
|
|
|
30111
30222
|
mode: res.mode,
|
|
30112
30223
|
featureFlags: res.featureFlags,
|
|
30113
30224
|
xrFeatureStates: res.xrFeatureStates,
|
|
30225
|
+
nativeAlpha,
|
|
30114
30226
|
};
|
|
30115
30227
|
const outDir = projectTarget.outDir;
|
|
30116
30228
|
const projectFiles = await buildStarterProjectFiles({
|
|
@@ -30185,7 +30297,7 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
|
|
|
30185
30297
|
const prereqs = [...(res.prerequisites || [])];
|
|
30186
30298
|
// Print prerequisites first, then next steps
|
|
30187
30299
|
printPrerequisites(prereqs);
|
|
30188
|
-
printNextSteps(projectTarget.displayPath, res.installNow, res.actionItems || [], projectTarget.inPlace, res.xrEnabled);
|
|
30300
|
+
printNextSteps(projectTarget.displayPath, res.installNow, res.actionItems || [], projectTarget.inPlace, res.xrEnabled, nativeAlpha);
|
|
30189
30301
|
}
|
|
30190
30302
|
finally {
|
|
30191
30303
|
await source.cleanup();
|
|
@@ -309,4 +309,4 @@ Hand `iwsdk-compose-scene`:
|
|
|
309
309
|
|
|
310
310
|
Do not compensate for a model-local defect with a scene transform. Do not start scene
|
|
311
311
|
lighting or camera iteration until the model passes isolated review.
|
|
312
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
312
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=95fc72ddf1f3915aa71a839558a3ce051b803214b25ad8c594e882068a3d7917 name=iwsdk-build-model (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -274,4 +274,4 @@ components, schema errors, image reconstruction, or ambiguous composition eviden
|
|
|
274
274
|
When the Fast Path does not apply, read and follow
|
|
275
275
|
[extended-workflow.md](references/extended-workflow.md). Do not load that reference
|
|
276
276
|
for a routine scene assembled from known manifest assets.
|
|
277
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
277
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=e6feb83023b2ddbe9a3cceea3b0deda0fe8beb9743d4af6b8e0a89ea31e61b93 name=iwsdk-compose-scene (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -71,4 +71,4 @@ established from the measured state.
|
|
|
71
71
|
Make at most one focused correction. Stop when the original symptom no longer
|
|
72
72
|
reproduces and the measured state agrees with the intended behavior. Call
|
|
73
73
|
`ecs_resume` before finishing and leave input buttons released.
|
|
74
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
74
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=7dd8250ca95e23b6f0696a86a3dfcb2d038ac730a7578118fb21290c6169c3f0 name=iwsdk-debug (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -85,4 +85,4 @@ not alter the project camera or render extra authored angles to manufacture an
|
|
|
85
85
|
occlusion view; stage the requested nodes once, then judge the live AR capture.
|
|
86
86
|
Do not inspect framework source when the build, registered-system query, entity
|
|
87
87
|
components, and console warnings already establish the failing layer.
|
|
88
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
88
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=819e3f213766f12b567fa8ffd5e343f1a17f83973642067d82ebd7c5dee1dbe3 name=iwsdk-depth-occlusion (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -31,6 +31,25 @@ Observable workspace state wins over wording:
|
|
|
31
31
|
already exist;
|
|
32
32
|
- explicit user selection of a child route overrides automatic routing.
|
|
33
33
|
|
|
34
|
+
## Distribution requests
|
|
35
|
+
|
|
36
|
+
A request that only ships an existing app — hosting it, packaging it for
|
|
37
|
+
Quest or the Horizon Store, making it work offline, or building, installing
|
|
38
|
+
and debugging a native `@iwer/native` APK — takes neither playbook. Invoke
|
|
39
|
+
the owning skill directly and let it own the task:
|
|
40
|
+
|
|
41
|
+
| Request | Skill |
|
|
42
|
+
| --------------------------------------------------------------------------------- | --------------------- |
|
|
43
|
+
| Put the app on a public HTTPS origin | `iwsdk-hosting` |
|
|
44
|
+
| Installable PWA, or a TWA APK of the hosted site, Store upload | `iwsdk-pwa-packaging` |
|
|
45
|
+
| Work with no connection after one visit | `iwsdk-offline` |
|
|
46
|
+
| Standalone APK with no browser (`build:metavr`, `native` section, `dist-metavr/`) | `iwsdk-metavr-native` |
|
|
47
|
+
|
|
48
|
+
"Make an APK" alone could mean either the TWA or the native APK; ask which,
|
|
49
|
+
using the comparison in `iwsdk-metavr-native` step 0. A request that changes
|
|
50
|
+
the experience and then ships it routes to a playbook first; invoke the
|
|
51
|
+
distribution skill after the playbook's work is verified.
|
|
52
|
+
|
|
34
53
|
## Internal handoff
|
|
35
54
|
|
|
36
55
|
1. State the selected route in one sentence.
|
|
@@ -43,4 +62,4 @@ Observable workspace state wins over wording:
|
|
|
43
62
|
|
|
44
63
|
iwsdk-dev does not add another implementation phase. The selected playbook owns
|
|
45
64
|
the work, evidence budget, specialist routing, verification, and stopping rule.
|
|
46
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
65
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=f21471a15775b322906d8b1431a149aab73ac6d34acfef6cc05159f7a9d005fb name=iwsdk-dev (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -279,4 +279,4 @@ synthetic `fov: 90`. Keep using step 3 for framing.
|
|
|
279
279
|
- `[iwsdk][gaze]` console lines and other errors;
|
|
280
280
|
- for a headset run, its serial, which Quest mode was used, and whether the
|
|
281
281
|
page was paired.
|
|
282
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
282
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=86e1e324dd71e8dd832b5d446e6bdc03bb5150cf5128c0650838cf6227b79817 name=iwsdk-glasses-test (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -72,4 +72,4 @@ to model context does not satisfy a requested file deliverable.
|
|
|
72
72
|
|
|
73
73
|
Stop once the requested grab/move/release path and final state are proven. Leave
|
|
74
74
|
the controller released and the XR session in the state the user requested.
|
|
75
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
75
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=ad099acb82205620cb9cce44f245f40baf7e6808038d7d94ff9d873f316473d2 name=iwsdk-grab (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -176,4 +176,4 @@ trip:
|
|
|
176
176
|
Packaging the hosted app into a signed Quest APK is the `iwsdk-pwa-packaging`
|
|
177
177
|
skill, and keeping an offline copy on the device — with the `sw.js` cache
|
|
178
178
|
headers that copy needs — is `iwsdk-offline`. This skill only gets it online.
|
|
179
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
179
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=360be8c5297e0b33bdbdf82188b95dbbcfc586b00d0c0840a21094eb9745e21d name=iwsdk-hosting (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-metavr-native
|
|
3
|
+
description: Build, install, run and debug an IWSDK VR or AR app as a standalone Quest APK with @iwer/native (alpha), which runs the app's own JavaScript on the headset without Quest Browser. Use when the project has a `native` section in iwsdk.config.json or a `build:metavr` script, when the user asks for a native or browserless Quest build, or when a dist-metavr APK fails to pack, launch, enter XR or fetch. Not for PWA/TWA store packaging of a hosted site (iwsdk-pwa-packaging) or for driving Quest Browser over ADB (iwsdk-native-xr-test).
|
|
4
|
+
argument-hint: '[goal, e.g. "add a native build", "the APK shows black"]'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Native Quest APK (@iwer/native, alpha)
|
|
8
|
+
|
|
9
|
+
`npm run build:metavr` runs `vite build --mode metavr && iwer-native pack`.
|
|
10
|
+
The Vite step is a normal production build without the IWER emulator, and with
|
|
11
|
+
the `native` section of `iwsdk.config.json` left out of the bundle. `pack` puts
|
|
12
|
+
`dist/` into a template APK that carries the @iwer/native runtime (V8, WebGL 2
|
|
13
|
+
over OpenGL ES, fetch, Web Audio, workers, a DOM stand-in, WebXR over OpenXR)
|
|
14
|
+
and signs it in Node. The result, `dist-metavr/<appName>.apk`, runs on the
|
|
15
|
+
headset with no browser and no server: app files load from the APK.
|
|
16
|
+
|
|
17
|
+
User request is in `$ARGUMENTS`.
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
0. Pick the route → native APK, or PWA/TWA (iwsdk-pwa-packaging)
|
|
21
|
+
1. Set up → IWSDK ≥ 1.2, @iwer/native, native section
|
|
22
|
+
2. Fit the app → VR only, offers XR, no HTML UI, allow-listed origins
|
|
23
|
+
3. Build and launch → doctor → build:metavr → install → run
|
|
24
|
+
4. Verify on device → logcat, debug endpoint, state hook
|
|
25
|
+
5. Ship → package id, signing, --release
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The package README is the reference for every config key, API and error:
|
|
29
|
+
`node_modules/@iwer/native/README.md`. Read its support matrix, Known
|
|
30
|
+
limitations and Troubleshooting before you promise a feature works natively.
|
|
31
|
+
Trust it over this skill if they disagree; the alpha changes between releases.
|
|
32
|
+
|
|
33
|
+
## Step 0 — Native APK or PWA?
|
|
34
|
+
|
|
35
|
+
| | **Native APK (this skill)** | **PWA/TWA (`iwsdk-pwa-packaging`)** |
|
|
36
|
+
| --- | --- | --- |
|
|
37
|
+
| Runs in | the @iwer/native runtime | Quest Browser, from a live URL |
|
|
38
|
+
| Needs hosting | no, files are in the APK | yes, a public HTTPS origin |
|
|
39
|
+
| Web fixes ship by | a new APK | redeploying the site |
|
|
40
|
+
| App modes | immersive VR and AR (passthrough) | immersive VR, AR, 2D panel |
|
|
41
|
+
| Web platform | the subset in the README matrix | the full browser |
|
|
42
|
+
| APK size | about 47 MB of runtime + assets | small wrapper |
|
|
43
|
+
|
|
44
|
+
Ask when the user says only "make an APK". Choose native for an offline,
|
|
45
|
+
self-contained immersive app; choose the PWA for a 2D panel, HTML UI, or an
|
|
46
|
+
app that depends on browser APIs the matrix marks "not yet" or "out of
|
|
47
|
+
scope".
|
|
48
|
+
|
|
49
|
+
## Step 1 — Set up
|
|
50
|
+
|
|
51
|
+
Requirements: `@iwsdk/core`, `@iwsdk/vite-plugin-dev` and `@iwsdk/create` 1.2.0
|
|
52
|
+
or later (1.1.0 rejects the `native` key), Node 20.19+, `adb` on `PATH` (or
|
|
53
|
+
`$ADB`/`$ANDROID_HOME`), and a Quest in developer mode with USB debugging
|
|
54
|
+
accepted. No Android SDK, NDK or Gradle is needed.
|
|
55
|
+
|
|
56
|
+
- **New project:** `npm create @iwsdk@latest <name> -- --target vr --metavr-native`
|
|
57
|
+
(or `--target ar`).
|
|
58
|
+
It adds `@iwer/native` (pinned), the `build:metavr` script, a `native`
|
|
59
|
+
section and `dist-metavr/` in `.gitignore`.
|
|
60
|
+
- **Existing IWSDK project:** run `npx @iwsdk/create@latest . --yes --target <vr|ar> --metavr-native`.
|
|
61
|
+
It adds the script, the dependency and the ignore entry but keeps your
|
|
62
|
+
`iwsdk.config.json`, so add the section it prints yourself:
|
|
63
|
+
|
|
64
|
+
```json
|
|
65
|
+
"native": {
|
|
66
|
+
"packageId": "com.example.myapp",
|
|
67
|
+
"appName": "myapp",
|
|
68
|
+
"network": { "allow": ["https://cdn.jsdelivr.net"] }
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Without it, `pack` stops at `iwsdk.config.json has no "native" section`.
|
|
73
|
+
|
|
74
|
+
Then `npx iwer-native doctor`. It checks Node, adb, the connected headsets, the
|
|
75
|
+
native config, signing and the bundled template. Fix every `[fail]` before
|
|
76
|
+
building. The `com.example` warning is fine for sideloading.
|
|
77
|
+
|
|
78
|
+
## Step 2 — Fit the app to the runtime
|
|
79
|
+
|
|
80
|
+
- **Immersive only.** `world.xr.mode` `"vr"` or `"ar"`; there is no 2D page, so
|
|
81
|
+
a Desktop 3D (`world.xr: false`) app cannot be packed. For `"ar"`, `pack`
|
|
82
|
+
declares passthrough itself. Plane, mesh, hit-test and anchor support needs a
|
|
83
|
+
room from Space Setup and is not yet device-tested in a real room (README
|
|
84
|
+
Known limitations): verify scene-understanding features on the headset.
|
|
85
|
+
A feature marked `required` that the headset lacks rejects the session, and
|
|
86
|
+
the app never leaves the splash: a Quest 3S has no depth sensing, so
|
|
87
|
+
`depthSensing: { required: true }` never starts there. Prefer optional
|
|
88
|
+
features and feature-detect them, and note the headset model you tested on
|
|
89
|
+
(`iwn-host.mjs info`). With several headsets attached, always pass `--serial`.
|
|
90
|
+
- **The app must offer XR.** Keep `world.xr.offer` at `"always"` (the default)
|
|
91
|
+
or `"once"`. The runtime shows only WebXR content: with `"none"` the app stays
|
|
92
|
+
black and logs `XR-LIFE-7` after 10 s.
|
|
93
|
+
- **No HTML UI.** There is no layout, CSS or pointer/keyboard event. Build UI in
|
|
94
|
+
3D with IWSDK spatial UI (`iwsdk-ui`). DOM overlays do not draw.
|
|
95
|
+
- **There is no browser to exit to.** Ending the session (the starter's
|
|
96
|
+
"Exit to Browser" button, `world.exitXR()`) makes `offer: "always"` start a new
|
|
97
|
+
session at once, so the button only flickers. Hide such controls in native
|
|
98
|
+
builds and let the system menu quit:
|
|
99
|
+
`const isNative = navigator.userAgent.includes('IWERNative');`
|
|
100
|
+
- **Network allow-list.** Only origins in `native.network.allow` are reachable
|
|
101
|
+
(`https://host[:port]`, no path). The starter needs `https://cdn.jsdelivr.net`
|
|
102
|
+
for its controller models. Prefer bundling assets in `public/` so the app works
|
|
103
|
+
offline. No WebSocket, IndexedDB, Cache API, service worker or HTTP cache.
|
|
104
|
+
- **Media.** `<video>`/`<audio>` file playback is not supported; use Web Audio
|
|
105
|
+
(`AudioContext`, buffer sources, gain, panner, `decodeAudioData`).
|
|
106
|
+
- **Check compatibility:** `npx iwer-native compat` (static) and
|
|
107
|
+
`npx iwer-native compat --trace` (a headless run into XR). `pack` runs the
|
|
108
|
+
static check and fails on an injected emulator; `pack --strict` fails on any
|
|
109
|
+
unsupported API. Treat the `WebAssembly.instantiateStreaming()` warning on an
|
|
110
|
+
IWSDK physics or UI build as expected: Havok and the MSDF worker fall back to
|
|
111
|
+
`WebAssembly.instantiate`, and physics runs. Act on every other warning: feature-detect
|
|
112
|
+
the API or drop it (`compat --verbose` shows the call site).
|
|
113
|
+
|
|
114
|
+
## Step 3 — Build, install, run
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
npm run --if-present typecheck
|
|
118
|
+
npm run build:metavr # dist-metavr/<appName>.apk, debug build
|
|
119
|
+
npx iwer-native install --serial <serial>
|
|
120
|
+
npx iwer-native run --serial <serial> # or: npx iwer-native pack --install --run
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The loop is quick (build about 5 s, pack under 1 s, install about 10 s), so
|
|
124
|
+
rebuild instead of reasoning about stale state. Always pass `--serial` when
|
|
125
|
+
more than one device is connected. Debug and release builds write the same
|
|
126
|
+
path; the last `pack` wins.
|
|
127
|
+
|
|
128
|
+
**Before blaming the app, check what the headset shows:**
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
adb -s <serial> shell dumpsys activity activities | grep topResumedActivity
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
- `com.example.<app>/android.app.NativeActivity` → the app is in front.
|
|
135
|
+
- `GuardianDialogActivity` ("Finding position in room") or
|
|
136
|
+
`LaunchCheckRequires6dofDialogActivity` ("Turn on tracking") → the headset has
|
|
137
|
+
lost tracking, usually because the room is dark or the cameras are covered.
|
|
138
|
+
`run` then reports `adb did not finish within 60 s`. A native APK needs 6DoF
|
|
139
|
+
tracking: ask the user for light. If the dialog stays after tracking is back,
|
|
140
|
+
`adb -s <serial> reboot` clears it.
|
|
141
|
+
- Any other system dialog (permissions, first-run notices) → ask the user to
|
|
142
|
+
answer it in the headset, or read its buttons with
|
|
143
|
+
`adb shell uiautomator dump` and answer it only if the user allowed you to.
|
|
144
|
+
|
|
145
|
+
## Step 4 — Verify on the device
|
|
146
|
+
|
|
147
|
+
IWSDK's CLI and MCP tools (`ecs`, `xr`, `scene`, `browser`) reach the managed
|
|
148
|
+
browser and paired Quest Browser pages, **not** a native APK. On the APK use:
|
|
149
|
+
|
|
150
|
+
1. **Logs:** `adb -s <serial> logcat -v tag | grep '/iwn'`. Every runtime tag
|
|
151
|
+
starts with `iwn`; app `console.*` output is `iwn-js`. A healthy launch logs
|
|
152
|
+
`xr: first WebXR frame`, then `xr-stats fps=72…` lines every few seconds.
|
|
153
|
+
Lines from an older process of the same app (another PID) are not this run.
|
|
154
|
+
2. **The debug endpoint** (debug builds; `pack --release --inspector` for a
|
|
155
|
+
release build). Forward it, then use the bundled client:
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
adb -s <serial> forward tcp:9229 localabstract:<packageId>_devtools_9229
|
|
159
|
+
kit="$(dirname "$(find .claude/skills .agents/skills -path '*/iwsdk-metavr-native/assets/iwn-host.mjs' -print -quit)")"
|
|
160
|
+
node "$kit/iwn-host.mjs" eval 'document.title'
|
|
161
|
+
node "$kit/iwn-host.mjs" shot shot.png left 0.5 # what the eye buffer shows
|
|
162
|
+
node "$kit/iwn-host.mjs" stats # fps, GC, heap, boot timings
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
`adb shell screencap` is black during an immersive session; use `shot`.
|
|
166
|
+
The shot follows the live head pose: a headset lying on a desk looks
|
|
167
|
+
wherever it points. It holds the app's layer only; in AR, passthrough is
|
|
168
|
+
not in it, so empty areas come out blank.
|
|
169
|
+
3. **App state.** The APK has no IWSDK command bridge, so expose the world for
|
|
170
|
+
tests yourself, only when asked for:
|
|
171
|
+
|
|
172
|
+
```ts
|
|
173
|
+
if (new URLSearchParams(location.search).has('iwsdkDebug')) {
|
|
174
|
+
(globalThis as { __world?: World }).__world = world;
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Launch with `npx iwer-native run --query iwsdkDebug=1`, then read state with
|
|
179
|
+
`eval` (for example `__world.player.position.toArray()`, or a value from
|
|
180
|
+
one of your components). Keep state you want to check in ECS components, as
|
|
181
|
+
AGENTS.md asks.
|
|
182
|
+
4. **A debugger:** `npx iwer-native run --inspect --forward 9229`, then open
|
|
183
|
+
`chrome://inspect` and add `localhost:9229`. If the port is
|
|
184
|
+
`still in use`, another debug build holds it:
|
|
185
|
+
`adb shell am force-stop <its packageId>`.
|
|
186
|
+
|
|
187
|
+
**Scripted input does not exist on the APK.** You cannot press, grab or point
|
|
188
|
+
from the CLI. Prove interaction logic in the emulator or Quest Browser with
|
|
189
|
+
`iwsdk-grab`, `iwsdk-ray` and `iwsdk-native-xr-test` (the same IWSDK code runs
|
|
190
|
+
there), and use the APK for what only it can show: that the app starts and
|
|
191
|
+
enters XR, renders, holds frame rate, loads its assets, reaches its network
|
|
192
|
+
origins, and that physics and audio run. Say which claims were verified where.
|
|
193
|
+
|
|
194
|
+
## Step 5 — Ship
|
|
195
|
+
|
|
196
|
+
- Replace `com.example.*` with your own reverse-domain `packageId`; stores
|
|
197
|
+
reject `com.example`. A changed id installs as a separate app.
|
|
198
|
+
- Add a `signing` section (keystore path plus the names of the environment
|
|
199
|
+
variables that hold the passwords) and build with
|
|
200
|
+
`npx iwer-native pack --release`. Never write passwords into
|
|
201
|
+
`iwsdk.config.json` or commit a keystore. Without `signing`, `--release` signs
|
|
202
|
+
with the debug key and warns.
|
|
203
|
+
- Raise `versionCode` for every upload. Set `icon` and `splash` (the README's
|
|
204
|
+
Configuration section lists every key; `iwer-native validate` checks them).
|
|
205
|
+
- Installing a release over a debug build signed with another key fails with
|
|
206
|
+
`INSTALL_FAILED_UPDATE_INCOMPATIBLE`: `adb uninstall <packageId>` first.
|
|
207
|
+
|
|
208
|
+
## Report
|
|
209
|
+
|
|
210
|
+
State the APK path, size and package id, the device serial and OS build
|
|
211
|
+
(`node "$kit/iwn-host.mjs" info`), the compat result, what you verified on the
|
|
212
|
+
APK (with logcat lines, `eval` values or shots) and what you verified only in
|
|
213
|
+
the emulator or Quest Browser, and any warning you left in place with its
|
|
214
|
+
reason. For a runtime bug, collect what the README's Reporting issues section
|
|
215
|
+
lists.
|
|
216
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=c28e2ac59fab5db24f36df736b7f246c7abbc2b016de2ae90a76a9a20669686e name=iwsdk-metavr-native (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
4
|
+
*
|
|
5
|
+
* This source code is licensed under the MIT license found in the
|
|
6
|
+
* LICENSE file in the root directory of this source tree.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
// Client for the @iwer/native debug endpoint (debug builds, or
|
|
10
|
+
// `pack --release --inspector`). Forward the port first:
|
|
11
|
+
// adb -s <serial> forward tcp:9229 localabstract:<packageId>_devtools_9229
|
|
12
|
+
//
|
|
13
|
+
// node iwn-host.mjs eval '<expression>' value of the expression (promises awaited)
|
|
14
|
+
// node iwn-host.mjs shot <out.png> [left|right|both] [scale] eye-buffer PNG
|
|
15
|
+
// node iwn-host.mjs stats frame, GC, heap and boot timings
|
|
16
|
+
// node iwn-host.mjs info device, runtime and app identity
|
|
17
|
+
//
|
|
18
|
+
// PORT selects another forwarded port (default 9229). Exit code 1 on an error
|
|
19
|
+
// reply, 2 when the endpoint does not answer.
|
|
20
|
+
import { writeFileSync } from 'node:fs';
|
|
21
|
+
|
|
22
|
+
const [method, ...args] = process.argv.slice(2);
|
|
23
|
+
const port = process.env.PORT || '9229';
|
|
24
|
+
let params;
|
|
25
|
+
let out;
|
|
26
|
+
switch (method) {
|
|
27
|
+
case 'eval':
|
|
28
|
+
params = { expression: args[0] ?? 'undefined', awaitPromise: true };
|
|
29
|
+
break;
|
|
30
|
+
case 'shot':
|
|
31
|
+
out = args[0] ?? 'iwn-shot.png';
|
|
32
|
+
params = { eye: args[1] ?? 'left', scale: Number(args[2] ?? 0.5) };
|
|
33
|
+
break;
|
|
34
|
+
case 'stats':
|
|
35
|
+
case 'info':
|
|
36
|
+
params = {};
|
|
37
|
+
break;
|
|
38
|
+
default:
|
|
39
|
+
console.error('usage: iwn-host.mjs eval <expr> | shot <out.png> [eye] [scale] | stats | info');
|
|
40
|
+
process.exit(2);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
const timer = setTimeout(() => {
|
|
44
|
+
console.error(`no reply from ws://127.0.0.1:${port}/host: is the app running a debug build, and is the port forwarded?`);
|
|
45
|
+
process.exit(2);
|
|
46
|
+
}, 40_000);
|
|
47
|
+
const ws = new WebSocket(`ws://127.0.0.1:${port}/host`);
|
|
48
|
+
ws.onopen = () => ws.send(JSON.stringify({ id: 1, method, params }));
|
|
49
|
+
ws.onerror = () => {
|
|
50
|
+
console.error(`cannot connect to ws://127.0.0.1:${port}/host: forward the port with adb first`);
|
|
51
|
+
process.exit(2);
|
|
52
|
+
};
|
|
53
|
+
ws.onmessage = (message) => {
|
|
54
|
+
clearTimeout(timer);
|
|
55
|
+
const reply = JSON.parse(String(message.data));
|
|
56
|
+
if (reply.error) {
|
|
57
|
+
console.error(reply.error);
|
|
58
|
+
process.exit(1);
|
|
59
|
+
}
|
|
60
|
+
if (method === 'shot') {
|
|
61
|
+
writeFileSync(out, Buffer.from(reply.png, 'base64'));
|
|
62
|
+
console.log(JSON.stringify({ file: out, width: reply.width, height: reply.height, frame: reply.frame }));
|
|
63
|
+
} else if (method === 'eval') {
|
|
64
|
+
console.log(typeof reply.result === 'string' ? reply.result : JSON.stringify(reply.result ?? null, null, 1));
|
|
65
|
+
} else {
|
|
66
|
+
delete reply.id;
|
|
67
|
+
console.log(JSON.stringify(reply, null, 1));
|
|
68
|
+
}
|
|
69
|
+
ws.close();
|
|
70
|
+
process.exit(0);
|
|
71
|
+
};
|
|
@@ -259,4 +259,4 @@ Report:
|
|
|
259
259
|
If the user wants to try the app in the headset afterwards, start a plain
|
|
260
260
|
session (`npx @iwsdk/cli dev up` with the session's `--ai-mode`, without
|
|
261
261
|
`--native-xr-control`) and give them the plain URL from `dev status`.
|
|
262
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
262
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=931a8822463f2bb6652cbbf2b7571db92e5331af44b598890057319b0177939b name=iwsdk-native-xr-test (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|