USURPER FOR THE WEB
===================

Usurper, the dark fantasy BBS classic by Jakob Dangarden (1993, GNU
GPL), running on its own on ordinary shared hosting: no BBS around it.
Players register with an email address, log in on a web page and play
the game in the browser's terminal. The sysop runs the town from a
panel.

This is the same game that runs as a native door under ATDT BBS, in
the same version. A fix to one is a fix to both.


WHAT YOU NEED
-------------

- PHP 8.1 or newer with the pdo_sqlite, mbstring, json, openssl and
  session extensions (every cPanel host has them). PHP's opcache should
  be on, as it is on nearly every host: the terminal asks the server
  for news every few seconds, and opcache is what makes that cheap.
- A directory the web server can write to (data/ is made at install).
- An SMTP mailbox to send from: the one your hosting account gives
  you is fine. Players confirm their email address before they play,
  and a lost password is reset by email.
- A cron job. The game's day turns at midnight (the townsfolk move,
  the crown taxes, the paper is written) and that needs a scheduled
  job; the installer prints the line to paste into cPanel.


INSTALLING
----------

1. Upload the contents of this folder (usurper-web/) to the place on
   your site where the game should live: the web root, or a
   subdirectory such as /usurper/, or a subdomain.
2. Open install.php in your browser and follow the four steps: the
   environment check, the site and its sysop account, outgoing mail
   (send yourself the test letter), install.
3. Paste the cron line from the last page into cPanel, Cron Jobs
   (every five minutes). The sysop panel's dashboard says when it last
   ran.
4. Log in to the panel (admin/) with the sysop account and set the
   town up under "The game": the town's name, the shopkeepers, the
   allowances, everything the DOS version's editor offered.
5. Open the town page and play. The sysop plays like anyone else.

The installer locks itself when it is done. You may delete
install.php afterwards.


UPGRADING
---------

Upload the new folder over the old one. Nothing under data/ is in the
zip, so your database, your art and your settings are untouched, and
the site brings its own schema up to date on the next request. Take
a backup first anyway (the panel's dashboard has a download button).


THE LAYOUT
----------

  index.php      the town page (who is on, the heroes, log in)
  play.php       the terminal
  api.php        what the terminal talks to
  account/       register, verify, log in, forgot, reset
  admin/         the sysop panel
  cron.php       the scheduler entry
  install.php    the installer
  runtime/       the door kernel (borrowed from ATDT)
  assets/        the terminal client, the VGA font, the styles
  game/          the game itself (the same files as the ATDT door)
  data/          made by the installer: the database, art, logs

data/ must not be served by the web server. The installer writes an
.htaccess that denies it on Apache, and the panel's dashboard checks
whether the host honoured it; on another server deny it yourself.


LICENCE
-------

Usurper is free software under the GNU General Public License (see
COPYING). The terminal client and the door kernel are borrowed from
ATDT BBS with its licence.
