pygutils 0.3.0

Package with utility functions and classes to work with Pygame.

Instalação

Eu recomendo a instalação utilizando o pipenv ou o virtualenv para permitir um gerenciamento melhor das dependências.

pipenv install pygutils

ou

pip install pygutils

Conteúdo

Animation -- Exemplo

class pygutils.animation.Animation(
    frames_sequence: list[pygame.Surface],
    animation_speed: int,
    on_finish: Callable[[], None] | None = None,
    loop: bool = True)

Classe que representa uma animação a partir de uma sequência de frames que são devolvidos em uma certa velocidade baseado no deltatime do jogo. É possível criar animações que são executadas apenas uma vez ou em loop. Além disso, ainda é possível definir um callback que será chamado todas as vezes que a animação for finalizada.

Parâmetros:

frames_sequence: sequência de superfícies que serão animadas; animation_speed: velocidade em que a animação será executada; on_finish: callback executado todas as vezes que a animação é concluída. Nulo por padrão; loop: flag que identifica se a animação deve ser executada continuamente ou apenas uma vez. Verdadeira por padrão.

Métodos e propriedades

property Animation.finished -> bool

• Propriedade que identifica se a animação foi finalizada. Em loops essa propriedade fica verdadeira apenas até a próxima chamada do método update.

Animation.next(self) -> pygame.Surface

• Método que retorna a próxima superfície da sequência.

Animation.reset(self) -> None

• Método que retorna a animação para o estado inicial.

Animation.update(self, delta_time: float) -> None

• Método que atualiza o índice da animação, chama o callback na finalização e reseta automaticamente caso seja uma animação em loop. Esse método deve ser chamado apenas uma vez a cada frame do jogo. O delta_time representa o tempo entre dois frames consecutivos.

Animation.copy(self) -> Animation

• Método que permite que a animação faça uma cópia de si mesma, mantendo os mesmos atributos passados anteriormente na hora da instânciação. A nova animação sempre começa no início dos frames.

Camera -- Exemplo

class pygutils.camera.Camera2D(
        bg_surface: Surface | None,
        camera_delay: Annotated[float, ValueRange(1, 100)],
        *sprites: Any | AbstractGroup | Iterable)

Classe derivada da pygame.sprite.Group contendo todas as funcionalidades porém adaptada para desenhar todos os sprites com um offset baseado no target, criando uma sensação de movimento onde o target consegue se mover pelo cenário.

Essa câmera considera a eixo y da tela, desenhando o sprite com o maior y acima do sprite com o menor, criando assim um efeito de sobreposição, dando uma melhor experiência para o player.

O desenho dos sprites é otimizado para que a apenas aqueles que estão visíveis atualmente na janela sejam desenhados, aumentando a performance para jogos com muitos elementos ativos ao mesmo tempo.

Parâmetros:

bg_surface: imagem do background que será desenhada antes de todos os sprites; camera_delay: adiciona o efeito de delay no movimento da câmera. O valor deve estar entre 1 e 100, sendo 1 sem nenhum delay e 100 o máximo possível *sprites: lista de sprites para manter a assinatura compatível com a classe `pygame.sprite.Group`

Métodos e propriedades

Camera2D.draw(self, surface: Surface, target: Sprite) -> list[Rect]

• Desenha na tela os elementos presentes no grupo que estão visíveis atualmente na janela. Essa classe também considera o elemento y de cada sprite, criando o efeito de sobreposição em jogos top-down.

Parâmetros:

surface: tela principal do jogo onde os elementos serão desenhados; target: objeto que será a referência para a centralização da câmera. Em geral, esse elemento é o player.

Event -- Exemplo

class pygutils.event.EventManager()

Classe que implementa o padrão de projeto Observer, que consiste em um mecanismo de assinatura para notificar multiplos objetos sobre qualquer evento que aconteça no objeto que está sendo observado. Essa classe pode ser utilizada para herança, que permite a qualquer classe se tornar um publisher, ou como um atributo público no objeto que será observado. Qualquer classe que atuará como subscriber deve possuir um método com a assinatura:

def notify(self, event: str, *args, **kwargs) -> None: ...

Métodos e propriedades

property EventManager.listeners -> dict[str, set[EventListener]]

• Propriedade que retorna o mapa de cada evento e dos subscribers registrados para ele.

EventManager.subscribe(self, event: str, listener: EventListener) -> None

• Permite que um objeto que atenda as especificações possa receber as notificações emitidas através do manager.

Parâmetros:

event: string que identifica o evento; listener: objeto que será registrado para ser notificado quando o evento for emitido.

EventManager.unsubscribe(self, event: str, listener: EventListener) -> None

• Permite que um objeto saia da lista de notificações de um evento específico.

Parâmetros:

event: string que identifica o evento; listener: objeto que será retirado da lista de notificações para o evento.

EventManager.notify(self, event: str, *args, **kwargs) -> None

• Notifica todos os objetos registrado para o evento que está sendo emitido.

Parâmetros:

event: string que identifica o evento; *args: argumentos posicionais adicionais que serão passados na hora da notificação; **args: argumentos nomeados adicionais que serão passados na hora da notificação.

Timer -- Exemplo

class pygutils.timer.Timer(
    duration_ms: int,
    callback: Callable[[], None] | None = None)

Classe que implementa um mecanismo para contabilizar o tempo decorrido e executar uma ação baseada em um callback passado como parâmetro para a instância. Com essa classe é possível implementar cooldowns e ações que precisam acontecer apenas uma vez após um determinado tempo.

Parâmetros:

duration_ms: tempo de duração do timer em milissegundos; callback: ação que será executada após o tempo de duração ser finalizado.

Métodos e propriedades

property Timer.active -> bool

• Propriedade que identifica se o timer está ativo, ou seja, ainda não passou o tempo necessário para atingir a duração especificada.

Timer.activate(self) -> None

• Ativa a contagem do timer. Ele pode ser reativado quantas vezes forem necessárias.

Timer.deactivate(self) -> None

• Desabilita a contagem do timer. Esse método é chamado automaticamente após o tempo de duração chegar ao fim.

Timer.update(self) -> None

• Verifica se o timer já foi finalizado, executa o callback, caso seja especificado, e desativa a contagem. Esse método deve ser chamado apenas uma vez a cada frame do jogo.

Créditos

assets

• Sprout Lands - Asset Pack
• Generic OLDWEST Pack