X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fyoink;a=blobdiff_plain;f=doc%2Fyoink.6.in;h=809faab292e91b7a0d49d1c94753424fd46ce61e;hp=5425c3a91f23021168972ed7120e6e1b591fcfa3;hb=64bd443538f57ad1bdff6c6b35953e72141129b2;hpb=838bc00015eb7f583c7cf4b3b1007697bf047da1 diff --git a/doc/yoink.6.in b/doc/yoink.6.in index 5425c3a..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] [-v|--version] [OPTION=VALUE]... +.B yoink [-h|--help] [-i|--info] [OPTION=VALUE]... .br .SH DESCRIPTION .PP @@ -42,10 +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 -v, --version -output version information and exit +.B -i, --info +Display build and environment details, and exit immediately. .br .SH TIPS .PP @@ -72,138 +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 the 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 -.I $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 -.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.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 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 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. +.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 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 @@ -213,29 +193,27 @@ 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 @@ -243,46 +221,45 @@ 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 -No sound yet. The original game never had sound, but it would probably be a -good idea. -.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, 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.