Uma integração JEV API útil é um pequeno serviço de decisão em torno de um grande sistema de jogo. O jogo possui o mundo oficial, traduz-o em um estado compacto e torna as ações permitidas agora. JEV avalia essa questão limitada; o executor valida a resposta e executa a ação.
O pipeline de integração
Game State -> Legal Actions -> Typed Question -> JEV -> Validate -> Execute or Fallback1. Projeto compacto Game State
Envie fatos que possam mudar a próxima decisão: função, saúde, ameaças visíveis, objetivo, recursos, tempos de espera, cobertura, intenção atual e uma versão monotônica do estado. Não envie todo o gráfico do objeto do mecanismo e não vaze informações ocultas que NPC não conseguiu perceber.
{ agentId: 'guard-07', healthRatio: 0.42, visibleThreats: 1, ammo: 3, stateVersion: 1842 }2. Definir Legal Actions
Cada candidato precisa de um nome estável, parâmetros explícitos, pré-condições e um proprietário de execução. Por exemplo: takeCover(coverId), attack(targetId), ou holdPosition(locationId). Construa a lista a partir do estado oficial; não peça a JEV para inventar IDs, rotas, habilidades ou parâmetros.
3. Escolha o primitivo
Use Choice quando um candidato deve ser selecionado, Score quando os candidatos precisam de classificação e um julgamento limitado de sim ou não quando a questão é uma porta, como abandonar um objetivo. Use a menor primitiva que corresponda à pergunta.
4. Ligue e valide
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);O método SDK exato pode variar. As invariantes não: comparam versões de estado, revalidam parâmetros e rejeitam resultados que não são mais legais. Uma resposta pode ficar obsoleta enquanto uma solicitação está em andamento.
5. Lidar com confiança
Se a resposta incluir probabilidade ou confiança, use-a como um sinal de política, não como permissão para ignorar a validação. A baixa confiança pode desencadear uma política local conservadora ou preservar a intenção atual.
6. Defina a cadência e fallback
Invoque eventos significativos ou um cronômetro tático limitado, não todos os quadros de renderização. Dê um prazo a cada solicitação. No tempo limite, mantenha uma ação segura ou use um fallback específico da função, como proteger-se, manter posição, seguir ou uma árvore de comportamento de autoria. Limite de uma decisão durante o voo por agente, a menos que o cancelamento e o pedido sejam explícitos.
7. Teste o contrato
Registre o estado projetado, Legal Actions, resposta, latência, versão do estado, resultado da validação, resultado da execução e motivo fallback. Repita a saúde baixa, sem munição, múltiplas ameaças, alvos perdidos, ações interrompidas e falha de serviço. Meça a qualidade da decisão, a latência, a taxa de resultados inválidos e a taxa fallback separadamente.
Elaborar o contrato de solicitação
Uma solicitação de produção deve conter uma versão do esquema, identidade do agente, versão do estado, projeção de estado permitida, Legal Actions, primitiva de decisão, objetivo, prazo e ID de correlação. Mantenha o objetivo curto e estável. Coloque restrições rígidas no código e nos dados, em vez de depender de um parágrafo de instruções.
{ schemaVersion: 'npc-decision-v1', agentId, stateVersion, state, legalActions, primitive: 'choice', deadlineMs, requestId }Elaborar o contrato de resposta
A resposta deve identificar o candidato selecionado ou Score, a versão do estado observado, confiança ou probabilidade quando disponível e o status do provedor. Trate a explicação como telemetria opcional, não como um campo de execução. O executor deve ser capaz de validar a ação sem analisar a prosa.
Tratamento de erros que mantém o jogo vivo
| Condição | Ação _ |
|---|---|
| Tempo limite | Ignorar a resposta e use o específico da função fallback |
| Inválido esquema | Registre o erro do contrato e falhe fechado |
| Obsoleto version | Descartar ou revalidar de acordo com a ação atual set |
| Provedor falha | Faça uma pequena espera e continue localmente |
| Repetido falha | Desativar decisões remotas para o agente e superfície telemetria |
Reprodução e observabilidade
Persistir informações suficientes para reproduzir uma decisão: estado projetado, Legal Actions, esquema de pergunta, resposta do modelo, carimbos de data/hora, versões de estado, resultado de validação, comando executado, resultado e razão fallback. Edite dados e segredos do jogador. Um recurso de repetição permite que os designers comparem um novo prompt ou provedor com os mesmos cenários sem carregar o jogo inteiro.
Onde o API deve parar
O API deveria retornar uma decisão, não transformar o mundo. Mantenha gravações de inventário, danos, autoridade de movimento e alterações de estado multijogador atrás do servidor ou mecanismo do jogo. Este limite torna as novas tentativas mais seguras e evita que uma solicitação duplicada aplique um efeito de jogo duas vezes.
Para um fluxo NPC completo, consulte JEV tutorial. Para design de espaço de ação, leia JEV Legal Actions. Para Unity, continue para JEV Unity tutorial.
