insolito

🇧🇷 Português | 🇺🇸 English

Um motor de jogo top-down em Pygame com um NPC controlado por um agente de IA generativa (Google Gemini).

Visão geral

insolito é um protótipo de jogo top-down de puzzle/aventura construído sobre Pygame, cuja característica central é um NPC autônomo controlado por um LLM (Google Gemini, via LangChain). Diferente de um NPC com IA scriptada, o agente recebe em tempo real o estado dos desafios do jogo e decide quando falar com o jogador, fazer perguntas ou se deslocar até um objetivo.

O projeto é um playground para estudar a integração de agentes de IA generativa dentro do game loop — não uma engine reutilizável genérica.

Arquitetura

launch.py                  # Game loop principal (init Pygame, eventos, update)
settings.py                # Constantes globais (TILESIZE, distâncias, etc.)
game/
├── core/
│   ├── core.py            # Entity, Camera e utilitários base
│   ├── camera.py          # Câmera com suavização (lerp)
│   └── debug.py           # Overlay de debug
├── level/
│   ├── level.py           # Construção do mapa e grupos de sprites
│   └── tile.py            # Carregamento de tiles do tilemap
├── player/
│   └── player.py          # Player, NPC, Inventory, Item, Door, Key, LogicGate...
├── challenges/
│   ├── challenges.py      # Step e Challenge (grafo de dependências de objetivos)
│   └── game_progress.py   # Rastreio de progresso + callbacks
├── pathfinding/
│   └── pathfinding.py     # A* sobre grid (heurística Manhattan)
└── agent/
    └── agent.py           # AgentManager: LangChain + Gemini, tools do NPC

Componentes notáveis

• Agente LLM em tempo real — o AgentManager expõe ferramentas ao modelo (send_message, ask_question, go_to_player, go_to_specific_step) e é acionado por gatilhos: a cada ~30s, ao concluir um step crítico, ou quando o jogador se afasta demais do NPC.
• Sistema de desafios em grafo — Step e Challenge formam um grafo de dependências; um objetivo só fica disponível quando seus pré-requisitos são concluídos.
• Pathfinding A* — navegação do NPC em grid com heurística de Manhattan.
• Câmera suavizada — interpolação (lerp) ao seguir o jogador.
• Inventário — 7 slots, seleção por teclas numéricas, drop direcional.
• Objetos lógicos — LogicGate, NegationPortal, TotemItem (alternam ativo/inativo), Door + Key.

Como executar

pip install pygame langchain langchain-google-genai python-dotenv
# Crie um arquivo .env a partir do exemplo:
cp .env.example .env
# Edite .env e coloque sua GOOGLE_API_KEY
python launch.py

Controles: WASD mover · E interagir · Q dropar item · 1–7 selecionar slot · N NPC seguir/parar · M NPC seguir objetivos.

Estado do projeto

Protótipo funcional. O jogo roda (colisão, inventário, objetivos e o agente respondem), mas é código de pesquisa/experimentação:

• Não há requirements.txt / pyproject.toml — dependências instaladas manualmente.
• Sem áudio, animação de sprites, ou tela de salvar/carregar.
• Alguns componentes (EntityManager, EventManager) estão definidos mas não totalmente integrados.
• A chave do Gemini é lida de GOOGLE_API_KEY no seu .env (não versionado — veja .env.example).

Licença

Este projeto ainda não declara uma licença; até que uma seja adicionada, todos os direitos são reservados ao autor.