Contents
Figmin XR Script API入門: 初心者向け開発手順と実機デバッグガイド
Figmin XR Script APIの初心者向け開発フローをステップバイステップで解説します。ローカル環境構築からAPI連携、最終的な実機動作確認まで、初歩から丁寧に解説します。本記事ではNode.js+TypeScript環境構築入門やADB接続時のトラブルシューティングといった具体的な技術的ポイントを網羅し、公式ドキュメントと併せて実装を進めることを推奨します。
Figmin XR Script API開発フローの概要
Quest 3でのMR開発ワークフローは、ローカル環境構築→API連携→実機デバッグという流れが基本です。特にPassthrough権限やADB接続時の設定ミスは、開発初期に多くの時間を浪費する要因となるため、事前に手順を確認することが重要です。公式ドキュメントと併せて環境構築から動作確認までの一連のフローを理解し、効率的な開発体制を整えましょう。
Node.js + TypeScript環境構築入門
Figmin XR Script APIを開発するためには、Node.jsとTypeScriptを用いたローカル環境が必須です。以下に必要なツールの導入とプロジェクト初期化の手順を解説します。
開発に必要なツールの導入
初心者向けには以下の手順で準備してください:
-
Node.js:
nvmでバージョン管理を行い、公式リポジトリで指定されているバージョン（例: v18.17.0）を使用することを推奨します。注意: バージョンは最新のものに更新される可能性があるため、公式ドキュメントを参照してください。
-
TypeScript:
npm install -g typescriptでグローバルインストールし、型定義ファイルをプロジェクト内に配置します。注意: プロジェクト構成は公式リポジトリの例を参考に調整してください。
-
ESLint / Prettier: 一貫したコードスタイルを保つために導入。公式リポジトリの設定ファイルを参考に
.eslintrc.jsや.prettierrcを作成します。
プロジェクト初期化と設定ファイル作成
プロジェクトフォルダ内に移動し、以下のように初期化します。
npm init -yで初期設定を行います。npm install --save-dev typescript ts-node @types/nodeを実行し、依存関係を導入します。tsconfig.jsonを作成し、以下の基本的な設定を記載します。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "compilerOptions": { "target": "ES2021", "module": "ESNext", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "outDir": "./dist" }, "include": ["src/**/*"] } |
注意: プロジェクト構成は公式リポジトリの例を参考に調整してください。
Figmin XR Script API連携入門
API連携には、型定義ファイルの導入とサンプルコードへの適用が不可欠です。以下に具体的な手順を示します。
型定義ファイルの導入手順
Figmin XR Script APIを使用するためには、公式リポジトリから型定義ファイル（.d.ts）を取得し、プロジェクト内に配置します。例として、以下のコマンドで依存関係をインストールできます。
|
1 2 |
npm install @figmin/xr-api-types --save-dev |
TypeScriptでは、この型定義を以下のようにimportして利用します。
|
1 2 |
import { FigminXR } from '@figmin/xr-api-types'; |
サンプルコードでの基本操作
APIのイベントリスナー登録処理に以下のテンプレートを使用します。
|
1 2 3 4 5 |
const xr = new FigminXR(); xr.on('deviceConnected', (device) => { console.log(`デバイス接続: ${device.id}`); }); |
コールバック関数の引数構造:
eventとpayloadが含まれるため、具体的な処理に応じて型を確認してください。
Quest 3でのPassthrough権限設定とデバッグ準備
Quest 3でFigmin XR Script APIを使用するには、開発者モードの有効化とADB接続が必須です。以下に手順を解説します。
開発者モード有効化手順
初心者向けに簡潔なステップを紹介します:
- Quest 3の「設定」アプリを開き、「システム」→「開発者オプション」へアクセス。
- 「デバッグモード」をONにし、USB接続やWi-Fi ADBを使用できるようにします。
注意: 初回設定時はAndroidのデバッガー認証を確認する必要があります。
ADB接続時の認証フロー
ADB経由でQuest 3と通信するには、以下のコマンドを実行します。
|
1 2 |
adb connect <IP_ADDRESS>:5555 |
Wi-Fi ADB接続: Quest 3のIPアドレスは
adb shell ip -4 addr show wlan0で取得可能です。IPアドレスが固定されていることを確認してください。
ADB/Wi-Fi ADBトラブルシューティング
ADB接続時に発生するエラー対応やポート設定は、開発に時間の浪費を招くため、事前に手順を把握しておく必要があります。
接続失敗時のエラーコード対応
| エラーコード | 対応策 |
|---|---|
| adb: failed to connect to |
IPアドレスが正しいか、ADBサーバーが起動しているかを確認してください。 |
| device not found: | USB接続が確立されているか、開発者オプションの「USBデバッグ」がONかチェックします。 |
ポートフォワーディング設定例
Wi-Fi ADBでのポートフォワーディングを設定するには、以下のコマンドを使用します。
|
1 2 |
adb forward tcp:8080 tcp:8080 |
リアルタイムオブジェクト操作処理入門
Figmin XR Script APIは、位置・回転・スケールの同期処理を実装することで、リアルタイムなオブジェクト操作が可能です。
位置・回転・スケールの同期処理
以下のようにTransformコンポーネントを直接編集する代わりに、Script APIを使用します。
|
1 2 3 4 |
xr.setObjectPosition("obj_001", { x: 0, y: 1.5, z: -2 }); xr.setObjectRotation("obj_001", { x: 30, y: 45, z: 0 }); xr.setObjectScale("obj_001", { x: 1.2, y: 1.2, z: 1.2 }); |
物理演算とのタイミング: 物理演算を考慮する場合は、
Update()内での操作を推奨します。
実機動作確認と次のステップ
実機でのテストは、アプリの品質向上に不可欠です。以下にログ出力や公式ドキュメントとの照合ポイントを解説します。
ログ出力の最適化方法
adb logcatでフィルタリングを行い、特定のエラーメッセージを抽出します。
|
1 2 |
adb logcat -s FigminXR:* --time-format u |
フィルタ技術: 特定のタグやログレベル（E:エラー, W:警告など）で絞り込むと効率的です。
公式ドキュメントとの照合ポイント
以下のチェックリストを参考に、API仕様書とコード実装の差分を確認してください。
- メソッド名や引数が一致しているか
- イベントリスナーの登録が正しいか
- 型定義ファイルと実際のAPIシグネチャが一致しているか
まとめ
本記事では、Figmin XR Script APIの初心者向け開発フローをステップバイステップで解説しました。以下に要点を整理します。
- ローカル環境構築: Node.js + TypeScriptを使用し、公式リポジトリの設定に則って構成する。
- API連携: 型定義ファイル導入とイベントリスナーの実装で動作確認を行う。
- Quest 3デバッグ: Passthrough権限やADB接続を事前に準備し、エラー対応策を理解しておく。
- 実機動作確認: ログ出力の最適化と公式ドキュメントとの照合で品質向上を目指す。
公式ドキュメントと併せて環境構築を開始し、実機での動作確認を実施してください。