renamed mippleton to library

[chaz/yoink] / doc / yoink.6.in

diff --git a/doc/yoink.6.in b/doc/yoink.6.in
index a7ad7768584e56aa5f1be613c2304024afe3e373..ece0fa5b474108bbbde5a81c5682d245c5018b31 100644 (file)
--- a/doc/yoink.6.in
+++ b/doc/yoink.6.in
@@ -28,24 +28,26 @@
 .SH NAME
 Yoink \- An alien-smashing action game.
 .SH SYNOPSIS
 .SH NAME
 Yoink \- An alien-smashing action game.
 .SH SYNOPSIS

-.B yoink [-h|--help] [-v|--version] [OPTION=VALUE]...
+.B yoink [-h|--help] [-i|--info] [OPTION=VALUE]...

 .br
 .SH DESCRIPTION
 .PP
 Leap tall buildings!  Crush stupid robots beneath your feet!  Wield your
 extra-terrestrial powers in the defence of humanity, and send those alien
 .br
 .SH DESCRIPTION
 .PP
 Leap tall buildings!  Crush stupid robots beneath your feet!  Wield your
 extra-terrestrial powers in the defence of humanity, and send those alien

-invaders back from whence they came!  Do all these things (apart from the last
-one at the moment) in Yoink!  You play the part of a flying alien heroine who
-must defend her home on Earth from other airborne alien invaders.  The game
-draws inspiration from classic arcade games like Joust, Bombjack, Rampage, and
-Defender--simple, fast-moving action.
+invaders back from whence they came!  This is Yoink.

 .PP
 .PP

+You play the part of a flying alien heroine who must defend her home on Earth
+from other airborne alien invaders.  The game draws inspiration from classic
+arcade games like Joust, Bombjack, Rampage, and Defender--simple, fast-moving
+action.  Basic arguments include:

 .TP
 .B -h, --help
 .TP
 .B -h, --help

-display this help and exit
+Display basic usage information, and exit immediately.

 .TP
 .TP

-.B -v, --version
-output version information and exit
+.B -i, --info
+Display build and environment details, and exit immediately.
+.br
+.SH TIPS

 .PP
 To attack, you must dive on the enemy at high speed.  If you're going too
 slowly, you'll just drift harmlessly by.  Diving from above gives different
 .PP
 To attack, you must dive on the enemy at high speed.  If you're going too
 slowly, you'll just drift harmlessly by.  Diving from above gives different


@@ -70,124 +72,118 @@ around, especially in the sky, if you can't find the last few.
 .PP
 There are a plethora of options available for tweaking various aspects of the
 game.  All options can be set either from a configuration file or by passing
 .PP
 There are a plethora of options available for tweaking various aspects of the
 game.  All options can be set either from a configuration file or by passing

-them as arguments.  Some of the more common options can be set from within the
-game.
+them as arguments.

 .PP
 A
 .B yoink
 .PP
 A
 .B yoink

-configuration file ("yoinkrc") consists of key-value pairs organized in a
-logical hierarchy.  The format of the file is human-readable, so you can get in
-there with your favorite text editor if you like to work under the hood.
+configuration file ("yoinkrc") consists of key-value pairs.  The format is not
+unlike that of other configuration files you are already familiar with.  The
+syntax used is lua.

 .B yoink
 .B yoink

-looks for configuration files and loads them in this order, with the options in
-prior configuration files taking precedence over the same options if they exist
-in multiple configuration files:
+looks for configuration files and loads them in this order, the options from
+each subsequent configuration files taking precedence over the same options if
+they exist in previous files.

 .TP
 .TP

-1. $YOINK_CONFIGFILE
-This is an optional environment variable.
+1. @DATADIR@/yoinkrc
+This is the base configuration file which should be considered read-only.  Look
+to this file as an example of the format used for configuration files.

 .TP
 .TP

-2. $HOME/.yoinkrc
-This is a specific user's configuration file.
+2. /etc/yoinkrc
+This is the system-wide configuration file.  Not available on Windows.

 .TP
 .TP

-3. /etc/yoinkrc
-This is a system-wide configuration file.
+3. $HOME/.yoinkrc
+This is your own personal configuration file.

 .TP
 .TP

-4. @datadir@/yoinkrc
-This is the base configuration file which should be considered read-only.  Look
-to this file as an example of the format used for configuration files.
+4. $YOINKRC
+This is an optional environment variable you can set to point to a configuration
+file.

 .PP
 Options that are passed as arguments take precedence over options loaded from
 .PP
 Options that are passed as arguments take precedence over options loaded from

-the configuration file(s).  This mechanism is good for running the game with a
-temporary setting which you do not intend to retain.  Keep in mind that if you
-edit and save options in-game, any options you have passed as arguments during
-the invocation of the game will be saved to the $HOME/.yoinkrc configuration
-file.  You may have to go into that file and remove any options you didn't
-intend to set.  When passing options as arguments, you must use the fully
-qualified name of the option if it exists in a subgroup.  For example:
+the configuration file(s).  This mechanism can be used to play the game with
+temporary settings which you do not intend to retain.  Here are some examples of
+passing options on the command-line:

 .PP
 .TP
 .PP
 .TP

-yoink video.fullscreen=true
-Set the option video.fullscreen to true.  This will run the game in full-screen
-mode.
+yoink fullscreen=true
+Run Yoink with the option
+.I fullscreen
+as true.  This will run the game in full-screen mode.

 .TP
 .TP

-yoink video.maxfps=60
-Set the option video.maxfps to 60.  This will cap the display rate at 60Hz.
+yoink maxfps=60
+Run Yoink with the option
+.I maxfps
+as 60.  This will cap the display rate at 60Hz.

 .PP
 .PP

-You can also set options with array values.  Arrays can be passed on the
-command line by surrounding all the parts with square brackets and separating
-each part by a comma.  For example:
+You can also set options with array values.  Arrays can be passed on the command
+line by surrounding all the parts with curly brackets and separating each part
+by a comma.  You may also have to quote the brackets so your shell doesn't parse
+them.  For example:

 .TP
 .TP

-yoink video.mode=[1024,768]
-Set the option video.mode to an array with numbers 1024 and 768.  The video size
-will be 1024x768.
+yoink videomode=\\{1024,768\\}
+Run Yoink with the top
+.I videomode
+as the numbers 1024 and 768.  The video size will be 1024x768.

 .PP
 Here is a list of some of the options available:
 .TP
 .PP
 Here is a list of some of the options available:
 .TP

-.B engine.timestep
-The amount of time in seconds between each update of the physics state.  A value
-of 0.01 or lower is ideal for accurate physics approximations.  Values that are
-much lower may introduce errors in the game.
+.B detail
+The level of detail.  Possible values are 1, 2, or 3 where 1 means the least
+amount of detail and 3 means the most.  This effects the number of objects drawn
+to the screen.  A high level of detail will draw everything but could cause poor
+frame rates if the graphics driver can't keep up with the load.  Lower levels
+will omit certain details which aren't crucial for playing the game with the
+possible benefit of higher frame rates.  See the Notes for more ways to increase
+the game's performance.  The default value is 3.

 .TP
 .TP

-.B input.grab
-Takes a boolean (true or false).  If true, the cursor pointer will be "stuck"
-within the area of the window, and many key combinations which would otherwise
-be handled by the window manager will instead be dropped.  This is a low-level
-option of limited usefulness.
+.B doublebuffer
+If true, double-buffering will be used to help minimize distortion and artifacts
+caused by the animation of the game.  Otherwise, a single buffer will be used.
+The default value is true.

 .TP
 .TP

-.B video.colorbuffers
-This takes an array of four number values which represent the number of bits to
-use for red, green, blue, and the alpha channel.  This is a low-level option of
-limited usefulness.  The default value is almost always preferable.
-.TP
-.B video.cursor
-This option effects the visibility of the cursor while it is "hovering" over the
-window.  If the value is true, the cursor will be visible.  Otherwise, the
-cursor will be hidden.
-.TP
-.B video.doublebuffer
-If true, double-buffering will be used to render animations with minimal
-distortions.  Otherwise, a single buffer will be used.  The recommended value is
-true.
-.TP
-.B video.fullscreen
+.B fullscreen

 If true, the window will capture the display and render the game in full screen
 If true, the window will capture the display and render the game in full screen

-splendor.  A value of false means the game will run in a window.
-.TP
-.B video.maxfps
-The maximum number of frames to be drawn per second.  A value of 50 is pretty
-good.  If your computer is pretty old, can get away with decreasing this value
-and still have reasonably smooth animation.  You can set this to a very high
-number to effectively render as many frames as is possible, but the actual rate
-could be limited by vertical display synchronization, depending on the X11
-driver and settings used.  You should not set this option higher than the point
-where the vertical synchronization effectively limits the draw rate or else the
-game may not be able to update the physics on schedule which could actually
-significantly lower the quality of the animation.
-.TP
-.B video.mode
-The resolution or size of the window.  The value is an array with three number
-elements representing the width, height, and bits per pixel that make up the
-video mode..  A typical value is [800,600,32] for a size of 800x600 pixels with
-millions of colors.
-.TP
-.B video.multisamplebuffers
-The number of multisample buffers used.
+splendor.  A value of false means the game will run in a window.  The default
+value is false.

 .TP
 .TP

-.B video.multisamplesamples
-The number of multisample samples used.
+.B maxfps
+The maximum number of frames to be drawn per second.  If your computer is really
+old, you can get away with decreasing this value and still have reasonably
+smooth animation.  You can set this to a very high number to effectively render
+as many frames as is possible, but the actual rate could be limited by vertical
+display synchronization, depending on the X11 driver and settings used.  You
+should not set this option higher than the point where the vertical
+synchronization effectively limits the draw rate or else the game may not be
+able to update the physics on schedule which could actually significantly lower
+the quality of the animation.  The default value is 40.

 .TP
 .TP

-.B video.printfps
-If true, the current number of frames being draw per second will be printed to
-the console.  This is usually off by default, but you can set this to true if
-you're interested in the draw rate you're actually getting.
+.B printfps
+If true, the current number of frames being drawn per second will be printed to
+the console.  The default value is false.

 .TP
 .TP

-.B video.resizable
+.B resizable

 If true, the window will be resizable by the window manager.  This option is
 If true, the window will be resizable by the window manager.  This option is

-meaningless if the game is drawing to the full screen.
+meaningless if the game is drawing to the full screen.  The default option is
+true.
+.TP
+.B showcursor
+This option effects the visibility of the cursor while it is "hovering" over the
+display.  If the value is true, the cursor will be visible.  Otherwise, the
+cursor will be hidden.  The default value is true.
+.TP
+.B timestep
+The number of times per second the simulation state will be updated.  A value
+of 100 or higher is ideal for a better physical simulation.  Values that are
+much lower cause the CPU to do less work, but accuracy will suffer.  Errors
+could be introduced in the game with extremely low values.  The default value
+is 80.

 .TP
 .TP

-.B video.swapcontrol
-If true, drawing will take place at a time which will minimize distortion caused
-by the vertical refreshing of displays.  The recommended value is true.
+.B videomode
+The resolution or size of the window.  The value is an array with three number
+elements representing the width, height, and bits per pixel that make up the
+video mode.  The third number is optional.  The default value is {800, 600}.
+.PP
+This is only a list of the more useful options.  You'll have to use the source
+to find out about the more esoteric options, but you probably won't need to.

 .br
 .SH ENVIRONMENT
 .PP
 .br
 .SH ENVIRONMENT
 .PP


@@ -197,40 +193,73 @@ responds to some variables in the environment:
 HOME
 If set to a path of a valid directory (presumably a user's home directory),
 .B yoink
 HOME
 If set to a path of a valid directory (presumably a user's home directory),
 .B yoink

-will load options from the configuration file at $HOME/.yoinkrc, if it exists.
-Saving options within the game will cause this file to be over-written with the
-new options.
+will look for a file at
+.I $HOME/.yoinkrc
+and load it as a configuration file.

 .TP
 USER
 .B yoink
 uses this variable to guess the user's nickname, for a high score entry or
 whatever.
 .TP
 .TP
 USER
 .B yoink
 uses this variable to guess the user's nickname, for a high score entry or
 whatever.
 .TP

-YOINK_CONFIGFILE
-If set to a path of a valid configuration file, 
-.B yoink
-will load the options from that file, and those options will take precedence
-over options loaded from other configuration files.  Any in-game saving will
-cause this file to be over-written by the new options rather than the file at
-$HOME/.yoinkrc.
-.TP

 YOINK_DATADIR
 If set to a path of a valid directory, 
 .B yoink
 will look in this directory first when it is loading game assets.  Set this
 YOINK_DATADIR
 If set to a path of a valid directory, 
 .B yoink
 will look in this directory first when it is loading game assets.  Set this

-variable if you move the game's assets to another directory or want to load your
-own assets.
+variable if you move the game's assets to another directory or perhaps want to
+load your own custom assets rather than the defaults.
+.TP
+YOINKRC
+If set to a path of a valid configuration file, 
+.B yoink
+will load the options from that file, and those options will take precedence
+over options loaded from other configuration files.
+.br
+.SH NOTES
+.PP
+Yoink may or may not be playable with acceptable frame rates without a hardware
+accelerated OpenGL driver installed and working, depending on how fast your CPU
+is.  Yoink is really not all that heavy on graphics, but it doesn't take much to
+overload a software implementation.  If you're stuck without hardware
+acceleration, there are some things you can do to get better frame rates, in
+order of effectiveness:
+.TP
+1. Decrease the resolution.
+Use the
+.I videomode
+option or just resize the window if the
+.I fullscreen
+option is false and the
+.I resizable
+option is true.  This speeds up software renderers considerably.
+.TP
+2. Decrease the timestep.
+Use the
+.I timestep
+option.  You can set the timestep to be as low as the your
+.I maxfps
+option, but it is not recommended to set this lower than the target frame rate.
+Remember the trade-off here is decreased simulation accuracy.  Try this to set
+your frame rate to 30Hz and your timestep to 60Hz:
+.PP
+yoink maxfps=30 timestep=maxfps\\*2
+.TP
+3. Decrease the level of rendering detail.
+Use the
+.I detail
+option.  The game world may look sparse or incomplete, but that may be better
+than choppy animation.

 .br
 .SH BUGS
 .PP
 .br
 .SH BUGS
 .PP

-The pixelated graphics are actually intentional.  It adds to the charm of the
-game, don't you think?
+Although the pixelated graphics are intentional, there are some unintended
+artifacts which are more obvious on certain OpenGL implementations.

 .PP
 .PP

-Send bug reports and patches to:
+Send bug reports, patches, and love notes to:

 .br
 .br

-Charles McGarvey <onefriedrice@brokenzipper.com>
+Charles McGarvey <@PACKAGE_BUGREPORT@>

 .SH AUTHOR
 .PP
 Neil Carter was the original creator of Yoink, his winning entry in the
 .SH AUTHOR
 .PP
 Neil Carter was the original creator of Yoink, his winning entry in the

-uDevGames 2003 Mac game development contest.  Charles McGarvey rewrote the game
-with SDL and is the current maintainer.
+uDevGames 2003 Mac game development contest.  Charles McGarvey restored the game
+and is the current maintainer.