lua build scripts
[chaz/yoink] / doc /
1 .\"
2 .\" Copyright (c) 2009-2010, Charles McGarvey
3 .\" All rights reserved.
4 .\"
5 .\" Distributable under the terms and conditions of the 2-clause BSD
6 .\" license; see the file COPYING for a complete text of the license.
7 .\"
8 .TH YOINK 6 "July 24, 2009"
10 Yoink \- An alien-smashing action game.
12 .B yoink [-hi] [OPTION=VALUE]...
14 Leap tall buildings! Crush stupid robots beneath your feet! Wield your
15 extra-terrestrial powers in the defense of humanity, and send those alien
16 invaders back from whence they came!
18 You play the part of a flying alien heroine who must defend her home on
19 Earth from other airborne alien invaders. The game draws inspiration from
20 classic arcade games like Joust, Bombjack, Rampage, and Defender--simple,
21 fast-moving action. Basic arguments include:
22 .TP
23 .B -h, --help
24 Display basic usage information, and exit immediately.
25 .TP
26 .B -i, --info
27 Display build and environment details, and exit immediately.
29 To attack, you must dive on the enemy at high speed. If you're going too
30 slowly, you'll just drift harmlessly by. Diving from above gives different
31 results from swooping in and hitting them from the side. If you're too
32 close to attack, try to build up speed by running away and bouncing off a
33 nearby building!
35 By charging your special alien powers, you can throw fireballs. The orange
36 bar at the top of the screen represents your power level--at maximum, you
37 can destroy almost anything. Aiming can be tricky, but with a little
38 practice it's quite easy to launch them in the right direction. Try doing
39 a little swoop or circle in the air to line yourself up before releasing
40 your fireball.
42 The heroine has limited energy, measured by the blue bar at the top of the
43 screen. When it runs out, it's game over! She can regain lost energy by
44 picking up bonuses dropped by enemies.
46 To complete the current attack wave, you must destroy all the enemies.
47 Hunt around, especially in the sky, if you can't find the last few.
49 You have a certain level of control over the operation of \fByoink\fP
50 through options passed as program arguments or given in config files.
51 \fByoink\fP looks for config files in several locations and in this order:
52 .TP
53 1. \fI@YOINK_DATADIR@/yoinkrc\fP
54 This is the base config file which should be considered read-only. Look to
55 this file as an example of the format used for config files.
56 .TP
57 2. \fI/etc/yoinkrc\fP
58 This is the system-wide config file.
59 .TP
60 3. \fI$HOME/.yoinkrc\fP
61 This is your own personal config file.
62 .TP
63 4. \fI$YOINKRC\fP
64 This is an optional environment variable you can set to the path of a
65 config file at a non-standard location. See the \fBENVIRONMENT\fP section
66 below for more information.
67 .PP
68 As usual, options that are passed as arguments take precedence over options
69 loaded from any config file. Here is a list of some of the options
70 available at your disposal:
71 .TP
72 .B detail
73 The level of detail. Possible values are 1, 2, or 3 where 1 means the
74 least amount of detail and 3 means the most. This effects the number of
75 objects drawn to the screen. A high level of detail will draw everything
76 but could cause poor frame rates if the graphics driver can't keep up with
77 the load. Lower levels will omit certain details which aren't crucial for
78 playing the game with the possible benefit of higher frame rates. See the
79 Notes for more ways to increase the game's performance. The default value
80 is 3.
81 .TP
82 .B doublebuffer
83 If true, double-buffering will be used to help minimize distortion and
84 artifacts caused by the animation of the game. Otherwise, a single buffer
85 will be used. The default value is true.
86 .TP
87 .B framerate
88 The target number of frames to be drawn per second. If your computer is
89 really old, you can get away with decreasing this value and still have
90 reasonably smooth animation. You can set this to a very high number to
91 effectively render as many frames as is possible, but the actual rate could
92 be limited by vertical display synchronization, depending on the X11 driver
93 and settings used. The default value is 50.
94 .TP
95 .B fullscreen
96 If true, the window will capture the display and render the game in full
97 screen splendor. A value of false means the game will run in a window.
98 The default value is false.
99 .TP
100 .B resizable
101 If true, the window will be resizable by the window manager. This option
102 is meaningless if the game is drawing to the full screen. The default
103 option is true.
104 .TP
105 .B showfps
106 If true, the current number of frames being drawn per second will be
107 printed to the console every second. The default value is false.
108 .TP
109 .B timestep
110 The number of times per second the simulation state will be updated. A
111 value of 100 or higher is ideal for a better physical simulation. Values
112 that are much lower cause the CPU to do less work, but accuracy will
113 suffer. Errors could be introduced in the game with extremely low values.
114 The default value is 80.
115 .TP
116 .B videomode
117 The resolution or size of the window. The value is an array with three
118 number elements representing the width, height, and bits per pixel that
119 make up the video mode. The third number is optional. The default value
120 is {800,600}. If passing on the command-line, you may need to escape the
121 curly braces so the shell doesn't parse them.
122 .PP
123 This is only a list of the more useful options. You'll have to use the
124 source to find out about the more esoteric options, but you probably won't
125 need to.
127 Here are some examples of typical usage:
128 .TP
129 $ yoink detail=2
130 Set the level of detail to 2 so that less stuff is drawn to the screen.
131 .TP
132 $ yoink fullscreen=true videomode=\\{1024,768\\}
133 Run \fByoink\fP at full screen with a resolution of 1024x768. Notice the
134 escapes for the curly braces so the shell doesn't parse them.
136 \fByoink\fP responds to some variables in the environment:
137 .TP
138 .I HOME
139 If set to a path of a valid directory (presumably your home directory),
140 \fByoink\fP will look for a file at \fI$HOME/.yoinkrc\fP and load it as a
141 config file.
142 .TP
143 .I USER
144 \fByoink\fP uses this variable as the user's name, for a high score entry
145 or whatever.
146 .TP
148 If set to a path of a valid directory, \fByoink\fP will look in this
149 directory first when it is loading game assets. Set this variable if you
150 move the game's assets to another directory or perhaps want to load your
151 own custom assets rather than the defaults.
152 .TP
154 If set to a path of a valid config file, \fByoink\fP will load the options
155 from that file, and those options will take precedence over options loaded
156 from other config files.
158 \fByoink\fP may or may not be playable with acceptable frame rates without
159 a hardware accelerated GL driver installed and working, depending on how
160 fast your CPU is. \fByoink\fP is really not all that heavy on graphics,
161 but it doesn't take much to overload a software implementation. You should
162 first check the documentation provided by your OS provider to see how to
163 enable direct rendering. If you're really stuck without hardware
164 acceleration, there are some things you can do to get marginally better
165 frame rates:
166 .TP
167 1. Decrease the resolution.
168 Use the \fBvideomode\fP option or just resize the window if the
169 \fBfullscreen\fP option is false and the \fBresizable\fP option is true.
170 This can speed up a software renderer considerably.
171 .TP
172 2. Decrease the level of rendering detail.
173 Use the \fBdetail\fP option. The game world may look sparse or incomplete,
174 but that's probably better than choppy animation if you can avoid it.
175 .TP
176 3. Decrease the framerate and/or timestep.
177 If your machine can't meet the target framerate, your actual framerate will
178 probably vary. You will have a better visual experience if you can reduce
179 the \fBframerate\fP to a point such that the actual framerate is basically
180 constant. A constant 20fps or 30fps will look better than a sporadic
181 40-60fps. You can also decrease the \fBtimestep\fP at the expense of
182 decreased simulation accuracy. You'll have to experiment with this value
183 to determine acceptable levels.
184 .PP
185 If you are having audio problems, you may need to upgrade OpenAL. Some
186 systems still provide an old, busted version of OpenAL which may result in
187 stuttering, lag, and other oddities. See about installing a recent version
188 of openal-soft, a high-quality software implementation that is still being
189 maintained.
190 .SH BUGS
191 .IP \(bu 3
192 The robots aren't very bright.
193 .IP \(bu
194 Although the pixelated graphics are intentional, there are some unintended
195 artifacts which are more obvious with certain video drivers.
196 .PP
197 Send bug reports, patches and love notes to:
198 .IP
199 Charles McGarvey <@BUGREPORT@>
201 .PP
202 Neil Carter was the original creator of Yoink, his winning entry in the
203 uDevGames 2003 Mac game development contest. Charles McGarvey restored the
204 game and is the current maintainer.
This page took 0.037927 seconds and 4 git commands to generate.