## 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
- Running
- Configuration
- Running from Source
- Building
- Roadmap

#### System Requirements

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.

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

#### Configuration

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

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:

`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 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]`

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

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.

#### 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