Skip to content

Latest commit

 

History

History
581 lines (378 loc) · 18.5 KB

README.cn.md

File metadata and controls

581 lines (378 loc) · 18.5 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是一个python的经典像素风游戏制作引擎。

由于像素风游戏的机制非常简单（如：最多只能显示16种颜色、播放4种声音等），现在你也可以轻松地享受这种游戏的制作过程。

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

Pyxel是开源的，大家可以免费使用。现在就让我们一起用Pyxel制作自己的游戏吧！

说明

  • 需要在Windows、Mac或Linux上运行
  • Programming with Python
  • 16 color palette
  • 3个256x256的图像库
  • 8个256x256的瓦片地图
  • 4个声道各含有64个可选音调
  • 可任意组合8个音乐
  • 支持键盘、鼠标及游戏手柄输入
  • 图像和音频编辑器

调色板



如何安装

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

安装Pyxel后，可以用以下命令将Pyxe例程复制到当前文件夹：

pyxel copy_examples

例程包含：

An examples can be executed with the following commands:

cd pyxel_examples
pyxel run 01_hello_pyxel.py

使用教程

创建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)

run函数的两个参数update函数和draw函数分别用来在需要时更新帧和绘制画面。

实际应用中，建议将pyxel代码封装成如下类：

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)

快捷键

以下快捷键可以在Pyxel运行时使用：

  • Esc
    退出应用
  • Alt(Option)+1
    截屏并保存在桌面
  • Alt(Option)+2
    重置屏幕录制的开始时间
  • Alt(Option)+3
    保存屏幕录制动图到桌面（最多10秒）
  • Alt(Option)+0
    切换性能监控（fps，更新时间，画面绘制时间）
  • Alt(Option)+Enter
    切换全屏

如何创建源文件

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

It starts with the following command:

pyxel edit [PYXEL_RESOURCE_FILE]

若指定Pyxel源文件（.pyxres）存在，则加载文件，若不存在，则以指定文件名新建文件。

若未指定源文件，则命名为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.

Pyxel编辑器有以下编辑模式。

图像编辑器：

此模式用来编辑图像库。

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.

瓦片地图(Tilemap)编辑器：

此模式用来编辑瓦片地图，其中图像库的图像以瓦片的样式排列。

音频编辑器：

此模式用来编辑音频。

音乐编辑器：

此模式用来编辑将录音有序编排形成的音乐。

其他创建源文件的方法

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

这些函数的具体用法请查阅API参考手册。

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

API参考手册

系统

  • width, height
    画面的宽和高

  • frame_count
    经过的帧数

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

源文件

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

输入

  • mouse_x, mouse_y
    当前鼠标指针的位置。

  • mouse_wheel
    当前鼠标滚轮的值。

  • btn(key)
    如果key被按下则返回True，否则返回False(按键定义列表)。

  • btnp(key, [hold], [period])
    如果key被按下则返回True。若设置了hold和period参数，则当key被按下持续hold帧时，在period帧间隙返回True。

  • btnr(key)
    如果key被松开，则在此帧返回True，否则返回False。

  • mouse(visible)
    如果visible为True则显示鼠标指针，为False则不显示。即使鼠标指针不显示，其位置同样会被更新。

显示

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

  • tilemap(tm)
    操作瓦片地图tm(0-7)（参考Tilemap类）

  • clip(x, y, w, h)
    设置画面绘制区域为从(x, y)开始的宽度w、高度为h的区域。clip()可以将绘制区域重置为全屏。

  • pal(col1, col2)
    绘制时用col1颜色代替col2颜色。pal()可以重置为初始色调。

  • cls(col)
    用col颜色清空画面。

  • pget(x, y)
    获取(x, y)处的像素颜色。

  • pset(x, y, col)
    用col颜色在(x, y)处绘制一个像素点。

  • line(x1, y1, x2, y2, col)
    用col颜色画一条从(x1, y1)到(x2, y2)的直线。

  • rect(x, y, w, h, col)
    用col颜色绘制一个从(x, y)开始的宽为w、高为h的矩形。

  • rectb(x, y, w, h, col)
    用col颜色绘制从(x, y)开始的宽为w、高为h的矩形边框。

  • circ(x, y, r, col)
    用col颜色绘制圆心为(x, y)，半径为r的圆形。

  • circb(x, y, r, col)
    用col颜色绘制圆心为(x, y)，半径为r的圆形边框。

  • tri(x1, y1, x2, y2, x3, y3, col)
    用col颜色绘制顶点分别为(x1, y1)，(x2, y2)，(x3, y3)的三角形。

  • trib(x1, y1, x2, y2, x3, y3, col)
    用col颜色绘制顶点分别为(x1, y1)，(x2, y2)，(x3, y3)的三角形边框。

  • blt(x, y, img, u, v, w, h, [colkey])
    将尺寸为(w, h)的区域从图像库的(u, v)复制到(x, y)。若w或h为负值，则在水平或垂直方向上翻转。若指定了colkey的值，则视作透明颜色。

  • 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)
    用col颜色在(x, y)绘制字符串s。

声音

  • sound(snd)
    操作音频snd(0-63)。（参考Sound类）
    示例：pyxel.sound(0).speed = 60

  • music(msc)
    操作音乐msc(0-7)（参考Music类）

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

Image类

  • width, height
    图像的宽和高。

  • data
    图像中的数据（256x256的二维列表）。

  • get(x, y)
    获取图像中(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).

Tilemap类

  • width, height
    瓦片地图(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).

Sound类

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

Music类

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

如何参与

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

可以通过pull requests(PRs)形式来提交补丁或修复。请确认你的pull request对应的issue地址在issue tracker中依然是open状态。

一旦提交pull request，则默认同意在MIT License的许可下发布。

其他信息

许可证

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.