manual.txt

                            * 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 ball is awarded for 100 coins.


* INSTRUCTIONS

Click Play  to begin.   Mouse motion tilts  the floor.   Mouse buttons
rotate the viewpoint.  The following  keyboard controls are defined by
default; most  of them can  be changed  in a configuration  file.  See
below for details.

    ESC    Pause and resume / Exit
    SHIFT  Fast camera rotation

    1      Chase Camera (default)
    2      Lazy Camera
    3      Manual Camera

    F9     Toggle frame counter
    F10    Hide HUD
    F12    Snap a screenshot

    UP     Tilt the floor forward
    DOWN   Tilt the floor backward
    LEFT   Tilt the floor left
    RIGHT  Tilt the floor right

    D      Rotate the view right
    S      Rotate the view left

    R      Restart the current level

    TAB    Cycle through scores in high-score table


* LEVEL PROGRESSION

Neverball levels are  grouped in level sets. There are  two game modes
or ways  of progressing through  the levels:  the Normal mode  and the
Challenge mode.

In  Normal  mode,   no  track  of  lives  or  balls   is  kept.   Each
unlocked/completed level is immediately  accessible and can be retried
and restarted at any point.

In Challenge mode,  the player is given a limited  number of balls and
attempts to  complete all  of the  levels in  turn, starting  with the
first level.   The game  ends once  the balls  run out  or the  set is
completed.  A set score is recorded upon completion.  Levels cannot be
restarted freely.

A set may contain a number of bonus levels.  Bonus levels are unlocked
by playing Challenge mode and completing  all of the levels leading up
to  each bonus  level.   After  unlocking a  bonus  level, it  becomes
playable in Normal mode.


* USER DATA FILES

Neverball  creates a  directory in  which it  stores user  data files.
These  files include  addons, screenshots,  high scores,  replays, and
configurations.

Under Unix,  Linux, and OSX  this directory is called  ".neverball" (a
hidden folder) and is created in the user's home directory.

Under Windows it is created in "Documents\My Games\Neverball".


* ADDONS

Additional Neverball content is usually distributed as a ZIP or PK3 (a
renamed ZIP) file.   A properly packaged ZIP file can  be installed by
dropping it into  the user data directory.  After a  restart, the game
will automatically use the new content.


* SCREENSHOTS

Screenshots taken in-game with the F12 key are stored in PNG format in
the user data directory.


* HIGH SCORES

The top  three fastest  times through each  level, the top  three coin
scores  and the top  three fastest  unlock scores  for each  level are
stored in the Scores directory within user data directory.

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

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


* 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.nbr".

Replay files are stored in the  Replays directory within the user data
directory.  They may be copied freely.   To view a replay, simply open
it with the Neverball executable. You  can also move it to the Replays
directory and it will appear in the Replay menu in-game.


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

    width  800
    height 600

        These keys determine the effective display resolution.  If for
        any reason  the resolution you're looking  for isn't available
        in the in-game settings, you can modify these values instead.

    fullscreen 0

        This key determines whether or not the application starts full
        screen.

    display 0

        Selects on which display the game window is placed.

    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      1
    key_camera_2      2
    key_camera_3      3
    key_camera_l      s
    key_camera_r      d
    key_camera_toggle e

        These keys  define keyboard mappings for  camera selection and
        rotation.  The three camera behaviors are as follows:

        1 - Chase  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 - Manual camera  does not rotate  except by  player command.

	key_camera_toggle toggles camera behaviour between 1 and 3.

    mouse_camera_1      none
    mouse_camera_2      none
    mouse_camera_3      none
    mouse_camera_l      left
    mouse_camera_r      right
    mouse_camera_toggle middle

        These   keys  match   the  respective   key_camera_*  options.
        Accepted values are: "none" (for no mapping), "left", "right",
        "wheelup",  "middle", "wheeldown"  or a  numeric  mouse button
        index.

    key_forward  up
    key_backward down
    key_left     left
    key_right    right

        These keys define keyboard mappings for tilt control.

    key_restart r

        This key defines a keyboard  mapping for a mid-game restart of
        the  current  level.   Handy  when  trying  to  record  a  new
        high-score, this function isn't available in challenge mode.

    key_score_next tab

        This key  defines a keyboard mapping for  cycling through Most
        Coins / Best Times /  Fast Unlock score tabs in the high-score
        board.

    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 300
    rotate_slow 150

        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 0

        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.

    ball_file ball/basic-ball/basic-ball

        This key determines the model used for the ball.

    replay_name %s-%l

        This  key specifies  the  format of  the  default replay  name
        generated when saving replays.

        The value  of replay_name  can include regular  characters and
        special  character sequences  which act  as place-holders  for
        certain "dynamic" text.  These sequences are recognised:

            %s  current set identifier (such as "easy" or "mym")
            %l  current level identifier (such as "03" or "IV")
            %%  single percentage sign

        Any other sequence starting with % is ignored.

        The resulting  replay name is  also suffixed by  an underscore
        and  a unique  2-digit number  to avoid  name collisions  with
        existing replays.

    stats 0

        This  key enables  print-out (to  standard output)  of running
        statistics of  the current  frame time  and frames-per-second,
        averaged over one second.  Most people won't need this.

    screenshot 0

        This key  holds the current  screenshot index.  The  number is
        incremented every time a  new screenshot is taken (by pressing
        F12) and it is appended to the image file name.

    stereo 0

        This key  enables quad-buffered stereo viewing  for those with
        the hardware to support it.  1 is on, 0 is off.

    vsync 1

        This key controls vertical  blanking synchronization.  1 is on
        (and is the default), 0 is off.

    multisample 0

        This key enables multisample full-screen antialiasing.  Values
        can be 2,  4, 8, etc., and can be  overspecified; in such case
        the game  will search for  the highest level  of multisampling
        supported by  your hardware.  (The best  value eventually gets
        written to the config file.)

    mipmap 1
    aniso  0

        These  keys  control  mipmapping  and  anisotropic  filtering,
        respectively.

        With mipmapping, smaller versions of  each texture are kept in
        video  memory, and  are referenced  when a  texture is  viewed
        from  a distance.   This  improves video  cache coherence  and
        eliminates texture  "swimming" on detailed textures  when seen
        from afar.  To disable mipmapping, set mipmap to 0.

        Related to mipmapping is anisotropic filtering.  "Anisotropic"
        basically means "not the same from all directions".  It refers
        to  cases where  a texture  might need  to be  compressed more
        vertically than  horizontally.  For  example, if a  texture is
        applied  to a  flat surface  and seen  from far  away then  it
        appears  much wider  than high.   Anisotropic filtering  takes
        care of  this.  To enable  it, set aniso  to a small  power of
        two.   If  you  have  weak hardware,  this  feature  won't  do
        anything.

    joystick 1

        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_axis_u 2

        Joystick axis number for view rotation control

    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

    wiimote_addr

        This key  specifies the address  of your Nintendo  Wii Remote.
        For more  information, see the  section on using  Wiimote with
        Neverball.


* WIIMOTE SUPPORT

For information  on how to build  the game with Wiimote  support under
Linux, see instructions in the file INSTALL in the source archive.

To use it, first make sure you've set up all the Bluetooth mumbo-jumbo
in your kernel  and what-not.  Once this is done,  you'll need to find
out your Wiimote's address like this:

    $ hcitool scan
    Scanning ...
            00:1B:7A:3E:45:7F       Nintendo RVL-CNT-01

This  hexadecimal   string  must  go   in  the  neverballrc   file  as
"wiimote_addr 00:1B:7A:3E:45:7F" so that the game knows that there's a
Wiimote to be used.

Now, when  you start the game  everything will proceed normally  but a
background thread  will place your Bluetooth  device into discoverable
mode.  You've got about  15 seconds to press 1 and  2 on your wiimote.
The Wiimote's LEDs will flash, and once the game makes friends with it
the Player 1 LED will be lit.  If you don't activate your Wiimote then
the  game  will  behave  normally and  the  Bluetooth  discovery  will
eventually time out.

From  there,  the  Wiimote  digital  pad works  like  a  joystick  for
navigating menus.  A and  B buttons are the A and  B buttons.  Home is
Pause.  Plus and  Minus are camera rotation controls.   Also, the tilt
sensor controls the floor.

The  Wiimote tilt  sensor is  a  surprisingly noisy  device, so  heavy
filtering is applied to the input.   For this reason, the controls may
feel sluggish.  This might improve with  an IR sensor bar, but has not
been tested.


* HILLCREST LABS LOOP SUPPORT

For  information on how  to build  the game  with Hillcrest  Labs Loop
support on all platforms, see  instructions in the file INSTALL in the
source archive.

To use a loop  to control the game, it must be  plugged in at startup.
If  the  loop  is  plugged  in,  it will  be  chosen  as  the  default
controller.   Hold  the  loop  upright,  and tilt  it  left/right  and
forward/backwards to control the  game.  Occasionally the sensors will
get miscalibrated;  to fix  this, simply  set the loop  on a  table or
stable surface for about 5 seconds, and the controls should be back to
normal.

When  not in game  mode, the  loop will  act like  a mouse  to control
menus.  When the  game is playing, the left  and right buttons control
the camera and the middle button will bring up a pause menu.

Web: <http://neverball.org/>