Debian Codegraph @

doc/scripts/sound.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 <html><head>
3 <!--
4 ---- (c) Copyright 2002-2007 by Lutz Sammer, Russell Smith
5
6 ---- This program is free software; you can redistribute it and/or modify
7 ---- it under the terms of the GNU General Public License as published by
8 ---- the Free Software Foundation; only version 2 of the License.
9 ----
10 ---- This program is distributed in the hope that it will be useful,
11 ---- but WITHOUT ANY WARRANTY; without even the implied warranty of
12 ---- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 ---- GNU General Public License for more details.
14 ----
15 ---- You should have received a copy of the GNU General Public License
16 ---- along with this program; if not, write to the Free Software
17 ---- Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
18 ---- 02111-1307, USA.
19 -->
20 <title>Bos Wars Scripting API: Icon</title>
21 <meta http-equiv="Content-Type" content="text/html; CHARSET=iso-8859-1">
22 <link rel="stylesheet" type="text/css" href="scripts.css">
23 </head>
24 <body>
25 <h1>Bos Wars Scripting API: Sound</h1>
26 <hr>
27 <a href="../index.html">Bos Wars</a>
28 <a href="../faq.html">FAQ</a>
29 <a href="savegame.html">PREV</a>
30 <a href="triggers.html">NEXT</a>
31 <a href="index.html">LUA Index</a>
32 <hr>
33 <a href="#DefineGameSounds">DefineGameSounds</a>
34 <a href="#GetEffectsVolume">GetEffectsVolume</a>
35 <a href="#GetMusicVolume">GetMusicVolume</a>
36 <a href="#IsEffectsEnabled">IsEffectsEnabled</a>
37 <a href="#IsMusicEnabled">IsMusicEnabled</a>
38 <a href="#MakeSound">MakeSound</a>
39 <a href="#MakeSoundGroup">MakeSoundGroup</a>
40 <a href="#MapSound">MapSound</a>
41 <a href="#PlayFile">PlayFile</a>
42 <a href="#PlayMusic">PlayMusic</a>
43 <a href="#PlaySound">PlaySound</a>
44 <a href="#PlaySoundFile">PlaySoundFile</a>
45 <a href="#SetChannelStereo">SetChannelStereo</a>
46 <a href="#SetChannelVolume">SetChannelVolume</a>
47 <a href="#SetEffectsEnabled">SetEffectsEnabled</a>
48 <a href="#SetEffectsVolume">SetEffectsVolume</a>
49 <a href="#SetGlobalSoundRange">SetGlobalSoundRange</a>
50 <a href="#SetMusicEnabled">SetMusicEnabled</a>
51 <a href="#SetMusicVolume">SetMusicVolume</a>
52 <a href="#SetSoundRange">SetSoundRange</a>
53 <a href="#SoundForName">SoundForName</a>
54 <a href="#StopAllChannels">StopAllChannels</a>
55 <a href="#StopChannel">StopChannel</a>
56 <a href="#StopMusic">StopMusic</a>
57 <hr>
58 <h2>Intro - Introduction to sound functions and variables</h2>
59
60 <p>Everything around sound.</p>
61
62 <h2>Functions</h2>
63
64 <a name="DefineGameSounds"></a>
65 <h3>DefineGameSounds("name", arg, [[name2, arg] ...])</h3>
66
67 <p>Specify some global sounds.</p>
68
69 <dl>
70 <dt>"name", arg</dt>
71 <dd>One of the following:
72 <ul>
73 <li>"click", SoundId</li>
74 <li>"placement-error", SoundId</li>
75 <li>"placement-success", SoundId</li>
76 <li>"rescue", SoundId</li>
77 </ul>
78 Where Soundid is the sound to use</dd>
79 <dt><I>RETURNS</I></dt>
80 <dd>Nothing</dd>
81 </dl>
82
83 <h4>Example</h4>
84
85 <pre class="lua">
86 -- Define sounds used by game
87 --
88 DefineGameSounds(
89
90 "placement-error", MakeSound("placement error", "ui/placement_error.wav"),
91 "placement-success", MakeSound("placement success", "ui/placement_success.wav"),
92 "click", sound_click, -- sound_click already define as SoundId
93
94 -- FIXME: Not ready
95 -- "transport-docking",
96 -- "building-construction",
97
98 "rescue", MakeSound("human rescue", "human/rescue.wav"),
99 </pre>
100
101 <a name="MakeSound"></a>
102 <h3>MakeSound("name", "file" or {"file1", "file2", ...})</h3>
103
104 <p>Asks the sound system to register a sound under a given name, with an
105 associated list of files (the list can be replaced by only one file).</p>
106
107 <dl>
108 <dt>name</dt>
109 <dd>Name of the sound.</dd>
110 <dt>file</dt>
111 <dd>Name of the file or a list of files.</dd>
112 <dt><I>RETURNS</I></dt>
113 <dd>A SoundId object that represents the registered sound.</dd>
114 </dl>
115
116 <h4>Example</h4>
117
118 <pre class="lua">
119 -- Makes the sounds "lightning" and "basic human voices acknowledge".
120 MakeSound("lightning", "spells/lightning.wav")
121
122 MakeSound("basic human voices acknowledge",
123 {"human/basic_voices/acknowledgement/1.wav",
124 "human/basic_voices/acknowledgement/2.wav",
125 "human/basic_voices/acknowledgement/3.wav",
126 "human/basic_voices/acknowledgement/4.wav"})
127 </pre>
128
129 <a name="MakeSoundGroup"></a>
130 <h3>MakeSoundGroup("name", "groupname1" or SoundId, "groupname2" or SoundId)</h3>
131
132 <p>Asks the sound system to build a special sound group.</p>
133
134 <dl>
135 <dt>name</dt>
136 <dd>Name of the sound.</dd>
137 <dt>group1</dt>
138 <dd>SoundId or string</dd>
139 <dt>group2</dt>
140 <dd>SoundId or string</dd>
141 <dt><I>RETURNS</I></dt>
142 <dd>A SoundId object that represents the sound group.</dd>
143 </dl>
144
145 <h4>Example</h4>
146
147 <pre class="lua">
148 -- Define selection sound groups.
149 MakeSoundGroup("footman-selected",
150 "basic human voices selected", "basic human voices annoyed")
151 </pre>
152
153 <a name="MapSound"></a>
154 <h3>MapSound("name", "sound")</h3>
155
156 <p>Asks the sound system to remap a sound id to a given name.</p>
157
158 <dl>
159 <dt>name</dt>
160 <dd>Name of the sound.</dd>
161 <dt>sound</dt>
162 <dd>Sound to map to: either a sound name (a string) or a SoundId.</dd>
163 </dl>
164
165 <h4>Example</h4>
166
167 <pre class="lua">
168 -- Maps the name "footman-acknowledge" to "basic human voices acknowledge".
169 MapSound("footman-acknowledge", "basic human voices acknowledge")
170 </pre>
171
172 <a name="PlaySoundFile"></a>
173 <h3>PlaySoundFile("name" [, callback])</h3>
174
175 <p>Plays a sound file.</p>
176
177 <dl>
178 <dt>name</dt>
179 <dd>Name of the file to play.</dd>
180 <dt>callback</dt>
181 <dd>An optional Lua function that the engine will call when the sound
182 finishes playing.</dd>
183 <dt><I>RETURNS</I></dt>
184 <dd>The channel number allocated for the sound, or -1 if no channels
185 are available. The Lua script can pass this number to various
186 "Channel" functions to control the sound as it plays.</dd>
187 </dl>
188
189 <h4>Example</h4>
190
191 <pre class="lua">
192 -- Play the file "spells/lightning.wav", with no callback.
193 PlaySoundFile("spells/lightning.wav")
194 </pre>
195
196 <a name="PlayFile"></a>
197 <h3>PlayFile("name" [, callback])</h3>
198
199 <p>Like <a href="#PlaySoundFile">PlaySoundFile</a>,
200 except the callback must be a LuaActionListener object.
201 Lua scripts should use PlaySoundFile instead.</p>
202
203 <a name="PlayMusic"></a>
204 <h3>PlayMusic("filename")</h3>
205
206 <p>Plays music from the specified file.</p>
207
208 <dl>
209 <dt>name</dt>
210 <dd>Name of the music file.</dd>
211 <dt><I>RETURNS</I></dt>
212 <dd>0 if it started playing music from the file.
213 -1 if music is disabled or an error occurred.</dd>
214 </dl>
215
216 <h4>Example</h4>
217
218 <pre class="lua">
219 -- Plays the music file "music/default.ogg".
220 PlayMusic("music/default.ogg")
221 </pre>
222
223 <a name="PlaySound"></a>
224 <h3>PlaySound("name")</h3>
225
226 <p>Asks the sound system to play the specified sound.</p>
227
228 <dl>
229 <dt>"name"</dt>
230 <dd>Name of the sound to play.</dd>
231 <dt><I>RETURNS</I></dt>
232 <dd>Nothing</dd>
233 </dl>
234
235 <h4>Example</h4>
236
237 <pre class="lua">
238 -- Play the sound "basic human voices ready".
239 PlaySound("basic human voices ready")
240 </pre>
241
242 <a name="SetGlobalSoundRange"></a>
243 <h3>SetGlobalSoundRange(distance)</h3>
244
245 <p>Sets the cut off distance.</p>
246
247 <dl>
248 <dt>distance</dt>
249 <dd>Max tile distance to hear sounds.</dd>
250 <dt><I>RETURNS</I></dt>
251 <dd>Nothing</dd>
252 </dl>
253
254 <h4>Example</h4>
255
256 <pre class="lua">
257 -- Set the sound range to 40.
258 SetGlobalSoundRange(40)
259 </pre>
260
261 <a name="SetMusicVolume"></a>
262 <h3>SetMusicVolume(volume)</h3>
263
264 <p>Sets the music volume.
265 <a href="#GetMusicVolume">GetMusicVolume</a> reads this setting back.</p>
266
267 <dl>
268 <dt>volume</dt>
269 <dd>Number between 0 and MaxVolume.</dd>
270 <dt><I>RETURNS</I></dt>
271 <dd>Nothing</dd>
272 </dl>
273
274 <h4>Example</h4>
275
276 <pre class="lua">
277 -- Set the music volume to 128.
278 SetMusicVolume(128)
279 </pre>
280
281 <a name="GetMusicVolume"></a>
282 <h3>GetMusicVolume()</h3>
283
284 <p>Gets the music volume.
285 <a href="#SetMusicVolume">SetMusicVolume</a> changes this setting.</p>
286
287 <dl>
288 <dt><I>RETURNS</I></dt>
289 <dd>Number between 0 and MaxVolume.</dd>
290 </dl>
291
292 <a name="SetSoundRange"></a>
293 <h3>SetSoundRange("name", distance)</h3>
294
295 <p>Sets the range of a given sound.</p>
296
297 <dl>
298 <dt>name</dt>
299 <dd>Name or SoundId of the sound.</dd>
300 <dt>distance</dt>
301 <dd>Max tile distance to hear the sound.</dd>
302 <dt><I>RETURNS</I></dt>
303 <dd>The name or SoundId given as the first parameter.</dd>
304 </dl>
305
306 <h4>Example</h4>
307
308 <pre class="lua">
309 -- Set the range of the sound "basic human voices ready" to 20.
310 SetSoundRange("basic human voices ready", 20)
311 </pre>
312
313 <a name="SetEffectsVolume"></a>
314 <h3>SetEffectsVolume(volume)</h3>
315
316 <p>Sets the volume of sound effects.
317 <a href="#GetEffectsVolume">GetEffectsVolume</a> reads this setting back.</p>
318
319 <dl>
320 <dt>volume</dt>
321 <dd>Number between 0 and MaxVolume.</dd>
322 <dt><I>RETURNS</I></dt>
323 <dd>Nothing</dd>
324 </dl>
325
326 <h4>Example</h4>
327
328 <pre class="lua">
329 -- Set the sound volume to 128.
330 SetEffectsVolume(128)
331 </pre>
332
333 <a name="GetEffectsVolume"></a>
334 <h3>GetEffectsVolume()</h3>
335
336 <p>Gets the volume of sound effects.
337 <a href="#SetEffectsVolume">SetEffectsVolume</a> changes this setting.</p>
338
339 <dl>
340 <dt><I>RETURNS</I></dt>
341 <dd>Number between 0 and MaxVolume.</dd>
342 </dl>
343
344 <a name="SoundForName"></a>
345 <h3>SoundForName("name")</h3>
346
347 <p>Asks the sound system to associate a sound id to a sound name.</p>
348
349 <dl>
350 <dt>name</dt>
351 <dd>Name of the sound.</dd>
352 <dt><I>RETURNS</I></dt>
353 <dd>SoundId</dd>
354 </dl>
355
356 <h4>Example</h4>
357
358 <pre class="lua">
359 SoundForName("peasant attack")
360 </pre>
361
362 <a name="SetEffectsEnabled"></a>
363 <h3>SetEffectsEnabled(enabled)</h3>
364
365 <p>Turns sound effects on or off.
366 <a href="#IsEffectsEnabled">IsEffectsEnabled</a> reads this setting back.</p>
367
368 <dl>
369 <dt>enabled</dt>
370 <dd>true or false.</dd>
371 <dt><I>RETURNS</I></dt>
372 <dd>Nothing</dd>
373 </dl>
374
375 <h4>Example</h4>
376
377 <pre class="lua">
378 -- Turns on sound effects.
379 SetEffectsEnabled(true)
380 </pre>
381
382 <a name="IsEffectsEnabled"></a>
383 <h3>IsEffectsEnabled()</h3>
384
385 <p>Checks whether sound effects are enabled.
386 <a href="#SetEffectsEnabled">SetEffectsEnabled</a> changes this setting.</p>
387
388 <dl>
389 <dt><I>RETURNS</I></dt>
390 <dd>true or false</dd>
391 </dl>
392
393 <a name="SetMusicEnabled"></a>
394 <h3>SetMusicEnabled(enabled)</h3>
395
396 <p>Turns music on or off.
397 When music has been disabled with SetMusicEnabled(false),
398 <a href="#PlayMusic">PlayMusic</a> does nothing.
399 <a href="#IsMusicEnabled">IsMusicEnabled</a> reads this setting back.</p>
400
401 <dl>
402 <dt>enabled</dt>
403 <dd>true or false.</dd>
404 <dt><I>RETURNS</I></dt>
405 <dd>Nothing</dd>
406 </dl>
407
408 <h4>Example</h4>
409
410 <pre class="lua">
411 -- Turns on music.
412 SetMusicEnabled(true)
413 </pre>
414
415 <a name="IsMusicEnabled"></a>
416 <h3>IsMusicEnabled()</h3>
417
418 <p>Checks whether music is enabled.
419 <a href="#SetMusicEnabled">SetMusicEnabled</a> changes this setting.</p>
420
421 <dl>
422 <dt><I>RETURNS</I></dt>
423 <dd>true or false</dd>
424 </dl>
425
426 <a name="StopMusic"></a>
427 <h3>StopMusic()</h3>
428
429 <p>Stops playing music.
430 Unlike <a href="#SetMusicEnabled">SetMusicEnabled</a>(false), this
431 does not prevent <a href="#PlayMusic">PlayMusic</a> from starting
432 music again.</p>
433
434 <dl>
435 <dt><I>RETURNS</I></dt>
436 <dd>Nothing</dd>
437 </dl>
438
439 <h4>Example</h4>
440
441 <pre class="lua">
442 -- Stop playing music.
443 StopMusic()
444 </pre>
445
446 <a name="SetChannelVolume"></a>
447 <h3>SetChannelVolume(channel, volume)</h3>
448
449 <p>Sets the sound volume of the channel.</p>
450
451 <dl>
452 <dt>channel</dt>
453 <dd>Channel number returned by <a href="#PlaySoundFile">PlaySoundFile</a>.</dd>
454 <dt>volume</dt>
455 <dd>The new sound volume of the channel.
456 Should be between 0 and MaxVolume.
457 If this parameter is negative, then SetChannelVolume
458 does not change the volume.
459 If this parameter is too large, then SetChannelVolume
460 uses MaxVolume instead.
461 <dt><I>RETURNS</I></dt>
462 <dd>The resulting sound volume of the channel,
463 or -1 if the channel number is out of range.</dd>
464 </dl>
465
466
467 <a name="SetChannelStereo"></a>
468 <h3>SetChannelStereo(channel, stereo)</h3>
469
470 <p>Sets the panning of the channel between the left and right outputs.</p>
471
472 <dl>
473 <dt>channel</dt>
474 <dd>Channel number returned by <a href="#PlaySoundFile">PlaySoundFile</a>.</dd>
475 <dt>stereo</dt>
476 <dd>The new panning position of the channel.
477 -128 means left, 0 means center, and 127 means right.
478 <dt><I>RETURNS</I></dt>
479 <dd>The resulting panning position of the channel,
480 or -1 if the channel number is out of range.</dd>
481 </dl>
482
483 <a name="StopChannel"></a>
484 <h3>StopChannel(channel)</h3>
485
486 <p>Stops the sound playing in the specified channel.</p>
487
488 <dl>
489 <dt>channel</dt>
490 <dd>Channel number returned by <a href="#PlaySoundFile">PlaySoundFile</a>.</dd>
491 <dt><I>RETURNS</I></dt>
492 <dd>Nothing</dd>
493 </dl>
494
495 <a name="StopAllChannels"></a>
496 <h3>StopAllChannels()</h3>
497
498 <p>Stops all sound effects currently playing.
499 Calls their callback functions, if any.
500 Does not stop music.</p>
501
502 <dl>
503 <dt><I>RETURNS</I></dt>
504 <dd>Nothing</dd>
505 </dl>
506
507 <hr>
508 All trademarks and copyrights on this page are owned by their respective owners.
509 <address>(c) 2002-2007 by <a href="http://boswars.org">
510 The Bos Wars Project</a></address></body></html>