X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fyoink;a=blobdiff_plain;f=doc%2Fyoink.6.in;h=ec41deebeb4913b918a558727cdd2e27220f4910;hp=d9e90bfdd20133ca43bdbe20c311a4c46752dd6d;hb=d11d8c63ab52c7f6eca2815e47cd6401e72f2c8c;hpb=9351bfa7871c88a5ad6e63f1d9c4483f50e4fed1

diff --git a/doc/yoink.6.in b/doc/yoink.6.in
index d9e90bf..ec41dee 100644
--- a/doc/yoink.6.in
+++ b/doc/yoink.6.in
@@ -28,7 +28,7 @@
 .SH NAME
 Yoink \- An alien-smashing action game.
 .SH SYNOPSIS
-.B yoink [-h|--help] [OPTION=VALUE]...
+.B yoink [-h|--help] [-i|--info] [OPTION=VALUE]...
 .br
 .SH DESCRIPTION
 .PP
@@ -42,7 +42,10 @@ arcade games like Joust, Bombjack, Rampage, and Defender--simple, fast-moving
 action.  Basic arguments include:
 .TP
 .B -h, --help
-display this help and exit
+Display basic usage information, and exit immediately.
+.TP
+.B -i, --info
+Display build and environment details, and exit immediately.
 .br
 .SH TIPS
 .PP
@@ -67,147 +70,103 @@ around, especially in the sky, if you can't find the last few.
 .br
 .SH OPTIONS
 .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.
-.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.
+Options are set from config files and command-line arguments.  A
 .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:
-.TP
-1. $YOINKRC
-This is an optional environment variable you can set to point to a configuration
-file.
-.TP
-2. $HOME/.yoinkrc
-This is a specific user's personal configuration file.
-.TP
-3. /etc/yoinkrc
-This is the system-wide configuration file.  Not available on Windows.
-.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.
-.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
-.I $HOME/.yoinkrc
-configuration file.  If this is not what you intended, 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:
-.PP
-.TP
-yoink video.fullscreen=true
-Set the option
-.I video.fullscreen
-to true.  This will run the game in full-screen mode.
-.TP
-yoink video.maxfps=60
-Set the option
-.I video.maxfps
-to 60.  This will cap the display rate at 60Hz.
-.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:
-.TP
-yoink video.mode=[1024,768]
-Set the option
-.I video.mode
-to an array with numbers 1024 and 768.  The video size will be 1024x768.
-.PP
-Here is a list of some of the options available:
-.TP
-.B engine.rngseed
-The number value used as a seed for the random number generator.  Set this to
-make the game more predictable.  This is typically only useful for debugging.
-.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 higher cause the CPU to do less work, but accuracy will suffer.  Errors
-could be introduced in the game with extremely high values.
-.TP
-.B game.detail
-The level of detail.  Possible values are high, medium, and low.  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 benefit of higher frame rates.  See the Notes for more
-ways to get good performance.
-.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.
-.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.showcursor
-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
+configfile ("yoinkrc") consists of key-value pairs.  They are loaded in this
+order:
+.TP
+1. @DATADIR@/yoinkrc
+This is the base config file which should be considered read-only.  Look to this
+file as an example of the format used for config files.
+.TP
+2. /etc/yoinkrc
+This is the system-wide config file.  Not available on Windows.
+.TP
+3. $HOME/.yoinkrc
+This is your own personal config file.
+.TP
+4. $YOINKRC
+This is an optional environment variable you can set to the path of a config
+file at a non-standard location.
+.PP
+As usual, options that are passed as arguments take precedence over options
+loaded from the config file(s).  Here is a list of some of the options available
+at your disposal:
+.TP
+.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
+.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
+.B fullscreen
+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.  The default
+value is false.
+.TP
+.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
+.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
+.B resizable
+If true, the window will be resizable by the window manager.  This option is
+meaningless if the game is drawing to the full screen.  The default option is
 true.
 .TP
-.B video.fullscreen
-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.
+.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 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.
+.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
-.B video.mode
+.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.  A typical value is [800,600] for a size of 800x600 pixels with
-millions of colors (the third number is optional).
-.TP
-.B video.multisamplebuffers
-The number of multisample buffers used.
-.TP
-.B video.multisamplesamples
-The number of multisample samples used.
+video mode.  The third number is optional.  The default value is {800,600}.  You
+may need to escape the curly braces so the shell doesn't parse them.
+.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 EXAMPLES
+.PP
+Here are some examples of typical usage:
+.PP
 .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.
+yoink fullscreen=true
+Run Yoink in full-screen mode.
 .TP
-.B video.resizable
-If true, the window will be resizable by the window manager.  This option is
-meaningless if the game is drawing to the full screen.
+yoink maxfps=60
+Cap the allowable frame-rate to 60Hz.
 .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.
-.br
+yoink videomode=\\{1024,768\\}
+Run yoink with a resultion of 1024x768.  Notice the escapes for the curly
+braces so the shell doesn't parse them.
 .SH ENVIRONMENT
 .PP
 .B yoink
@@ -218,10 +177,7 @@ If set to a path of a valid directory (presumably a user's home directory),
 .B yoink
 will look for a file at
 .I $HOME/.yoinkrc
-and load it as a configuration file.  Saving options within the game will cause
-this file to be over-written with the new options, unless the
-.I YOINKRC
-variable is set.
+and load it as a config file.
 .TP
 USER
 .B yoink
@@ -236,13 +192,10 @@ 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, 
+If set to a path of a valid config 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
-.I $HOME/.yoinkrc
-config file.
+over options loaded from other config files.
 .br
 .SH NOTES
 .PP
@@ -250,37 +203,41 @@ 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:
-.PP
-1. Decrease the resolution with the
-.I video.mode
-option.  Due to the nature of the graphics in the game, you can go as low as
-320x240 and not notice a large reduction in image quality.  You can take
-advantage of this by decreasing the resolution and running full-screen (so the
-window is not so itty bitty on your monitor).  This will help out a lot.  Try
-this:
-.TP
-yoink video.mode=[320,240] video.fullscreen=true
-.PP
-2. Decrease the level of detail with the
-.I game.detail
-option.
-.PP
-On the other hand, if you already get high frame rates, you may also want to cap
-the rate so that your computer doesn't do more work than it really needs to.
-This may be useful when you run
-.B yoink
-on your production server at work.  You can get reasonably smooth animation at
-around 30fps, but you can probably tell a difference between that and a higher
-rate like 50fps.  The latter will look noticeably smoother and nice, while the
-former is just "acceptable."  See the
-.I video.maxfps
-option.
+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 to set your
+maxfps to 30Hz and your timestep to 60Hz:
+.PP
+yoink maxfps=30 timestep=60
+.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
 Although the pixelated graphics are intentional, there are some unintended
-artifacts which are more obvious on certain OpenGL implementations.
+artifacts which are more obvious with certain video drivers.
+.PP
+The robots are not very bright.
 .PP
 Send bug reports, patches, and love notes to:
 .br