.\"
-.\" Copyright (c) 2009, Charles McGarvey
+.\" Copyright (c) 2009-2011, Charles McGarvey
.\" All rights reserved.
.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions are met:
-.\"
-.\" * Redistributions of source code must retain the above copyright notice,
-.\" this list of conditions and the following disclaimer.
-.\" * Redistributions in binary form must reproduce the above copyright
-.\" notice, this list of conditions and the following disclaimer in the
-.\" documentation and/or other materials provided with the distribution.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
-.\" IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
-.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
-.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
-.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
-.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
-.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
-.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
-.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\" Distributable under the terms and conditions of the 2-clause BSD
+.\" license; see the file COPYING for a complete text of the license.
.\"
-.hy
-.TH YOINK 6 "July 24, 2009"
-.SH NAME
-Yoink \- An alien-smashing action game.
-.SH SYNOPSIS
-.B yoink [-h|--help] [-i|--info] [OPTION=VALUE]...
-.br
-.SH DESCRIPTION
-.PP
+.Dd July 24, 2009
+.Dt YOINK 6
+.Os
+.Sh NAME
+.Nm yoink
+.Nd an alien-smashing action game
+.Sh SYNOPSIS
+.Nm yoink
+.Op Fl hi
+.Op Ar OPTION=VALUE ...
+.Sh DESCRIPTION
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! 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
+extra-terrestrial powers in the defense of humanity, and send those alien
+invaders back from whence they came!
+.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 options include:
+.Bl -tag -width flag
+.It Fl h, -help
Display basic usage information, and exit immediately.
-.TP
-.B -i, --info
+.It Fl i, -info
Display build and environment details, and exit immediately.
-.br
-.SH TIPS
-.PP
+.El
+.Pp
+For a list of the other options available, see
+.Xr yoinkrc 5 Ns .
+.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
-results from swooping in and hitting them from the side. If you're too close to
-attack, try to build up speed by running away and bouncing off a nearby
-building!
-.PP
-By charging your special alien powers, you can throw fireballs. The orange bar
-at the top of the screen represents your power level--at maximum, you can
-destroy almost anything. Aiming can be tricky, but with a little practice it's
-quite easy to launch them in the right direction. Try doing a little swoop or
-circle in the air to line yourself up before releasing your fireball.
-.PP
+results from swooping in and hitting them from the side. If you're too
+close to attack, try to build up speed by running away and bouncing off a
+nearby building!
+.Pp
+By charging your special alien powers, you can throw fireballs. The orange
+bar at the top of the screen represents your power level--at maximum, you
+can destroy almost anything. Aiming can be tricky, but with a little
+practice it's quite easy to launch them in the right direction. Try doing
+a little swoop or circle in the air to line yourself up before releasing
+your fireball.
+.Pp
The heroine has limited energy, measured by the blue bar at the top of the
screen. When it runs out, it's game over! She can regain lost energy by
picking up bonuses dropped by enemies.
-.PP
-To complete the current attack wave, you must destroy all the enemies. Hunt
-around, especially in the sky, if you can't find the last few.
-.br
-.SH OPTIONS
-.PP
-Options are set from config files and command-line arguments. A
-.B yoink
-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 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 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}. 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
-yoink fullscreen=true
-Run Yoink in full-screen mode.
-.TP
-yoink maxfps=60
-Cap the allowable frame-rate to 60Hz.
-.TP
-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
-responds to some variables in the environment:
-.TP
-HOME
-If set to a path of a valid directory (presumably a user's home directory),
-.B yoink
+.Pp
+To complete the current attack wave, you must destroy all the enemies.
+Hunt around, especially in the sky, if you can't find the last few.
+.Sh FILES
+.Bl -tag -width Fl
+.It Pa @pkgdatadir@/yoinkrc
+The configuration file with the default options. This file is to be
+considered read-only and should be looked to as an example of the file
+format (see
+.Xr yoinkrc 5 Ns ).
+.It Pa /etc/yoinkrc
+The system-wide configuration file.
+.It Pa ~/.yoinkrc
+The user's specialized configuration file.
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width Fl
+.It Ev HOME
+If set to the path of a valid directory (presumably your home directory),
+.Nm
will look for a file at
-.I $HOME/.yoinkrc
+.Pa $HOME/.yoinkrc
and load it as a config file.
-.TP
-USER
-.B yoink
-uses this variable to guess the user's nickname, for a high score entry or
-whatever.
-.TP
-YOINK_DATADIR
-If set to a path of a valid directory,
-.B yoink
+.It Ev USER
+.Nm
+uses this variable as the user's name, for a high score entry or whatever.
+.It Ev YOINK_DATADIR
+If set to a path of a valid directory,
+.Nm
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 perhaps want to
-load your own custom assets rather than the defaults.
-.TP
-YOINKRC
-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 config 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 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 with certain video drivers.
-.PP
-The robots are not very bright.
-.PP
-Send bug reports, patches, and love notes to:
-.br
-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 restored the game
-and is the current maintainer.
+variable if you move the game's assets to another directory or perhaps want
+to load your own custom assets rather than the defaults.
+.It Ev YOINKRC
+If set to a path of a valid config file,
+.Nm
+will load the options from that file, and those options will take
+precedence over options loaded from other config files.
+.El
+.Sh SEE ALSO
+.Xr yoinkrc 5
+.Sh HISTORY
+.Nm Yoink
+was originally created for Mac OS X by Neil Carter. It was a winning entry
+in the uDevGames 2003 Mac game development contest.
+.Sh AUTHOR
+.Bl -tag -width 2i -compact
+.It An Charles McGarvey
+.Mt @email@
+.El
+.Sh CAVEATS
+.Nm
+requires direct rendering. A software implementation of GL will probably
+run to slowly to provide a decent framerate. If you're stuck without
+hardware acceleration, some options may be able to boost framerates
+somewhat. See
+.Ar videomode Ns ,
+.Ar detail Ns ,
+.Ar framerate
+and
+.Ar timestep
+in
+.Xr yoinkrc 5
+for more information.
+.Pp
+If you are having audio problems, you may need to upgrade OpenAL. Some
+systems still provide an old, busted version of OpenAL which may result in
+stuttering, lag, and other oddities. See about installing a recent version
+of openal-soft, a high-quality software implementation that is still being
+maintained.
+.Sh BUGS
+Submit bug reports and/or patches to:
+.Lk http://www.dogcows.com/yoink/newticket "Yoink Bug Tracker"
projects / chaz / yoink / blobdiff