"Those Funny Funguloids!"
Copyright (c) 2006-2007, Mika Halttunen & Teemu Ruokolainen


This document is intented to help you build Funguloids under Linux and
was written by Piet <funguloids@superpiet.de>.


REQUIREMENTS
------------

  To build funguloids from source, you need to have a number of tools and
  libraries installed. Note that most of these things should already be
  available prepackaged and optimized for your distribution, so it is
  recommended that you check your distribution first before downloading the
  source code from the websites.

* Linux development tools (your distribution should come with these)
    - gcc compiler (you need the C++ compiler g++), bintools

* Ogre 3D SDK (version 1.4 or later)
    - 3D graphics library (http://www.ogre3d.org/)

  Be sure to have compiled support for NVIDIA's Cg Toolkit into Ogre as
  Funguloids makes use of shaders :-)

  There are also reports of problems with the FreeImage library. Ogre can use
  FreeImage or DevIL for image loading. Due to licensing issues FreeImage is
  the current default library so if you experience crashes related to
  FreeImage try compiling Ogre against DevIL (use '--disable-freeimage' when
  configuring the Ogre source).

* Object Oriented Input System (OIS)
    - cross platform input system (http://sourceforge.net/projects/wgois)

* Lua (version 5.1 or later)
    - light-weight and powerful scripting language (http://www.lua.org/)

    There is some confusion in the naming of the pkg-config file across the
    various Linux distributions. Debian package based distris have named the
    file 'lua5.1.pc' to allow multiple versions of Lua to be installed in
    parallel. Self compiled versions use 'lua.pc' and some distris might even
    ship Lua development packages without this file. configure searches in some
    reasonable locations and upon failure tries to use the pkg-config file. Use
    the '--with-lua=' option to specify the path to the include file 'lua.hpp'.

* OpenGL
    OpenGL libraries and headers are specific to your graphics card. Make sure
    that you have hardware accelerated OpenGL drivers installed. Software
    renderers like Mesa will make funguloids unplayable slow.


  Funguloids needs sound support and can use OpenAL or FMOD for sound
  rendering (I personally recommend using OpenAL over FMOD since it is free,
  open source and does not boast about being best in every aspect):

* FMOD Ex
  - commercial sound library (http://www.fmod.org/)
  - comes with built-in support for Ogg Vorbis and MP3

OR

* OpenAL
  - open source sound library and 3D sound renderer (http://www.openal.org/)
  - both the OpenAL library and the AL utilities (ALUT) are needed. They might
    come in one or two packages, depending on your distribution.

  With OpenAL, you can optionally enable support for background music from
  Ogg Vorbis or MP3 files. You then need to supply:

* Ogg Vorbis support
  - open and patent-free audio encoding (http://www.vorbis.com/)
  - libvorbis and libogg are both needed. You are problably best off with
    your distribution's optimized packages.

AND/OR

* MP3 support via libmad
  - high-quality MPEG audio decoder (http://www.underbit.com/products/mad/)
  - called MAD because of its effects on developers (just kidding, it is
    'MPEG Audio Decoder')


INSTALLATION
------------

  In best autotools tradition, simply enter the source directory and execute

    ./configure
    make
    make install

  This will configure funguloids to be installed in the '/usr/local/' tree with
  automagic detection of libraries and features. For the last part (the
  'make install') you need to have write access to the directories you are
  installing in (probably root for a system-wide installation; try
  'sudo make install'). For configuration options see below.

  If you have downloaded the sources without data files, you will need to copy
  them into '${prefix}/share/games/funguloids/'. The files needed are
  'bootstrap.mpk' and 'funguloids.mpk' (${prefix} defaults to
  '/usr/local/' and can be set with the --prefix option).

  Start the game by executing '${prefix}/games/funguloids'. It will create a
  directory ('.funguloids/') in your home directory containing the
  configuration and highscores (unless you compiled the shared highscores
  feature, see below).

  If you like you can add system-wide music files (only the extensions 'ogg'
  and 'mp3' will be recognised) in  '${prefix}/share/games/funguloids/music/'.
  Each user can have his own additional tracks in '~/.funguloids/music/'.

  To remove Funguloids from your computer use 'make uninstall'. It will
  probably leave some empty directories but most of the files will be
  removed ;-)


  You can customise the build process by specifying additional parameters for
  the configure script. Type './configure --help' for additional informations.
  The most important options are:

    --prefix=<path>
        This is the basic path under which funguloids will be installed. You
        can set this to '$HOME' if you want to install it in your home
        directory. Defaults to '/usr/local/'.

    --enable-shared-highscore
        This enables the use of a system-wide highscore file. It will be
        installed as '/var/games/funguloids/hiscore.lst' (no configure
        option so far) with its group set to 'games', which allows users from
        this group to save their highscores. You have to make sure by yourself
        that this group exists and all players are in this group (Funguloids
        cannot be installed setgid as GTK (used by the Ogre setup) prohibits
        that for security reasons). Also note that there is no locking so
        concurrent write access might garble the scores. Use this feature on
        your own risk or send a patch if you really depend on more robust
        score keeping across systems.

ICON FILE
---------

  There is a icon included that you can use for your desktop manager's menu.
  Its location is '${prefix}/share/pixmaps/funguloids.png'.


SETTING UP AUDIO OUTPUT
-----------------------

  Getting audio output to work on Linux can be a pain! Today ALSA is the sound
  system of choice and comes with "legacy support" for OSS, the old (Linux)
  interface for audio output via /dev/dsp. While ALSA supports multiple sound
  sources (applications doing audio output simultanously) and a lot of other
  gimmicks, it still has to be set up (although the defaults are rather
  resonable)!
  My first advice is to simply try it. Start Funguloids and if you have sound
  output everything is fine. If not, read on ;-)
  However, this is not the place to go too deep into all those details but a
  few words might save you some headaches. I assume that some sort of sound
  output already works on your system (like playing back MP3s).
  One basic problem is that only one application can use the sound hardware. If
  your desktop manager uses a 'sound daemon' of some kind (like esd or artsd)
  this daemon has already connected to your sound card and allows no other
  application to do audio output. Note that this is not only true for 'sound
  daemons'. Every application that does sound output directly to the sound card
  will block the hardware). In this case you can 1) either stop the sound
  daemon, 2) tell Funguloids to use this sound daemon or 3) configure ALSA to
  allow more than one applications to connect to the sound hardware.
  Option 1) should be clear. Everytime you want to play Funguloids you
  have to stop the sound daemon and start it again after you finished. This is
  not really convenient and not neccessary in most cases. 2) With OpenAL sound
  rendering you can tell OpenAL to use the sound daemon. You do this by creating
  a configuration file in your home directory named '.openalrc'. This file
  should at least contain the following line:
    (define devices '(SOUNDDEVICE))
  with SOUNDDEVICE being one (or a space-separated list) of 'alsa', 'esd',
  'arts', 'sdl', or 'native'. Search the web for more informations about the
  '.openalrc'. To my knowledge there is no current official documentation for
  this file. Please correct me if I'm wrong.
  Option 3) can be achived by either using hardware that supports sound mixing
  ('SB Live' comes to my mind) or using ALSA's 'dmix' plugin. With a recent
  ALSA library you can simply specify
    (define alsa-out-device "plug:dmix")
  in your '.openalrc'. However, all applications that are supposed to do audio
  output at the same time must use 'plug:dmix' or else it won't work. This can
  be remedied by defining ALSA's 'default' device to be 'plug:dmix', so that
  all recent (ALSA >= 1.0) applications do so be default. You can put your
  configuration into $HOME/.asoundrc or system-wide in /etc/asound.conf.
  For details have a look in the ALSA wiki at http://alsa.opensrc.org/,
  notably http://alsa.opensrc.org/.asoundrc and http://alsa.opensrc.org/Dmix

  If you have choosen FMOD Ex for audio rendering, you can tell it to use ALSA
  or OSS. In Funguloids' configuration file 'gamesettings.cfg' you can set
  the option 'fmod_use_alsa' to 'on' fpr ALSA output and 'off' for OSS. The
  default is to use ALSA.


  Clicks, pops and scratching sound
  ---------------------------------
  Even if you have audio output working you might get some 'noise' / clicking /
  popping sound (you name it). This is encountered by more than a few people
  and is in my experience always caused by sample rate mismatch. For example
  your sound card is fixed to a sample rate of 48 kHz and you are playing back
  audio data with a sample rate of 44,1 kHz (quite common since DVD audio is at
  48kHz and CD audio is at 44,1 kHz). During playback the sound system has to
  convert 44,1 to 48 kHz. When this isn't done carefully you end up with single
  samples just not 'fitting together' - and producing the dreaded clicks. While
  the actual resampling isn't the problem, the timing is. Again, search the web
  for details. You can set up ALSA to do explicit sample
  rate conversation or tell dmix to use your preferred sample rate (dmix'
  default sample rate is 48 kHz). However, while this might fix the clicks for
  one sample rate it might break the other so do some testing until you are
  happy with both. I cannot give a simple solution as the details depend on
  your hardware but you should start setting dmix' 'rate' option to 44100 and
  try different values for the configuration options 'period_size' and
  'buffer_size' as they are the keys. And make sure you have read the wiki
  pages mentioned above.


Good luck and have fun!

