9. Referência da API

Esta seção documenta as APIs e módulos do MINECRAFT - FGA - 2025/1.

9.1. Módulos Principais

9.2. Módulo Models

Model do Personagem (Player) Representa um personagem do jogo com seus atributos e comportamentos

class models.player.Player(id_player, nome, vida_maxima, vida_atual, forca, localizacao, nivel, experiencia, current_chunk_id=None, inventario=<factory>)[source]

Bases: object

Model que representa um personagem no banco de dados

Variables:

id_player (int) – ID único do personagem no banco
nome (str) – Nome do personagem
vida_maxima (int) – Vida máxima do personagem
vida_atual (int) – Vida atual do personagem
forca (int) – Força do personagem
localizacao (str) – Localização atual do personagem
nivel (int) – Nível do personagem
experiencia (int) – Experiência acumulada

__eq__(other)[source]

Comparação de igualdade baseada no ID

__hash__()[source]

Hash baseado no ID

__post_init__()[source]: Validações após inicialização

__repr__()[source]

Representação detalhada do personagem

__str__()[source]

Representação string do personagem

current_chunk_id: int | None = None

experiencia: int

forca: int

gain_experience(amount)[source]

Adiciona experiência ao personagem

Parameters:: amount (int) – Quantidade de experiência 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

heal(amount)[source]

Cura o personagem

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

id_player: int

inventario: List[InventoryEntry]

is_alive()[source]

Verifica se o personagem está vivo

level_up()[source]

Tenta fazer o personagem subir de nível

Returns:: True se subiu de nível
Return type:: bool

localizacao: str

nivel: int

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

vida_atual: int

vida_maxima: int

class models.player.PlayerSession(id_player, 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_player (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_player: 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

Model do Chunk Representa um chunk do mapa do jogo

class models.chunk.Chunk(id_chunk, id_bioma, id_mapa, x, y)[source]

Bases: object

Model que representa um chunk do mapa

Variables:

id_chunk (int) – Identificador único do chunk (chave primária)
id_bioma (int) – FK para Bioma.id_bioma
id_mapa (int) – FK para Mapa.id_mapa
x (int) – Coordenada X do chunk no grid
y (int) – Coordenada Y do chunk no grid

__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: int

id_chunk: int

id_mapa: int

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

x: int

y: int

Model do Mapa Representa um mapa do jogo com seus chunks e características

class models.mapa.Mapa(id_mapa, nome, turno, chunks=<factory>)[source]

Bases: object

Model que representa um mapa do jogo

Variables:

id_mapa (int) – Identificador único do mapa (chave primária)
nome (str) – Nome do mapa
turno (models.mapa.TurnoType) – Turno do mapa
chunks (List[models.chunk.Chunk]) – Lista de chunks relacionados a este mapa
_chunk_repository – Repository para acesso aos chunks (injeção de dependência)

__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

chunks: List[Chunk]

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]

id_mapa: int

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'

Model do Bioma Representa um bioma do jogo com suas características

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

Bases: object

Model que representa um bioma do jogo

Variables:

id_bioma (int) – Identificador único do bioma (chave primária)
nome (str) – Nome do bioma
descricao (str) – Descrição do bioma

__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

descricao: str

id_bioma: int

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'

9.2.1. Player

class models.player.Player(id_player, nome, vida_maxima, vida_atual, forca, localizacao, nivel, experiencia, current_chunk_id=None, inventario=<factory>)[source]

Bases: object

Model que representa um personagem no banco de dados

Variables:

id_player (int) – ID único do personagem no banco
nome (str) – Nome do personagem
vida_maxima (int) – Vida máxima do personagem
vida_atual (int) – Vida atual do personagem
forca (int) – Força do personagem
localizacao (str) – Localização atual do personagem
nivel (int) – Nível do personagem
experiencia (int) – Experiência acumulada

__eq__(other)[source]

Comparação de igualdade baseada no ID

__hash__()[source]

Hash baseado no ID

__post_init__()[source]: Validações após inicialização

__repr__()[source]

Representação detalhada do personagem

__str__()[source]

Representação string do personagem

current_chunk_id: int | None = None

experiencia: int

forca: int

gain_experience(amount)[source]

Adiciona experiência ao personagem

Parameters:: amount (int) – Quantidade de experiência 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

heal(amount)[source]

Cura o personagem

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

id_player: int

inventario: List[InventoryEntry]

is_alive()[source]

Verifica se o personagem está vivo

level_up()[source]

Tenta fazer o personagem subir de nível

Returns:: True se subiu de nível
Return type:: bool

localizacao: str

nivel: int

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

vida_atual: int

vida_maxima: int

9.2.2. Chunk

class models.chunk.Chunk(id_chunk, id_bioma, id_mapa, x, y)[source]

Bases: object

Model que representa um chunk do mapa

Variables:

id_chunk (int) – Identificador único do chunk (chave primária)
id_bioma (int) – FK para Bioma.id_bioma
id_mapa (int) – FK para Mapa.id_mapa
x (int) – Coordenada X do chunk no grid
y (int) – Coordenada Y do chunk no grid

__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: int

id_chunk: int

id_mapa: int

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

x: int

y: int

9.2.3. Mapa

class models.mapa.Mapa(id_mapa, nome, turno, chunks=<factory>)[source]

Bases: object

Model que representa um mapa do jogo

Variables:

id_mapa (int) – Identificador único do mapa (chave primária)
nome (str) – Nome do mapa
turno (models.mapa.TurnoType) – Turno do mapa
chunks (List[models.chunk.Chunk]) – Lista de chunks relacionados a este mapa
_chunk_repository – Repository para acesso aos chunks (injeção de dependência)

__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

chunks: List[Chunk]

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]

id_mapa: int

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

9.2.4. Bioma

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

Bases: object

Model que representa um bioma do jogo

Variables:

id_bioma (int) – Identificador único do bioma (chave primária)
nome (str) – Nome do bioma
descricao (str) – Descrição do bioma

__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

descricao: str

id_bioma: int

nome: str

9.3. Módulo Repositories

9.3.1. PlayerRepository

9.3.2. ChunkRepository

9.3.3. MapaRepository

9.3.4. BiomaRepository

9.4. Módulo Services

9.4.1. InterfaceService

9.4.2. GameService

9.5. Módulo player_manager

9.5.1. PlayerSession

9.5.2. Funções de Gerenciamento

9.5.3. Funções de Exibição

9.6. Módulo db_helpers

utils.db_helpers.check_data_seeded()[source]: Verifica se os dados iniciais foram inseridos (incluindo novas tabelas)

utils.db_helpers.check_database_connection()[source]: Verifica se é possível conectar ao banco de dados

utils.db_helpers.check_map_with_1000_chunks()[source]: Verifica se o mapa com 1000 chunks já foi criado

utils.db_helpers.check_new_structure_tables()[source]: Verifica se todas as tabelas da nova estrutura existem

utils.db_helpers.check_tables_exist()[source]: Verifica se as tabelas principais existem no banco usando repositórios

utils.db_helpers.connection_db()[source]

utils.db_helpers.execute_sql_file(conn, file_path)[source]: Executa um arquivo SQL no banco de dados

utils.db_helpers.initialize_database()[source]: Inicializa o banco de dados com a nova estrutura organizada

utils.db_helpers.setup_database()[source]: Configura o banco de dados antes da execução da aplicação

9.6.1. Conexão com Banco

utils.db_helpers.connection_db()[source]

9.6.2. Execução de SQL

utils.db_helpers.execute_sql_file(conn, file_path)[source]: Executa um arquivo SQL no banco de dados

9.6.3. Verificações

utils.db_helpers.check_database_connection()[source]: Verifica se é possível conectar ao banco de dados

utils.db_helpers.check_tables_exist()[source]: Verifica se as tabelas principais existem no banco usando repositórios

utils.db_helpers.check_data_seeded()[source]: Verifica se os dados iniciais foram inseridos (incluindo novas tabelas)

9.6.4. Inicialização

utils.db_helpers.initialize_database()[source]: Inicializa o banco de dados com a nova estrutura organizada

utils.db_helpers.setup_database()[source]: Configura o banco de dados antes da execução da aplicação

9.7. Módulo display

9.7.1. Interface Principal

9.7.2. Funções de Jogo

9.7.3. Gerenciamento de Personagens

9.7.4. Utilitários

9.8. Módulo Utils

utils.db_helpers.check_data_seeded()[source]: Verifica se os dados iniciais foram inseridos (incluindo novas tabelas)

utils.db_helpers.check_database_connection()[source]: Verifica se é possível conectar ao banco de dados

utils.db_helpers.check_map_with_1000_chunks()[source]: Verifica se o mapa com 1000 chunks já foi criado

utils.db_helpers.check_new_structure_tables()[source]: Verifica se todas as tabelas da nova estrutura existem

utils.db_helpers.check_tables_exist()[source]: Verifica se as tabelas principais existem no banco usando repositórios

utils.db_helpers.connection_db()[source]

utils.db_helpers.execute_sql_file(conn, file_path)[source]: Executa um arquivo SQL no banco de dados

utils.db_helpers.initialize_database()[source]: Inicializa o banco de dados com a nova estrutura organizada

utils.db_helpers.setup_database()[source]: Configura o banco de dados antes da execução da aplicação

9.8.1. Conexão com Banco

utils.db_helpers.connection_db()[source]

9.8.2. Execução de SQL

utils.db_helpers.execute_sql_file(conn, file_path)[source]: Executa um arquivo SQL no banco de dados

9.8.3. Verificações

utils.db_helpers.check_database_connection()[source]: Verifica se é possível conectar ao banco de dados

utils.db_helpers.check_tables_exist()[source]: Verifica se as tabelas principais existem no banco usando repositórios

utils.db_helpers.check_data_seeded()[source]: Verifica se os dados iniciais foram inseridos (incluindo novas tabelas)

9.8.4. Inicialização

utils.db_helpers.initialize_database()[source]: Inicializa o banco de dados com a nova estrutura organizada

utils.db_helpers.setup_database()[source]: Configura o banco de dados antes da execução da aplicação

9.9. Estrutura de Dados

9.9.1. Player

A classe Player representa um jogador no jogo:

class Player:
    def __init__(self, id_jogador: int, nome: str, vida_max: int,
                 vida_atual: int, xp: int, forca: int,
                 id_chunk_atual: Optional[int] = None):
        self.id_jogador = id_jogador
        self.nome = nome
        self.vida_max = vida_max
        self.vida_atual = vida_atual
        self.xp = xp
        self.forca = forca
        self.id_chunk_atual = id_chunk_atual

Atributos: * id_jogador: ID único do personagem no banco * nome: Nome do personagem * vida_max: Vida máxima * vida_atual: Vida atual * xp: Experiência acumulada * forca: Força do personagem * id_chunk_atual: ID do chunk atual

Métodos: * is_alive(): Verifica se está vivo * take_damage(damage): Aplica dano * heal(amount): Cura o personagem * gain_xp(amount): Adiciona experiência

9.9.2. Chunk

A classe Chunk representa uma divisão do mundo:

class Chunk:
    def __init__(self, numero_chunk: int, id_bioma: str,
                 id_mapa_nome: str, id_mapa_turno: str):
        self.numero_chunk = numero_chunk
        self.id_bioma = id_bioma
        self.id_mapa_nome = id_mapa_nome
        self.id_mapa_turno = id_mapa_turno

9.9.3. Mapa

A classe Mapa representa um mapa do jogo:

class Mapa:
    def __init__(self, nome: str, turno: str):
        self.nome = nome
        self.turno = turno

9.9.4. Bioma

A classe Bioma representa um tipo de bioma:

class Bioma:
    def __init__(self, nome_bioma: str):
        self.nome_bioma = nome_bioma

9.10. Padrões de Uso

9.10.1. Gerenciamento de Jogadores

# Criar jogador
player = Player(1, "João", 100, 100, 0, 10)

# Salvar no banco
saved_player = player_repository.save(player)

# Carregar jogador
loaded_player = player_repository.find_by_id(1)

# Aplicar dano
loaded_player.take_damage(20)

# Salvar alterações
player_repository.save(loaded_player)

9.10.2. Gerenciamento de Chunks

# Buscar chunk
chunk = chunk_repository.find_by_id(1)

# Buscar chunks adjacentes
adjacent_chunks = chunk_repository.find_adjacent_chunks(1, "Dia")

# Mover jogador para chunk
player.id_chunk_atual = chunk.numero_chunk
player_repository.save(player)

9.10.3. Uso dos Services

# Usar InterfaceService
interface_service = InterfaceService()

# Criar jogador via service
player = interface_service.create_player("João", 100, 10)

# Mover jogador
interface_service.move_player_to_chunk(player, 1)

# Obter estatísticas
stats = interface_service.get_player_statistics()

9.11. Próximos Passos

Para mais informações:

Banco de Dados - Estrutura do banco de dados
Desenvolvimento - Guia de desenvolvimento
Contribuindo - Como contribuir