README.pt.md

[ English | 中文 | Deutsch | Español | Français | Italiano | 日本語 | 한국어 | Português | Русский | Türkçe | Українська ]

Pyxel é um motor de jogos retrô para Python.

Graças às suas especificações simples inspiradas em consoles de jogos retrô, assim como permitir a exibição de apenas 16 cores e apenas 4 sons poderem ser reproduzidos ao mesmo tempo, você pode se sentir à vontade para fazer jogos em estilo pixel art.

A motivação para o desenvolvimento do Pyxel é o feedback dos utilizadores. Por favor, dê a Pyxel uma estrela em GitHub!

As especificações e APIs de Pyxel são inspiradas por PICO-8 e TIC-80.

O Pyxel é de código aberto sob a licença MIT e de utilização gratuita. Vamos começar fazendo um jogo retrô com Pyxel!

Especificações

• Funciona em Windows, Mac, Linux e Web
• Programação em Python
• Paleta de 16 cores
• 3 bancos de imagens de 256x256 pixels
• 8 mapas de tiles de 256x256 pixels
• 4 canais com 64 sons definíveis
• 8 faixas de música que podem combinar qualquer som
• Entradas de teclado, mouse e gamepad
• Editor de imagens e sons
• Expansão de cores, canais e bancos pelo usuário

Paleta de cores

Como instalar

Windows

Após instalar o Python3 (versão 3.8 ou superior), execute o seguinte comando:

pip install -U pyxel

Se instalar Python utilizando o instalador oficial, verifique a caixa de verificação Add Python 3.x to PATH para activar o comando pyxel.

Mac

Depois de instalar o Homebrew, execute os seguintes comandos:

brew install pipx
pipx ensurepath
pipx install pyxel

Para atualizar a versão após a instalação do Pyxel, execute pipx upgrade pyxel.

Linux

Após instalar o pacote SDL2 (libsdl2-dev no Ubuntu), Python3 (versão 3.8 ou superior), e python3-pip, execute o seguinte comando:

sudo pip3 install -U pyxel

Se o acima mencionado não funcionar, tente auto-construir-se de acordo com as instruções em Makefile.

Web

A versão web do Pyxel não requer instalação de Python ou Pyxel e corre em PCs, bem como smartphones e tablets com navegadores web suportados.

Para instruções específicas, por favor consulte esta página.

Testando os exemplos Pyxel

Após instalar o Pyxel, os exemplos serão copiados para o diretório atual com o seguinte comando:

pyxel copy_examples

Os exemplos copiados são os seguintes:

01_hello_pyxel.py	Aplicação simples	Demo	Code
02_jump_game.py	Jogo de pulo com o arquivo de recursos do Pyxel	Demo	Code
03_draw_api.py	Demonstração das APIs de desenho	Demo	Code
04_sound_api.py	Demonstração das APIs de som	Demo	Code
05_color_palette.py	Lista da paleta de cores	Demo	Code
06_click_game.py	Jogo de clique com mouse	Demo	Code
07_snake.py	Jogo Snake com BGM	Demo	Code
08_triangle_api.py	Demonstração da API de desenho de triângulos	Demo	Code
09_shooter.py	Jogo de tiro com transição de tela	Demo	Code
10_platformer.py	Jogo side-scrolling de plataforma com mapa	Demo	Code
11_offscreen.py	Renderização fora do ecrã com classe de Image	Demo	Code
12_perlin_noise.py	Animação sonora Perlin	Demo	Code
13_bitmap_font.py	Desenho de uma fonte bitmap	Demo	Code
14_synthesizer.py	Sintetizador que utiliza funcionalidades de expansão de áudio	Demo	Code
15_tiled_map_file.py	Carregar e desenhar um ficheiro de mapa de azulejos (.tmx)	Demo	Code
16_transform.py	Rotação e dimensionamento de imagens	Demo	Code
99_flip_animation.py	Animação com função flip (apenas plataformas não-web)	Demo	Code
30sec_of_daylight.pyxapp	1º jogo vencedor de Pyxel Jam de Adam	Demo	Code
megaball.pyxapp	Jogo de física de bola arcade por Adam	Demo	Code
8bit-bgm-gen.pyxapp	Gerador de música de fundo feito por frenchbread	Demo	Code

Os exemplos podem ser executados com os seguintes comandos:

cd pyxel_examples
pyxel run 01_hello_pyxel.py
pyxel play 30sec_of_daylight.pyxapp

Como usar

Criando uma aplicação Pyxel

Após importar o módulo Pyxel em seu script Python, especifique o tamanho da janela com a função init, em seguida inicialize a aplicação Pyxel com a função run.

import pyxel

pyxel.init(160, 120)

def update():
    if pyxel.btnp(pyxel.KEY_Q):
        pyxel.quit()

def draw():
    pyxel.cls(0)
    pyxel.rect(10, 10, 20, 20, 11)

pyxel.run(update, draw)

Os argumentos da função run são as funções update, para atualizar cada frame, e draw para desenhar a tela quando for necessário.

Em uma aplicação real, é recomendado colocar código pyxel em uma classe, como feito abaixo:

import pyxel

class App:
    def __init__(self):
        pyxel.init(160, 120)
        self.x = 0
        pyxel.run(self.update, self.draw)

    def update(self):
        self.x = (self.x + 1) % pyxel.width

    def draw(self):
        pyxel.cls(0)
        pyxel.rect(self.x, 0, 8, 8, 9)

App()

Ao criar gráficos simples sem animação, a função show pode ser utilizada para tornar o código mais conciso.

import pyxel

pyxel.init(120, 120)
pyxel.cls(1)
pyxel.circb(60, 60, 40, 7)
pyxel.show()

Executando uma aplicação Pyxel

Um script Python criado pode ser executado utilizando o comando python:

python PYTHON_SCRIPT_FILE

Também pode ser executado com o comando pyxel run:

pyxel run PYTHON_SCRIPT_FILE

Adicionalmente, o comando pyxel watch permite a monitorização de alterações num diretório especificado, re-executando automaticamente o programa quando são detectadas alterações:

pyxel watch WATCH_DIR PYTHON_SCRIPT_FILE

A monitorização do diretório pode ser interrompida premindo Ctrl(Command)+C.

Controles Especiais

Os seguintes controles especiais podem ser executados quando uma aplicação Pyxel estiver sendo executada:

• Esc
  Encerra a aplicação
• Alt(Option)+1
  Salva uma captura de tela para a área de trabalho
• Alt(Option)+2
  Reinicia o momento inicial do vídeo de captura de tela.
• Alt(Option)+3
  Salva um vídeo de captura de tela na área de trabalho (até 10 segundos)
• Alt(Option)+9
  Alternar entre os modos de ecrã (Crisp/Smooth/Retro)
• Alt(Option)+0
  Ativa/desativa o monitor de performance (fps, tempo de update e tempo de draw)
• Alt(Option)+Enter
  Ativa/desativa tela cheia
• Shift+Alt(Option)+1/2/3
  Guardar o banco de imagens correspondente no ambiente de trabalho
• Shift+Alt(Option)+0
  Guardar a paleta de cores atual no ambiente de trabalho

Como criar um Recurso

O Editor Pyxel pode criar imagens e sons usados em uma aplicação Pyxel.

Ele é inicializado com o seguinte comando:

pyxel edit PYXEL_RESOURCE_FILE

Se o arquivo de recursos Pyxel (.pyxres) existir, o arquivo será carregado, e se ele não existir, um novo arquivo com o nome especificado será criado. Se o arquivo de recursos for omitido, o nome será my_resource.pyxres.

Após iniciar o Editor Pyxel, o arquivo pode ser trocado arrastando e soltando outro arquivo de recursos.

O arquivo recursos criado pode ser carregado através da função load.

O Editor Pyxel possuí os seguintes modos de edição.

Editor de Imagem

O modo para editar bancos de imagem.

Arrastar e largar um ficheiro de imagem (PNG/GIF/JPEG) no Editor de imagens para carregar a imagem no banco de imagens atualmente selecionado.

Editor de Tilemap

O modo para editar tilemaps em que imagens dos bancos de imagens são organizados em um padrão de tiles.

Arraste e largue um ficheiro TMX (Tiled Map File) no Tilemap Editor para carregar a sua camada na ordem de desenho que corresponde ao número de tilemap atualmente selecionado.

Editor de Som

O modo para editar sons.

Editor de Música

O modo para editar músicas nas quais os sons são organizados na ordem de execução.

Outros métodos de criação de recursos

Imagens e tilemaps Pyxel também podem ser criados pelos seguintes métodos:

• Criar uma imagem de uma lista de strings com a função Image.set ou com a função Tilemap.set
• Carregar um arquivo de imagem (PNG/GIF/JPEG) na paleta Pyxel com a função Image.load

Sons Pyxel também podem ser criados com o seguinte método:

• Criar um som de uma strings com a função Sound.set ou com a função Music.set

Favor consultar a referência da API para o uso dessas funções.

Como distribuir uma aplicação

O Pyxel suporta um formato de arquivo de distribuição dedicado (arquivo de aplicação Pyxel) que é multiplataforma.

Criar o ficheiro de aplicação Pyxel (.pyxapp) com o comando pyxel package:

pyxel package APP_DIR STARTUP_SCRIPT_FILE

Se a candidatura deve incluir recursos ou módulos adicionais, coloque-os no directório da candidatura.

Os metadados podem ser exibidos em tempo de execução, especificando-os no seguinte formato dentro do script de inicialização. Outros campos além de title e author podem ser omitidos.

# title: Pyxel Platformer
# author: Takashi Kitao
# desc: A Pyxel platformer example
# site: https://github.com/kitao/pyxel
# license: MIT
# version: 1.0

O arquivo de aplicação criado pode ser executado com o comando pyxel play:

pyxel play PYXEL_APP_FILE

O ficheiro de aplicação Pyxel também pode ser convertido num ficheiro executável ou HTML com os comandos pyxel app2exe ou pyxel app2html.

Referência da API

Sistema

• width, height
  A largura e a altura da tela

• frame_count
  O número dos quadros decorridos

• init(width, height, [title], [fps], [quit_key], [display_scale], [capture_scale], [capture_sec])
  Inicializa a aplicação Pyxel com tamanho de tela (width, height). As seguintes opções podem ser especificadas: o título da janela com title, a taxa de quadros com fps, a tecla para fechar a aplicação com quit_key, a escala da exposição com display_scale, a escala da captura de tela com capture_scale, o tempo máximo de gravação do vídeo da captura de tela capture_sec.
  Ex. pyxel.init(160, 120, title="My Pyxel App", fps=60, quit_key=pyxel.KEY_NONE, capture_scale=3, capture_sec=0)

• run(update, draw)
  Roda a aplicação Pyxel e chama a função update para atualizar os quadros e a função draw para desenhá-los.

• show()
  Mostra a tela e espera até a tecla Esc ser pressionada.

• flip()
  Refrear o ecrã por uma moldura. A aplicação sai quando a tecla Esc é premida. Esta função não funciona na versão Web.

• quit()
  Feche a aplicação Pyxel.

Recurso

• load(filename, [excl_images], [excl_tilemaps], [excl_sounds], [excl_musics])
  Carrega o arquivo de recursos (.pyxres). Se uma opção for True, o recurso não será carregado. Se um arquivo de paleta (.pyxpal) com o mesmo nome existir no mesmo local que o arquivo de recurso, a cor de exibição da paleta também será alterada. O arquivo de paleta é uma entrada hexadecimal das cores de exibição (por exemplo, 1100FF), separada por novas linhas. O arquivo de paleta também pode ser usado para alterar as cores exibidas no Pyxel Editor.

Entrada

• mouse_x, mouse_y
  A posição atual do cursor do mouse

• mouse_wheel
  O valor atual da roda de rolagem do mouse

• btn(key)
  Retorna True se key é pressionada, caso contrário retorna False. (lista de definições de teclas)

• btnp(key, [hold], [repeat])
  Retorna True se key for pressionada naquele quadro, caso contrário retorna False. Quando hold e repeat são especificados, True será retornado durante o intervalo de quadros repeat, no qual key estiver pressionada por mais que hold quadros.

• btnr(key)
  Retorna True se key for solta naquele quadro, caso contrário retorna False

• mouse(visible)
  Se visible for True, mostra o cursor do mouse. Se for False, esconde. Mesmo se o cursor do mouse não for visível, sua posição é atualizada.

Gráficos

• colors
  Lista da paleta de cores da tela. A cor da tela é especificada por um valor numérico de 24 bits. Use colors.from_list e colors.to_list para atribuir e pegar listas do Python.
  Ex. old_colors = pyxel.colors.to_list(); pyxel.colors.from_list([0x111111, 0x222222, 0x333333]); pyxel.colors[15] = 0x112233

• images
  Lista dos bancos de imagens (0-2). (veja a classe de Imagem)
  Ex. pyxel.images[0].load(0, 0, "title.png")

• tilemaps
  Lista dos mapas de azulejos (0-7). (ver a classe de Tilemap)

• clip(x, y, w, h)
  Define a área de desenho da tela de (x, y) para a largura w e altura h. Redefina a área de desenho para tela cheia com clip()

• camera(x, y)
  Altera as coordenadas do canto superior esquerdo da tela para (x, y). Redefina as coordenadas do canto superior esquerdo para (0, 0) com camera().

• pal(col1, col2)
  Substitui a cor col1 com col2 ao desenhar. Use pal() para voltar para a paleta inicial.

• dither(alpha)
  Aplica dithering (pseudo-transparência) no desenho. Define alpha no intervalo 0.0-1.0, onde 0.0 é transparente e 1.0 é opaco.

• cls(col)
  Limpar a tela com a cor col

• pget(x, y)
  Captura a cor de um pixel em (x, y).

• pset(x, y, col)
  Desenha um pixel de cor col em (x, y).

• line(x1, y1, x2, y2, col)
  Desenha uma linha da cor col de (x1, y1) até (x2, y2).

• rect(x, y, w, h, col)
  Desenha um retângulo de largura w, altura h e cor col a partir de (x, y).

• rectb(x, y, w, h, col)
  Desenha o contorno de um retângulo de largura w, altura h e cor col a partir de (x, y).

• circ(x, y, r, col)
  Desenha um círculo de raio r e cor col em (x, y).

• circb(x, y, r, col)
  Desenha o contorno de um círculo de raio r e cor col em (x, y).

• elli(x, y, w, h, col)
  Desenhar uma elipse de largura w, altura h e cor col de (x, y).

• ellib(x, y, w, h, col)
  Desenhar o contorno de uma elipse de largura w, altura h e cor col de (x, y).

• tri(x1, y1, x2, y2, x3, y3, col)
  Desenha um triangulo com os vértices (x1, y1), (x2, y2), (x3, y3) e cor col

• trib(x1, y1, x2, y2, x3, y3, col)
  Desenha o contorno de um triangulo com os vértices (x1, y1), (x2, y2), (x3, y3) e cor col

• fill(x, y, col)
  Desenhar uma elipse de largura w, altura h e cor col de (x, y).

• blt(x, y, img, u, v, w, h, [colkey], [rotate], [scale])
  Copia a região de tamanho (w, h) de (u, v) do banco de imagens img(0-2) para (x, y). Se um valor negativo for definido para w e/ou h, será invertido horizontalmente e/ou verticalmente. Se colkey for especificada, será tratado como cor transparente. Se rotate(em graus), scale(1.0=100%), ou ambos forem especificados, a transformação correspondente será aplicada.

• bltm(x, y, tm, u, v, w, h, [colkey], [rotate], [scale])
  Copia a região de tamanho (w, h) de (u, v) do tilemap tm(0-7) para (x, y). Se um valor negativo for definido para w e/ou h, será invertido horizontalmente e/ou verticalmente. Se colkey for especificada, será tratado como cor transparente. Se rotate(em graus), scale(1.0=100%), ou ambos forem especificados, a transformação correspondente será aplicada. O tamanho de um tile é de 8x8 pixels e é armazenado em um tilemap como uma tupla de (tile_x, tile_y).

• text(x, y, s, col)
  Desenha uma string s de cor col em (x, y).

Áudio

• sounds
  Lista dos sons (0-63). (ver a classe de Som)
  Ex. pyxel.sounds[0].speed = 60

• musics
  Lista das músicas (0-7). (ver a classe de Musica)

• play(ch, snd, [tick], [loop], [resume])
  Reproduz o som snd(0-63) no canal ch(0-3). Se snd é uma lista, os sons serão reproduzidos em ordem. A posição inicial da reprodução pode ser especificada por tick(1 tick = 1/120 segundos). Se True for especificado para loop, a reprodução será feita em laço. Para retomar o som anterior após o término da reprodução, defina resume como True.

• playm(msc, [tick], [loop])
  Reproduz a música msc(0-7). A posição inicial da reprodução pode ser especificada por tick(1 tick = 1/120 segundos). Se True for especificado para loop, a reprodução será feita em laço.

• stop([ch])
  Para a reprodução do canal ch(0-3). stop() para parar a reprodução de todos os canais.

• play_pos(ch)
  Obtém a posição do canal ch(0-3) da reprodução de som como uma tupla de (sound_no, note_no). Retorna None quando a reprodução para.

Matemática

• ceil(x)
  Devolve o menor inteiro maior ou igual a x.

• floor(x)
  Devolve o maior inteiro menor ou igual a x.

• sgn(x)
  Devolve 1 quando x é positivo, 0 quando é 0 e -1 quando é negativo.

• sqrt(x)
  Devolve a raiz quadrada de x.

• sin(deg)
  Devolve o seno de deg graus.

• cos(deg)
  Retorna o cosseno de deg graus.

• atan2(y, x)
  Devolve o arctangente de y/x em graus.

• rseed(seed)
  Define a semente do gerador do número aleatório.

• rndi(a, b)
  Retorna um inteiro aleatório maior ou igual a a' e menor ou igual a b'.

• rndf(a, b)
  Devolve uma decimal aleatória maior ou igual a a e menor ou igual a b.

• nseed(seed)
  Define a semente do ruído de Perlin.

• noise(x, [y], [z])
  Retorna o valor do ruído Perlin para as coordenadas especificadas.

Classe de Imagem

• width, height
  Largura e altura da imagem

• set(x, y, data)
  Define a imagem em (x, y) por uma lista de strings.
  Ex. pyxel.images[0].set(10, 10, ["0123", "4567", "89ab", "cdef"])

• load(x, y, filename)
  Carrega um arquivo de imagem (PNG/GIF/JPEG) em (x, y).

• pget(x, y)
  Pega a cor do pixel em (x, y).

• pset(x, y, col)
  Desenha um pixel de cor col em (x, y).

Classe de Tilemap

• width, height
  A largura e a altura do tilemap

• imgsrc
  O banco de imagem (0-2) referenciado pelo tilemap

• set(x, y, data)
  Define o tilemap em (x, y) por uma lista de strings.
  Ex. pyxel.tilemap(0).set(0, 0, ["0000 0100 a0b0", "0001 0101 a1b1"])

• load(x, y, filename, layer)
  Carregar a camada na ordem de desenho layer(0-) a partir do ficheiro TMX (Tiled Map File) em (x, y).

• pget(x, y)
  Pega o tile em (x, y). Um tile é uma tupla de (tile_x, tile_y).

• pset(x, y, tile)
  Desenha um tile em (x, y). Um tile é uma tupla de (tile_x, tile_y).

Classe de Som

• notes
  Lista de notas (0-127). Quanto maior o número, mais agudo, e ao chegar em 33 ele se torna 'A2'(440Hz). O resto é -1.

• tones
  Lista de tons (0:Triangular / 1:Quadrada / 2:Pulso / 3:Ruído)

• volumes
  Lista de volumes (0-7)

• effects
  Lista de efeitos (0:None / 1:Slide / 2:Vibrato / 3:FadeOut / 4:Half-FadeOut / 5:Quarter-FadeOut)

• speed
  Velocidade de reprodução. 1 é a velocidade maior, e quanto maior o número, mais lenta ela é. No valor 120, o tempo de uma nota se torna 1 segundo.

• set(notes, tones, volumes, effects, speed)
  Define as notas, tons, volumes e efeitos com uma string. Se os tons, volumes e efeitos são mais curtos que as notas, elas se repetirão do começo.

• set_notes(notes)
  Define as notas com uma string 'CDEFGAB'+'#-'+'01234' ou 'R'. É insensível à maiúsculas ou minúsculas e espaços em branco são ignorados.
  Ex. pyxel.sounds[0].set_notes("G2B-2D3R RF3F3F3")

• set_tones(tones)
  Define os tons com uma string composta por 'TSPN'. É insensível à maiúsculas ou minúsculas e espaços em branco são ignorados.
  Ex. pyxel.sounds[0].set_tones("TTSS PPPN")

• set_volumes(volumes)
  Define os volumes com uma string composta por '01234567'. É insensível à maiúsculas ou minúsculas e espaços em branco são ignorados.
  Ex. pyxel.sounds[0].set_volumes("7777 7531")

• set_effects(effects)
  Define os efeitos com uma string composta por 'NSVFHQ'. É insensível à maiúsculas ou minúsculas e espaços em branco são ignorados.
  Ex. pyxel.sounds[0].set_effects("NFNF NVVS")

Classe de Musica

• seqs
  Lista bi-dimensional de sons (0-63) com o número de canais

• set(seq0, seq1, seq2, ...)
  Define as listas de sons (0-63) para todos os canais. Se uma lista vazia for especificada, aquele canal não será utilizado para reprodução de sons.
  Ex. pyxel.musics[0].set([0, 1], [], [3])

APIs Avançadas

Pyxel possui "APIs avançadas" que não são mencionadas nesse manual de referência pois elas podem "confundir usuários" ou "precisam de conhecimento especializado para usar".

Se você está familiarizado com suas habilidades, tente criar projetos incríveis utilizando isto como pista!

Como Contribuir

Relatando Problemas

Utilize o Issue Tracker para relatar bugs e sugerir funcionalidades/melhorias. Antes de relatar uma issue, tenha certeza que não exista uma issue similar aberta.

Teste Manual

Qualquer um testando o código manualmente e relatando bugs ou sugestões de melhorias no Issue Tracker são muito bem vindos!

Submetendo uma Pull Request

Patches/correções serão aceitas na forma de pull requests (PRs). Tenha certeza de que o que o pull request tenta resolver esteja em aberto no issue tracker.

A solicitação de pull enviada é considerada como um acordo para publicação sob a Licença MIT.

Outras informações

• FAQ
• de utilizaExemplos dores
• Conta de programador X

Licença

Pyxel está sob a Licença MIT. Ele pode ser reutilizado dentro de software proprietário, desde que todas as cópias do software ou de partes substanciais incluam uma cópia dos termos da Licença MIT e também um aviso de direitos autorais.

Recrutando Patrocinadores

Pyxel está procurando patrocinadores nos patrocinadores do GitHub. Considere patrocinar o Pyxel para manutenção contínua e acréscimos de recursos. Os patrocinadores podem consultar sobre o Pyxel como um benefício. Por favor, veja aqui para detalhes.