Open Sourcing the Magnificent Escape Action

Leon Nicholls em Google Developers Follow 14 de maio · 8 min ler

Em um post anterior , discuti o design e a implementação do meu jogo Magnificent Escape para o Google Assistente. Recebi muitas perguntas sobre o código e o agente Dialogflow. Então, decidi abrir o código do jogo.

Vou explicar como o projeto é organizado e também discutir os últimos aprendizados do jogo neste post.

Repo Github

O agente Dialogflow e o código fonte de atendimento do jogo estão disponíveis no GitHub . Alguns dos principais arquivos incluem:

  • app.js – o principal ponto de entrada para o aplicativo Node.js, que inicia um servidor da Web para lidar com o cumprimento do agente Dialogflow.
  • fulfillment.js – o ponto final do cumprimento principal do servidor da web.
  • game.js – funções para gerenciar a lógica e o estado do jogo.
  • rooms.json – a estrutura de dados JSON para as salas do jogo.
  • prompts.js – os prompts usados nas respostas para o usuário.
  • analytics.js – uma classe de utilitário para enviar eventos ao Google Analytics.

utils.js – uma coleção de funções utilitárias para manipular correspondência de intenção e geração de resposta.

Cumprimento

A ação é implementada no Dialogflow e seu preenchimento do Node.js é implantado no Google App Engine . Eu usei o App Engine para outros projetos grandes e ele tem sido confiável e executado extremamente bem em grande escala.

meios de comunicação

Como mencionei em meus posts anteriores sobre este jogo, comprei áudio livre de royalties das músicas do Pond5 e do Getty Images . No entanto, não tenho o direito de distribuir esses sons. Por isso, removi todos eles do código de código aberto e os substituímos por sons gratuitos da biblioteca de sons do Actions on Google.

Há também várias imagens e ícones que substituímos pelo conteúdo licenciado da Wikimedia pela Creative Commons.

O código fonte

A versão mais recente do Action tem mais de 6.000 linhas de código. Originalmente, a lógica de preenchimento principal para os manipuladores de intenção era tudo em um único arquivo Node.js, que funcionava bem para um pequeno número de intenções. Mas, à medida que o número de intenções aumentava, isso se tornou menos administrável.

A biblioteca cliente Actions on Google Node.js não fornece uma boa maneira de modularizar os manipuladores de intenção em arquivos Node.js separados. Dois dos exemplos de Ações no Google Github fornecem suas próprias soluções de roteamento personalizadas para isso: o Number Genie e a Ação de I / O. Como eu tinha o objetivo de abrir o código do jogo e garantir que o código fosse reutilizável para outras ações, decidi evitar essas soluções personalizadas.

Um aspecto da evolução do jogo que ajudou a tornar o código mais modular foi a lógica de preenchimento de slots personalizada. Isso exigia a introdução de funções auxiliares, que poderiam então ser movidas para outro arquivo para reduzir a contagem de linhas do arquivo principal de atendimento. Outras funções de utilidade também foram combinadas em outro arquivo para reduzir ainda mais a contagem de linhas.

Eu não estava completamente satisfeito com a forma como o design acabou e ia passar algum tempo modularizando o código ainda mais, mas as várias opções que considerei só tornariam o código mais obscuro e menos útil para outros desenvolvedores aprenderem e reutilizarem. . Uma solução melhor pode ser ter uma opção de roteamento incorporada na biblioteca cliente que suporte ações maiores. Um problema relacionado é que o Dialogflow também poderia fazer um trabalho melhor ao permitir que as intenções fossem agrupadas em vez de apenas fornecer uma lista longa.

O agente Dialogflow

O agente Dialogflow tem 122 intenções e 12 entidades. Para fazer o trabalho de preenchimento de slots personalizado (que discuto no meu primeiro post ), criei uma intenção para cada tipo de dado de slot e designei cada um seu próprio contexto, que é ativado dinamicamente em cumprimento. A prioridade de intenção dessas tentativas de preenchimento de slot também está definida para estar no nível mais alto, para que quaisquer outras intenções com frases do usuário semelhantes não sejam selecionadas pelo Dialogflow enquanto o contexto associado estiver ativo.

Aqui está uma das intenções do slot para obter um valor de direção do usuário:

As entidades cobrem todos os tipos de dados que o jogo precisa obter do usuário para explorar as salas e alterar o estado dos vários itens:

Para cada um desses, desativei a configuração "Permitir expansão automática", pois recebi algumas correspondências inesperadas, mas sua milhagem pode variar.

Dados dos quartos

Os dados das salas são armazenados em um único arquivo JSON estático. Como os dados da sala não iam mudar com frequência, não havia necessidade de usar um banco de dados.

Cada quarto tem os seguintes recursos:

  • Metadados que descrevem cada sala (por exemplo, nome, nível).
  • Recursos para dispositivos de tela (por exemplo, URLs para imagens).
  • Um conjunto de recompensas: os usuários são recompensados com dicas enquanto exploram a sala.
  • Um conjunto de direções: norte, sul, leste, oeste, cima, baixo.
  • Cada direção tem uma descrição e pelo menos um item.
  • Um conjunto de itens: itens que estão na sala e que o usuário pode ver e interagir.
  • Cada item suporta várias ações (por exemplo, olhar, mover, usar, etc.).
  • Cada item tem um estado e também pode depender do estado de outros itens.
  • Interagir com um item pode alterar o estado do item e pode revelar outros itens (por exemplo, abrir uma gaveta, encontrar uma ferramenta).
  • Os usuários podem coletar itens encontrados e adicioná-los ao inventário.
  • Itens no inventário podem ser usados em outros itens da sala (por exemplo, use a chave de fenda no parafuso).
  • Itens especiais, como cofres, têm uma solução que o usuário precisa resolver (por exemplo, um número de voltas diferentes do mostrador).
  • Há ovos de páscoa escondidos em cada quarto, que recompensam o usuário com uma dica especial.
  • Interagir com determinados itens permitirá que o usuário escape da sala (por exemplo, destranque a porta).

Eu tinha pensado em dividir os dados de cada item para que eles pudessem ser reutilizados em todos os quartos. Para o conjunto atual de salas, há variações nos itens em cada sala, então eu não teria obtido muito benefício em tal projeto. No entanto, se um número maior de salas precisar de suporte, a modularização das definições da sala provavelmente será necessária.

Análise de jogabilidade

Com base nos dados do Google Analytics, as principais intenções do Dialogflow correspondentes à primeira sala, o escritório, estão em ordem de uso:

  1. Direção – para olhar em uma direção específica (por exemplo, "Eu quero olhar para o leste")
  2. Procure um item em particular (por exemplo, “olhe para a mesa”)
  3. Turns – para girar o dial do cofre (por exemplo, “gire para a direita”)
  4. Aberto – para itens de abertura (por exemplo, “abrir a gaveta”)
  5. Lado – para observar os vários lados dos itens (por exemplo, “olhe para trás da pintura”)
  6. Sugestão – para obter uma sugestão de jogar o jogo (por exemplo, "dê-me uma dica")
  7. Fallback padrão – para manipular qualquer entrada do usuário que não corresponda a quaisquer outras intenções.

Os resultados para as outras salas são semelhantes, mas a intenção de “Dica” é invocada menos.

Eu ainda acho muito encorajador o quanto alguns usuários tentam ganhar cada quarto. Alguns usuários levam horas explorando cada quarto. A maioria dos usuários que ganharam o primeiro quarto leva menos de 20 minutos, e eu suponho que esses usuários estejam mais familiarizados com o gênero e a mecânica do jogo.

Para o lobby, é interessante ver como os usuários escolhem um quarto. Isso corresponde à nossa experiência com os usuários de modelos, onde descobrimos que os usuários selecionarão as respostas às perguntas de várias maneiras. Isso inclui a seleção de opções por posição ou até mesmo a atribuição de valores parciais de opções. Mesmo que você restrinja a maneira como espera que o usuário selecione as opções, descobrimos que os usuários não seguem as instruções e apenas querem responder às perguntas de maneira normal. Então, para este jogo, há intenções para “o quarto”, “o primeiro” e “número dois”.

Curiosamente, a intenção “Sem entrada” aparece entre as 10 principais intenções para o lobby. O jogo implementa boas técnicas de recuperação de erros para alertar novamente o usuário para selecionar uma sala.

Também é muito interessante que a intenção de “Cancelar” não tenha uma alta taxa de acerto para o lobby. Isso significa que a maioria dos usuários escolhe uma sala e experimenta o jogo.

Estou muito feliz com o desempenho do Protocolo de Medição do Google Analytics para rastrear vários eventos e dados no jogo. Se alguma coisa, eu deveria estar rastreando ainda mais aspectos do jogo. Você pode ler mais sobre como usar o Google Analytics na minha postagem " Analytics for Actions ".

Reflexão sobre o projeto

Foi muito gratificante trabalhar em um projeto que é muito maior do que as amostras típicas que minha equipe cria para desenvolvedores em minha função como Engenheiro de Relações com o Desenvolvedor no Google. Eu encontrei muitos problemas e criei várias soluções. Estes foram repassados para nossas equipes de produtos e engenharia para ajudar a melhorar nossa experiência de desenvolvedor.

Também tem sido encorajador ver as reações dos desenvolvedores em meus posts anteriores sobre o projeto e como isso os ajudou com vários problemas de produção que eles encontraram.

Eu ainda acho que fazer um jogo de escapar da sala foi um bom gênero para implementar como uma ação. Jogos semelhantes tiveram sucesso em outras plataformas de voz. Além disso, é uma mecânica de jogo simples que pode ser rapidamente aprendida por usuários iniciantes. Eu estava particularmente interessado em quão bem isso funcionaria em um dispositivo somente de áudio, e fiquei muito satisfeito com o resultado final.

Criando uma produção pronta Ação que segue as melhores práticas é um esforço substancial que requer um grande número de intenções e lógica de preenchimento associada. Isso também requer uma variedade de conhecimentos, especialmente em relação ao design de conversas , com os quais a maioria dos desenvolvedores não está familiarizada. No entanto, o esforço pode proporcionar uma experiência envolvente para os usuários, mesmo nesse estágio inicial das plataformas de voz.

Ao abrir o código do jogo, espero que isso incentive mais desenvolvedores a experimentar o Actions. Realmente pode ser muito divertido! Encorajo-o a aceitar o máximo de código e as intenções do Dialogflow que você precisa para suas próprias ideias, e esperamos que você também compartilhe suas experiências com seus colegas desenvolvedores.

Você pode encontrar minha equipe e eu no Reddit e Stack Overflow .

Quero mais? Participe do programa da comunidade de desenvolvedores do Actions on Google e você poderá ganhar um crédito mensal de US $ 200 do Google Cloud e uma camiseta do Assistente ao publicar seu primeiro aplicativo.