| Name | pygutils JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | |
| Summary | Package with utility functions and classes to work with Pygame. |
| upload_time | 2023-10-22 13:16:30 |
| maintainer | |
| docs_url | None |
| author | Lucas Eliaquim |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
python
pygame
utility
helpers
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
Instalação
----------
Eu recomendo a instalação utilizando o `pipenv` ou o `virtualenv` para permitir um gerenciamento melhor das dependências.
```bash
pipenv install pygutils
```
ou
```bash
pip install pygutils
```
Conteúdo
--------
<div id="animation" />
<details>
<summary>
<strong>Animation --</strong>
<a href="https://github.com/LEMSantos/pygutils/blob/main/pygutils/examples/animation_example.py">Exemplo</a>
</summary>
```python
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.
<table>
<tr>
<td><strong>Parâmetros:</strong></td>
<td>
<strong>frames_sequence</strong>: sequência de superfícies que serão animadas;<br>
<strong>animation_speed</strong>: velocidade em que a animação será executada;<br>
<strong>on_finish</strong>: callback executado todas as vezes que a animação é concluída. Nulo por padrão;<br>
<strong>loop</strong>: flag que identifica se a animação deve ser executada continuamente ou apenas uma vez. Verdadeira por padrão.<br>
</td>
</tr>
</table>
#### Métodos e propriedades
```python
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`.
```python
Animation.next(self) -> pygame.Surface
```
- Método que retorna a próxima superfície da sequência.
```python
Animation.reset(self) -> None
```
- Método que retorna a animação para o estado inicial.
```python
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 <strong>delta_time</strong> representa o tempo entre dois frames consecutivos.
```python
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.
</details>
<div id="camera" />
<details>
<summary>
<strong>Camera --</strong>
<a href="https://github.com/LEMSantos/pygutils/blob/main/pygutils/examples/camera_example.py">Exemplo</a>
</summary>
```python
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.
<table>
<tr>
<td><strong>Parâmetros:</strong></td>
<td>
<strong>bg_surface</strong>: imagem do background que será desenhada antes de todos os sprites;<br>
<strong>camera_delay</strong>: 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<br>
<strong>*sprites</strong>: lista de sprites para manter a assinatura compatível com a classe `pygame.sprite.Group`<br>
</td>
</tr>
</table>
#### Métodos e propriedades
```python
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.
<table align="center">
<tr>
<td><strong>Parâmetros:</strong></td>
<td>
<strong>surface</strong>: tela principal do jogo onde os elementos serão desenhados;<br>
<strong>target</strong>: objeto que será a referência para a centralização da câmera. Em geral, esse elemento é o player.<br>
</td>
</tr>
</table>
</details>
<div id="event" />
<details>
<summary>
<strong>Event --</strong>
<a href="https://github.com/LEMSantos/pygutils/blob/main/pygutils/examples/event_example.py">Exemplo</a>
</summary>
```python
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:
```python
def notify(self, event: str, *args, **kwargs) -> None: ...
```
#### Métodos e propriedades
```python
property EventManager.listeners -> dict[str, set[EventListener]]
```
- Propriedade que retorna o mapa de cada evento e dos subscribers registrados para ele.
```python
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.
<table align="center">
<tr>
<td><strong>Parâmetros:</strong></td>
<td>
<strong>event</strong>: string que identifica o evento;<br>
<strong>listener</strong>: objeto que será registrado para ser notificado quando o evento for emitido.<br>
</td>
</tr>
</table>
```python
EventManager.unsubscribe(self, event: str, listener: EventListener) -> None
```
- Permite que um objeto saia da lista de notificações de um evento específico.
<table align="center">
<tr>
<td><strong>Parâmetros:</strong></td>
<td>
<strong>event</strong>: string que identifica o evento;<br>
<strong>listener</strong>: objeto que será retirado da lista de notificações para o evento.<br>
</td>
</tr>
</table>
```python
EventManager.notify(self, event: str, *args, **kwargs) -> None
```
- Notifica todos os objetos registrado para o evento que está sendo emitido.
<table align="center">
<tr>
<td><strong>Parâmetros:</strong></td>
<td>
<strong>event</strong>: string que identifica o evento;<br>
<strong>*args</strong>: argumentos posicionais adicionais que serão passados na hora da notificação;<br>
<strong>**args</strong>: argumentos nomeados adicionais que serão passados na hora da notificação.<br>
</td>
</tr>
</table>
</details>
<div id="timer" />
<details>
<summary>
<strong>Timer --</strong>
<a href="https://github.com/LEMSantos/pygutils/blob/main/pygutils/examples/timer_example.py">Exemplo</a>
</summary>
```python
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.
<table>
<tr>
<td><strong>Parâmetros:</strong></td>
<td>
<strong>duration_ms</strong>: tempo de duração do timer em milissegundos;<br>
<strong>callback</strong>: ação que será executada após o tempo de duração ser finalizado.<br>
</td>
</tr>
</table>
#### Métodos e propriedades
```python
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.
```python
Timer.activate(self) -> None
```
- Ativa a contagem do timer. Ele pode ser reativado quantas vezes forem necessárias.
```python
Timer.deactivate(self) -> None
```
- Desabilita a contagem do timer. Esse método é chamado automaticamente após o tempo de duração chegar ao fim.
```python
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.
</details>
Créditos
--------
#### assets
- [Sprout Lands - Asset Pack](https://cupnooble.itch.io/sprout-lands-asset-pack)
- [Generic OLDWEST Pack](https://bakudas.itch.io/generic-oldwest-pack)
Raw data
{
"_id": null,
"home_page": "",
"name": "pygutils",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "python,pygame,utility,helpers",
"author": "Lucas Eliaquim",
"author_email": "<lemsantos.dev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/78/74/4381f66dff87789d1f9af7cbb23e7c9d194edd27da76be7aea4b02c48c71/pygutils-0.3.0.tar.gz",
"platform": null,
"description": "\nInstala\u00e7\u00e3o\n----------\n\nEu recomendo a instala\u00e7\u00e3o utilizando o `pipenv` ou o `virtualenv` para permitir um gerenciamento melhor das depend\u00eancias.\n\n```bash\npipenv install pygutils\n```\n\nou\n\n```bash\npip install pygutils\n```\n\nConte\u00fado\n--------\n\n<div id=\"animation\" />\n\n<details>\n\n<summary>\n <strong>Animation --</strong>\n <a href=\"https://github.com/LEMSantos/pygutils/blob/main/pygutils/examples/animation_example.py\">Exemplo</a>\n</summary>\n\n```python\nclass pygutils.animation.Animation(\n frames_sequence: list[pygame.Surface],\n animation_speed: int,\n on_finish: Callable[[], None] | None = None,\n loop: bool = True)\n```\n\nClasse que representa uma anima\u00e7\u00e3o a partir de uma sequ\u00eancia de frames que s\u00e3o devolvidos em uma certa velocidade baseado no deltatime do jogo. \u00c9 poss\u00edvel criar anima\u00e7\u00f5es que s\u00e3o executadas apenas uma vez ou em loop. Al\u00e9m disso, ainda \u00e9 poss\u00edvel definir um callback que ser\u00e1 chamado todas as vezes que a anima\u00e7\u00e3o for finalizada.\n\n<table>\n <tr>\n <td><strong>Par\u00e2metros:</strong></td>\n <td>\n <strong>frames_sequence</strong>: sequ\u00eancia de superf\u00edcies que ser\u00e3o animadas;<br>\n <strong>animation_speed</strong>: velocidade em que a anima\u00e7\u00e3o ser\u00e1 executada;<br>\n <strong>on_finish</strong>: callback executado todas as vezes que a anima\u00e7\u00e3o \u00e9 conclu\u00edda. Nulo por padr\u00e3o;<br>\n <strong>loop</strong>: flag que identifica se a anima\u00e7\u00e3o deve ser executada continuamente ou apenas uma vez. Verdadeira por padr\u00e3o.<br>\n </td>\n </tr>\n</table>\n\n#### M\u00e9todos e propriedades\n\n```python\nproperty Animation.finished -> bool\n```\n- Propriedade que identifica se a anima\u00e7\u00e3o foi finalizada. Em loops essa propriedade fica verdadeira apenas at\u00e9 a pr\u00f3xima chamada do m\u00e9todo `update`.\n\n```python\nAnimation.next(self) -> pygame.Surface\n```\n- M\u00e9todo que retorna a pr\u00f3xima superf\u00edcie da sequ\u00eancia.\n\n```python\nAnimation.reset(self) -> None\n```\n- M\u00e9todo que retorna a anima\u00e7\u00e3o para o estado inicial.\n\n```python\nAnimation.update(self, delta_time: float) -> None\n```\n- M\u00e9todo que atualiza o \u00edndice da anima\u00e7\u00e3o, chama o callback na finaliza\u00e7\u00e3o e reseta automaticamente caso seja uma anima\u00e7\u00e3o em loop. Esse m\u00e9todo deve ser chamado apenas uma vez a cada frame do jogo. O <strong>delta_time</strong> representa o tempo entre dois frames consecutivos.\n\n```python\nAnimation.copy(self) -> Animation\n```\n- M\u00e9todo que permite que a anima\u00e7\u00e3o fa\u00e7a uma c\u00f3pia de si mesma, mantendo os mesmos atributos passados anteriormente na hora da inst\u00e2ncia\u00e7\u00e3o. A nova anima\u00e7\u00e3o sempre come\u00e7a no in\u00edcio dos frames.\n\n</details>\n\n\n<div id=\"camera\" />\n\n<details>\n\n<summary>\n <strong>Camera --</strong>\n <a href=\"https://github.com/LEMSantos/pygutils/blob/main/pygutils/examples/camera_example.py\">Exemplo</a>\n</summary>\n\n```python\nclass pygutils.camera.Camera2D(\n bg_surface: Surface | None,\n camera_delay: Annotated[float, ValueRange(1, 100)],\n *sprites: Any | AbstractGroup | Iterable)\n```\n\nClasse derivada da `pygame.sprite.Group` contendo todas as funcionalidades por\u00e9m adaptada para desenhar todos os sprites com um offset baseado no target, criando uma sensa\u00e7\u00e3o de movimento onde o target consegue se mover pelo cen\u00e1rio.\n\nEssa c\u00e2mera 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\u00e7\u00e3o, dando uma melhor experi\u00eancia para o player.\n\nO desenho dos sprites \u00e9 otimizado para que a apenas aqueles que est\u00e3o vis\u00edveis atualmente na janela sejam desenhados, aumentando a performance para jogos com muitos elementos ativos ao mesmo tempo.\n\n<table>\n <tr>\n <td><strong>Par\u00e2metros:</strong></td>\n <td>\n <strong>bg_surface</strong>: imagem do background que ser\u00e1 desenhada antes de todos os sprites;<br>\n <strong>camera_delay</strong>: adiciona o efeito de delay no movimento da c\u00e2mera. O valor deve estar entre 1 e 100, sendo 1 sem nenhum delay e 100 o m\u00e1ximo poss\u00edvel<br>\n <strong>*sprites</strong>: lista de sprites para manter a assinatura compat\u00edvel com a classe `pygame.sprite.Group`<br>\n </td>\n </tr>\n</table>\n\n#### M\u00e9todos e propriedades\n\n```python\nCamera2D.draw(self, surface: Surface, target: Sprite) -> list[Rect]\n```\n- Desenha na tela os elementos presentes no grupo que est\u00e3o vis\u00edveis atualmente na janela. Essa classe tamb\u00e9m considera o elemento `y` de cada sprite, criando o efeito de sobreposi\u00e7\u00e3o em jogos top-down.\n<table align=\"center\">\n <tr>\n <td><strong>Par\u00e2metros:</strong></td>\n <td>\n <strong>surface</strong>: tela principal do jogo onde os elementos ser\u00e3o desenhados;<br>\n <strong>target</strong>: objeto que ser\u00e1 a refer\u00eancia para a centraliza\u00e7\u00e3o da c\u00e2mera. Em geral, esse elemento \u00e9 o player.<br>\n </td>\n </tr>\n</table>\n\n</details>\n\n\n<div id=\"event\" />\n\n<details>\n\n<summary>\n <strong>Event --</strong>\n <a href=\"https://github.com/LEMSantos/pygutils/blob/main/pygutils/examples/event_example.py\">Exemplo</a>\n</summary>\n\n```python\nclass pygutils.event.EventManager()\n```\n\nClasse que implementa o padr\u00e3o de projeto Observer, que consiste em um mecanismo de assinatura para notificar multiplos objetos sobre qualquer evento que aconte\u00e7a no objeto que est\u00e1 sendo observado. Essa classe pode ser utilizada para heran\u00e7a, que permite a qualquer classe se tornar um `publisher`, ou como um atributo p\u00fablico no objeto que ser\u00e1 observado. Qualquer classe que atuar\u00e1 como `subscriber` deve possuir um m\u00e9todo com a assinatura:\n\n```python\ndef notify(self, event: str, *args, **kwargs) -> None: ...\n```\n\n#### M\u00e9todos e propriedades\n\n```python\nproperty EventManager.listeners -> dict[str, set[EventListener]]\n```\n- Propriedade que retorna o mapa de cada evento e dos subscribers registrados para ele.\n\n```python\nEventManager.subscribe(self, event: str, listener: EventListener) -> None\n```\n- Permite que um objeto que atenda as especifica\u00e7\u00f5es possa receber as notifica\u00e7\u00f5es emitidas atrav\u00e9s do manager.\n<table align=\"center\">\n <tr>\n <td><strong>Par\u00e2metros:</strong></td>\n <td>\n <strong>event</strong>: string que identifica o evento;<br>\n <strong>listener</strong>: objeto que ser\u00e1 registrado para ser notificado quando o evento for emitido.<br>\n </td>\n </tr>\n</table>\n\n```python\nEventManager.unsubscribe(self, event: str, listener: EventListener) -> None\n```\n- Permite que um objeto saia da lista de notifica\u00e7\u00f5es de um evento espec\u00edfico.\n<table align=\"center\">\n <tr>\n <td><strong>Par\u00e2metros:</strong></td>\n <td>\n <strong>event</strong>: string que identifica o evento;<br>\n <strong>listener</strong>: objeto que ser\u00e1 retirado da lista de notifica\u00e7\u00f5es para o evento.<br>\n </td>\n </tr>\n</table>\n\n```python\nEventManager.notify(self, event: str, *args, **kwargs) -> None\n```\n- Notifica todos os objetos registrado para o evento que est\u00e1 sendo emitido.\n<table align=\"center\">\n <tr>\n <td><strong>Par\u00e2metros:</strong></td>\n <td>\n <strong>event</strong>: string que identifica o evento;<br>\n <strong>*args</strong>: argumentos posicionais adicionais que ser\u00e3o passados na hora da notifica\u00e7\u00e3o;<br>\n <strong>**args</strong>: argumentos nomeados adicionais que ser\u00e3o passados na hora da notifica\u00e7\u00e3o.<br>\n </td>\n </tr>\n</table>\n\n</details>\n\n\n<div id=\"timer\" />\n\n<details>\n\n<summary>\n <strong>Timer --</strong>\n <a href=\"https://github.com/LEMSantos/pygutils/blob/main/pygutils/examples/timer_example.py\">Exemplo</a>\n</summary>\n\n```python\nclass pygutils.timer.Timer(\n duration_ms: int,\n callback: Callable[[], None] | None = None)\n```\n\nClasse que implementa um mecanismo para contabilizar o tempo decorrido e executar uma a\u00e7\u00e3o baseada em um callback passado como par\u00e2metro para a inst\u00e2ncia. Com essa classe \u00e9 poss\u00edvel implementar cooldowns e a\u00e7\u00f5es que precisam acontecer apenas uma vez ap\u00f3s um determinado tempo.\n\n<table>\n <tr>\n <td><strong>Par\u00e2metros:</strong></td>\n <td>\n <strong>duration_ms</strong>: tempo de dura\u00e7\u00e3o do timer em milissegundos;<br>\n <strong>callback</strong>: a\u00e7\u00e3o que ser\u00e1 executada ap\u00f3s o tempo de dura\u00e7\u00e3o ser finalizado.<br>\n </td>\n </tr>\n</table>\n\n#### M\u00e9todos e propriedades\n\n```python\nproperty Timer.active -> bool\n```\n- Propriedade que identifica se o timer est\u00e1 ativo, ou seja, ainda n\u00e3o passou o tempo necess\u00e1rio para atingir a dura\u00e7\u00e3o especificada.\n\n```python\nTimer.activate(self) -> None\n```\n- Ativa a contagem do timer. Ele pode ser reativado quantas vezes forem necess\u00e1rias.\n\n```python\nTimer.deactivate(self) -> None\n```\n- Desabilita a contagem do timer. Esse m\u00e9todo \u00e9 chamado automaticamente ap\u00f3s o tempo de dura\u00e7\u00e3o chegar ao fim.\n\n```python\nTimer.update(self) -> None\n```\n- Verifica se o timer j\u00e1 foi finalizado, executa o callback, caso seja especificado, e desativa a contagem. Esse m\u00e9todo deve ser chamado apenas uma vez a cada frame do jogo.\n\n</details>\n\n\nCr\u00e9ditos\n--------\n\n#### assets\n\n- [Sprout Lands - Asset Pack](https://cupnooble.itch.io/sprout-lands-asset-pack)\n- [Generic OLDWEST Pack](https://bakudas.itch.io/generic-oldwest-pack)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Package with utility functions and classes to work with Pygame.",
"version": "0.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/LEMSantos/pygutils/issues",
"Source": "https://github.com/LEMSantos/pygutils"
},
"split_keywords": [
"python",
"pygame",
"utility",
"helpers"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0430739ff83b799250e0b9558e7f87f9fbb8216f2e83707d457b64e9abccae22",
"md5": "67bf13762c0d496d839782ee0bab09c9",
"sha256": "475a3a04a905307ac32eb5a67aa7dd522a5a19b255440ab396a645160441bca3"
},
"downloads": -1,
"filename": "pygutils-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "67bf13762c0d496d839782ee0bab09c9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 14809,
"upload_time": "2023-10-22T13:16:28",
"upload_time_iso_8601": "2023-10-22T13:16:28.785711Z",
"url": "https://files.pythonhosted.org/packages/04/30/739ff83b799250e0b9558e7f87f9fbb8216f2e83707d457b64e9abccae22/pygutils-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "78744381f66dff87789d1f9af7cbb23e7c9d194edd27da76be7aea4b02c48c71",
"md5": "27cdedcee45035ce4aee6bf36be4e6a6",
"sha256": "5aa4d7b52f3b73c5a33a4424ec5699dd39ac49a8a90ff557e94b7f83843bece6"
},
"downloads": -1,
"filename": "pygutils-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "27cdedcee45035ce4aee6bf36be4e6a6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 13585,
"upload_time": "2023-10-22T13:16:30",
"upload_time_iso_8601": "2023-10-22T13:16:30.656888Z",
"url": "https://files.pythonhosted.org/packages/78/74/4381f66dff87789d1f9af7cbb23e7c9d194edd27da76be7aea4b02c48c71/pygutils-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-22 13:16:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LEMSantos",
"github_project": "pygutils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pygutils"
}
