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 100 coins  to save your progress and earn  an extra ball.  Red
   9 coins are worth 5.  Blue coins are worth 10.
  10
  11
  12 Neverball requires:
  13
  14     SDL               http://www.libsdl.org/download-1.2.php
  15     SDL_image         http://www.libsdl.org/projects/SDL_image/
  16     SDL_mixer         http://www.libsdl.org/projects/SDL_mixer/
  17     SDL_ttf           http://www.libsdl.org/projects/SDL_ttf/
  18
  19
  20
  21 * THANKS TO
  22
  23     Mehdi Yousfi Monod  (Feature ideas and levels)
  24     Derek Arndt         (OSX packaging)
  25     Phil Harper         (TheOpenCD packaging, icons)
  26     Max Gilead          (Debian packaging)
  27     Michael Sterret     (Gentoo ebuild)
  28     Christoph Frick     (OSX port)
  29     Jeremy Messenger    (FreeBSD port)
  30     Erik Auerswald      (Mouse invert)
  31     Corey Edwards       (Joystick select)
  32
  33     Countless others for play testing and bug reports.
  34
  35     http://www.happypenguin.org
  36     http://www.flipcode.com
  37
  38
  39
  40 * BUILDING
  41
  42     make                     (Unix)
  43 or
  44     nmake /fMakefile-W32     (Windows with MSVC)
  45
  46 The executables  will be copied to  the base directory.   Maps will be
  47 processed and copied into data/sol/.  By default, an uninstalled build
  48 may be executed in place.
  49
  50
  51
  52 * RUNNING
  53
  54     ./neverball
  55
  56 Click Play  to begin.   Mouse motion tilts  the floor.   Mouse buttons
  57 rotate the  viewpoint.  The  following keyboard controls  are defined.
  58 See below for details.
  59
  60     SPACE  Pause and resume / Release mouse grab
  61     ESC    End a game / Exit
  62
  63     F1     Default Camera                            (configurable)
  64     F2     Lazy Camera                               (configurable)
  65     F3     Static Camera                             (configurable)
  66
  67     F7     Toggle wire mode
  68     F8     Toggle nice mode
  69     F9     Toggle frame counter
  70     F10    Snap a screenshot
  71     F11    Save the current demo
  72     F12    Toggle look-around mode
  73
  74
  75 * HIGH SCORES
  76
  77 The top three fastest times through each level, and the top three coin
  78 scores for each level are stored in files named .neverballhs-*.
  79
  80 The top  three fastest  times and  most coins scores  for each  set of
  81 levels are also stored.  To achieve  a set score, the player must play
  82 through all 25 levels of a set in one attempt.
  83
  84 The total set time will  include time spent during both successful and
  85 unsuccesful level  plays, thus  time-outs and fall-outs  count against
  86 the total time.
  87
  88 The  total  set  coin  count  will include  only  coins  collected  on
  89 successful  level plays.   This  prevents unbounded  coin scores  from
  90 being collected on levels with more than 100 coins.
  91
  92
  93
  94 * DEMO REPLAY
  95
  96 Neverball  includes a  simple  mechanism for  recording and  replaying
  97 games.  Each level played is  recorded to the file .neverballrp.  This
  98 file may  be found in your home  directory under Unix, or  in the game
  99 data directory under Windows.
 100
 101 The "Demo"  item of  the main  title menu plays  back the  most recent
 102 recording.  Press F11 to copy  the current recording to a sequentially
 103 numbered file.  This  allows you to save a  replay without immediately
 104 overwriting it by playing the next level.  If a recording is preserved
 105 while it is being created, it will be truncated.
 106
 107 Currently, the only way to  select a numbered recording for demoing is
 108 to copy it on top of the existing .neverballrp file.
 109
 110 Note that replay files are  not currently portable between machines of
 111 different byte order.
 112
 113
 114
 115 * INSTALLATION
 116
 117 The game executable may be moved as desired.
 118
 119 However, game  assets are described  using relative path  names.  Thus
 120 the game must  run within the data directory in  order for asset names
 121 to resolve correctly.  Upon starting,  the game will attempt to change
 122 into this directory, as defined in config.h.
 123
 124 If the data directory is to  be renamed or moved for installation, the
 125 CONFIG_PATH variable in config.h must be changed to match.
 126
 127 Alternatively, the CONFIG_PATH variable may  be set to "." if the game
 128 is started  from within the data directory.   Even MORE alternatively,
 129 the data path may be specified as the first command line option.
 130
 131
 132
 133 * CONFIGURATION
 134
 135 Global settings  are stored  in the file  .neverballrc.  This  file is
 136 created  when  the  game exits,  and  should  be  found in  your  home
 137 directory under Unix, or in the game data directory under Windows.  It
 138 consists of key / value  pairs.  Some of these values are configurable
 139 using  the in-game options  screen.  Other  meaningful keys  and their
 140 default values follow.
 141
 142     mouse_sense 300
 143
 144         This  key controls  mouse  sensitivity.  The  value gives  the
 145         number of screen pixels the  mouse pointer must move to rotate
 146         the floor  through its entire  range.  A smaller  number means
 147         more sensitive.
 148
 149     mouse_invert 0
 150
 151         This key inverts the vertical mouse axis if set to 1.
 152
 153     key_camera_1 f1
 154     key_camera_2 f2
 155     key_camera_3 f3
 156     key_camera_l left
 157     key_camera_r right
 158
 159         These keys  define keyboard mappings for  camera selection and
 160         rotation.  Key  names are specified using  SDL's canonical key
 161         naming convention.  The three camera behaviors are as follows:
 162
 163         1 - Strict  camera stays behind the ball by  cueing off of the
 164         velocity of the  ball.  It is very  responsive,  but sometimes
 165         confusing.
 166
 167         2 - Lazy  camera chases a point a set  distance from the ball.
 168         It is seldom  surprising, but at times it  is not sufficiently
 169         responsive.
 170
 171         3 - Locked camera  does not rotate  except by  player command.
 172
 173     view_fov 50
 174     view_dp  75
 175     view_dc  25
 176     view_dz  200
 177
 178         These keys  define the view of the ball.  They give  the field
 179         of view in degrees,  the height of the view point,  the height
 180         of the view center,  and the horizontal distance from the ball
 181         in centimeters, respectively.  (The ball is  50 centimeters in
 182         diameter in most levels.)
 183
 184         The default values  for these keys changed with version 1.2.6.
 185         Some players may be interested in using the  old values.  They
 186         were as follows:
 187
 188             view_fov 40
 189             view_dp  400
 190             view_dc  0
 191             view_dz  600
 192
 193     fps 0
 194
 195         This key enables an on-screen frames-per-second counter. Press
 196         F9 to toggle this flag in-game.
 197
 198     nice 1
 199
 200         This  key  enables  a  delay  function  after  each  frame  is
 201         rendered, forcing a context  switch and ensuring that the game
 202         does not utilize 100% of the CPU.  0 is off, 1 is on.
 203
 204         If the  frame rate is not  fast enough for you,  or you simply
 205         want to  test the  performance of the  game on  your hardware,
 206         disable it.
 207
 208         Press F8 to toggle this flag in-game.
 209
 210     shadow 1
 211
 212         This key determines the technique used when rendering the ball
 213         shadow.  Many video boards  have bad support for multitexture,
 214         or  broken texture clamping.   If the  shadow does  not render
 215         properly, one of these may help.
 216
 217         0 - Disable the shadow entirely.
 218
 219         1 - Clamp to edge.   If the shadow displays correctly, but the
 220         floor surround the shadow does not, try this.
 221
 222         2 - Clamp.  If the shadow repeats across the entire floor, try
 223         this.
 224
 225     stereo 0
 226
 227         This key  enables quad-buffered stereo viewing  for those with
 228         the hardware to support it.  It gives an angle in degrees that
 229         determines the  interocular distance.  0  is normal non-stereo
 230         viewing.  2 gives  a  good  stereo effect.   If  the eyes  are
 231         swapped, give a negative value, like -2.
 232
 233     joystick 0
 234
 235         This key  enables joystick control.  0  is off, 1  is on.  The
 236         game may still be controlled with the mouse even while gamepad
 237         control  is enabled.   However,  random noise  from an  analog
 238         controller at rest can disrupt normal mouse input.
 239
 240     joystick_device 0
 241
 242         This  number selects  which joystick  to use if  more than one
 243         joystick is  found. 0 is the first  joystick, 1 is the  second
 244         and so on.
 245
 246     joystick_axis_x 0
 247
 248         Joystick horizontal axis number
 249
 250     joystick_axis_y 1
 251
 252         Joystick vertical axis number
 253
 254     joystick_button_a 0
 255
 256         Joystick menu select button
 257
 258     joystick_button_b 1
 259
 260         Joystick menu cancel button
 261
 262     joystick_button_r 2
 263
 264         Joystick counter-clockwise camera rotation button
 265
 266     joystick_button_l 3
 267
 268         Joystick clockwise camera rotation button
 269
 270     joystick_button_exit 4
 271
 272         Joystick exit button
 273
 274
 275
 276 * KNOWN ISSUES
 277
 278 At the  time of this writing,  there are known issues  with certain 3D
 279 accelerater  boards  that  may  impact  or even  preclude  the  game's
 280 function.  While it is good that the 3D hardware market is very broad,
 281 it is an  unfortunate fact that OpenGL support  varies in quality from
 282 one configuration  to another.   It is impossible  for a  developer to
 283 work around bugs in all  boards, so some configurations must simply be
 284 declared unsupported.
 285
 286 - The  Intel i8xx  series is  not supported  under Linux.   Its broken
 287 multi-texturing  and  texture   clamping  make  Neverball  unplayable.
 288 Windows support is fine.
 289
 290 - Several older Radeons including, but not limited to, the Mobility M5
 291 and some  models of the  All-In-Wonder series are not  supported under
 292 Windows.  Note that the Mobility M6 and all tested PCI Radeons down to
 293 the 7500 are known to be very good.
 294
 295
 296 <rlk@snth.net>