Skip to content

Latest commit

 

History

History
584 lines (381 loc) · 19.7 KB

README.pt.md

File metadata and controls

584 lines (381 loc) · 19.7 KB
Raw

[ English | 中文 | Deutsch | Español | Français | Italiano | 日本語 | 한국어 | Português | Русский ]

NOTE: This manual has not yet been translated for Pyxel version 1.5.0. We are looking for volunteers to translate and check for mistakes!

Pyxel é uma engine 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.

The specifications of Pyxel are referring to awesome PICO-8 and TIC-80.

Pyxel é open source e livre para utilização. Vamos começar fazendo um jogo retrô com Pyxel!

Especificações

  • Executável no Windows, Mac e Linux
  • Programming with Python
  • 16 color palette
  • 3 bancos de imagens de tamanho 256x256
  • 8 tilemaps de tamanho 256x256
  • 4 canais com 64 sons definíveis
  • 8 músicas que podem combinar sons arbitrários
  • Entrada de teclado, mouse e joystick
  • Editor de imagem e som

Paleta de cores



Como instalar

There are two types of Pyxel, a packaged version and a standalone version.

Install Packaged Version

The packaged version of Pyxel uses Pyxel as a Python extension module.

Recommended for those who are familiar with managing Python packages using the pip command or who want to develop full-fledged Python applications.

Windows

After installing Python3 (version 3.7 or higher), run the following command:

pip install -U pyxel

Mac

After installing Python3 (version 3.7 or higher), run the following command:

pip3 install -U pyxel

Linux

After installing the SDL2 package (libsdl2-dev for Ubuntu), Python3 (version 3.7 or higher), and python3-pip, run the following command:

pip3 install -U pyxel

If the above doesn't work, try self-building by following the steps below after installing cmake and rust:

git clone https://github.com/kitao/pyxel.git
cd pyxel
make clean all RELEASE=1
pip3 install .

Install Standalone Version

The standalone version of Pyxel uses Pyxel as a standalone tool that does not depend on Python.

Recommended for those who want to start programming easily without worrying about Python settings, or those who want to play Pyxel games immediately.

Windows

Download and run the latest version of the Windows installer (pyxel-[version]-windows-setup.exe) from the Download Page.

Mac

After installing Homebrew, run the following commands:

brew tap kitao/pyxel
brew install pyxel

Linux

After installing the SDL2 package (libsdl2-dev for Ubuntu) and installing Homebrew, run the following commands:

brew tap kitao/pyxel
brew install pyxel

If the above doesn't work, try self-building the packaged version.

Try Pyxel Examples

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:

An examples can be executed with the following commands:

cd pyxel_examples
pyxel run 01_hello_pyxel.py

Como usar

Criando uma aplicação Pyxel

After importing the Pyxel module in your python script, specify the window size with init function first, then starts the Pyxel application with run function.

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

It is also possible to write simple code using show function and flip function to draw simple graphics and animations.

show function displays the screen and waits until the Esc key is pressed.

import pyxel

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

flip function updates the screen once.

import pyxel

pyxel.init(120, 80)

while True:
    pyxel.cls(3)
    pyxel.rectb(pyxel.frame_count % 160 - 40, 20, 40, 40, 7)
    pyxel.flip()

Run Pyxel Application

The created Python script can be executed with the following command:

pyxel run PYTHON_SCRIPT_FILE

For the packaged version, it can be executed like a normal Python script:

cd pyxel_examples
python3 PYTHON_SCRIPT_FILE

(For Windows, type python instead of python3)

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)+0
    Ativa/desativa o monitor de performance (fps, tempo de update e tempo de draw)
  • Alt(Option)+Enter
    Ativa/desativa tela cheia

Como criar um Recurso

Pyxel Editor can create images and sounds used in a Pyxel application.

It starts with the following command:

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.

After starting Pyxel Editor, the file can be switched by dragging and dropping another resource file. If the resource file is dragged and dropped while holding down Ctrl(Cmd) key, only the resource type (Image/Tilemap/Sound/Music) that is currently being edited will be loaded. This operation enables to combine multiple resource files into one.

The created resource file can be loaded with load function.

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

Editor de Imagem:

O modo para editar bancos de imagem.

By dragging and dropping an image file (png/gif/jpeg) onto the Image Editor screen, the image can be loaded into the currently selected image bank.

Editor de Tilemap:

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

Editor de Som:

O modo para editar sons.

Editor de Musica:

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

Pyxel images and tilemaps can also be created by the following methods:

  • Create an image from a list of strings with Image.set function or Tilemap.set function
  • Load an image file (png/gif/jpeg) in Pyxel palette with Image.load function

Pyxel sounds can also be created in the following method:

  • Create a sound from strings with Sound.set function or Music.set function

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

How to Distribute Application

Pyxel supports a dedicated application distribution file format (Pyxel application file) that works across platforms.

Create the Pyxel application file (.pyxapp) with the following command:

pyxel package APP_ROOT_DIR STARTUP_SCRIPT_FILE

If the application should include resources or additional modules, place them in the application folder.

The created application file can be executed with the following command:

pyxel play PYXEL_APP_FILE

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], [capture_sec])
    Initialize the Pyxel application with screen size (width, height). The following can be specified as options: the window title with title, the frame rate with fps, the key to quit the application with quit_key, and the maximum recording time of the screen capture video with capture_sec.
    e.g. pyxel.init(160, 120, title="Pyxel with Options", fps=60, quit_key=pyxel.KEY_NONE, capture_sec=0)

  • run(update, draw)
    Start the Pyxel application and call update function for frame update and draw function for drawing.

  • show()
    Show the screen and wait until the Esc key is pressed. (Do not use in normal applications)

  • flip()
    Updates the screen once. (Do not use in normal applications)

  • quit()
    Quit the Pyxel application at the end of the current frame.

Recurso

  • load(filename, [image], [tilemap], [sound], [music])
    Load the resource file (.pyxres). If False is specified for the resource type (image/tilemap/sound/music), the resource will not be loaded.

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], [period])
    Retorna True se key for pressionada naquele quadro, caso contrário retorna False. Quando hold e period são especificados, True será retornado durante o intervalo de quadros period, 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
    List of the palette display colors. The display color is specified by a 24-bit numerical value. Use colors.from_list and colors.to_list to directly assign and retrieve Python lists.
    e.g. org_colors = pyxel.colors.to_list(); pyxel.colors[15] = 0x112233; pyxel.colors.from_list(org_colors)

  • image(img)
    Operate the image bank img (0-2). (See the Image class)
    e.g. pyxel.image(0).load(0, 0, "title.png")

  • image(img, [system])
    Opera o banco de imagens img(0-2) (veja a classe de Imagem). Se system for True, o banco de imagens do sistema pode ser acessado. 3 é para a fonte e o editor de recursos. 4 é para tela
    e.g. pyxel.image(0).load(0, 0, "title.png")

  • tilemap(tm)
    Opera o tilemap tm(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()

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

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

  • 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

  • blt(x, y, img, u, v, w, h, [colkey])
    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

  • bltm(x, y, tm, u, v, w, h, [colkey])
    Draw the tilemap tm (0-7) to (x, y) according to the tile information of size (w, h) from (u, v). If colkey is specified, treated as transparent color. The size of a tile is 8x8 pixels and is stored in a tilemap as a tuple of (x in tile, y in tile).

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

Áudio

  • sound(snd)
    Opera o som snd(0-63). (ver a classe de Som)
    e.g. pyxel.sound(0).speed = 60

  • music(msc)
    Opera a música msc (0-7) (ver a classe de Musica)

  • play_pos(ch)
    Get the sound playback position of channel ch (0-3) as a tuple of (sound no, note no). Returns None when playback is stopped.

  • play(ch, snd, loop=False)
    Play the sound snd (0-63) on channel ch (0-3). If snd is a list, it will be played in order. If True is specified for loop, loop playback is performed.

  • playm(msc, loop=False)
    Play the music msc (0-7). If True is specified for loop, loop playback is performed.

  • stop([ch])
    Stops playback of the specified channel ch (0-3). stop() to stop playing all channels.

Classe de Imagem

  • width, height
    Largura e altura da imagem

  • data
    Os dados da imagem (lista bidimensional de 256x256)

  • get(x, y)
    Pega os dados da imagem em (x, y)

  • set(x, y, data)
    Set the image at (x, y) by a list of strings.
    e.g. pyxel.image(0).set(10, 10, ["1234", "5678", "9abc", "defg"])

  • load(x, y, filename)
    Load the image file (png/gif/jpeg) at (x, y).

Classe de Tilemap

  • width, height
    A largura e a altura do tilemap

  • refimg
    The image bank (0-2) referenced by the tilemap

  • set(x, y, data)
    Set the tilemap at (x, y) by a list of strings.
    e.g. pyxel.tilemap(0).set(0, 0, ["000102", "202122", "a0a1a2", "b0b1b2"])

  • pget(x, y)
    Get the tile at (x, y). A tile is a tuple of (x in tile, y in tile).

  • pset(x, y, tile)
    Draw a tile at (x, y). A tile is a tuple of (x in tile, y in tile).

Classe de Som

  • notes
    List of notes (0-127). The higher the number, the higher the pitch, and at 33 it becomes 'A2'(440Hz). The rest is -1.

  • tones
    List of tones (0:Triangle / 1:Square / 2:Pulse / 3:Noise)

  • volumes
    List of volumes (0-7)

  • effects
    List of effects (0:None / 1:Slide / 2:Vibrato / 3:FadeOut)

  • speed
    Playback speed. 1 is the fastest, and the larger the number, the slower the playback speed. At 120, the length of one note becomes 1 second.

  • set(notes, tones, volumes, effects, speed)
    Set notes, tones, volumes, and effects with a string. If the tones, volumes, and effects length are shorter than the notes, it is repeated from the beginning.

  • set_notes(notes)
    Set the notes with a string made of 'CDEFGAB'+'#-'+'0123' or 'R'. Case-insensitive and whitespace is ignored.
    e.g. pyxel.sound(0).set_note("G2B-2D3R RF3F3F3")

  • set_tones(tones)
    Set the tones with a string made of 'TSPN'. Case-insensitive and whitespace is ignored.
    e.g. pyxel.sound(0).set_tone("TTSS PPPN")

  • set_volumes(volumes)
    Set the volumes with a string made of '01234567'. Case-insensitive and whitespace is ignored.
    e.g. pyxel.sound(0).set_volume("7777 7531")

  • set_effects(effects)
    Set the effects with a string made of 'NSVF'. Case-insensitive and whitespace is ignored.
    e.g. pyxel.sound(0).set_effect("NFNF NVVS")

Classe de Musica

  • sequences
    Two-dimensional list of sounds (0-63) listed by the number of channels

  • set(seq0, seq1, seq2, seq3)
    Set the lists of sound (0-63) of all channels. If an empty list is specified, that channel is not used for playback.
    e.g. pyxel.music(0).set([0, 1], [2, 3], [4], [])

Advanced APIs

Pyxel has "advanced APIs" that are not mentioned in this reference because they "may confuse users" or "need specialized knowledge to use".

If you are familiar with your skills, try to create amazing works with this as a clue!

Como Contribuir

Submitting Issue

Use the Issue Tracker to submit bug reports and feature/enhancement requests. Before submitting a new issue, ensure that there is no similar open issue.

Manual Testing

Anyone manually testing the code and reporting bugs or suggestions for enhancements in the Issue Tracker are very welcome!

Submitting 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.

Será considerado que todo pull request tenha concordado a ser publicado sob a licença MIT.

Outras informações

Licença

Pyxel is under MIT License. It can be reused within proprietary software, provided that all copies of the software or its substantial portions include a copy of the terms of the MIT License and also a copyright notice.