Pacman-Core

Projeto desenvolvido no âmbito de uma Iniciação Científica (PIBIC/PIBITI CNPq 2025-2026) no CEFET-MG. O repositório contém a implementação de um jogo 2D estilo Pac-Man com arquitetura modular, concebida para permitir a integração de técnicas de Inteligência Artificial em camadas separadas.

Contexto da Iniciação Científica

• Título do projeto: Desenvolvimento de Jogos Arcade com Integração de Técnicas de Inteligência Artificial: Uma Abordagem Experimental
• Coordenador: Anderson Grandí Pires (CEFET-MG, campus Leopoldina)
• Equipe: bolsistas voluntários e PIBIC responsáveis pela implementação dos jogos Snake e Pac-Man.
• Objetivo geral: investigar e aplicar técnicas de IA em jogos arcade, desenvolvendo agentes capazes de interagir e aprender em ambientes simulados.
• Palavras-chave: Agentes inteligentes, Arcade, Inteligência Artificial, Jogos digitais.

O foco deste repositório é a implementação do jogo.

Estrutura do projeto

LICENSE
README.md
requirements.txt
data/
    images/
    settings/
        config.json
        default_maze.txt
    sounds/
src/
    main.py
    application/
        game_loop.py
        ghost_director.py
    controllers/
        input_controller.py
    domain/
        entities/
            pacman.py
            blinky.py
            pinky.py
            inky.py
            clyde.py
        services/
            movement_service.py
            collision_service.py
            interaction_service.py
        world/
            maze.py
        states.py
    infrastructure/
        assets/
        audio/
        config/
        rendering/
        tests/

Principais componentes

• main.py: inicialização, carregamento de configurações e assets, laço principal de jogo.
• application/game_loop.py: lógica do ciclo do jogo (movimentação, colisões, mudanças de estado, eventos).
• domain/services: serviços de movimento, colisão e interação com pellets.
• domain/entities: classes de Pac-Man e fantasmas com comportamento individualizado.
• application/ghost_director.py: alternância entre modos SCATTER e CHASE dos fantasmas.
• controllers/input_controller.py: abstração da entrada do jogador (futuramente substituível por controlador de IA).
• infrastructure/rendering/game_renderer.py: dessina o labirinto e as entidades usando Pygame.

Dependências

O jogo usa Python 3.12 e as seguintes bibliotecas (ver requirements.txt):

• pygame

Instale com:

python -m venv venv
source venv/bin/activate     # macOS/Linux
# ou venv\\Scripts\\activate  # Windows
pip install -r requirements.txt

Executando o jogo

python -m src.main

O arquivo de configurações data/settings/config.json permite ajustar parâmetros como velocidade, tempos de modo, alvos dos fantasmas, entre outros. O labirinto padrão encontra-se em data/settings/default_maze.txt.

Como Jogar

O objetivo principal é acumular a maior pontuação possível comendo todos os pontos espalhados pelo labirinto sem ser capturado pelos fantasmas.

Mecânicas Principais

• Pontos (Pac-Dots): Itens comuns que aumentam a pontuação. O nível termina quando todos são coletados.
• Pastilhas de Força (Power Pellets): Itens maiores situados nos cantos do mapa. Ao comê-los, os fantasmas ficam vulneráveis temporariamente (ficam azuis) e podem ser comidos pelo Pac-Man para pontos extras.

Controles

• Seta para Cima: Move o Pac-Man para cima.
• Seta para Baixo: Move o Pac-Man para baixo.
• Seta para Esquerda: Move o Pac-Man para a esquerda.
• Seta para Direita: Move o Pac-Man para a direita.

Os Fantasmas

Cada fantasma possui uma "personalidade" e um algoritmo de perseguição distinto, tornando o jogo estratégico:

1. Blinky (Vermelho):

   • É o perseguidor direto.
   • Ele persegue o Pac-Man incansavelmente, mirando diretamente na posição atual do jogador.
   • Geralmente é o fantasma mais agressivo.

2. Pinky (Rosa):

   • É o emboscador.
   • Ele tenta prever o movimento do jogador, mirando em uma posição à frente de onde o Pac-Man está indo.
   • O objetivo dele é cercar o jogador, não apenas segui-lo.

3. Inky (Ciano):

   • É o estrategista imprevisível.
   • A posição alvo dele é calculada com base na posição do Pac-Man e na posição do Blinky.
   • Isso faz com que seus movimentos pareçam erráticos, ora cercando o jogador, ora perseguindo diretamente.

4. Clyde (Laranja):

   • É o "covarde" ou indeciso.
   • Se ele estiver longe do Pac-Man, ele persegue como o Blinky.
   • Se ele chegar muito perto do Pac-Man (menos de 8 blocos de distância), ele desiste da perseguição e foge para o canto inferior esquerdo do labirinto.

Organização e documentação

• Cada módulo e classe possui docstrings descrevendo responsabilidades e contratos.
• O README apresenta visão geral e instruções de uso.
• O projeto está estruturado para facilitar a extensão; por exemplo, a troca do controlador do Pac-Man por um agente de Q-learning é suportada sem alterações no laço principal.

Futuras melhorias

• Implementar testes automatizados mais abrangentes (src/infrastructure/tests).
• Adicionar um config/schema.py ou usar pydantic para validar o config.json.

Licença

Este código está licenciado sob a MIT License.