A useful JEV API integration is a small decision service around a large game system. The game owns the authoritative world, translates it into compact state, and creates the actions legal now. JEV evaluates that bounded question; the executor validates the answer and performs the action.
The integration pipeline
Game State -> Legal Actions -> Typed Question -> JEV -> Validate -> Execute or Fallback1. Design compact Game State
Send facts that could change the next decision: role, health, visible threats, objective, resources, cooldowns, cover, current intent, and a monotonic state version. Do not send the entire engine object graph, and do not leak hidden information the NPC could not perceive.
{ agentId: 'guard-07', healthRatio: 0.42, visibleThreats: 1, ammo: 3, stateVersion: 1842 }2. Define Legal Actions
Each candidate needs a stable name, explicit parameters, preconditions, and an execution owner. For example: takeCover(coverId), attack(targetId), or holdPosition(locationId). Build the list from authoritative state; do not ask JEV to invent IDs, routes, abilities, or parameters.
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 fallback
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 fallback 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 fallback reason. Replay low health, no ammunition, multiple threats, lost targets, interrupted actions, and service failure. Measure decision quality, latency, invalid-result rate, and fallback 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 fallback |
| 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 fallback 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.
