no need to rebuild version.c every time
[chaz/yoink] / doc / yoink.6.in
1 .\"
2 .\" Copyright (c) 2009, Charles McGarvey
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions are
7 .\" met:
8 .\"
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
16 .\" IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
17 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
18 .\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
19 .\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
20 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
21 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
25 .\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 .\"
27 .\"
28 .TH YOINK 6 "July 24, 2009"
29 .SH NAME
30 Yoink \- An alien-smashing action game.
31 .SH SYNOPSIS
32 .B yoink [-h|--help] [-i|--info] [OPTION=VALUE]...
33 .SH DESCRIPTION
34 Leap tall buildings! Crush stupid robots beneath your feet! Wield your
35 extra-terrestrial powers in the defence of humanity, and send those alien
36 invaders back from whence they came!
37
38 You play the part of a flying alien heroine who must defend her home on
39 Earth from other airborne alien invaders. The game draws inspiration from
40 classic arcade games like Joust, Bombjack, Rampage, and Defender--simple,
41 fast-moving action. Basic arguments include:
42 .TP
43 .B -h, --help
44 Display basic usage information, and exit immediately.
45 .TP
46 .B -i, --info
47 Display build and environment details, and exit immediately.
48 .SH TIPS
49 To attack, you must dive on the enemy at high speed. If you're going too
50 slowly, you'll just drift harmlessly by. Diving from above gives different
51 results from swooping in and hitting them from the side. If you're too
52 close to attack, try to build up speed by running away and bouncing off a
53 nearby building!
54
55 By charging your special alien powers, you can throw fireballs. The orange
56 bar at the top of the screen represents your power level--at maximum, you
57 can destroy almost anything. Aiming can be tricky, but with a little
58 practice it's quite easy to launch them in the right direction. Try doing
59 a little swoop or circle in the air to line yourself up before releasing
60 your fireball.
61
62 The heroine has limited energy, measured by the blue bar at the top of the
63 screen. When it runs out, it's game over! She can regain lost energy by
64 picking up bonuses dropped by enemies.
65
66 To complete the current attack wave, you must destroy all the enemies.
67 Hunt around, especially in the sky, if you can't find the last few.
68 .SH OPTIONS
69 You have a certain level of control over the operation of \fByoink\fP
70 through options passed as program arguments or given in config files.
71 \fByoink\fP looks for config files in several locations and in this order:
72 .TP
73 1. \fI@DATADIR@/yoinkrc\fP
74 This is the base config file which should be considered read-only. Look to
75 this file as an example of the format used for config files.
76 .TP
77 2. \fI/etc/yoinkrc\fP
78 This is the system-wide config file.
79 .TP
80 3. \fI$HOME/.yoinkrc\fP
81 This is your own personal config file.
82 .TP
83 4. \fI$YOINKRC\fP
84 This is an optional environment variable you can set to the path of a
85 config file at a non-standard location. See the \fBENVIRONMENT\fP section
86 below for more information.
87 .PP
88 As usual, options that are passed as arguments take precedence over options
89 loaded from any config file. Here is a list of some of the options
90 available at your disposal:
91 .TP
92 .B detail
93 The level of detail. Possible values are 1, 2, or 3 where 1 means the
94 least amount of detail and 3 means the most. This effects the number of
95 objects drawn to the screen. A high level of detail will draw everything
96 but could cause poor frame rates if the graphics driver can't keep up with
97 the load. Lower levels will omit certain details which aren't crucial for
98 playing the game with the possible benefit of higher frame rates. See the
99 Notes for more ways to increase the game's performance. The default value
100 is 3.
101 .TP
102 .B doublebuffer
103 If true, double-buffering will be used to help minimize distortion and
104 artifacts caused by the animation of the game. Otherwise, a single buffer
105 will be used. The default value is true.
106 .TP
107 .B fullscreen
108 If true, the window will capture the display and render the game in full
109 screen splendor. A value of false means the game will run in a window.
110 The default value is false.
111 .TP
112 .B maxfps
113 The maximum number of frames to be drawn per second. If your computer is
114 really old, you can get away with decreasing this value and still have
115 reasonably smooth animation. You can set this to a very high number to
116 effectively render as many frames as is possible, but the actual rate could
117 be limited by vertical display synchronization, depending on the X11 driver
118 and settings used. You should not set this option higher than the point
119 where the vertical synchronization effectively limits the draw rate or else
120 the game may not be able to update the physics on schedule which could
121 actually significantly lower the quality of the animation. The default
122 value is 40.
123 .TP
124 .B printfps
125 If true, the current number of frames being drawn per second will be
126 printed to the console. The default value is false.
127 .TP
128 .B resizable
129 If true, the window will be resizable by the window manager. This option
130 is meaningless if the game is drawing to the full screen. The default
131 option is true.
132 .TP
133 .B timestep
134 The number of times per second the simulation state will be updated. A
135 value of 100 or higher is ideal for a better physical simulation. Values
136 that are much lower cause the CPU to do less work, but accuracy will
137 suffer. Errors could be introduced in the game with extremely low values.
138 The default value is 80.
139 .TP
140 .B videomode
141 The resolution or size of the window. The value is an array with three
142 number elements representing the width, height, and bits per pixel that
143 make up the video mode. The third number is optional. The default value
144 is {800,600}. If passing on the command-line, you may need to escape the
145 curly braces so the shell doesn't parse them.
146 .PP
147 This is only a list of the more useful options. You'll have to use the
148 source to find out about the more esoteric options, but you probably won't
149 need to.
150 .SH EXAMPLES
151 Here are some examples of typical usage:
152 .TP
153 $ yoink maxfps=60
154 Cap the allowable frame-rate to 60Hz.
155 .TP
156 $ yoink fullscreen=true
157 Run \fByoink\fP in full-screen mode.
158 .TP
159 $ yoink videomode=\\{1024,768\\}
160 Run \fByoink\fP with a resolution of 1024x768. Notice the escapes for the
161 curly braces so the shell doesn't parse them.
162 .SH ENVIRONMENT
163 \fByoink\fP responds to some variables in the environment:
164 .TP
165 .I HOME
166 If set to a path of a valid directory (presumably a user's home directory),
167 \fByoink\fP will look for a file at \fI$HOME/.yoinkrc\fP and load it as a
168 config file.
169 .TP
170 .I USER
171 \fByoink\fP uses this variable to guess the user's nickname, for a high
172 score entry or whatever.
173 .TP
174 .I YOINK_DATADIR
175 If set to a path of a valid directory, \fByoink\fP will look in this
176 directory first when it is loading game assets. Set this variable if you
177 move the game's assets to another directory or perhaps want to load your
178 own custom assets rather than the defaults.
179 .TP
180 .I YOINKRC
181 If set to a path of a valid config file, \fByoink\fP will load the options
182 from that file, and those options will take precedence over options loaded
183 from other config files.
184 .SH NOTES
185 \fByoink\fP may or may not be playable with acceptable frame rates without
186 a hardware accelerated GL driver installed and working, depending on how
187 fast your CPU is. \fByoink\fP is really not all that heavy on graphics,
188 but it doesn't take much to overload a software implementation. You should
189 first check the documentation provided by your OS provider to see how to
190 enable direct rendering. If you're really stuck without hardware
191 acceleration, there are some things you can do to get marginally better
192 frame rates:
193 .TP
194 1. Decrease the resolution.
195 Use the \fBvideomode\fP option or just resize the window if the
196 \fBfullscreen\fP option is false and the \fBresizable\fP option is true.
197 This can speed up a software renderer considerably.
198 .TP
199 2. Decrease the level of rendering detail.
200 Use the \fBdetail\fP option. The game world may look sparse or incomplete,
201 but that's probably better than choppy animation.
202 .TP
203 3. Decrease the timestep.
204 You can set the \fBtimestep\fP to be as low as the your \fBmaxfps\fP
205 option. Remember the trade-off here is decreased simulation accuracy.
206 .PP
207 If you are having audio problems, you may need to upgrade OpenAL. Some
208 systems still provide an old, busted version of OpenAL which may result in
209 stuttering, lag, and other oddities. See about installing a recent version
210 of openal-soft, a high-quality software implementation that is still being
211 maintained.
212 .SH BUGS
213 .IP \(bu 3
214 The robots are currently lacking in intelligence.
215 .IP \(bu
216 Although the pixelated graphics are intentional, there are some unintended
217 artifacts which are more obvious with certain video drivers.
218 .PP
219 Send bug reports, patches, and love notes to:
220 .IP
221 Charles McGarvey <@PACKAGE_BUGREPORT@>
222 .SH AUTHOR
223 .PP
224 Neil Carter was the original creator of Yoink, his winning entry in the
225 uDevGames 2003 Mac game development contest. Charles McGarvey restored the
226 game and is the current maintainer.
This page took 0.038425 seconds and 4 git commands to generate.