Modelos

O MINECRAFT - FGA - 2025/1 utiliza uma arquitetura baseada em models para representar as entidades do jogo. Esta abordagem garante separação de responsabilidades, reutilização de código e facilita a manutenção.

Estrutura de Models

app/src/models/
├── __init__.py          # Exporta todas as models
├── player.py            # Model do personagem
├── chunk.py             # Model do chunk
├── bioma.py             # Model do bioma
├── mapa.py              # Model do mapa
└── example_usage.py     # Exemplos de uso

PlayerSession

A model PlayerSession representa um personagem ativo na sessão do jogo.

class models.player.PlayerSession(id_jogador, nome, vida_max, vida_atual, xp, forca, id_chunk_atual=None, chunk_bioma=None, chunk_mapa_nome=None, chunk_mapa_turno=None)[source]

Bases: object

Model que representa um personagem ativo na sessão do jogo

Variables:

id_jogador (int) – ID único do personagem no banco
nome (str) – Nome do personagem
vida_max (int) – Vida máxima do personagem
vida_atual (int) – Vida atual do personagem
xp (int) – Experiência acumulada
forca (int) – Força do personagem
id_chunk_atual (int | None) – ID do chunk onde o personagem está
chunk_bioma (str | None) – Nome do bioma atual (cache para performance)
chunk_mapa_nome (str | None) – Nome do mapa atual (cache para performance)
chunk_mapa_turno (str | None) – Turno atual (Dia/Noite) (cache para performance)

__repr__()[source]

Representação detalhada do personagem

__str__()[source]

Representação string do personagem

can_move()[source]

Verifica se o personagem pode se mover

Returns:: True se pode se mover
Return type:: bool

chunk_bioma: str | None = None

chunk_mapa_nome: str | None = None

chunk_mapa_turno: str | None = None

forca: int

gain_xp(amount)[source]

Adiciona experiência ao personagem

Parameters:: amount (int) – Quantidade de XP a ser adicionada

get_health_bar(width=20)[source]

Retorna uma barra de vida visual

Parameters:: width (int) – Largura da barra em caracteres
Returns:: String representando a barra de vida
Return type:: str

get_health_percentage()[source]

Retorna a porcentagem de vida atual

Returns:: Porcentagem de vida (0.0 a 1.0)
Return type:: float

get_location_display()[source]

Retorna a localização formatada para exibição

Returns:: String formatada da localização
Return type:: str

heal(amount)[source]

Cura o personagem

Parameters:: amount (int) – Quantidade de vida a ser restaurada

id_chunk_atual: int | None = None

id_jogador: int

is_alive()[source]

Verifica se o personagem está vivo

nome: str

take_damage(damage)[source]

Aplica dano ao personagem

Parameters:: damage (int) – Quantidade de dano a ser aplicado
Returns:: True se o personagem ainda está vivo após o dano
Return type:: bool

to_dict()[source]

Converte o personagem para dicionário

vida_atual: int

vida_max: int

xp: int

Exemplo de uso:

from src.models.player import PlayerSession

# Criar um personagem
player = PlayerSession(
    id_jogador=1,
    nome="Steve",
    vida_max=100,
    vida_atual=85,
    xp=150,
    forca=12,
    id_chunk_atual=5,
    chunk_bioma="Floresta",
    chunk_mapa_nome="Mapa_Principal",
    chunk_mapa_turno="Dia"
)

# Verificar se está vivo
if player.is_alive():
    print("Personagem está vivo!")

# Aplicar dano
sobreviveu = player.take_damage(20)

# Exibir barra de vida
print(player.get_health_bar())

Chunk

A model Chunk representa um chunk do mapa do jogo.

class models.chunk.Chunk(numero_chunk, id_bioma, id_mapa_nome, id_mapa_turno)[source]

Bases: object

Model que representa um chunk do mapa

Variables:

numero_chunk (int) – ID único do chunk (chave primária)
id_bioma (str) – Nome do bioma do chunk (FK para Bioma.NomeBioma)
id_mapa_nome (str) – Nome do mapa (parte da FK para Mapa)
id_mapa_turno (str) – Turno do mapa (parte da FK para Mapa)

__eq__(other)[source]

Comparação de igualdade baseada na chave primária

__hash__()[source]

Hash baseado na chave primária

__repr__()[source]

Representação detalhada do chunk

__str__()[source]

Representação string do chunk

belongs_to_map(mapa_nome, mapa_turno)[source]

Verifica se o chunk pertence a um mapa específico

Parameters:

mapa_nome (str) – Nome do mapa
mapa_turno (str) – Turno do mapa

Returns:

True se o chunk pertence ao mapa

Return type:

bool

get_adjacent_chunk_ids(map_size=32)[source]

Retorna os IDs dos chunks adjacentes Baseado na lógica de grid do mapa

Parameters:: map_size (int) – Tamanho do mapa (assumindo mapa quadrado)
Returns:: Lista de IDs dos chunks adjacentes
Return type:: List[int]

get_bioma_type()[source]

Retorna o tipo de bioma como string

Returns:: Nome do bioma
Return type:: str

get_display_name()[source]

Retorna o nome formatado do chunk para exibição

Returns:: String formatada do chunk
Return type:: str

get_map_key()[source]

Retorna a chave do mapa como tupla

Returns:: Tupla (nome_mapa, turno_mapa)
Return type:: tuple

id_bioma: str

id_mapa_nome: str

id_mapa_turno: str

is_day()[source]

Verifica se é dia no chunk

is_desert()[source]

Verifica se o chunk é um deserto

is_forest()[source]

Verifica se o chunk é uma floresta

is_jungle()[source]

Verifica se o chunk é uma selva

is_night()[source]

Verifica se é noite no chunk

is_ocean()[source]

Verifica se o chunk é um oceano

numero_chunk: int

Exemplo de uso:

from src.models.chunk import Chunk

# Criar um chunk
chunk = Chunk(
    numero_chunk=1,
    id_bioma="Floresta",
    id_mapa_nome="Mapa_Principal",
    id_mapa_turno="Dia"
)

# Verificar tipo de bioma
if chunk.is_forest():
    print("É uma floresta!")

# Verificar se pertence a um mapa
if chunk.belongs_to_map("Mapa_Principal", "Dia"):
    print("Pertence ao mapa principal de dia!")

# Obter chunks adjacentes
adjacentes = chunk.get_adjacent_chunk_ids()

Bioma

A model Bioma representa um bioma do jogo.

class models.bioma.Bioma(nome)[source]

Bases: object

Model que representa um bioma do jogo

Variables:: nome (str) – Nome do bioma (chave primária - NomeBioma)

__eq__(other)[source]

Comparação de igualdade baseada na chave primária

__hash__()[source]

Hash baseado na chave primária

__repr__()[source]

Representação detalhada do bioma

__str__()[source]

Representação string do bioma

nome: str

class models.bioma.BiomaType(value)[source]

Bases: Enum

Tipos de bioma disponíveis no jogo

DESERTO = 'Deserto'

FLORESTA = 'Floresta'

OCEANO = 'Oceano'

SELVA = 'Selva'

Biomas Predefinidos:

from src.models.bioma import BIOMAS_PREDEFINIDOS, BiomaType

# Usar bioma predefinido
deserto = BIOMAS_PREDEFINIDOS[BiomaType.DESERTO]

# Obter tipo enum
tipo = deserto.get_bioma_type()

# Obter informações para exibição
info = deserto.get_display_info()

Mapa

A model Mapa representa um mapa do jogo com seus chunks e características.

class models.mapa.Mapa(nome, turno)[source]

Bases: object

Model que representa um mapa do jogo

Variables:

nome (str) – Nome do mapa (parte da chave primária composta)
turno (models.mapa.TurnoType) – Turno do mapa (parte da chave primária composta)
_chunk_repository – Repository para acesso aos chunks (injetado)

__eq__(other)[source]

Comparação de igualdade baseada na chave primária composta

__hash__()[source]

Hash baseado na chave primária composta

__post_init__()[source]: Converte string para enum se necessário

__repr__()[source]

Representação detalhada do mapa

__str__()[source]

Representação string do mapa

get_bioma_distribution()[source]

Retorna a distribuição de biomas no mapa

Returns:: Dicionário com bioma e quantidade de chunks
Return type:: Dict[str, int]

get_chunk_by_id(chunk_id)[source]

Busca um chunk pelo ID neste mapa

Parameters:: chunk_id (int) – ID do chunk
Returns:: Chunk encontrado ou None
Return type:: Chunk | None

get_chunks()[source]

Retorna os chunks deste mapa usando o repository

get_chunks_by_bioma(bioma)[source]

Retorna todos os chunks de um bioma específico neste mapa

Parameters:: bioma (str) – Nome do bioma
Returns:: Lista de chunks do bioma
Return type:: List[Chunk]

get_display_info()[source]

Retorna informações formatadas do mapa para exibição

Returns:: Dicionário com informações do mapa
Return type:: Dict[str, Any]

is_day_map()[source]

Verifica se é um mapa de dia

is_night_map()[source]

Verifica se é um mapa de noite

nome: str

set_chunk_repository(repository)[source]: Define o repository de chunks (injeção de dependência)

turno: TurnoType

class models.mapa.TurnoType(value)[source]

Bases: Enum

Tipos de turno disponíveis

DIA = 'Dia'

NOITE = 'Noite'

Exemplo de uso:

from src.models.mapa import Mapa, TurnoType
from src.models.chunk import Chunk

# Criar mapa
mapa = Mapa(
    nome="Mapa_Principal",
    turno=TurnoType.DIA
)

# Criar chunks
chunks = [
    Chunk(1, "Deserto", "Mapa_Principal", "Dia"),
    Chunk(2, "Floresta", "Mapa_Principal", "Dia"),
]

# Associar chunks ao mapa
mapa.set_chunks(chunks)

# Buscar chunk por ID
chunk = mapa.get_chunk_by_id(1)

# Obter distribuição de biomas
distribuicao = mapa.get_bioma_distribution()

Relacionamentos do Banco de Dados

As models refletem exatamente a estrutura do banco de dados:

Mapa (Nome, Turno) ← Chunk (Id_mapa_nome, Id_mapa_turno)
Bioma (NomeBioma) ← Chunk (Id_bioma)
Chunk (Numero_chunk) ← Jogador (Id_Chunk_Atual)

Características dos Relacionamentos:

Mapa: Chave primária composta (Nome, Turno)
Bioma: Chave primária simples (NomeBioma)
Chunk: Chave primária simples (Numero_chunk) com FKs para Bioma e Mapa
Jogador: Referencia Chunk através de Id_Chunk_Atual

Integração com o Sistema

As models são utilizadas em conjunto com o sistema de gerenciamento de personagens:

from src.models.player import PlayerSession
from src.utils.player_manager import load_player_by_id, set_current_player

# Carregar personagem do banco
player = load_player_by_id(1)

if player:
    # Definir como personagem ativo
    set_current_player(player)

    # Usar métodos da model
    print(f"Localização: {player.get_location_display()}")
    print(f"Barra de vida: {player.get_health_bar()}")

Vantagens da Arquitetura de Models

Separação de Responsabilidades: Cada model tem responsabilidades bem definidas
Reutilização: Models podem ser usadas em diferentes partes do sistema
Manutenibilidade: Mudanças em uma model não afetam outras partes
Testabilidade: Cada model pode ser testada independentemente
Documentação: Models são auto-documentadas com docstrings
Type Safety: Uso de type hints para melhor desenvolvimento
Fidelidade ao Banco: Models refletem exatamente a estrutura do banco

Exemplos Completos

Para ver exemplos completos de uso das models, execute:

python -m app.src.models.example_usage

Este comando demonstra todas as funcionalidades das models com exemplos práticos baseados na estrutura real do banco de dados.