初回起動と Runtime
Android 版の初回起動は2段階に分かれています：まずアプリのプライベート領域に Linux Runtime をデプロイし、その上で Runtime 内の AzurPilot を起動します。各段階で発生するエラーメッセージは明確に分離されています。
デプロイステートマシン
| ステート | 意味 | 次のアクション |
|---|---|---|
Checking | 導入済みバージョンのチェック中 | 自動継続 |
NotInstalled | 未デプロイの状態 | ホーム画面で「Runtime をダウンロード」をタップ |
NotBundled | 軽量版かつ Release に当該アーキテクチャが存在しない | 完全版 APK を導入 |
LowDisk | 空きストレージ容量が 2 GB 未満 | ストレージの空き容量を確保 |
Downloading | ダウンロード進行中（圧縮バイト数で計測） | 完了を待機 |
Extracting | 展開処理中（圧縮バイト数で計測） | 完了を待機 |
Ready | 準備完了 | 「起動」をタップ可能 |
Failed | デプロイ異常 | エラー詳細（reason）を確認して再試行 |
デプロイは自動的には開始されません。完全版 APK には rootfs が内包されていますが、「Runtime をダウンロード」ボタンをタップして初めて展開が開始されます。これは空き容量不足時のサイレント障害を防ぐための設計です。
デプロイ時の内部処理
- 前回の未完了処理（
rootfs.previous）が存在する場合は復旧。 .provisionedフラグ、BUILD_MANIFEST、端末の ABI が一致しているかを検証。- 一時ディレクトリ
rootfs.tmpに展開し、完了後にアトミックにrootfsへリネーム（途中で中断しても中途半端なデータは残りません）。 config/（SQLite データベース、インスタンス設定含む）、password.txt、log/を保持。- 新しいプロビジョニングフラグを書き込んで完了。
ダウンロード処理は4並列セグメント取得に対応しており（8 MiB 以上の場合に Range プローブを実施）、失敗時は自動的に単一接続にフォールバックしてリトライします。完了後はサイズと SHA-256 チェックサムを照合し、不一致時は Failed ステートへ遷移します。
初回の WebUI 起動が遅い理由
rootfs のサイズ削減のため、配布パッケージからは __pycache__ が除去されています。初回起動時はすべての Python モジュールのバイトコードが再コンパイルされるため、WebUI が準備完了になるまでに90秒以上かかる場合があります。この際、ログには以下が出力されます：
AzurPilot WebUI not ready within 90000msこれは想定通りの警告メッセージであり、システムエラーではありません。しばらく待機すると自然に起動し、2回目以降の起動は数秒で完了するようになります。
初期化中にアプリをタスクキルしないでください
初期化中にアプリを強制終了すると、ロックファイルやセッションが不完全な状態で残存します。自然に起動するのを待つか、アプリ内の「Runtime を停止」ボタンから正常終了させてください。
アプリに必要な権限
| 権限 | 用途 | 付与しない場合の影響 |
|---|---|---|
| 通知 | フォアグラウンドサービス、ペアリングコード、タスク通知 | 通知領域からの無線ペアリングが利用不能 |
| バッテリー最適化の除外 | バックグラウンド常駐保護 | 画面消灯後にプロセスが OS に終了されるリスク |
| 他のアプリの上に重ねて表示 | グローバルフローティング操作パネル | 他のアプリを使用中にオーバーレイ操作が不可 |
| 不明なアプリのインストール | アプリ内からの APK 自己更新 | 手動でのダウンロードとインストールが必要 |
| すべてのファイルへのアクセス（任意） | ログを端末の共有領域へエクスポート | アプリのプライベートディレクトリにのみ出力 |
メーカー製端末ではさらに「自動起動」「バックグラウンドポップアップ」「省電力ポリシー」等の設定が必要です。Android 12+ の「正確なアラーム」権限は本アプリには不要です。
特権サービスのアクティベーション
ローカル実行を行うには特権サービスのアクティベートが必須です。これが未完了の場合、仮想ディスプレイの生成、画面キャプチャ、タッチ操作の注入が行えません。3つの方法が用意されています：
| 方式 | 推奨対象 | 設定場所 |
|---|---|---|
| 内蔵 ADB（推奨） | Android 11 以降 | 設定 → 実行とセキュリティ → 内蔵 Shizuku |
| Root | Root 化済み端末 | 同画面で Root を選択 |
| 外部 Shizuku / Sui | すでに Shizuku マネージャーを導入済み | 同画面で外部サービスを選択 |
詳細な手順は権限のアクティベーションを参照してください。
Runtime の起動
- ホーム画面で Runtime のステータスが
Readyであることを確認します。 - 「起動」ボタンをタップします。
- ステータスが「実行中」に遷移するのを待ちます（初回は長めの時間がかかります）。
- 「コンソール」タブを開き、内蔵された WebUI が表示されることを確認します。
内蔵 WebUI はデスクトップ版と同一のフロントエンドであり、ポート 25548 上で Runtime が 127.0.0.1 にリッスンします。ホストの AzurPilotGateway が唯一の /api/v1/ws 購読者となります。
最初のインスタンスの作成
コンソール → インスタンス一覧 → 新規作成をタップします。名前は ap または任意の識別名を入力します。
対象端末上のゲームのパッケージ名を選択します。日本版クライアントの場合は日本版のパッケージ名を選択してください。
Android ホスト上では、スクリーンショットおよび操作方式に必ず azurpilot_android を指定してください。他の方式は外部 ADB 接続を前提としているため、端末内部の仮想ディスプレイを操作できません。
まずは「研究（科研）」または「委託」を有効化し、次回実行時刻を現在に設定します。
周回画面で映像の変化が確認でき、ログにタスクの開始および終了が出力されれば、一連のパイプライン構築は完了です。
動作確認チェックリスト
| 確認項目 | 合格基準 |
|---|---|
| Runtime ステータス | 「実行中」を維持し、再起動ループが発生していないこと |
| 画面推流 | 周回画面にゲームの描画が正常に反映されていること |
| コンソール | インスタンス一覧およびタスク設定画面が正常にロードされること |
| タスク進行 | ログにタスク開始と終了が記録され、ゲーム内の状態が遷移していること |
| バックグラウンド維持 | 他のアプリへ切り替えて5分経過後もタスクが中断なく継続していること |