
                            * 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 coins to unlock the exit  and earn extra balls.  Red coins are
worth 5.   Blue coins are  worth 10.  A  free ball is awarded  for 100
coins.


Requirements:

    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 Neverball levels)
    Pasi Kallinen       (Neverputt holes)
    Derek Arndt         (OSX packaging)
    Phil Harper         (TheOpenCD packaging, icons)
    Max Gilead          (Debian packaging)
    Michael Sterret     (Gentoo ebuild)
    Christoph Frick     (OSX port)
    Jeremy Messenger    (FreeBSD port)
    Erik Auerswald      (Mouse invert)
    Corey Edwards       (Joystick select)
    Kyle Hoker          (Feature ideas and testing)

    Countless others for play testing and bug reports.

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



* BUILDING

Under Unix, Linux, and OSX, simply run

    make

Under Windows, build using the provided Visual Studio solution.

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
    SHIFT  Fast camera rotation

    F1     Default Camera                            (configurable)
    F2     Lazy Camera                               (configurable)
    F3     Static Camera                             (configurable)

    F7     Toggle wire mode
    F8     Toggle nice mode
    F9     Toggle frame counter
    F10    Snap a screenshot
    F12    Toggle look-around mode



* INSTALLATION

The game  searches for game assets  in the following  three places, in
this order.  If the game is  to be installed globally, at least one of
them must be set.

1) The directory specified on the command line.

2) The directory given by the NEVERBALL_DATA environment variable.

3) The directory given by the CONFIG_DATA variable defined in config.h

A normal Linux installation would  probably copy the data directory to
"/usr/local/games/neverball/" and  change the CONFIG_DATA  variable to
match.

A  normal  Windows installation  would  simply  copy  the entire  game
directory  to "C:\Program Files\Neverball"  and leave  the CONFIG_DATA
variable to its default value "./data".



* USER DATA FILES

Neverball creates  a directory called ".neverball" in  which it stores
user  data  files.  These  files  include  high  scores, replays,  and
configurations.  Under Unix, Linux,  and OSX this directory is created
in your home directory.  Under Windows it is assumed that the user has
permission  to write to  the game  data directory,  and the  user data
directory is created within.



* HIGH SCORES

The top three fastest times through each level, and the top three coin
scores for each  level are stored in files  named neverballhs-* in the
user data directory.

The top  three fastest  times and  most coins scores  for each  set of
levels are also stored.  To achieve  a set score, the player must play
through all 25 levels of a set in one attempt.

The total set time will  include time spent during both successful and
unsuccesful level  plays, thus  time-outs and fall-outs  count against
the total time.

The  total  set  coin  count  will include  only  coins  collected  on
successful  level plays.   This  prevents unbounded  coin scores  from
being collected on levels with more than 100 coins.



* REPLAYS

Neverball  includes a  mechanism for  recording and  replaying levels.
The player may enter  a name for each replay at the  end of the level.
By default, the most recent unsaved  level will be saved to the replay
file named "Last".

Replay  files are  stored in  the user  data directory.   They  may be
copied freely.  To  view a replay you have  downloaded, simply move it
to  the user  data directory  and it  will appear  in the  Replay menu
in-game.

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



* CONFIGURATION

Game  settings are stored  in the  file neverballrc  in the  user data
directory.  This file is created  when the game exits.  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_invert 0

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

    key_camera_1 f1
    key_camera_2 f2
    key_camera_3 f3
    key_camera_l left
    key_camera_r right

        These keys  define keyboard mappings for  camera selection and
        rotation.  Key  names are specified using  SDL's canonical key
        naming convention.  The three camera behaviors are as follows:

        1 - Strict  camera stays behind the ball by  cueing off of the
        velocity of the  ball.  It is very  responsive,  but sometimes
        confusing.

        2 - Lazy  camera chases a point a set  distance from the ball.
        It is seldom  surprising, but at times it  is not sufficiently
        responsive.

        3 - Locked camera  does not rotate  except by  player command.

    view_fov 50
    view_dp  75
    view_dc  25
    view_dz  200
    
        These keys  define the view of the ball.  They give  the field
        of view in degrees,  the height of the view point,  the height
        of the view center,  and the horizontal distance from the ball
        in centimeters, respectively.  (The ball is  50 centimeters in
        diameter in most levels.)
        
        The default values  for these keys changed with version 1.2.6.
        Some players may be interested in using the  old values.  They
        were as follows:
        
            view_fov 40
            view_dp  400
            view_dc  0
            view_dz  600

    rotate_fast 200
    rotate_slow 100

        These keys control the rate of camera rotation.  Roughly, they
        give  the rate  of lateral  camera motion  in  centimeters per
        seconds,  so the  actual rotation  rate depends  upon view_dz,
        above.  The fast rate is used when the Shift key is held down.

    fps 0

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

    nice 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.

    coin png/coin.png
    ball png/ball.png

        These keys determine the texture image applied to the coin and
        ball.  If  you prefer collecting euros  to collecting dollars,
        set:

            coin png/euro_coin.png

    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.

    joystick 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.

    joystick_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.

    joystick_axis_x 0

        Joystick horizontal axis number

    joystick_axis_y 1

        Joystick vertical axis number

    joystick_button_a 0

        Joystick menu select button

    joystick_button_b 1

        Joystick menu cancel button

    joystick_button_r 2

        Joystick counter-clockwise camera rotation button

    joystick_button_l 3

        Joystick clockwise camera rotation button

    joystick_button_exit 4

        Joystick exit button



Contact: <robert.kooima@gmail.com>
