yarwelp / PX8

Open source Fantasy Console in Rust (with Python and Lua)

PX8

• Demos
• Download
  • Binaries
• Requirements
• Build
• Resolution
• Coordinate System
• Keyboard Shortcut
• Run a cartridge
• Edit a cartridge
• Display options
• How to create a new cartridge
  • Python
  • Lua
• Cartridge format
• API documentation

PX8 is an Open Source Fantasy Console (128x128 pixels) in Rust, by using a cartridge that contains the code/gfx/music. The code could be in Python/Lua, or you could create directly everything in pure Rust by using it as a library.

It is still in development, but it is usable and the main features are:

• 128x128 pixels default resolution
• Predefined palettes (pico-8, c64, etc), or use any RGB colors
• Python 3 / Lua 5.X support for the cartridge without tokens limit
• Desktop/Mobile/Browser (Emscripten) support
• Controls with dpad + 2 buttons (gamecontroller/joystick support)
• Unlimited sprites (8x8)
• Map support (128x32)
• Edition of the cartridge data
• PX8 format to be able to use your favorite code editor for Python/Lua/Rust
• Change the screen definition (128x128, 256x256, WIDTHxHEIGHT)
• Screenshot (PNG) / Video recording (GIF)
• Pico-8 compatibility + cartridge (P8/P8.PNG) format support
• Audio support is in progress

It works on all platforms (Linux/OSX/Windows), in the browser (via Emscripten), and on tiny hardware like Raspberry Pi 2/3.

The console is inspired from the awesome Pico-8, so there is a compatibility mode (not 100%) available with Pico-8 console and cartridges (P8/PNG).

Demos

The time for each frame is slow (10ms) in the GIF, and doesn't correspond to the speed of the game.

Editor mode:

More advanced examples:

• Advanced Micro Platformer - Starter Kit http://www.lexaloffle.com/bbs/?tid=28793 in Python https://github.com/Gigoteur/PX8/tree/master/games/amp

• 2D Terrain Generation (http://www.lexaloffle.com/bbs/?uid=12213) in Python https://github.com/Gigoteur/PX8/tree/master/games/terrain

• Voxel framework (http://www.lexaloffle.com/bbs/?tid=28308) in Python https://github.com/Gigoteur/PX8/tree/master/demos/voxel

Download

You can get directly the latest version via git:

git clone https://github.com/Gigoteur/PX8.git
cd PX8

Binaries

Or you can get binaries for multiples platforms directly on itch.io:

• Raspberry Pi (available)
• Windows (Work in progress)
• Linux (Work in progress)
• Mac (Work in progress)

Requirements

You will need multiple things:

• SDL2
• python3
• libreadline

Linux

Packages:

• libsdl2-dev
• libreadline-dev
• libpython3-dev

Raspberry Pi

Please enable the GL Driver (7 - Advanced Options -> Ac - GL Driver -> Yes) via:

sudo raspi-config

OSX

Build

You could build PX8 with cargo directly, in release mode for example, with the support of Python and Lua.

cargo build --features="cpython lua" --release 

Resolution

By default the resolution will 128x128 but you can change the default values by specifying the values of the env variables PX8_SCREEN_WIDTH + PX8_SCREEN_HEIGHT during the compulation:

PX8_SCREEN_WIDTH=256 PX8_SCREEN_HEIGHT=256

Example:

PX8_SCREEN_WIDTH=256 PX8_SCREEN_HEIGHT=256 cargo build --release

With GFX-RS

If you want to use the gfx_rs renderer (WIP):

cargo build --features="gfx_rs_renderer" --release 

SDL + Opengl

You can force opengl with SDL via the '-o' option:

./target/release/px8 -o ./games/ski/ski.px8

With Emscripten

You must follow the following guide to install Emscripten.

You can see example of PX8 + Emscripten in the demos repository. You could also see live example from your browser:

• Hello World [Source Code] [Live Demo]
• Lua Cartridge [Source Code] [Live Demo]
• Cast [Source Code] [Live Demo]

Coordinate system

Each pixel can be access from 0 to 128 (or the new defined width/height) :

Keyboard Shortcut

Player 1:

• cursors, Z,X / C,V / N,M

Player 2:

• ESDF, LSHIFT,A / TAB,Q,E

System shortcut:

• F2: FPS debug
• F3: Take a screenshot
• F4: Take a video
• F5: Save the current cartridge
• F6: Switch between editor/play mode
• F7: Switch to the next available palette

Run a cartridge

You should be able to run it directly by providing the path of the cartridge:

./target/release/px8 ./games/ski/ski.px8

Demos

You could run the API demos:

./target/release/px8 -s 4 ./demos/api_demos.py 

or some fancy demos:

./target/release/px8 -s 4 ./demos/demos.py
./target/release/px8 -s 4 ./demos/voxel/voxel.px8
./target/release/px8 -s 4 ./demos/pong/pong.px8

Edit a cartridge

You can edit the GFX in the cartridge by using the specific '-e' option, and alternate between the run mode and the editor with 'F6':

./target/release/px8 -s 4 -e ./games/ski/ski.px8

and you can save the GFX with 'F5'.

Display options

Change the scale

With the '-s' option you can change the size of the console, so you can increase it (2/4/8/10).

You can also use the fullscreen option by using '-f' option.

SDL + OpenGL

You can add the '-o' option to force SDL to use OpenGL

Compatibility mode with PICO8

You could load a PICO8 cartridge file by using the '-m pico8' option to convert the Lua code.

How to create a new cartridge

PX8 will call 3 functions, at startup or during the runtime:

• _init : Called once on startup, mainly to initialize your variables
• _update: Called once per visible frame, mainly to get keyboard input for example
• _draw: Called once per visible frame, mainly to draw things on the screen :)

After that you can use the API to do your game. There is no limitation of what you can do in Python or Lua languages.

By default I don't do any modification in the Python or Lua interpreter, so you are free to create threads, load native files, etc

Python

You can create a classical Python program, all you need is to define the previous functions (_init, _update, _draw), and you can import any packages.

def _init():
  px8_print("INIT")
  
def _update():
  px8_print("UPDATE")
  
def _draw():
  px8_print("DRAW")

Lua

function _init()
  print("INIT")
end

function _update()
  print("UPDATE")
end

function _draw()
  print("DRAW")
end

Cartridge format

Format	Read	Write
P8	✅	✅
P8.PNG	✅	🔴
PX8	✅	✅

API documentation

API	Rust	Python	Lua
camera	✅	✅	✅
circ	✅	✅	✅
circfill	✅	✅	✅
clip	✅	✅	✅
cls	✅	✅	✅
color	✅	✅	✅
cursor	🔴	🔴	🔴
ellipse	✅	✅	✅
ellipsefill	✅	✅	✅
fget	✅	✅	✅
flip	🔴	🔴	🔴
fset	✅	✅	✅
line	✅	✅	✅
pal	✅	✅	✅
palt	✅	✅	✅
pget	✅	✅	✅
print	✅	✅	✅
pset	✅	✅	✅
rect	✅	✅	✅
rectfill	✅	✅	✅
sget	✅	✅	✅
spr	✅	✅	✅
sset	✅	✅	✅
sspr	✅	✅	✅
trigon	✅	✅	✅
trigonfill	🔴	🔴	🔴
btn	✅	✅	✅
btnp	✅	✅	✅
map	✅	✅	✅
mget	✅	✅	✅
mset	✅	✅	✅

More details here about each function with the arguments: API