minor build system, doc fixes
[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 framerate
108 The target number of frames to be drawn per second. If your computer is
109 really old, you can get away with decreasing this value and still have
110 reasonably smooth animation. You can set this to a very high number to
111 effectively render as many frames as is possible, but the actual rate could
112 be limited by vertical display synchronization, depending on the X11 driver
113 and settings used. The default value is 50.
114 .TP
115 .B fullscreen
116 If true, the window will capture the display and render the game in full
117 screen splendor. A value of false means the game will run in a window.
118 The default value is false.
119 .TP
120 .B resizable
121 If true, the window will be resizable by the window manager. This option
122 is meaningless if the game is drawing to the full screen. The default
123 option is true.
124 .TP
125 .B showfps
126 If true, the current number of frames being drawn per second will be
127 printed to the console every second. The default value is false.
128 .TP
129 .B timestep
130 The number of times per second the simulation state will be updated. A
131 value of 100 or higher is ideal for a better physical simulation. Values
132 that are much lower cause the CPU to do less work, but accuracy will
133 suffer. Errors could be introduced in the game with extremely low values.
134 The default value is 80.
135 .TP
136 .B videomode
137 The resolution or size of the window. The value is an array with three
138 number elements representing the width, height, and bits per pixel that
139 make up the video mode. The third number is optional. The default value
140 is {800,600}. If passing on the command-line, you may need to escape the
141 curly braces so the shell doesn't parse them.
142 .PP
143 This is only a list of the more useful options. You'll have to use the
144 source to find out about the more esoteric options, but you probably won't
145 need to.
146 .SH EXAMPLES
147 Here are some examples of typical usage:
148 .TP
149 $ yoink detail=2
150 Set the level of detail to 2 so that less stuff is drawn to the screen.
151 .TP
152 $ yoink fullscreen=true videomode=\\{1024,768\\}
153 Run \fByoink\fP at full screen with a resolution of 1024x768. Notice the
154 escapes for the curly braces so the shell doesn't parse them.
155 .SH ENVIRONMENT
156 \fByoink\fP responds to some variables in the environment:
157 .TP
158 .I HOME
159 If set to a path of a valid directory (presumably your home directory),
160 \fByoink\fP will look for a file at \fI$HOME/.yoinkrc\fP and load it as a
161 config file.
162 .TP
163 .I USER
164 \fByoink\fP uses this variable to guess the user's nickname, for a high
165 score entry or whatever.
166 .TP
167 .I YOINK_DATADIR
168 If set to a path of a valid directory, \fByoink\fP will look in this
169 directory first when it is loading game assets. Set this variable if you
170 move the game's assets to another directory or perhaps want to load your
171 own custom assets rather than the defaults.
172 .TP
173 .I YOINKRC
174 If set to a path of a valid config file, \fByoink\fP will load the options
175 from that file, and those options will take precedence over options loaded
176 from other config files.
177 .SH NOTES
178 \fByoink\fP may or may not be playable with acceptable frame rates without
179 a hardware accelerated GL driver installed and working, depending on how
180 fast your CPU is. \fByoink\fP is really not all that heavy on graphics,
181 but it doesn't take much to overload a software implementation. You should
182 first check the documentation provided by your OS provider to see how to
183 enable direct rendering. If you're really stuck without hardware
184 acceleration, there are some things you can do to get marginally better
185 frame rates:
186 .TP
187 1. Decrease the resolution.
188 Use the \fBvideomode\fP option or just resize the window if the
189 \fBfullscreen\fP option is false and the \fBresizable\fP option is true.
190 This can speed up a software renderer considerably.
191 .TP
192 2. Decrease the level of rendering detail.
193 Use the \fBdetail\fP option. The game world may look sparse or incomplete,
194 but that's probably better than choppy animation if you can avoid it.
195 .TP
196 3. Decrease the framerate and/or timestep.
197 If your machine can't meet the target framerate, your actual framerate will
198 probably vary. You will have a better visual experience if you can reduce
199 the \fBframerate\fP to a point such that the actual framerate is basically
200 constant. A constant 20fps or 30fps will look better than a sporadic
201 40-60fps. You can also decrease the \fBtimestep\fP at the expense of
202 decreased simulation accuracy. You'll have to experiment with this value
203 to find out acceptable levels.
204 .PP
205 If you are having audio problems, you may need to upgrade OpenAL. Some
206 systems still provide an old, busted version of OpenAL which may result in
207 stuttering, lag, and other oddities. See about installing a recent version
208 of openal-soft, a high-quality software implementation that is still being
209 maintained.
210 .SH BUGS
211 .IP \(bu 3
212 The robots are currently lacking in intelligence.
213 .IP \(bu
214 Although the pixelated graphics are intentional, there are some unintended
215 artifacts which are more obvious with certain video drivers.
216 .PP
217 Send bug reports, patches, and love notes to:
218 .IP
219 Charles McGarvey <@PACKAGE_BUGREPORT@>
220 .SH AUTHOR
221 .PP
222 Neil Carter was the original creator of Yoink, his winning entry in the
223 uDevGames 2003 Mac game development contest. Charles McGarvey restored the
224 game and is the current maintainer.
This page took 0.03924 seconds and 4 git commands to generate.