PIEMulator
==========

Play the DOS games of Pie in the Sky Software's POWER engine family on
modern Windows and Linux: Pie in the Sky's own games, from Lethal Tender
(1993) on, the games made with the 3D Game Creation System (GCS), and the
games on POWER 3D and the engines derived from it. GCS itself runs too,
with its level editor and paint program.

No DOS box is needed. Play the games as they looked in the 90s, or with an
OpenGL view in widescreen, with mouse look and WASD controls.

Web page:  https://rickomax.github.io/piemulator
Discord:   https://discord.gg/kKvzfqFTJ
Ko-fi:     https://ko-fi.com/X8X3MRF5W


No original code inside
-----------------------

PIEMulator contains no code from GCS, its engines or any game, and was not
made from their source code. It is a reimplementation of the PC the games
were written for.

When a game starts, PIEMulator reads the game's own programs from your
folder and turns them into native code in memory, on your computer. When
the game ends, that code is gone. Nothing made from a game is saved,
shipped with PIEMulator or sent anywhere.


Games are not included
----------------------

PIEMulator does not include, sell or distribute any game, nor GCS itself.
To play, you need your own copy of the game's files, as it was shipped,
its programs included. Please don't ask for copies of games in the
project's channels.


Getting started
---------------

1. Extract PIEMulator to a folder of its own.

2. Make a folder named "games" next to piemulator, and put each game in a
   folder of its own inside it. The game list shows each game's usual
   folder name when you select it; a game in a folder with that name is
   found by itself. Or keep a game where it is and choose its folder with
   the "..." button. To use GCS itself, put its folder, named GCS, next to
   piemulator.

       PIEMulator\
           piemulator.exe
           games.ini
           GCS\                                                 (GCS itself)
           games\
               Lethal_Tender_(1993)_(Pie_in_the_Sky_Software)\
               Stop_Nick_Macki_(1993)_(Pie_in_the_Sky_Software)\
               ...

   On Linux the "games" folder's name is lower case. An unpacked archive
   can be used as it is: the game is found up to three folders deep.

3. Run piemulator.exe (on Linux, piemulator). It opens the game list.

4. Pick a game and press Play. The game starts in the same window, and the
   list comes back when it ends.


The game list
-------------

    Enter       Play the selected game
    Tab         Type the game's folder
    F2          Controls: the key bindings
    F3          Save the folders and settings
    F4          Sort the list by name, year or author
    Esc         Exit
    A letter    Jump to the games starting with it

Start maximized, Start in fullscreen, Mouse sensitivity and Volume apply
to every game. Games with adult content are hidden unless you ask for them
(see "The settings file").


While playing
-------------

    = / -           Less or more HUD: the full HUD, a minimal one along
                    the window's edges, or none at all
    Alt+Enter       Fullscreen or a window
    Alt+F7          Modern controls on or off (the game's original keys)
    Alt+F8          Widescreen on or off
    Alt+F9          The OpenGL view, or the game's own renderer
    Alt+F10         Show the frame rates
    Alt+F11         Capture the mouse, or let it go
    Alt+F12         Smooth textures and picture
    Alt+any key     Sends that key itself, not what it is bound to
                    (to type a name, say)


Controls
--------

While you play, the modern controls are on. Each key sends one of the
game's own keys, so the game works as it always did. All the game's other
keys still work: weapons 1 to 9, the map, Esc and the rest.

There are three sets of bindings: while playing, while choosing an object
to drop, and in the menus (also the map and the pause and help screens).
A key that isn't listed sends itself.

    Press          Playing                 Choosing an object    Menus
                                           to drop
    W              Walk forward            W                     Up
    S              Walk backward           S                     Down
    A              Sidestep left           Previous object       Left
    D              Sidestep right          Next object           Right
    E              Pick up, read a memo    Drop it               Choose (Enter)
    Q              Choose an object        Cancel (Esc)          Q
                   to drop
    Space          Jump                    Space                 Space
    Mouse          Turn, and look up and down in the OpenGL view
    Left button    Fire                                          The game's mouse
    Right button   Pick up                                       The game's mouse

Some games come with bindings of their own, to match their controls. In
Stop Nick Macki, which kicks and fires with Space, the left mouse button
and Ctrl send Space.

To change the bindings, press F2 (Controls) in the game list, for the
selected game or for every game. Click an input and press the game's key
it should send, or choose Pick up, None, or Clear to go back to the
default. Add input takes any key, mouse button or the mouse wheel.


The settings file
-----------------

The game list keeps its settings in piemulator.cfg, next to piemulator (or
in your user settings folder, if that one can't be written). It can be
edited by hand, for example:

    show_adult=1             list games with adult content
    mouse_sensitivity=1.5    0.25 to 2.5
    bind.all.wheelup=2       the mouse wheel picks weapons 2 and 3
    bind.all.wheeldown=3

What PIEMulator knows of each game (its name, folder, default bindings) is
in games.ini, next to piemulator.


Troubleshooting
---------------

The game list can't find a game
    Select the game and choose its folder with "...". The folder must hold
    the game as it was shipped, programs included. An installer or an
    archive must be installed or unpacked first.

A game runs slowly
    If the console says the game "is not a known game executable", its
    program was changed or comes from a release PIEMulator doesn't know.
    It still runs, but slower. Please tell us which game and release it
    is, on Discord, so it can be added.

Windows warns that the program is from an unknown publisher
    The beta builds are not signed yet. Choose "More info", then "Run
    anyway". Or, before unpacking, right-click the downloaded .zip, choose
    Properties, tick Unblock and press OK.

The mouse doesn't turn the view
    Press Alt+F11 to capture the mouse, and check that the modern controls
    are on (Alt+F7).

The controls don't match the game's instructions
    The modern controls change them on purpose. Alt+F7 turns them off, for
    the game's original keys. Or change a single key in Controls (F2).

I can't type a name, or a letter does something else
    Hold Alt while typing: Alt with a key sends that key itself.

Something looks wrong in the OpenGL view
    Press Alt+F9 to switch to the game's own renderer, and let us know on
    Discord which game and where.

On Linux, the folder picker doesn't open
    It needs zenity or an xdg-desktop-portal. You can also type the
    folder: select the game and press Tab.


Limitations
-----------

- No network, modem or serial play.
- No joystick.
- PIEMulator is a beta. Not every game has been played through to the end.


About
-----

PIEMulator is developed and maintained by Ricardo Reis. It is free, and
may not be sold, or included with anything that is sold, without
permission. It is not affiliated with or endorsed by Pie in the Sky
Software.

3D Game Creation System, POWER 3D and Lethal Tender are (C) Pie in the Sky
Software. The games made with them belong to their authors. PIEMulator,
its developers and contributors are not responsible for unauthorised or
illegal redistribution of copyrighted game files.

Third-party software:
- SDL 3 - zlib License
- Capstone - BSD 3-Clause License
- TinyCC - GNU LGPL 2.1, as libtcc.dll (libtcc.so on Linux), which you
  may replace with your own build. Source: https://repo.or.cz/tinycc.git,
  commit 43c7708b85681a2fd4451c8a541af4494a8919b2, unmodified.

The licences, and how TinyCC was built, are in the "licenses" folder.
