4 releases
Uses old Rust 2015
0.0.4 | Jul 14, 2017 |
---|---|
0.0.3 | May 12, 2017 |
0.0.2 | Jan 25, 2017 |
0.0.1 | Jan 10, 2017 |
#8 in #8-bit
2.5MB
15K
SLoC
PX8
- Demos
- Download
- Requirements
- Build
- Resolution
- Coordinate System
- Keyboard Shortcut
- Run a cartridge
- Edit a cartridge
- Display options
- How to create a new cartridge
- Cartridge format
- API documentation
PX8 is an Open Source Fantasy Console (128x128 pixels default resolution) 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.
- 128x128 pixels default resolution
- Predefined palettes (pico-8, c64, etc)
- 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)
- Editor for the sprite and map data
- PX8 format to be able to use your favorite code editor for Python/Lua/Rust
- Mutliple fonts support (pico-8, bbc, cbmII, appleII)
- Change the screen definition dynamically and the aspect ratio
- Screenshot (PNG) / Video recording (GIF)
- Pico-8 compatibility + cartridge (P8/P8.PNG) format support
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%, and it is not the goal of the project) available with Pico-8 console and cartridges (P8/PNG).
You can follow the development here.
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/examples/voxel
-
BR: it is an example from duckduckontheloose (https://github.com/seleb/DuckDuckOnTheLoose) https://github.com/Gigoteur/PX8/tree/master/games/BR
-
Flappy bird clone(http://p1xl.com/files/flappy.p8): https://github.com/Gigoteur/PX8/tree/master/games/flappy
More gifs ?
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 latest binaries for multiples platforms directly on itch.io. Only the Raspberry PI and Linux builds are free to download, but you can build your own executable for free (see the BUILD instruction):
Requirements
You will need multiple things:
- SDL2
- SDL2_mixer
- python3
Linux
Packages for Debian/Ubuntu:
- libsdl2-dev
- libsdl2-mixer-dev
- libpython3-dev
Raspberry Pi
Please enable the GL Driver (7 - Advanced Options -> Ac - GL Driver -> Yes) via:
sudo raspi-config
OSX
Install external dependencies via brew:
- brew install python3
- brew install sdl2
- brew install sdl2_mixer
Right now you need to export the DYLD_FALLBACK_LIBRARY_PATH env variable for the python support, e.g:
- export DYLD_FALLBACK_LIBRARY_PATH=/usr/local/Cellar/python3/3.5.1/Frameworks/Python.framework/Versions/3.5/lib
Build for Linux/Windows/OSX
The first thing to do is to install Rust, so please go to rustup and follow all instructions.
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 calling the mode API function:
mode(width, height, [aspect_ratio])
Example:
mode(128, 128, 1.0)
mode(512, 128, 4.0)
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. After that you can find some help here.
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]
- Hello World 2 [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: Information debug (FPS, time execution (draw,update), palette name)
- F3: Take a screenshot (png)
- F4: Take a video (gif)
- F5: Save the current cartridge's data (if opened with editor mode)
- F6: Switch between editor/play mode (if opened with editor 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 ./examples/api_demos.py
or some fancy demos:
./target/release/px8 -s 4 ./examples/demos.py
./target/release/px8 -s 4 ./examples/voxel/voxel.px8
./target/release/px8 -s 4 ./examples/pong/pong.px8
./target/release/px8 -s 4 ./games/ski/ski.px8
./target/release/px8 -s 4 ./games/amp/amp.px8
./target/release/px8 -s 4 ./games/terrain/terrain.px8
./target/release/px8 -s 4 ./games/BR/BR.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
You will be able to find more technical documentation in the wiki
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 | ✅ | ✅ | ✅ |
ellipse | ✅ | ✅ | ✅ |
ellipsefill | ✅ | ✅ | ✅ |
fget | ✅ | ✅ | ✅ |
fset | ✅ | ✅ | ✅ |
font | ✅ | ✅ | ✅ |
line | ✅ | ✅ | ✅ |
mode | ✅ | ✅ | ✅ |
pal | ✅ | ✅ | ✅ |
palt | ✅ | ✅ | ✅ |
pget | ✅ | ✅ | ✅ |
✅ | ✅ | ✅ | |
pset | ✅ | ✅ | ✅ |
noise | ✅ | ✅ | ✅ |
noise_set_feed | ✅ | ✅ | ✅ |
rect | ✅ | ✅ | ✅ |
rectfill | ✅ | ✅ | ✅ |
sget | ✅ | ✅ | ✅ |
spr | ✅ | ✅ | ✅ |
sset | ✅ | ✅ | ✅ |
sspr | ✅ | ✅ | ✅ |
trigon | ✅ | ✅ | ✅ |
trigonfill | 🔴 | 🔴 | 🔴 |
btn | ✅ | ✅ | ✅ |
btnp | ✅ | ✅ | ✅ |
map | ✅ | ✅ | ✅ |
mget | ✅ | ✅ | ✅ |
mset | ✅ | ✅ | ✅ |
More details here about each function with the arguments: API
Dependencies
~31MB
~628K SLoC