Playscii logo

Documentation

Playscii (pronounced play-skee) is an art, animation, and game creation tool.

See the Art Mode page for detailed info on how to create artwork and animations with Playscii.

See the Game Mode page for detailed info on how to create games with Playscii.

General README-type information on running and building Playscii follows.


Table of Contents


System Requirements

Playscii should run in Windows Vista, 7, 8.1, and 10 (32-bit and 64-bit), macOS 10.10 Yosemite or higher, and any reasonably modern desktop version of Linux.

Hardware-wise you'll need a video card that's capable of OpenGL 2.1, with Vertex Array Object and GLSL 1.30 support. If your computer was made after 2008 or so, you're probably fine. You can check to see if your hardware supports VAOs here; if you see OES_vertex_array_object in the "Supported Extensions" section, you're good. As for GLSL version, Playscii will detect your supported version on startup and quit with an error message if version 1.30 or higher is not found.

Running

If you're looking at Playscii in the itch.io app, simply click Install and then Launch! Note that if you're doing this in Linux, you're running from source and should follow the instructions for installing dependencies in that section.

If you downloaded the ZIP file with "win32" in its name, you should have a Windows build you can run by double-clicking playscii.exe, without needing to install anything listed below.

If you downloaded the DMG file, this is the Mac application bundle which can be installed in the standard manner, by opening the disk image file and then dragging Playscii.app into your Applications folder. You don't need to install anything else.

If you downloaded the ZIP file with "source" in its name or from the project's source code repository, you can run Playscii from its source code on any of the supported operating systems if you have Python and a few libraries installed. See the Running from Source and Building sections below.

Configuration

Most users won't need to edit them, but just in case - Playscii places its configuration files in OS-appropriate folders:

Documents (your art, color palettes, etc) are stored in eg ~/Documents/Playscii in OSX and Linux, and the appropriate "My Documents" folder in Windows.

You can override many program defaults in the file playscii.cfg. This file starts with a few possible "commented-out" overrides to get you started. You can enable one by deleting the # character at the start of the line. Every line in that file must be a valid Python expression, so edit carefully!

Likewise you can change Playscii's keyboard command binds in the binds.cfg file.

Running from Source

Running from source is only recommended if a binary build isn't available for your OS and/or you want to play with the latest still-in-development version. If you're doing so, you'll need some version of Python 3 - sorry, Python 2 is not supported - and the following libraries:

These libraries are all pretty easy to install using PIP, the package manager that comes with Python 3.4 and later. Find the pip executable and run it from the command line, like so:

pip install pysdl2 pyopengl numpy pillow appdirs pdoc

In Windows the pip executable is in the Scripts\ subfolder of your Python install folder, eg c:\Python34. On some Unix-like systems (Linux and OSX) the pip binary to run may be called pip3 to distinguish it from any Python 2 installations. On Unix-like systems you may also need to run pip as super user to let it install system libraries, eg by pre-pending sudo to the command above.

Once you have the dependencies installed, you can run Playscii from source like so:

python playscii.py [optional name of art file to open]

Building

To produce Windows EXE builds, in addition to the above dependencies you'll also need PyInstaller.

Simply run build_windows.bat and it will place a complete build in the dist\ subfolder. You may need to provide needed DLLs, such as SDL2.dll, SDL2_mixer.dll and its dependencies.

The process for Mac Application bundles is quite similar: install PyInstaller, and run the build_mac.sh script.

Roadmap

Many of Playscii's intended features have now been implemented, but you can see a list of planned features on the Playscii Trello. Please don't take anything there as a promise, though. If you'd find something on there especially valuable, feel free to vote or comment!



<< back to Playscii main page