README

   1
   2                             * Neverball *
   3
   4
   5 Tilt the  floor to roll a  ball through an obstacle  course within the
   6 given time.  If the ball falls or time expires, a ball is lost.
   7
   8 Collect coins to unlock the exit  and earn extra balls.  Red coins are
   9 worth 5.   Blue coins are  worth 10.  A  free ball is awarded  for 100
  10 coins.
  11
  12
  13 Requirements:
  14
  15     SDL               http://www.libsdl.org/download-1.2.php
  16     SDL_image         http://www.libsdl.org/projects/SDL_image/
  17     SDL_mixer         http://www.libsdl.org/projects/SDL_mixer/
  18     SDL_ttf           http://www.libsdl.org/projects/SDL_ttf/
  19
  20
  21
  22 * THANKS TO
  23
  24     Mehdi Yousfi Monod  (Feature ideas and Neverball levels)
  25     Pasi Kallinen       (Neverputt holes)
  26     Derek Arndt         (OSX packaging)
  27     Phil Harper         (TheOpenCD packaging, icons)
  28     Max Gilead          (Debian packaging)
  29     Michael Sterret     (Gentoo ebuild)
  30     Christoph Frick     (OSX port)
  31     Jeremy Messenger    (FreeBSD port)
  32     Erik Auerswald      (Mouse invert)
  33     Corey Edwards       (Joystick select)
  34     Kyle Hoker          (Feature ideas and testing)
  35
  36     Countless others for play testing and bug reports.
  37
  38     http://www.happypenguin.org
  39     http://www.flipcode.com
  40
  41
  42
  43 * BUILDING
  44
  45 Under Unix, Linux, and OSX, simply run
  46
  47     make
  48
  49 Under Windows, build using the provided Visual Studio solution.
  50
  51 The executables  will be copied to  the base directory.   Maps will be
  52 processed and copied into data/sol/.  By default, an uninstalled build
  53 may be executed in place.
  54
  55
  56
  57 * RUNNING
  58
  59     ./neverball
  60
  61 Click Play  to begin.   Mouse motion tilts  the floor.   Mouse buttons
  62 rotate the  viewpoint.  The  following keyboard controls  are defined.
  63 See below for details.
  64
  65     SPACE  Pause and resume / Release mouse grab
  66     ESC    End a game / Exit
  67     SHIFT  Fast camera rotation
  68
  69     F1     Default Camera                            (configurable)
  70     F2     Lazy Camera                               (configurable)
  71     F3     Static Camera                             (configurable)
  72
  73     F7     Toggle wire mode
  74     F8     Toggle nice mode
  75     F9     Toggle frame counter
  76     F10    Snap a screenshot
  77     F12    Toggle look-around mode
  78
  79
  80
  81 * INSTALLATION
  82
  83 The game  searches for game assets  in the following  three places, in
  84 this order.  If the game is  to be installed globally, at least one of
  85 them must be set.
  86
  87 1) The directory specified on the command line.
  88
  89 2) The directory given by the NEVERBALL_DATA environment variable.
  90
  91 3) The directory given by the CONFIG_DATA variable defined in config.h
  92
  93 A normal Linux installation would  probably copy the data directory to
  94 "/usr/local/games/neverball/" and  change the CONFIG_DATA  variable to
  95 match.
  96
  97 A  normal  Windows installation  would  simply  copy  the entire  game
  98 directory  to "C:\Program Files\Neverball"  and leave  the CONFIG_DATA
  99 variable to its default value "./data".
 100
 101
 102
 103 * USER DATA FILES
 104
 105 Neverball creates  a directory called ".neverball" in  which it stores
 106 user  data  files.  These  files  include  high  scores, replays,  and
 107 configurations.  Under Unix, Linux,  and OSX this directory is created
 108 in your home directory.  Under Windows it is assumed that the user has
 109 permission  to write to  the game  data directory,  and the  user data
 110 directory is created within.
 111
 112
 113
 114 * HIGH SCORES
 115
 116 The top three fastest times through each level, and the top three coin
 117 scores for each  level are stored in files  named neverballhs-* in the
 118 user data directory.
 119
 120 The top  three fastest  times and  most coins scores  for each  set of
 121 levels are also stored.  To achieve  a set score, the player must play
 122 through all 25 levels of a set in one attempt.
 123
 124 The total set time will  include time spent during both successful and
 125 unsuccesful level  plays, thus  time-outs and fall-outs  count against
 126 the total time.
 127
 128 The  total  set  coin  count  will include  only  coins  collected  on
 129 successful  level plays.   This  prevents unbounded  coin scores  from
 130 being collected on levels with more than 100 coins.
 131
 132
 133
 134 * REPLAYS
 135
 136 Neverball  includes a  mechanism for  recording and  replaying levels.
 137 The player may enter  a name for each replay at the  end of the level.
 138 By default, the most recent unsaved  level will be saved to the replay
 139 file named "Last".
 140
 141 Replay  files are  stored in  the user  data directory.   They  may be
 142 copied freely.  To  view a replay you have  downloaded, simply move it
 143 to  the user  data directory  and it  will appear  in the  Replay menu
 144 in-game.
 145
 146 Note that replay files are  not currently portable between machines of
 147 different byte order.
 148
 149
 150
 151 * CONFIGURATION
 152
 153 Game  settings are stored  in the  file neverballrc  in the  user data
 154 directory.  This file is created  when the game exits.  It consists of
 155 key /  value pairs.  Some of  these values are  configurable using the
 156 in-game  options  screen.  Other  meaningful  keys  and their  default
 157 values follow.
 158
 159     mouse_sense 300
 160
 161         This  key controls  mouse  sensitivity.  The  value gives  the
 162         number of screen pixels the  mouse pointer must move to rotate
 163         the floor  through its entire  range.  A smaller  number means
 164         more sensitive.
 165
 166     mouse_invert 0
 167
 168         This key inverts the vertical mouse axis if set to 1.
 169
 170     key_camera_1 f1
 171     key_camera_2 f2
 172     key_camera_3 f3
 173     key_camera_l left
 174     key_camera_r right
 175
 176         These keys  define keyboard mappings for  camera selection and
 177         rotation.  Key  names are specified using  SDL's canonical key
 178         naming convention.  The three camera behaviors are as follows:
 179
 180         1 - Strict  camera stays behind the ball by  cueing off of the
 181         velocity of the  ball.  It is very  responsive,  but sometimes
 182         confusing.
 183
 184         2 - Lazy  camera chases a point a set  distance from the ball.
 185         It is seldom  surprising, but at times it  is not sufficiently
 186         responsive.
 187
 188         3 - Locked camera  does not rotate  except by  player command.
 189
 190     view_fov 50
 191     view_dp  75
 192     view_dc  25
 193     view_dz  200
 194
 195         These keys  define the view of the ball.  They give  the field
 196         of view in degrees,  the height of the view point,  the height
 197         of the view center,  and the horizontal distance from the ball
 198         in centimeters, respectively.  (The ball is  50 centimeters in
 199         diameter in most levels.)
 200
 201         The default values  for these keys changed with version 1.2.6.
 202         Some players may be interested in using the  old values.  They
 203         were as follows:
 204
 205             view_fov 40
 206             view_dp  400
 207             view_dc  0
 208             view_dz  600
 209
 210     rotate_fast 200
 211     rotate_slow 100
 212
 213         These keys control the rate of camera rotation.  Roughly, they
 214         give  the rate  of lateral  camera motion  in  centimeters per
 215         seconds,  so the  actual rotation  rate depends  upon view_dz,
 216         above.  The fast rate is used when the Shift key is held down.
 217
 218     fps 0
 219
 220         This key enables an on-screen frames-per-second counter. Press
 221         F9 to toggle this flag in-game.
 222
 223     nice 1
 224
 225         This  key  enables  a  delay  function  after  each  frame  is
 226         rendered, forcing a context  switch and ensuring that the game
 227         does not utilize 100% of the CPU.  0 is off, 1 is on.
 228
 229         If the  frame rate is not  fast enough for you,  or you simply
 230         want to  test the  performance of the  game on  your hardware,
 231         disable it.
 232
 233         Press F8 to toggle this flag in-game.
 234
 235     coin png/coin.png
 236     ball png/ball.png
 237
 238         These keys determine the texture image applied to the coin and
 239         ball.  If  you prefer collecting euros  to collecting dollars,
 240         set:
 241
 242             coin png/euro_coin.png
 243
 244     stereo 0
 245
 246         This key  enables quad-buffered stereo viewing  for those with
 247         the hardware to support it.  It gives an angle in degrees that
 248         determines the  interocular distance.  0  is normal non-stereo
 249         viewing.  2 gives  a  good  stereo effect.   If  the eyes  are
 250         swapped, give a negative value, like -2.
 251
 252     joystick 0
 253
 254         This key  enables joystick control.  0  is off, 1  is on.  The
 255         game may still be controlled with the mouse even while gamepad
 256         control  is enabled.   However,  random noise  from an  analog
 257         controller at rest can disrupt normal mouse input.
 258
 259     joystick_device 0
 260
 261         This  number selects  which joystick  to use if  more than one
 262         joystick is  found. 0 is the first  joystick, 1 is the  second
 263         and so on.
 264
 265     joystick_axis_x 0
 266
 267         Joystick horizontal axis number
 268
 269     joystick_axis_y 1
 270
 271         Joystick vertical axis number
 272
 273     joystick_button_a 0
 274
 275         Joystick menu select button
 276
 277     joystick_button_b 1
 278
 279         Joystick menu cancel button
 280
 281     joystick_button_r 2
 282
 283         Joystick counter-clockwise camera rotation button
 284
 285     joystick_button_l 3
 286
 287         Joystick clockwise camera rotation button
 288
 289     joystick_button_exit 4
 290
 291         Joystick exit button
 292
 293
 294
 295 Contact: <robert.kooima@gmail.com>