ASCII DASH Files

ASCII DASH v1.3 as of 14.May.2024
=================================

This software is a remake of the famous BOULDER DASH game for the
Atari 800 from 1984. It utilizes the NCurses library to play the game
on a text terminal, hence the name ASCII DASH.

Installation on Linux
---------------------

Before starting the installation, please make sure that you have the
latest software installed on your Linux system.

On Ubuntu for example, we open a terminal window and type the
following command line, which asks you to enter your super-user
password and proceeds with the necessary updates:

   sudo apt-get update

To compile the game with GCC and CMake, the NCurses development
library needs to be installed as a dependency. It has the following
package name:

   libncurses5-dev

To install the above package (plus GCC and CMake), we type the
following command line in the terminal:

   sudo apt-get install g++ cmake libncurses5-dev

Optionally, the SDL library via the packages

   libsdl1.2-dev libsdl-mixer1.2-dev

or the SDL2 library via the packages

   libsdl2-dev libsdl2-mixer-dev

needs to be installed to provide sound playback. The SDL library also
provides joystick support, if the joystick package is installed. In
order install SDL with joystick support, we type:

   sudo apt-get install libsdl1.2-dev libsdl-mixer1.2-dev joystick

Now we restart the computer and proceed with the game:

After we have unpacked the game software into a directory
(e.g. "ascii-dash" in our home folder), we open a terminal and change
the working directory to that directory:

   cd ascii-dash

Then the application can be compiled and started with the following
command line:

   cmake . && make && ./main

On Debian Linux and Linux Mint the installation procedure is exactly
the same. On other Linux distributions the procedure is very similar -
just the package installer and the package names are usually
different.

For example, to install GCC, CMake and NCurses on openSUSE based
distributions, we type:

   sudo zypper install gcc-c++ cmake ncurses5-devel-static

On Fedora based distributions we type:

   sudo yum install gcc-c++ cmake ncurses5-devel-static

Installation on VirtualBox
--------------------------

If your Ubuntu system is running on a VirtualBox virtual machine, the
joystick emulation is activated, when the mouse is located outside of
the terminal window. When the mouse is positioned to the left, right,
top and bottom of the window, the virtual joystick is going to be
moved into the respective direction.

Installation on MacOS X
-----------------------

Same as for Ubuntu, except that you just install XCode (in particular
the XCode command line tools) and CMake.

Installation on Windows
-----------------------

Same as for Ubuntu, except that you install Ubuntu as a virtual
machine in Virtual Box (www.virtualbox.org). It is recommended to use
Virtual Box 6.0 and Ubuntu 18.04 LTS.

In principle, the game also runs in the Windows-Subsystem for Linux
(WSL), but this is not recommended due to various WSL issues like
missing sound playback etc. Please use Virtual Box.

Loading custom cave data
------------------------

To load a custom cave set, supply the path, the cave file name prefix
and the number of caves on the command line, for example to load the
original Boulder Dash I caves that are supplied with ASCII DASH, we
type:

   ./main data BD-I 20

Importing BDCFF cave data
-------------------------

Many custom cave sets are supplied as a BDCFF file (Boulder Dash
Common File Format). To import those caves into ASCII DASH, we use
GDash (https://bitbucket.org/czirkoszoltan/gdash) as a file format
converter:

   gdash <caveset.bd> -t <output> -q

For ease of importing a cave set, the "bdcff" directory contains the
"convertcaves.sh" script, which batch processes all *.bd files in that
directory.

Trouble Shooting
----------------

This game was tested on Ubuntu 18.04 with a Speedlink Competition Pro
USB joystick. For other setups the joystick may or may not function
properly. To see, if the joystick is working, we type:

   jstest /dev/input/js0

If the joystick axis or fire buttons are not identified correctly,
then the mapping can be changed with the --axis1 --axis2 --invert1
--invert2 --fire1 and --fire2 command line options.

Program Usage
-------------

To see the entire list of available command line options, we type:

   ./main --help

Happy ASCII coding!
Stefan