Referência da API

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

Módulos Principais

Módulo Models

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

class models.player.Player(id_jogador, nome, vida_maxima, vida_atual, forca, localizacao, nivel, experiencia)[source]

Bases: object

Model que representa um personagem no banco de dados

Variables:

id_jogador (int | None) – 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

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_jogador: int | None

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

Model do 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

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

models.mapa.exemplo_uso_repository()[source]: Exemplo de como usar o Mapa com Repository Pattern

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

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

Player

class models.player.Player(id_jogador, nome, vida_maxima, vida_atual, forca, localizacao, nivel, experiencia)[source]

Bases: object

Model que representa um personagem no banco de dados

Variables:

id_jogador (int | None) – 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

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_jogador: int | None

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

Chunk

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

Mapa

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

Bioma

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

Módulo Repositories

PlayerRepository

ChunkRepository

MapaRepository

BiomaRepository

Módulo Services

InterfaceService

GameService

Módulo player_manager

PlayerSession

Funções de Gerenciamento

Funções de Exibição

Módulo db_helpers

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

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_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 dados básicos

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

Conexão com Banco

utils.db_helpers.connection_db()[source]

Execução de SQL

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

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

Inicialização

utils.db_helpers.initialize_database()[source]: Inicializa o banco de dados com dados básicos

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

Módulo display

Interface Principal

Funções de Jogo

Gerenciamento de Personagens

Utilitários

Módulo Utils

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

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_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 dados básicos

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

Conexão com Banco

utils.db_helpers.connection_db()[source]

Execução de SQL

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

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

Inicialização

utils.db_helpers.initialize_database()[source]: Inicializa o banco de dados com dados básicos

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

Estrutura de Dados

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

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

Mapa

A classe Mapa representa um mapa do jogo:

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

Bioma

A classe Bioma representa um tipo de bioma:

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

Padrões de Uso

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)

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)

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()

Próximos Passos

Para mais informações:

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