5742a5e51963b9dcc518380c0abbb358133ad101
[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.
73 .PP
74 A
75 .B yoink
76 configuration file ("yoinkrc") consists of key-value pairs. The format is not
77 unlike that of other configuration files you are already familiar with. The
78 syntax used is lua.
79 .B yoink
80 looks for configuration files and loads them in this order, the options from
81 each subsequent configuration files taking precedence over the same options if
82 they exist in previous files.
83 .TP
84 1. @DATADIR@/yoinkrc
85 This is the base configuration file which should be considered read-only. Look
86 to this file as an example of the format used for configuration files.
87 .TP
88 2. /etc/yoinkrc
89 This is the system-wide configuration file. Not available on Windows.
90 .TP
91 3. $HOME/.yoinkrc
92 This is your own personal configuration file.
93 .TP
94 4. $YOINKRC
95 This is an optional environment variable you can set to point to a configuration
96 file.
97 .PP
98 Options that are passed as arguments take precedence over options loaded from
99 the configuration file(s). This mechanism can be used to play the game with
100 temporary settings which you do not intend to retain. Here are some examples of
101 passing options on the command-line:
102 .PP
103 .TP
104 yoink fullscreen=true
105 Run Yoink with the option
106 .I fullscreen
107 as true. This will run the game in full-screen mode.
108 .TP
109 yoink maxfps=60
110 Run Yoink with the option
111 .I maxfps
112 as 60. This will cap the display rate at 60Hz.
113 .PP
114 You can also set options with array values. Arrays can be passed on the command
115 line by surrounding all the parts with curly brackets and separating each part
116 by a comma. You may also have to quote the brackets so your shell doesn't parse
117 them. For example:
118 .TP
119 yoink videomode=\\{1024,768\\}
120 Run Yoink with the top
121 .I videomode
122 as the numbers 1024 and 768. The video size will be 1024x768.
123 .PP
124 Here is a list of some of the options available:
125 .TP
126 .B detail
127 The level of detail. Possible values are 1, 2, or 3, 1 meaning the least amount
128 of detail and 3 meaning the most. This effects the number of objects drawn to
129 the screen. A high level of detail will draw everything but could cause poor
130 frame rates if the graphics driver can't keep up with the load. Lower levels
131 will omit certain details which aren't crucial for playing the game with the
132 benefit of higher frame rates. See the Notes for more ways to increase the
133 game's performance. The default value is 3.
134 .TP
135 .B doublebuffer
136 If true, double-buffering will be used to help minimize distortion and artifacts
137 caused by the animation of the game. Otherwise, a single buffer will be used.
138 The default value is true.
139 .TP
140 .B fullscreen
141 If true, the window will capture the display and render the game in full screen
142 splendor. A value of false means the game will run in a window. The default
143 value is false.
144 .TP
145 .B maxfps
146 The maximum number of frames to be drawn per second. If your computer is really
147 old, you can get away with decreasing this value and still have reasonably
148 smooth animation. You can set this to a very high number to effectively render
149 as many frames as is possible, but the actual rate could be limited by vertical
150 display synchronization, depending on the X11 driver and settings used. You
151 should not set this option higher than the point where the vertical
152 synchronization effectively limits the draw rate or else the game may not be
153 able to update the physics on schedule which could actually significantly lower
154 the quality of the animation. The default value is 40.
155 .TP
156 .B printfps
157 If true, the current number of frames being drawn per second will be printed to
158 the console. The default value is false.
159 .TP
160 .B resizable
161 If true, the window will be resizable by the window manager. This option is
162 meaningless if the game is drawing to the full screen. The default option is
163 true.
164 .TP
165 .B showcursor
166 This option effects the visibility of the cursor while it is "hovering" over the
167 display. If the value is true, the cursor will be visible. Otherwise, the
168 cursor will be hidden. The default value is true.
169 .TP
170 .B timestep
171 The number of times per second the simulation state will be updated. A value
172 of 100 or higher is ideal for a better physical simulation. Values that are
173 much lower cause the CPU to do less work, but accuracy will suffer. Errors
174 could be introduced in the game with extremely low values. The default value
175 is 80.
176 .TP
177 .B videomode
178 The resolution or size of the window. The value is an array with three number
179 elements representing the width, height, and bits per pixel that make up the
180 video mode. The third number is optional. The default value is {800, 600}.
181 .PP
182 This is only a list of the more useful options. You'll have to use the source
183 to find out about the more esoteric options, but you probably won't need to.
184 .br
185 .SH ENVIRONMENT
186 .PP
187 .B yoink
188 responds to some variables in the environment:
189 .TP
190 HOME
191 If set to a path of a valid directory (presumably a user's home directory),
192 .B yoink
193 will look for a file at
194 .I $HOME/.yoinkrc
195 and load it as a configuration file.
196 .TP
197 USER
198 .B yoink
199 uses this variable to guess the user's nickname, for a high score entry or
200 whatever.
201 .TP
202 YOINK_DATADIR
203 If set to a path of a valid directory,
204 .B yoink
205 will look in this directory first when it is loading game assets. Set this
206 variable if you move the game's assets to another directory or perhaps want to
207 load your own custom assets rather than the defaults.
208 .TP
209 YOINKRC
210 If set to a path of a valid configuration file,
211 .B yoink
212 will load the options from that file, and those options will take precedence
213 over options loaded from other configuration files.
214 .br
215 .SH NOTES
216 .PP
217 Yoink may or may not be playable with acceptable frame rates without a hardware
218 accelerated OpenGL driver installed and working, depending on how fast your CPU
219 is. Yoink is really not all that heavy on graphics, but it doesn't take much to
220 overload a software implementation. If you're stuck without hardware
221 acceleration, there are some things you can do to get better frame rates, in
222 order of effectiveness:
223 .TP
224 1. Decrease the resolution.
225 Use the
226 .I videomode
227 option or just resize the window if the
228 .I fullscreen
229 option is false and the
230 .I resizable
231 option is true. This speeds up software renderers considerably.
232 .TP
233 2. Decrease the timestep.
234 Use the
235 .I timestep
236 option. You can set the timestep to be as low as the your
237 .I maxfps
238 option, but it is not recommended to set this lower than the target frame rate.
239 Remember the trade-off here is decreased simulation accuracy. Try this to set
240 your frame rate to 30Hz and your timestep to 60Hz:
241 .PP
242 yoink maxfps=30 timestep=maxfps\\*2
243 .TP
244 3. Decrease the level of rendering detail.
245 Use the
246 .I detail
247 option. The game world may look sparse or incomplete, but that may be better
248 than choppy animation.
249 .br
250 .SH BUGS
251 .PP
252 Although the pixelated graphics are intentional, there are some unintended
253 artifacts which are more obvious on certain OpenGL implementations.
254 .PP
255 Send bug reports, patches, and love notes to:
256 .br
257 Charles McGarvey <@PACKAGE_BUGREPORT@>
258 .SH AUTHOR
259 .PP
260 Neil Carter was the original creator of Yoink, his winning entry in the
261 uDevGames 2003 Mac game development contest. Charles McGarvey restored the game
262 and is the current maintainer.
This page took 0.039229 seconds and 3 git commands to generate.