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

diff --git a/doc/yoink.6.in b/doc/yoink.6.in
index d9e90bf..809faab 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
@@ -69,144 +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
-them as arguments.  Some of the more common options can be set from within the
-game.
+them as arguments.
 .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
-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.
+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
-2. $HOME/.yoinkrc
-This is a specific user's personal configuration file.
+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
-3. /etc/yoinkrc
+2. /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.
+3. $HOME/.yoinkrc
+This is your own personal configuration file.
+.TP
+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
-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:
+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
-yoink video.fullscreen=true
-Set the option
-.I 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
-yoink video.maxfps=60
-Set the option
-.I 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
 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:
+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
-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.
+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
-.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.
+.B detail
+The level of detail.  Possible values are 1, 2, or 3, 1 meaning the least amount
+of detail and 3 meaning 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
+benefit of higher frame rates.  See the Notes for more ways to increase the
+game's performance.  The default value is 3.
 .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.
+.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 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.
+.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 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.
+.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 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.
+.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 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
+.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.
-.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.
-.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.
-.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.
+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
@@ -218,10 +195,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 configuration file.
 .TP
 USER
 .B yoink
@@ -239,10 +213,7 @@ 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.  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 configuration files.
 .br
 .SH NOTES
 .PP
@@ -250,32 +221,34 @@ 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:
+acceleration, there are some things you can do to get better frame rates, in
+order of effectiveness:
 .TP
-yoink video.mode=[320,240] video.fullscreen=true
-.PP
-2. Decrease the level of detail with the
-.I game.detail
-option.
+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
-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.
+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