_便利な JEV API 統合は、大規模なゲーム システムに関する小規模な意思決定サービスです。ゲームは権威ある世界を所有し、それをコンパクトな状態に変換し、現在合法的なアクションを作成します。 JEV は、その限定された質問を評価します。実行者は回答を検証し、アクションを実行します。統合パイプライン_
Game State -> Legal Actions -> Typed Question -> JEV -> Validate -> Execute or Fallback
Game State -> Legal Actions -> Typed Question -> JEV -> Validate -> Execute or Fallback{ agentId: 'guard-07', healthRatio: 0.42, visibleThreats: 1, ammo: 3, stateVersion: 1842 }
_2. Legal Actions を定義します各候補には、安定した名前、明示的なパラメータ、前提条件、および実行所有者が必要です。例:
{ agentId: 'guard-07', healthRatio: 0.42, visibleThreats: 1, ammo: 3, stateVersion: 1842 }const result = await jev.decide({ state, legalActions, question: 'Protect the relay' }); const current = buildLegalActions(world, npc); if (!current.some(action => sameAction(action, result))) return フォールバック(); return executor.run(result);
_正確なSDK方法は異なる場合があります。不変条件は、状態バージョンの比較、パラメータの再検証、および不正になった結果の拒否を行いません。リクエストの処理中、レスポンスは古くなる可能性があります。_5.ハンドルの信頼性応答に確率または信頼度が含まれる場合は、検証をバイパスする許可としてではなく、ポリシー信号として使用します。信頼度が低いと、保守的なローカル ポリシーがトリガーされるか、現在の意図が維持される可能性があります。_6.ケイデンスとフォールバックを設定します。すべてのレンダリング フレームではなく、意味のあるイベントまたは制限された戦術タイマーを呼び出します。各リクエストに期限を設定します。タイムアウトになったら、安全なアクションを維持するか、役割固有の フォールバック (隠れる、位置を保持する、フォローする、または作成されたビヘイビアー ツリーなど) を使用します。キャンセルと注文が明示的でない限り、エージェントごとに進行中の決定を 1 つに制限します。_7.契約をテストします投影された状態、Legal Actions、応答、待ち時間、状態バージョン、検証結果、実行結果、および フォールバック 理由をログに記録します。体力の低下、弾薬の不足、複数の脅威、目標の喪失、アクションの中断、サービスの失敗を再現します。意思決定の品質、レイテンシ、無効な結果の割合、フォールバック の割合を個別に測定します。リクエストコントラクトを設計プロダクション リクエストには、スキーマ バージョン、エージェント ID、状態バージョン、許可された状態投影、Legal Actions、決定プリミティブ、目的、期限、および相関 ID が含まれている必要があります。対物レンズを短く安定させてください。命令の段落に依存するのではなく、コードとデータに厳しい制約を設けます。_{ schemaVersion: 'npc-decision-v1', agentId, stateVersion, state, legalActions, primitive: 'choice', deadlineMs, requestId }_応答コントラクトを設計応答は、選択された候補またはScore、観察された状態のバージョン、信頼度または確率（利用可能な場合）、およびプロバイダーのステータスを識別する必要があります。説明を実行フィールドとしてではなく、オプションのテレメトリとして扱います。実行者は、散文を解析せずにアクションを検証できる必要があります。ゲームを存続させるためのエラー処理条件アクション _タイムアウト無視応答を返し、ロール固有のフォールバック無効スキーマ契約エラーを記録して失敗する閉店古いバージョン現在のアクションを破棄または再検証しますset_プロバイダー失敗短いバックオフをトリップして続行しますローカル_繰り返し失敗エージェントとサーフェスのリモート決定を無効にしますテレメトリーリプレイとオブザーバビリティ決定を再現するのに十分な情報を保存します: 予測された状態、Legal Actions、質問スキーマ、モデル応答、タイムスタンプ、状態バージョン、検証結果、実行されたコマンド、結果、フォールバック 理由。プレーヤーのデータと秘密を編集します。リプレイ ハーネスを使用すると、デザイナーはゲーム全体をロードせずに、新しいプロンプトまたはプロバイダーを同じシナリオと比較できます。API が停止する場所API は世界を変更するのではなく、決定を返す必要があります。インベントリの書き込み、ダメージ、移動権限、およびマルチプレイヤーの状態の変更をゲーム サーバーまたはエンジンの背後に保持します。この境界により、再試行がより安全になり、重複したリクエストによってゲームプレイ エフェクトが 2 回適用されるのを防ぎます。NPC の完全なフローについては、JEV チュートリアル を参照してください。アクションスペースの設計については、JEV を参照してください。 Unity については、JEV Unity チュートリアル_. に進みます。
3. Choose the primitive
Use Choice when one candidate should be selected, Score when candidates need ranking, and a bounded yes-or-no judgment when the question is a gate such as whether to abandon an objective. Use the smallest primitive that matches the question.
4. Call and validate
const result = await jev.decide({ state, legalActions, question: 'Protect the relay' }); const current = buildLegalActions(world, npc); if (!current.some(action => sameAction(action, result))) return fallback(); return executor.run(result);The exact SDK method may vary. The invariants do not: compare state versions, revalidate parameters, and reject results that are no longer legal. A response can become stale while a request is in flight.
5. Handle confidence
If the response includes probability or confidence, use it as a policy signal, not as permission to bypass validation. Low confidence can trigger a conservative local policy or preserve the current intent.
6. Set cadence and フォールバック
Call on meaningful events or a bounded tactical timer, not every render frame. Give each request a deadline. On timeout, keep a safe action or use a role-specific フォールバック such as take cover, hold position, follow, or an authored behavior tree. Limit one in-flight decision per agent unless cancellation and ordering are explicit.
7. Test the contract
Log projected state, legal actions, response, latency, state version, validation result, execution outcome, and フォールバック reason. Replay low health, no ammunition, multiple threats, lost targets, interrupted actions, and service failure. Measure decision quality, latency, invalid-result rate, and フォールバック rate separately.
Design the request contract
A production request should carry a schema version, agent identity, state version, permitted state projection, legal actions, decision primitive, objective, deadline, and correlation ID. Keep the objective short and stable. Put hard constraints in code and data rather than relying on a paragraph of instructions.
{ schemaVersion: 'npc-decision-v1', agentId, stateVersion, state, legalActions, primitive: 'choice', deadlineMs, requestId }Design the response contract
The response should identify the selected candidate or score, the observed state version, confidence or probability when available, and a provider status. Treat explanation as optional telemetry, not as an execution field. The executor should be able to validate the action without parsing prose.
Error handling that keeps the game alive
| Condition | Action |
|---|---|
| Timeout | Ignore the response and use the role-specific フォールバック |
| Invalid schema | Record the contract error and fail closed |
| Stale version | Discard or revalidate against the current action set |
| Provider failure | Trip a short backoff and continue locally |
| Repeated failure | Disable remote decisions for the agent and surface telemetry |
Replay and observability
Persist enough information to reproduce a decision: projected state, legal actions, question schema, model response, timestamps, state versions, validation result, executed command, outcome, and フォールバック reason. Redact player data and secrets. A replay harness lets designers compare a new prompt or provider against the same scenarios without loading the entire game.
Where the API should stop
The API should return a decision, not mutate the world. Keep inventory writes, damage, movement authority, and multiplayer state changes behind the game server or engine. This boundary makes retries safer and prevents a duplicated request from applying a gameplay effect twice.
For a full NPC flow, see JEV tutorial. For action-space design, read JEV legal actions. For Unity, continue to JEV Unity tutorial.
