X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fyoink;a=blobdiff_plain;f=doc%2Fyoink.6.in;h=ece0fa5b474108bbbde5a81c5682d245c5018b31;hp=a7ad7768584e56aa5f1be613c2304024afe3e373;hb=bffc879fc8ee8167bb123310d39fad4e2f426ffd;hpb=7d15b919681bb9ec0088b4b27c6abf62d6dfb9b1 diff --git a/doc/yoink.6.in b/doc/yoink.6.in index a7ad776..ece0fa5 100644 --- a/doc/yoink.6.in +++ b/doc/yoink.6.in @@ -28,24 +28,26 @@ .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 -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 +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 -display this help and exit +Display basic usage information, and exit immediately. .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 @@ -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 -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: +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 -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 -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 -3. /etc/yoinkrc -This is a system-wide configuration file. +3. $HOME/.yoinkrc +This is your own personal configuration file. .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 -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 -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 -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 -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 -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 -.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 -.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 -.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 -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 -.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 -.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 -.B video.resizable +.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. +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 -.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 @@ -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 -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 -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 -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 -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 -Send bug reports and patches to: +Send bug reports, patches, and love notes to: .br -Charles McGarvey +Charles McGarvey <@PACKAGE_BUGREPORT@> .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.