所有権とライフサイクル
同時に1件の案内
start(modId, request) と restore(modId, checkpoint) は、その案内を操作する Navigation オブジェクトを返します。状態取得・更新・停止は、このオブジェクトのメソッドを呼びます。案内が既にある場合は、同じMOD IDからの開始も BUSY です。オブジェクトは自分の連携クラス内で保持し、保存や他MODへの受け渡しはしないでください。
MOD IDは [a-z][a-z0-9_-]{0,63} に合う名前で指定します。呼出元を表す名前であり、その名前から既存の案内を取得したり操作したりすることはできません。同じMODが次の案内を開始しても、古いオブジェクトから新しい案内は操作できません。
案内オブジェクトはMOD同士が協調するための所有権の境界です。同じJVM内で実行されるコードに対するセキュリティサンドボックスではありません。
| 出来事 | 呼び出し側の次の処理 |
|---|---|
| 開始・復元に成功 | 案内オブジェクトを保持し、通知を受け取るコールバックを1つ登録 |
開始が BUSY |
現在の案内には干渉せず、使用中であることを表示 |
| 古い状態に基づく更新が拒否 | 現在の状態を読み、元の変更がまだ必要か判断 |
| ディメンション移動 | 所有者と案内オブジェクトを保持。ワールドのセッションは継続 |
| 終了通知 | 案内オブジェクトを破棄し、通知されたチェックポイントを保存 |
| ワールド退出 | 保存キューの処理を完了し、自分の非同期調査を取消 |
| 再びワールド参加 | そのワールドの保存を読み、明示的に復元して新しい案内オブジェクトを取得 |
読取・更新・復元の失敗を、無条件の新しい start に置き換えないでください。元の依頼を失い、別の所有者と競合する原因になります。
通知を受けてから次の処理へ
navigation.observe(callback) はその所有者の通知用コールバックを置き換えます。通知はMinecraftのクライアントスレッドで実行されます。次の観測時に現在の状態が通知され、その後は変更があるたびに通知されます。終了時の通知は1回です。終了通知ではコールバックを呼ぶ前に案内オブジェクトが失効します。
コールバックは短く保ちます。通知された不変のデータをUIの状態管理へ、チェックポイントのバイト列を実行順序を保つ保存キューへ渡してください。コールバック内からNaviを変更しないでください。 次のコマンドが必要なら、コールバックから戻った後のクライアントtickへ予約します。同じスレッド上で即実行するexecutorでは、この遅延を保証できません。
通知用コールバックは一時停止やプレイヤー向けの効果音から独立しています。コールバックが例外を投げても再実行されません。NavigationUpdate.End は ACTIVE、STOPPED、ARRIVED、WORLD_LEFT、FAILED を区別します。
revisionは判断時点の状態を表す
replace は依頼を置き換えます。refine は目的地と通過済みの経由地点を保ちながら、選んだ部分だけを更新します。どちらも読取に成功した snapshot.revision() が必要です。
- エンティティの経由地点を変える場合は、
snapshot.tracking().revision()もobservedTargetRevisionに指定。 - 転送ネットワークを変える場合は、
snapshot.connectionsRevision()をrefinementのnetworkメソッドに指定。 - 経由地点を指定しなければ現在の残りを保持。空リストなら明示的に削除。
取消後に非同期処理の結果が届いたら、呼び出し側で破棄します。古い結果をNaviが拒否した場合は現在の状態を読み、再計算するか調査を終了してください。同じ入力を繰り返すだけでは復旧しません。
保存は呼び出し側の責任
NavigationCheckpoint は残りの案内を保存・復元できるデータです。案内オブジェクトやワーカーのキャッシュは含みません。自分のワールド・プレイヤー識別子に対応付けて checkpoint.bytes() を保存します。中身を解析・編集しないでください。NavigationCheckpoint.fromBytes(bytes) は値を作るだけで、Naviが restore 時に形式を検証します。
保存順序を保ち、古いワールドの遅い書込みで新しいデータを上書きしないようにします。終了時のチェックポイントも保存してください。手動停止や到着は残りの案内を消し、ワールド退出では残せます。終了通知を無視すると、終了済みの案内が復活してしまいます。そのワールドの保存処理を終了する前に、保存キューを完了させます。
案内オブジェクトが有効な間の明示保存には navigation.checkpoint() を使えます。失効後の最終値は終了通知のコールバックから受け取ります。入力サイズ上限は2 MiBです。破損・互換性のないバイト列は復元に失敗します。別の案内を黙って開始せず、失敗を扱ってください。
エラーと診断
APIは NavigationResult.Success または Failure(code, message) を返します。BUSY、NO_WORLD、INVALID_NAVIGATION、WRONG_THREAD、REENTRANT_OPERATION などを扱い、未知のコードにも汎用の表示を用意します。不正なDTOの構築は、API呼出しより前に IllegalArgumentException や NullPointerException を投げる場合があります。
取得した状態（snapshot）のactivity/reason文字列は観測結果であり、再試行やAI起動の指示ではありません。未知の値は汎用状態として扱います。通常の進行通知で経路全体をコピーすることもありません。
補助調査を行う場合は、経過時間だけでなくsnapshotに含まれる補助が必要な問題（assistance incident）を使います。reportAssistance はその問題に対する補助処理の実際の状態を報告するAPIで、アシスタントを起動するものではありません。処理を案内オブジェクト・依頼のrevision・問題のID・移動対象のtarget revisionに対応付け、現在の依頼と一致しなくなった調査を取消してください。