Adonthell 0.3


    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License as
    published by the Free Software Foundation.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    COPYING file for more details.



Installation:
=============

When compiling Adonthell from source, refer to the INSTALL and
NEWBIE files for details. Additional information for compiling
on a specific platform can be found in the respective README.<os>
files.

Note that this package alone doesn't allow you to play anything -
you'll need a game package in addition to this one. The official
game package for this release is Waste's Edge release 0.3. If you
don't already have it, you should download it and install it next to
this package.


Configuring Adonthell:
======================

The most important settings (Screen Mode, Audio Volume and Language)
can be changed within the game itself. Some additional settings can
only be changed by manually editing the configuration file. This
file is create the first time you run Adonthell, and can usually be
found in: $HOME/.config/adonthell/adonthellrc.


The available options and what they do are:

- Screen-mode

  Whether Adonthell should run fullscreen or in windowed mode
  0 = Windowed mode, 1 = Letterbox mode, 2 = Fullscreen mode

  In window mode, a window just small enough to fit your desktop
  is created.

  In letterbox mode, the game runs fullscreen at your desktop
  resolution, but preserves its 4:3 aspect ratio. So on 16:9
  or even wider screens common today, you will see a black border
  at the edges of the screen, but the image quality will be good.

  In fullscreen mode, your display resolution will be switched
  to 640x480 and (depending on your display), no border will be
  present. Due to scaling and stretching of the graphics to fit
  your display, image may appear somewhat blurry.


- Screen

  Which display to use in fullscreen mode in case you are using
  multiple monitors
  0 = your primary display,
  1 = 2nd display,
  2 = 3rd display,
  and so on


- Language [locale]

  Specifies which language to use. As long as this option is unset,
  the language is determined by one of the following environment
  variables: LANG, LC_ALL or LC_MESSAGES. Once the option is set,
  it overrides any environment variable. For a listing of valid
  locale strings, run 'locale -a'.

  Of course, the game you run has to provide the translation you
  chose here, otherwise you'll get the default (i.e. English) text.
  Languages available in this package:

  Language    Locale
  ------------------
  Danish      da_DA
  Dutch       nl_NL
  English     C
  French      fr_FR (incomplete)
  Italian     it_IT
  Spanish     es_ES (incomplete)

  If new languages become available, they will be announced on
  our website: http://adonthell.nongnu.org/

  If you want to help translate Waste's Edge into your own
  language, please have a look at The Translation Project
  http://translationproject.org/domain/wastesedge.html


- Font [font.ttf]

  Chose a true type font to use for displaying text.

  If the default font doesn't suit you, or if it does not contain
  the glyphs required by the Language you selected, you can specify
  a different font here. Either enter an absolute path to a font
  file in true type format or enter the font name and copy the font
  into <gamedatadir>/gfx/window/font/ .


- Quick-load

  Whether the last saved game should be automatically continued at
  startup. Only works if at least one saved game exists.
  0 = disable, 1 = enable


- Audio-channels

  Whether sound should be mono or stereo
  0 = Mono, 1 = Stereo


- Audio-resolution

  Whether audio output should be 8 or 16 bit
  0 = 8 bit, 1 = 16 bit


- Audio-sample-rate

  0 = 11025 Hz, 1 = 22050 Hz, 2 = 44100 Hz


- Audio-volume

  The mixer setting, 0 - 100 %

  (Note that a value of 0 will turn audio completely off)


Running Adonthell:
==================

Okay, now you're ready to launch the program. Type

$> adonthell-0.3 <gamename>

to run the game named <gamename>. To get a list of currently
installed games you can play, type:

$> adonthell-0.3 -l

This will print a list of the installed games you can launch
with above command.

For further information on how to play Adonthell, please refer to the
PLAYING file that comes with the game data.


Directories:
============

- $HOME/.config/adonthell
  contains the configuration file

- $HOME/.local/share/adonthell/
  contains your saved games

- Global data directory
  You can get this directory by invoking 'adonthell -d' (by default
  /usr/local/share/adonthell). This is the directory where games will
  install to. If you have a game installed somewhere else, you can
  play it by invoking 'adonthell -g </full/path/to/my/game>'


Release Notes:
==============

The main purpose of this release is to ensure that Adonthell -
Waste's Edge can still be enjoyed on modern operating systems.
To that end, support for newer versions of GCC, SDL and Python
have been implemented.

Adonthell - Waste's Edge -, or v0.3 for short is no complete RPG.
As the v0.3 implies, the engine is far from being finished, although
it should be free of severe bugs.  Missing features include combat,
items and magic.  But you can interact with NPC's and the game
world, and the internals enable us to create a basic plot, so v0.3
is actually playable!

You're greatly invited to report us bugs, problems, or anything you
think we should know. Any feedback is appreciated, so don't hesitate!


Contact:
========

You can reach us in various ways:

Mailing list:  adonthell-general@nongnu.org
Web site:      http://adonthell.nongnu.org
Tech support:  http://savannah.nongnu.org/support/?group_id=702


Reporting Bugs:
===============

We hope you'll never have to, but if you discover a problem, we
would like to hear about it. Please use the Development mailing list
(adonthell-devel@nongnu.org) for that. You can find informations on
this and other mailing lists at

    http://adonthell.nongnu.org/contact/mailinglist.html


Thank you for trying this software.
- The Adonthell team.

                Adonthell on GNU/Linux

This file contains additional information for compiling Adonthell
under GNU/Linux. For general compilation instructions refer to the
INSTALL file. Even more details are found within the NEWBIE file.

"Universal" AppImage package:
=============================
In order to create a binary distributable package of Adonthell
that is not tied to any single distribution, a set of scripts are
provided to create a standalone AppImage package, that works in
a similar fashion as application bundles on MacOS X.

Prerequisites
-------------
In addition to the dependencies listed in the INSTALL file, the
following extra packages are required:

* AppImageKit
  https://github.com/probonopd/AppImageKit

  See https://github.com/probonopd/AppImageKit/wiki/Creating-AppImages
  for detailed installation instructions.

* virtualenv
  https://pypi.python.org/pypi/virtualenv

  See https://virtualenv.pypa.io/en/stable/ for installation
  instructions.

Creating Adonthell AppImage
---------------------------

In the adonthell-0.3.x directory, run

    make_linux_appimg.sh

If all goes well, it should configure, build and install Adonthell into
Adonthell.AppDir, including all shared libraries and a complete Python
environment. All that is mising now in the bundle is the actual game data.

Change into the wastesedge-0.3.x directory and run

    make_linux_appimg.sh ../adonthell-0.3.x/Adonthell.AppDir

(adjusting the location to the .AppDir as needed). This will configure,
build and install Waste's Edge into the Adonthell.AddDir folder, which
then will be turned into a self-extracting, executable, compressed ISO
image containing Adonthell and all it's dependencies, ready to run on
(almost) any Linux system with a recent enough version of glibc.

For maximum compatibility, it is recommended to create the AppImage on
a fairly old build system.

                       Adonthell on MacOS X

This file contains additional information for compiling Adonthell
under MacOS X. For general compilation instructions refer to the
INSTALL file. Even more details are found within the NEWBIE file.


Preparations:
=============
Install the Developer command line tools or XCode from

    http://developer.apple.com/macosx/

or the App Store.

If you plan to create a proper application bundle for Adonthell, it is
advised to install all the required dependencies under /usr/local. If
this folder does not exist yet, you should create it now.

Open the terminal and type

    sudo mkdir /usr/local/

Before installing any dependencies, you should also consider which
version of OSX to target. By default, this will be the version you
build it on (and likely newer versions). If support for older versions
are desired, this can be achieved via the MACOSX_DEPLOYMENT_TARGET
environment variable. E.g.

    export MACOSX_DEPLOYMENT_TARGET=10.6

Due to limitations of recent SDL2 versions, the minimum supported
target as of June 2016 is OSX 10.6 Snow Leopard and may be higher in
the future. Use an older version of SDL2, if this proves to be an
issue.

Now you can go about installing all the dependencies listed in the
INSTALL file. Extract each archive, cd into the respective directory
and run the usual commands

    ./configure
    make
    sudo make install

Please refer to the documentation of each library for more detailed
instructions.

Note that for the official OSX binaries, the following configure
options were used instead of the default

    Freetype   : ./configure --with-png=no --with-bzip2=no
    SDL2       : ./configure --without-x
    SDL2_mixer : ./configure --disable-music-ogg-shared


Compiling Adonthell:
====================
After all libraries have been installed successfully, it just takes
another

    ./configure
    make
    sudo make install

to compile and install Adonthell locally. Repeat the same steps for
the Waste's Edge data and you are done. You can now launch Adonthell
by typing

    /usr/local/bin/adonthell-0.3 wastesedge


Creating a .App bundle:
=======================
If you'd rather create nice bundle that can be placed into your Applications
folder, you can use the included make_osx_bundle.sh scripts instead of manually
compiling Adonthell and Waste's Edge. However, make sure all prerequisite
libraries are still installed under /usr/local.

Now, in the adonthell-0.3.x directory, run

    ./make_osx_bundle.sh

If all goes well, it should configure, build and install Adonthell into
Adonthell.app and copy and prepare all the required libs from /usr/local.
All that is mising now in the bundle is the actual game data.

Change into the wastesedge-0.3.x directory and run

    ./make_osx_bundle.sh ../adonthell-0.3.x/Adonthell.app

(adjusting the location to the bundle as needed). This will configure,
build and install Waste's Edge into the Adonthell.app bundle, making it
ready to use.


Codesigning and creating a disk image:
======================================
In order to distribute the app bundle created above, the usual way on OSX is
to package everything into a disk image (.dmg). In order to automate this, the
make_dmg.sh in the osx/ directory can be used. This also contains the required
commands to sign the bundle and resulting image, provided a suitable certificate
is present in your keychain. Signing of the image itself requires OSX 10.11.4 or
newer.

Creating of the disk image requires the dmgbuild Python module, available from

    https://pypi.python.org/pypi/dmgbuild

Download, extract, then install by running

    python setup.py install --user

In case installation fails because of conflicting pyobjc system packages, update
those by running before repeating the installation

    sudo env CC=clang easy_install -U pyobjc-core

In order to enable code signing, set the environment variable CODESIGN_IDENTITY
to the name of the certificate, as shown by the Keychain Access.app, i.e.:

    export CODESIGN_IDENTITY="<certificate name>"

Now change into the wastesedge-0.3.x/osx directory and run

    ./make_dmg.sh ../../adonthell-0.3.x/Adonthell.app

                       Adonthell on Windows

This file contains additional information for compiling Adonthell under
Windows for x86 and/or x64. For general compilation instructions refer
to the INSTALL file. Even more details are found within the NEWBIE file.


Build Environment:
==================
The recommended way to compile Adonthell for Windows is to use the mingw64
distribution of the GNU Compiler Collection. Since Adonthell uses a build
system based on GNU Autotools, a unixish environment such as provided by
MSys2 is also required. So start by downloading the latest version from:

  https://sourceforge.net/projects/msys2/files/Base/x86_64/

For detailed installation instructions please refer to:

  https://github.com/msys2/msys2/wiki/MSYS2-installation

As an alternative, http://www.msys2.org/ also links to the download and
runs you through the installation with a number of screenshots.

Using the 64 bit version of MSys2 is recommended as it can create both 32bit
and 64bit binaries.


Dependencies:
=============
Once MSys2 has been installed, you will need to install a number of packages
through the MSys2 package manager (pacman) which are required by Adonthell.

The package names below are the 64bit variants and as such result in a 64bit
version of Adonthell. To create 32bit binaries, replace x86_64 with i686 in
the package names below. Install each package by typing

  pacman -S <package name>

The following packages are required:

  tar
  make
  mingw-w64-x86_64-gcc
  mingw-w64-x86_64-gettext
  mingw-w64-x86_64-pkg-config
  mingw-w64-x86_64-python3
  mingw-w64-x86_64-SDL2_mixer
  mingw-w64-x86_64-SDL2_ttf


Compiling Adonthell:
====================
After installing all the libraries and tools above, we're finally
ready to compile Adonthell. For this, make sure to exit the MSys2 shell
and open the mingw64 (or mingw32) environment instead.

Extract both adonthell-0.3.x.tar.gz and wastesedge-0.3.x.tar.gz and
in each directory, run the usual commands:

    ./configure
    make
    make install

to compile and install Adonthell locally. You can now launch Adonthell
by typing

    adonthell-wastesedge


Distributable Package:
======================
To create a version of Adonthell that can be used outside the mingw
environment, or on a different computer running Windows, a set of scripts
are provided. Make sure that the dependencies listed above are installed
and the compile step worked. Then, in the adonthell-0.3.x directory, run

    ./make_windows_pkg.sh

If all goes well, it will configure, build and install into a directory
called Adonthell/, including all the required DLLs not present in the
Windows System32 folder. Now only the actual game data is missing.

Change into the wastesedge-0.3.x directory and run

    make_windows_pkg.sh ../adonthell-0.3.x/Adonthell

(adjusting the location to the Adonthell directory as needed). This will
configure, build and install Waste's Edge and make the package ready to
use. You can now zip it up and transfer it to any other Windows system.

To start the game, use the adonthell-wastesedge.bat script.


Installer:
==========
To make distribution of the Windows package a little more professional,
a .msi installer can be built once the steps above are complete.

This requires the WiX Toolset, downloadable from

    http://wixtoolset.org/

Make sure it is in your PATH, i.e.

    export PATH=$PATH:/C/Program\ Files\ \(x86\)/WiX\ Toolset\ v3.10/bin

(adjusting the location to the WiX bin directory accordingly)

Change into the wastesedge-0.3.x/win32 directory and run

    ./make_msi.sh ../../adonthell-0.3.x/Adonthell

(adjusting the location to the Adonthell directory as needed).

If all goes well, the installer will be created in the current directory.


Additional Notes:
=================
(1) In order to embed the correct icon in the Adonthell executable,
    the rcedit program needs to be present in the PATH. It can be
    dowloaded from

        https://github.com/electron/node-rcedit/tree/master/bin

(2) In order to keep the list of external DLLs included in the package
    at a minimum, it pays to use custom compiled versions of SDL2_mixer,
    Freetype and SDL2_tff. Configure those with the following flags

    Freetype   : ./configure --with-png=no --with-bzip2=no
    SDL2_mixer : ./configure --disable-music-ogg-shared

    In this case, make sure to install mingw-w64-x86_64-libvorbis and
    mingw-w64-x86_64-SDL2 instead of SDL2_mixer and SDL2_ttf.

(3) Due to bugs present in SDL 2.0.4, it is recommended to use version
    2.0.5 (once available), or to compile SDL from source as well, using
    at least revision 17e0ded12e6f:

        https://hg.libsdl.org/SDL/archive/17e0ded12e6f.tar.bz2

    To compile this using mingw, the following patch also needs to be
    applied

        https://bugzilla.libsdl.org/show_bug.cgi?id=3399

(4) Codesigning of the Adonthell executable and the MSI installer will
    be done automatically by the make_msi.sh script, provided you have
    Microsofts signtool from the Windows Platform SDK in your PATH and
    a suitable certificate added to the Windows certificate store.