Skip to content
/ PX8 Public
forked from Gigoteur/UnicornConsole

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

License

MIT license
6 stars 47 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

peterbrittain/PX8

BranchesTags
 
 

Repository files navigation

Travis for PX8 PX8 Crate LICENSE

PX8

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.

Specifications:

  • 128x128 pixels default resolution
  • Predefined 16 colour palettes (pico-8, c64, etc)
  • Python 3 / Lua 5.3 support for the cartridge without tokens limit
  • Desktop/Mobile/Browser (Emscripten) support
  • Controls with dpad + 2 buttons (gamecontroller/joystick support)
  • Unlimited 8x8 sprites
  • Map 128x32 8-bit cels
  • Editor for the sprite / map
  • PX8 format to be able to use your favorite code editor for Python/Lua/Rust
  • Mutliple fonts support (pico-8, bbc, cbmII, appleII)
  • Audio support (wav/mp3/etc) and an integrated Chiptune with Klystrack
  • Change the screen definition dynamically and the aspect ratio dynamically
  • Screenshot (PNG) / Video recording (GIF)
  • Pico-8 compatibility + cartridge (P8/P8.PNG) format support

It works on all platforms (Linux/OSX/Windows/Raspberry PI), in the browser (via Emscripten).

You can follow the development of the project here.

Donate

Editor mode:

Multiple resolution support:

More advanced examples:

More gifs ?

Download

You can get prebuild binaries for many platforms directly on itch.io or you can build your own executable with the latest changements (see the BUILD instruction):

Source code

You can get directly the source code of the latest version via git:

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

Build

The first thing to do is to install Rust, so please go to rustup and follow all instructions.

The build is the same for all platforms (Linux/OSX/Windows).

You must build PX8 with cargo directly in release mode to have the best perf. And you can choose to disable the following plugins for the cartridge:

  • cpython
  • px8_plugin_lua (rust-lua53 with modification)

For example to have all features:

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

Requirements

You will need multiple things:

  • SDL2
  • python3

Linux

Packages for Debian/Ubuntu:

  • libsdl2-dev
  • libpython3-dev
Raspberry Pi

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

sudo raspi-config

OSX

Install external dependencies via brew:

  • brew install python3
  • brew install sdl2

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

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:

Coordinate system

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

Keyboard Shortcut

Right now only 2 players could play a cartridge.

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
  • F7: Switch to the next available palette
  • P: Pause the console

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

or some fancy demos:

./target/release/px8 -s 4 ./examples/demos.p8
./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 directly the GFX (Sprites + Map) with the 'F6' hotkey (to alternate between the run mode and the editor), or to open the cartridge by using the specific '-e' option:

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

and you can save the GFX data 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

The syntax of Python program is exactly the same that the Python 3.

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

This is a modified version of Lua 5.3.4 that supports:

  • Compound-assignment operators (+=,-=,*=,/=,%=)
function _init()
  print("INIT")
end

function _update()
  print("UPDATE")
end

function _draw()
  print("DRAW")
end

Tutorials

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 ✅ ✅ ✅
print ✅ ✅ ✅
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

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

About

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

Resources

Readme

License

MIT license

Code of conduct

Code of conduct
Activity

Stars

6 stars

Watchers

3 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

No packages published

Languages

  • C 76.7%
  • Rust 11.3%
  • HTML 6.1%
  • C++ 2.4%
  • Python 2.1%
  • Java 1.1%
  • Other 0.3%