PSXLE (or PSX __L__earning __E__nvironment) is an PlayStation 1 (PSX) emulator, written in C, that allows programmatic control of PlayStation games. This documentation covers the associated Python library PSXLE-py, which allows simple per-game integration with OpenAI Gym and other Python applications. The design and development of PSXLE is shown in the paper on arXiv.
Note: a pre-built version of psxle
will soon be available from http://carlospurves.com/, if you're using this version, you can skip to "Installing".
The following are requirements to build psxle
on your own computer. Note that this has only been tested on Ubuntu 16.04+ and other systems may require additonal steps.
cmake
xvfb
libsdl2-dev
libglib2.0-dev
libgtk-3-dev
While cmake
can be used directly for a system-wide installation, you can make use of the pre-prepared build_psxle
script to automate the process for most cases. You should then be able to build psxle
using:
./build_psxle.sh
The default build directory will be set to ./psxle_build
(relative to where the script runs), although you can choose a different directory as an argument to the build script.
To install, run:
./install_psxle.sh
The Python library's main function is to expose a Console
class to represent a PlayStation instance. This class is designed to support interations that broadly fall into four categories:
-
General
run
andkill
control the executing process of the emulatorfreeze
andunfreeze
will freeze and unfreeze the emulator's execution, respectivelyspeed
is a property ofConsole
which, when set, will synchronously set the speed of execution of the console, expressed as a percentage relative to default speed
-
Controler
hold_button
andrelease_button
simulate a press down and release of a given controller button, call these control eventstouch_button
holds, pauses for a given amount of time and then releases a given buttondelay_button
adds a (millisecond-order) delay between successive control events
-
RAM
read_bytes
andwrite_byte
to directly read and write console memory.add_memory_listener
andclear_memory_listeners
control which parts of console memory will have asynchronous listeners attatched when the console startssleep_memory_listener
andwake_memory_listener
tell the console which listeners are active
-
Audio/Visual
-
start_recording_audio
andstop_recording_audio
contrrol when the console should record audio and when it shoud stop -
get_screen
synchronously returns annp.array
of the console's instantaneous visual output
-
Using a combination of these methods allows for the creation of a game abstraction. See the PSXLE paper on aXiv for more discussion. More information will be made available here soon.
Note: console emulation requires a disk image of a game. None are provided here. These should be obtained legitimately through purchased copies and used only for personal use.
To begin running a PlayStation console (assuming installation is successfull), run:
python3 quickstart.py <PATH TO ISO>
This will start a console to run the specified game and enter a python REPL with a Console
object given by c
. You can type, for example c.freeze
to freeze the console, or c.speed = 200
to run the console at double speed.