Playscii should run in Windows Vista, 7, 8.1, and 10 (32-bit and 64-bit), macOS 10.12 Sierra 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 GLSL 1.30 support. If your computer was made after 2008 or so, you're probably fine. Playscii will detect your supported GLSL version on startup and quit with an error message if version 1.30 or higher is not found.

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 the section below.

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.

Please note that as of at least macOS 10.13 "High Sierra" and later, you will have to bypass an OS-level security feature to run Playscii, as it is non-notarized software. I have no plans to offer notarized macOS builds. Once you've got Playscii.app in your Applications folder, run the following command from a Terminal:
xattr -dr com.apple.quarantine /Applications/Playscii.app
You should then be able to click the app to launch it as normal.

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.

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

• Windows 7-10: C:\Users\[your username]\AppData\Local\Playscii
• Linux: ~/.config/Playscii
• macOS: ~/Library/Application Support/Playscii

Documents (your art, color palettes, etc) are stored in eg ~/Documents/Playscii in macOS 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 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:

• PySDL2
• PyOpenGL
• Numpy
• Pillow or any compatible derivative of Python Image Library (PIL)
• appdirs
• pdoc - only needed if you want to generate documentation from Playscii's source itself. Mainly useful for game creation.

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:

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

On most systems, SDL2_mixer - which Playscii's Game Mode uses for sound playback - is a separate library from SDL2 core, so you'll also need to install that, by providing SDL2_mixer.dll and all its dependency DLLs in Windows, or as a system library (eg from a package manager) on *NIX-based operating systems.

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

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

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.

Michael Lazar has created a fork of Playscii on Github, with only a few very minor changes, that has been reported by some Mac users to work well on their newer systems. See these notes from that repository for specific commands to run to get the right build environment. I cannot offer support for builds made with this fork, however.

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!