In a reliable game AI integration, JEV should not invent arbitrary commands. The game first generates Legal Actions: choices possible under current rules, perception, resources, and authority constraints. JEV can choose or score those candidates; the executor rechecks them before changing the world.
What is a Legal Action?
A Legal Action is a meaningful command the current agent is allowed to attempt. It has a stable name, explicit parameters, preconditions, and an execution owner. Examples include attack(targetId), takeCover(coverId), heal(allyId), and retreat(routeId).
Why not free-form actions?
Free-form generation makes validation, testing, and balancing harder. A model may return a target that no longer exists, an unreachable route, or an unimplemented verb. A closed action set turns invention into selection: designers inspect candidates, QA replays them, and the executor rejects anything outside the contract.
Generate candidates in game code
if (canSeeTarget && ammo > 0) add({ name: 'attack', targetId }); if (safeCover) add({ name: 'takeCover', coverId }); if (allyNeedsHelp) add({ name: 'assist', allyId }); if (empty) add({ name: 'holdPosition' });The builder uses authoritative state and the agent's perception. The candidate list is still a snapshot and is not a substitute for final validation.
Choice, Score, and gates
Use Choice when one candidate should be selected, Score when targets or routes need ranking, and a bounded yes-or-no judgment as a gate such as whether to abandon an objective. For large spaces, narrow candidates first and choose second.
Revalidate before execution
When the response arrives, rebuild or recheck the current action set. Verify name, parameters, state version, target existence, resources, and authority. If a candidate disappeared, discard the response and use a fallback. Never force an old decision into a new world state.
const current = buildLegalActions(world, npc); const selected = current.find(action => sameAction(action, decision)); if (!selected) return fallback(); return execute(selected);How large should the action space be?
Start with a few options that represent real trade-offs. Exposing every movement option forces the decision layer to solve navigation and tactics together. For a squad NPC, defend, take cover, assist, attack, and retreat can be enough; navigation and abilities handle low-level details.
Stale actions and fallback
Targets die, cooldowns start, routes block, and perception changes. Treat staleness as normal in a real-time game. Discard the result, rebuild state, and continue with a deterministic policy. For API implementation, read JEV API usage. For NPC architecture, see JEV NPC.
A useful action schema
Represent each action as data with an ID, intent, parameters, preconditions, estimated duration, resource cost, and executor. The ID should be stable for the current snapshot, while target and location references should be explicit. This gives designers and QA a shared vocabulary for discussing behavior.
{ id: 'cover-wall-a', intent: 'takeCover', target: { coverId: 'wall-a' }, cost: { timeMs: 900 }, preconditions: ['reachable', 'notOccupied'] }Prune before you rank
Hard constraints belong before model evaluation. Remove actions that violate range, cooldown, ownership, visibility, navigation, or multiplayer rules. Only then should JEV compare softer trade-offs such as safety, objective pressure, resource conservation, and team coordination. This reduces noise and makes the result easier to explain.
When the action space is large
Use a two-stage design: first score or filter candidates into a small frontier, then choose one action. For example, game code can generate twenty visible cover points, JEV can score their tactical value, and a deterministic policy can keep the best three before a final Choice. Navigation still owns path validity.
Action-space design is game balance
Adding an action changes the NPC's strategy space. Adding retreat may make a guard survive longer; adding assist may improve squad cohesion but delay the objective. Version the action vocabulary, replay representative encounters, and ask designers to review not only whether an action is legal but also whether it creates the intended trade-off.
Contract tests
- Every candidate has a handler.
- Every handler checks current preconditions again.
- Unknown action IDs fail closed.
- Parameter types and target ownership are validated.
- Stale candidates are rejected in replay and live tests.
- The fallback remains legal when the candidate list is empty.
