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