
                             * Neverball *


Tilt the  floor to roll a  ball through an obstacle  course within the
given time.  If the ball falls or time expires, a ball is lost.

Collect 100 coins  to save your progress and earn  an extra ball.  Red
coins are worth 5.  Blue coins are worth 10.


Neverball requires:

    SDL               http://www.libsdl.org/download-1.2.php
    SDL_image         http://www.libsdl.org/projects/SDL_image/
    SDL_mixer         http://www.libsdl.org/projects/SDL_mixer/
    SDL_ttf           http://www.libsdl.org/projects/SDL_ttf/



* THANKS TO

    Mehdi Yousfi Monod  (Feature ideas and levels)
    Max Gilead          (Debian packaging)
    Michael Sterret     (Gentoo ebuild)
    Christoph Frick     (OSX port)
    Jeremy Messenger    (FreeBSD port)
    Erik Auerswald      (Mouse invert)
    Corey Edwards       (Joystick select)

    Countless others for play testing and bug reports.

    http://www.happypenguin.org
    http://www.flipcode.com



* BUILDING

    make                     (Unix)
or
    nmake /fMakefile-W32     (Windows with MSVC)

The executables  will be copied to  the base directory.   Maps will be
processed and copied into data/sol/.  By default, an uninstalled build
may be executed in place.



* RUNNING

    ./neverball

Click Play  to begin.   Mouse motion tilts  the floor.   Mouse buttons
rotate the  viewpoint.  The  following keyboard controls  are defined.
See below for details.

    SPACE  Pause and resume / Release mouse grab
    ESC    End a game / Exit

    F1     Default Camera
    F2     Lazy Camera
    F3     Static Camera

    F9     Toggle frame counter
    F10    Snap a screenshot
    F11    Save the current demo



* DEMO REPLAY

Neverball  includes a  simple  mechanism for  recording and  replaying
games.  Each level played is  recorded to the file .neverballrp.  This
file may  be found in your home  directory under Unix, or  in the game
data directory under Windows.

The "Demo"  item of  the main  title menu plays  back the  most recent
recording.  Press F11 to copy  the current recording to a sequentially
numbered file.  This  allows you to save a  replay without immediately
overwriting it by playing the next level.  If a recording is preserved
while it is being created, it will be truncated.

Currently, the only way to  select a numbered recording for demoing is
to copy it on top of the existing .neverballrp file.

Note that replay files are  not currently portable between machines of
different byte order.



* INSTALLATION

The game executable may be moved as desired.

However, game  assets are described  using relative path  names.  Thus
the game must  run within the data directory in  order for asset names
to resolve correctly.  Upon starting,  the game will attempt to change
into this directory, as defined in config.h.

If the data directory is to  be renamed or moved for installation, the
CONFIG_PATH variable in config.h must be changed to match.

Alternatively, the CONFIG_PATH variable may  be set to "." if the game
is started  from within the data directory.   Even MORE alternatively,
the data path may be specified as the first command line option.



* CONFIGURATION

Global settings  are stored  in the file  .neverballrc.  This  file is
created  when  the  game exits,  and  should  be  found in  your  home
directory under Unix, or in the game data directory under Windows.  It
consists of key / value  pairs.  Some of these values are configurable
using  the in-game options  screen.  Other  meaningful keys  and their
default values follow.

    mouse_sense 300

        This  key controls  mouse  sensitivity.  The  value gives  the
        number of screen pixels the  mouse pointer must move to rotate
        the floor  through its entire  range.  A smaller  number means
        more sensitive.

    mouse_inv 0

        This key inverts the vertical mouse axis if set to 1.

    camera 0

        This   key   selects   from   3  different   camera   tracking
        modes. Throughout development,  a few different camera control
        strategies were tried.  Each  had its propents, but none could
        claim a majority.

        0 - Strict  camera stays behind the ball by  cueing off of the
        velocity of the  ball.  It is very  responsive,  but sometimes
        confusing.  Press F1 to select this camera in-game.

        1 - Lazy  camera chases a point a set  distance from the ball.
        It is seldom  surprising, but at times it  is not sufficiently
        responsive.  Press F2 to select this camera in-game.

        2 - Locked camera  does not rotate  except by  player command.
        Press F3 to select this camera in-game.

    fps 0

        This key enables an on-screen frames-per-second counter. Press
        F9 to toggle this flag in-game.

    niceness 1

        This  key  enables  a  delay  function  after  each  frame  is
        rendered, forcing a context  switch and ensuring that the game
        does not utilize 100% of the CPU.  0 is off, 1 is on.

        If the  frame rate is not  fast enough for you,  or you simply
        want to  test the  performance of the  game on  your hardware,
        disable it.

        Press F8 to toggle this flag in-game.

    stereo 0

        This key  enables quad-buffered stereo viewing  for those with
        the hardware to support it.  It gives an angle in degrees that
        determines the  interocular distance.  0  is normal non-stereo
        viewing.  2 gives  a  good  stereo effect.   If  the eyes  are
        swapped, give a negative value, like -2.

    joy 0

        This key  enables joystick control.  0  is off, 1  is on.  The
        game may still be controlled with the mouse even while gamepad
        control  is enabled.   However,  random noise  from an  analog
        controller at rest can disrupt normal mouse input.

    joy_device 0

        This  number selects  which joystick  to use if  more than one
        joystick is  found. 0 is the first  joystick, 1 is the  second
        and so on.

    axis_x 0

        Joystick horizontal axis number

    axis_y 1

        Joystick vertical axis number

    button_a 0

        Joystick menu select button

    button_b 1

        Joystick menu cancel button

    button_r 2

        Joystick counter-clockwise camera rotation button

    button_l 3

        Joystick clockwise camera rotation button

    button_exit 4

        Joystick exit button



* KNOWN ISSUES

At the  time of this writing,  there are known issues  with certain 3D
accelerater  boards  that  may  impact  or even  preclude  the  game's
function.  While it is good that the 3D hardware market is very broad,
it is an  unfortunate fact that OpenGL support  varies in quality from
one configuration  to another.   It is impossible  for a  developer to
work around bugs in all  boards, so some configurations must simply be
declared unsupported.

- The  Intel i8xx  series is  not supported  under Linux.   Its broken
multi-texturing  and  texture   clamping  make  Neverball  unplayable.
Windows support is fine.

- Several older Radeons including, but not limited to, the Mobility M5
and some  models of the  All-In-Wonder series are not  supported under
Windows.  Note that the Mobility M6 and all tested PCI Radeons down to
the 7500 are known to be very good.


<rlk@snth.net>
