99c48fad90b93224c8df4139aae0fe8a15f6ae6f
[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 met:
7 .\"
8 .\" * Redistributions of source code must retain the above copyright notice,
9 .\" this list of conditions and the following disclaimer.
10 .\" * Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\"
14 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
15 .\" IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
16 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
17 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
18 .\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
19 .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
20 .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
21 .\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
22 .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
23 .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
24 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25 .\"
26 .hy
27 .TH YOINK 6 "July 24, 2009"
28 .SH NAME
29 Yoink \- An alien-smashing action game.
30 .SH SYNOPSIS
31 .B yoink [-h|--help] [OPTION=VALUE]...
32 .br
33 .SH DESCRIPTION
34 .PP
35 Leap tall buildings! Crush stupid robots beneath your feet! Wield your
36 extra-terrestrial powers in the defence of humanity, and send those alien
37 invaders back from whence they came! This is Yoink.
38 .PP
39 You play the part of a flying alien heroine who must defend her home on Earth
40 from other airborne alien invaders. The game draws inspiration from classic
41 arcade games like Joust, Bombjack, Rampage, and Defender--simple, fast-moving
42 action. Basic arguments include:
43 .TP
44 .B -h, --help
45 display this help and exit
46 .br
47 .SH TIPS
48 .PP
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 close to
52 attack, try to build up speed by running away and bouncing off a nearby
53 building!
54 .PP
55 By charging your special alien powers, you can throw fireballs. The orange bar
56 at the top of the screen represents your power level--at maximum, you can
57 destroy almost anything. Aiming can be tricky, but with a little practice it's
58 quite easy to launch them in the right direction. Try doing a little swoop or
59 circle in the air to line yourself up before releasing your fireball.
60 .PP
61 The heroine has limited energy, measured by the blue bar at the top of the
62 screen. When it runs out, it's game over! She can regain lost energy by
63 picking up bonuses dropped by enemies.
64 .PP
65 To complete the current attack wave, you must destroy all the enemies. Hunt
66 around, especially in the sky, if you can't find the last few.
67 .br
68 .SH OPTIONS
69 .PP
70 There are a plethora of options available for tweaking various aspects of the
71 game. All options can be set either from a configuration file or by passing
72 them as arguments. Some of the more common options can be set from within the
73 game.
74 .PP
75 A
76 .B yoink
77 configuration file ("yoinkrc") consists of key-value pairs organized in a
78 logical hierarchy. The format of the file is human-readable, so you can get in
79 there with your favorite text editor if you like to work under the hood.
80 .B yoink
81 looks for configuration files and loads them in this order, with the options in
82 prior configuration files taking precedence over the same options if they exist
83 in multiple configuration files:
84 .TP
85 1. $YOINKRC
86 This is an optional environment variable you can set to point to a configuration
87 file.
88 .TP
89 2. $HOME/.yoinkrc
90 This is a specific user's personal configuration file.
91 .TP
92 3. /etc/yoinkrc
93 This is the system-wide configuration file. Not available on Windows.
94 .TP
95 4. @DATADIR@/yoinkrc
96 This is the base configuration file which should be considered read-only. Look
97 to this file as an example of the format used for configuration files.
98 .PP
99 Options that are passed as arguments take precedence over options loaded from
100 the configuration file(s). This mechanism is good for running the game with a
101 temporary setting which you do not intend to retain. Keep in mind that if you
102 edit and save options in-game, any options you have passed as arguments during
103 the invocation of the game will be saved to the
104 .I $HOME/.yoinkrc
105 configuration file. If this is not what you intended, you may have to go into
106 that file and remove any options you didn't intend to set. When passing options
107 as arguments, you must use the fully qualified name of the option if it exists
108 in a subgroup. For example:
109 .PP
110 .TP
111 yoink video.fullscreen=true
112 Set the option
113 .I video.fullscreen
114 to true. This will run the game in full-screen mode.
115 .TP
116 yoink video.maxfps=60
117 Set the option
118 .I video.maxfps
119 to 60. This will cap the display rate at 60Hz.
120 .PP
121 You can also set options with array values. Arrays can be passed on the command
122 line by surrounding all the parts with square brackets and separating each part
123 by a comma. For example:
124 .TP
125 yoink video.mode=[1024,768]
126 Set the option
127 .I video.mode
128 to an array with numbers 1024 and 768. The video size will be 1024x768.
129 .PP
130 Here is a list of some of the options available:
131 .TP
132 .B engine.rngseed
133 The number value used as a seed for the random number generator. Set this to
134 make the game more predictable. This is typically only useful for debugging.
135 .TP
136 .B engine.timestep
137 The amount of time in seconds between each update of the physics state. A value
138 of 0.01 or lower is ideal for accurate physics approximations. Values that are
139 much higher cause the CPU to do less work, but accuracy will suffer. Errors
140 could be introduced in the game with extremely high values.
141 .TP
142 .B game.detail
143 The level of detail. Possible values are high, medium, and low. This effects
144 the number of objects drawn to the screen. A high level of detail will draw
145 everything but could cause poor frame rates if the graphics driver can't keep up
146 with the load. Lower levels will omit certain details which aren't crucial for
147 playing the game with the benefit of higher frame rates. See the Notes for more
148 ways to get good performance.
149 .TP
150 .B input.grab
151 Takes a boolean (true or false). If true, the cursor pointer will be "stuck"
152 within the area of the window, and many key combinations which would otherwise
153 be handled by the window manager will instead be dropped. This is a low-level
154 option of limited usefulness.
155 .TP
156 .B video.colorbuffers
157 This takes an array of four number values which represent the number of bits to
158 use for red, green, blue, and the alpha channel. This is a low-level option of
159 limited usefulness. The default value is almost always preferable.
160 .TP
161 .B video.showcursor
162 This option effects the visibility of the cursor while it is "hovering" over the
163 window. If the value is true, the cursor will be visible. Otherwise, the
164 cursor will be hidden.
165 .TP
166 .B video.doublebuffer
167 If true, double-buffering will be used to render animations with minimal
168 distortions. Otherwise, a single buffer will be used. The recommended value is
169 true.
170 .TP
171 .B video.fullscreen
172 If true, the window will capture the display and render the game in full screen
173 splendor. A value of false means the game will run in a window.
174 .TP
175 .B video.maxfps
176 The maximum number of frames to be drawn per second. A value of 50 is pretty
177 good. If your computer is pretty old, can get away with decreasing this value
178 and still have reasonably smooth animation. You can set this to a very high
179 number to effectively render as many frames as is possible, but the actual rate
180 could be limited by vertical display synchronization, depending on the X11
181 driver and settings used. You should not set this option higher than the point
182 where the vertical synchronization effectively limits the draw rate or else the
183 game may not be able to update the physics on schedule which could actually
184 significantly lower the quality of the animation.
185 .TP
186 .B video.mode
187 The resolution or size of the window. The value is an array with three number
188 elements representing the width, height, and bits per pixel that make up the
189 video mode. A typical value is [800,600] for a size of 800x600 pixels with
190 millions of colors (the third number is optional).
191 .TP
192 .B video.multisamplebuffers
193 The number of multisample buffers used.
194 .TP
195 .B video.multisamplesamples
196 The number of multisample samples used.
197 .TP
198 .B video.printfps
199 If true, the current number of frames being draw per second will be printed to
200 the console. This is usually off by default, but you can set this to true if
201 you're interested in the draw rate you're actually getting.
202 .TP
203 .B video.resizable
204 If true, the window will be resizable by the window manager. This option is
205 meaningless if the game is drawing to the full screen.
206 .TP
207 .B video.swapcontrol
208 If true, drawing will take place at a time which will minimize distortion caused
209 by the vertical refreshing of displays. The recommended value is true.
210 .br
211 .SH ENVIRONMENT
212 .PP
213 .B yoink
214 responds to some variables in the environment:
215 .TP
216 HOME
217 If set to a path of a valid directory (presumably a user's home directory),
218 .B yoink
219 will look for a file at
220 .I $HOME/.yoinkrc
221 and load it as a configuration file. Saving options within the game will cause
222 this file to be over-written with the new options, unless the
223 .I YOINKRC
224 variable is set.
225 .TP
226 USER
227 .B yoink
228 uses this variable to guess the user's nickname, for a high score entry or
229 whatever.
230 .TP
231 YOINK_DATADIR
232 If set to a path of a valid directory,
233 .B yoink
234 will look in this directory first when it is loading game assets. Set this
235 variable if you move the game's assets to another directory or perhaps want to
236 load your own custom assets rather than the defaults.
237 .TP
238 YOINKRC
239 If set to a path of a valid configuration file,
240 .B yoink
241 will load the options from that file, and those options will take precedence
242 over options loaded from other configuration files. Any in-game saving will
243 cause this file to be over-written by the new options rather than the
244 .I $HOME/.yoinkrc
245 config file.
246 .br
247 .SH NOTES
248 .PP
249 Yoink may or may not be playable with acceptable frame rates without a hardware
250 accelerated OpenGL driver installed and working, depending on how fast your CPU
251 is. Yoink is really not all that heavy on graphics, but it doesn't take much to
252 overload a software implementation. If you're stuck without hardware
253 acceleration, there are some things you can do to get better frame rates:
254 .PP
255 1. Decrease the resolution with the
256 .I video.mode
257 option. Due to the nature of the graphics in the game, you can go as low as
258 320x240 and not notice a large reduction in image quality. You can take
259 advantage of this by decreasing the resolution and running full-screen (so the
260 window is not so itty bitty on your monitor). This will help out a lot. Try
261 this:
262 .TP
263 yoink video.mode=[320,240] video.fullscreen=true
264 .PP
265 2. Decrease the level of detail with the
266 .I game.detail
267 option.
268 .PP
269 On the other hand, if you already get high frame rates, you may also want to cap
270 the rate so that your computer doesn't do more work than it really needs to.
271 This may be useful when you run
272 .B yoink
273 on your production server at work. You can get reasonably smooth animation at
274 around 30fps, but you can probably tell a difference between that and a higher
275 rate like 50fps. The latter will look noticeably smoother and nice, while the
276 former is just "acceptable." See the
277 .I video.maxfps
278 option.
279 .br
280 .SH BUGS
281 .PP
282 Although the pixelated graphics are intentional, there are some unintended
283 artifacts which are more obvious on certain OpenGL implementations.
284 .PP
285 Send bug reports, patches, and love notes to:
286 .br
287 Charles McGarvey <onefriedrice@brokenzipper.com>
288 .SH AUTHOR
289 .PP
290 Neil Carter was the original creator of Yoink, his winning entry in the
291 uDevGames 2003 Mac game development contest. Charles McGarvey restored the game
292 and is the current maintainer.
This page took 0.041919 seconds and 3 git commands to generate.