Debian Codegraph @

doc/scripts/config.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 <html><head>
3 <!--
4 ---- (c) Copyright 2002-2010 by Lutz Sammer, Russell Smith, Francois Beerten
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: Config</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: Config</h1>
26 <hr>
27 <a href="../index.html">Bos Wars</a>
28 <a href="../faq.html">FAQ</a>
29 <a href="ai.html">PREV</a>
30 <a href="editor.html">NEXT</a>
31 <a href="index.html">LUA Index</a>
32 <hr>
33 <a href="#AStarFixedUnitCrossingCost">AStarFixedUnitCrossingCost</a>
34 <a href="#AStarKnowUnseenTerrain">AStarKnowUnseenTerrain</a>
35 <a href="#AStarMovingUnitCrossingCost">AStarMovingUnitCrossingCost</a>
36 <a href="#AStarUnknownTerrainCost">AStarUnknownTerrainCost</a>
37 <a href="#AlliedUnitRecyclingEfficiency">AlliedUnitRecyclingEfficiency</a>
38 <a href="#DefineDecorations">DefineDecorations</a>
39 <a href="#DefineDefaultResourceNames">DefineDefaultResourceNames</a>
40 <a href="#DefineSprites">DefineSprites</a>
41 <a href="#EnemyUnitRecyclingEfficiency">EnemyUnitRecyclingEfficiency</a>
42 <a href="#EnergyCost">EnergyCost</a>
43 <a href="#GetVideoFullScreen">GetVideoFullScreen</a>
44 <a href="#GetVideoResolution">GetVideoResolution</a>
45 <a href="#MagmaCost">MagmaCost</a>
46 <a href="#MaxCosts">MaxCosts</a>
47 <a href="#Preference">Preference</a>
48 <a href="#preferences">preferences</a>
49 <a href="#RevealMap">RevealMap</a>
50 <a href="#RightButtonAttacks">RightButtonAttacks</a>
51 <a href="#RightButtonMoves">RightButtonMoves</a>
52 <a href="#SavePreferences">SavePreferences</a>
53 <a href="#SetAllPlayersBuildingLimit">SetAllPlayersBuildingLimit</a>
54 <a href="#SetAllPlayersUnitLimit">SetAllPlayersUnitLimit</a>
55 <a href="#SetAllPlayersTotalUnitLimit">SetAllPlayersTotalUnitLimit</a>
56 <a href="#SetBuildingCapture">SetBuildingCapture</a>
57 <a href="#SetClickMissile">SetClickMissile</a>
58 <a href="#SetDamageMissile">SetDamageMissile</a>
59 <a href="#SetDoubleClickDelay">SetDoubleClickDelay</a>
60 <a href="#SetFogOfWar">SetFogOfWar</a>
61 <a href="#SetFogOfWarGraphics">SetFogOfWarGraphics</a>
62 <a href="#SetGrabMouse">SetGrabMouse</a>
63 <a href="#SetGodMode">SetGodMode</a>
64 <a href="#SetGroupKeys">SetGroupKeys</a>
65 <a href="#SetHoldClickDelay">SetHoldClickDelay</a>
66 <a href="#SetKeyScroll">SetKeyScroll</a>
67 <a href="#SetLeaveStops">SetLeaveStops</a>
68 <a href="#SetMaxOpenGLTexture">SetMaxOpenGLTexture</a>
69 <a href="#SetMaxSelectable">SetMaxSelectable</a>
70 <a href="#SetMinimapTerrain">SetMinimapTerrain</a>
71 <a href="#SetMouseScroll">SetMouseScroll</a>
72 <a href="#SetMouseScrollSpeedControl">SetMouseScrollSpeedControl</a>
73 <a href="#SetMouseScrollSpeedDefault">SetMouseScrollSpeedDefault</a>
74 <a href="#SetSpeedBuild">SetSpeedBuild</a>
75 <a href="#SetSpeedTrain">SetSpeedTrain</a>
76 <a href="#SetSpeeds">SetSpeeds</a>
77 <a href="#SetTitleScreens">SetTitleScreens</a>
78 <a href="#SetVideoFullScreen">SetVideoFullScreen</a>
79 <a href="#SetVideoResolution">SetVideoResolution</a>
80
81 <hr>
82 <h2>Intro - Introduction to config functions and variables</h2>
83
84 General configurations.
85
86 <h2>Constants</h2>
87
88 <h3 id="resource_type_identifiers">Resource type identifiers</h3>
89
90 These integer constants identify types of resources.
91 They are used as indices in the
92 <a href="#AlliedUnitRecyclingEfficiency">AlliedUnitRecyclingEfficiency</a>,
93 <a href="#EnemyUnitRecyclingEfficiency">EnemyUnitRecyclingEfficiency</a>,
94 and <a href="ui.html#UI.Resources">UI.Resources</a> tables.
95
96 <dl>
97 <dt><a name="EnergyCost">EnergyCost</a></dt>
98 <dd>The energy resource type.</dd>
99 <dt><a name="MagmaCost">MagmaCost</a></dt>
100 <dd>The magma resource type.</dd>
101 <dt><a name="MaxCosts">MaxCosts</a></dt>
102 <dd>The total number of different resource types.</dd>
103 </dl>
104
105 <h2>Functions</h2>
106 <a name="DefineDefaultResourceNames"></a>
107 <h3>DefineDefaultResourceNames("name", ...)</h3>
108
109 <p>Names the resources in a given order.
110 The engine does not display these names to the user;
111 it uses them in save files only.
112 Consequently, these names should not be localized.</p>
113
114 <p>(Although this function is called DefineDefaultResourceNames,
115 there is no mechanism for overriding these "default" names with
116 others.)</p>
117
118 <dl>
119 <dt>name</dt>
120 <dd>Name to give to the resource. There should be two names:
121 first one for <a href="#EnergyCost">EnergyCost</a>,
122 and then one for <a href="#MagmaCost">MagmaCost</a>.</dd>
123 <dt><i>RETURNS</i></dt>
124 <dd>Nothing</dd>
125 </dl>
126
127 <h4>Example</h4>
128
129 <pre class="lua">
130 -- Define Resource names
131 DefineDefaultResourceNames(
132 "energy", "magma")
133 </pre>
134
135
136 <a name="DefineSprites"></a>
137 <h3>DefineSprites({tag = value, ...}, ...)</h3>
138
139 Define sprites to be shown for variables.
140 You can define multiple sprites in the same DefineSprites call or
141 each sprite in a separate call; the effect is the same either way.
142
143
144 <dl>
145 Tag could be :
146 <dt>Name = "sprite-name"</dt>
147 <dd>name of the sprite. This is how the Method parameter of
148 <a href="#DefineDecorations">DefineDecorations</a> refers to the sprite.</dd>
149 <dt>File = "filename"</dt>
150 <dd>filename containing the sprite</dd>
151 <dt>Offset = {x, y}</dt>
152 <dd>offset when drawing the sprite.
153 Positive values move the sprite to the right or down.</dd>
154 <dt>Size = {width, height}</dt>
155 <dd>Size of the sprite.
156 The graphic file may contain multiple frames of this size.</dd>
157 </dl>
158
159 <h4>Example</h4>
160
161 <pre class="lua">
162 DefineSprites(
163 {Name = "sprite-health", File = "graphics/ui/health2.png", Offset = {0, -4}, Size = {31, 4}},
164 {Name = "sprite-mana", File = "graphics/ui/mana2.png", Offset = {0, -1}, Size = {31, 4}})
165 </pre>
166
167 <a name="GetVideoFullScreen"></a>
168 <h3>GetVideoFullScreen()</h3>
169
170 Check if the game is in full screen or windowed mode.
171
172 <dl>
173 <dt><i>RETURNS</i></dt>
174 <dd>True if full screen, false if in windowed mode</dd>
175 </dl>
176
177 <h4>Example</h4>
178
179 <pre class="lua">
180 -- Get Fullscreen
181 fullscreen = GetVideoFullScreen()
182 </pre>
183
184 <a name="GetVideoResolution"></a>
185 <h3>GetVideoResolution()</h3>
186
187 Get the video resolution.
188
189 <dl>
190 <dt><i>RETURNS</i></dt>
191 <dd>Width and Height of current resolution</dd>
192 </dl>
193
194 <h4>Example</h4>
195
196 <pre class="lua">
197 -- Get the video resolution
198 w,h = GetVideoResolution()
199 </pre>
200
201 <a name="DefineDecorations"></a>
202 <h3>DefineDecorations({tag = value, ...}, ...)</h3>
203 Define how to show variables.
204
205 <dl>
206 <dt>Index = variable</dt>
207 <dd>
208 Which variable's value this decoration will show. It can be a
209 <a href="unittype.html#predefined-variables">predefined variable</a>,
210 or a custom variable defined with <a href="unittype.html#DefineVariables">DefineVariables</a>.</dd>
211 <dt>Offset = {x, y}, OffsetPercent = {xp, yp}</dt>
212 <dd>Decoration is placed at {x + weight(unit) * xp, y + height(unit) * yp} from the unit.</dd>
213 <dt>CenterX = boolean, CenterY = boolean</dt>
214 <dd>If set to true, use center of decoration instead of the upper-left corner.</dd>
215 <dt id="DefineDecorations.ShowIfNotEnable">ShowIfNotEnable = boolean</dt>
216 <dd>if false (default), show decoration only when variable is enable.</dd>
217 <dt>ShowWhenMax = boolean</dt>
218 <dd>if false, don't show when variable value is max.</dd>
219 <dt>ShowOnlySelected = boolean</dt>
220 <dd>if true, show only when unit is selected.</dd>
221 <dt>HideNeutral = boolean</dt>
222 <dd>if true, don't show for neutral unit.</dd>
223 <dt>HideAllied = boolean</dt>
224 <dd>if true, don't show for allied unit (but show your :) ).</dd>
225 <dt>ShowOpponent = boolean</dt>
226 <dd>if true, show also for opponent unit.</dd>
227
228 <dt>Method = {method-name, {tag = value}}</dt>
229 <dd>Which method we use to show variable.
230 The current engine supports only one method:</dd>
231 <dl>
232 <dt>"sprite", {"sprite-name"}</dt>
233 <dd>Show the p-th icon of the sprite
234 (p depands of variable percent value: from full (left) to empty (right of th image)).
235 The sprite is defined by <a href="#DefineSprites">DefineSprites()</a>.</dd>
236 </dl>
237 </dl>
238
239 <h4>Example</h4>
240
241 <pre class="lua">
242 -- Equivalent of ShowHealthDot
243 DefineDecorations({Index = "HitPoints", HideNeutral = true, CenterX = true,
244 OffsetPercent = {50, 100}, Method = {"sprite", {"sprite-health"}}})
245 </pre>
246
247 <a name="RevealMap"></a>
248 <h3>RevealMap()</h3>
249
250 Reveal the entire map.
251
252 <dl>
253 <dt><i>RETURNS</i></dt>
254 <dd>Nothing</dd>
255 </dl>
256
257 <h4>Example</h4>
258
259 <pre class="lua">
260 RevealMap()
261 </pre>
262
263 <a name="RightButtonAttacks"></a>
264 <h3>RightButtonAttacks()</h3>
265
266 If you prefer fighters are attacking by right clicking empty space.
267 This cancels any previous <a href="#RightButtonMoves">RightButtonMoves</a>.
268
269 <dl>
270 <dt><i>RETURNS</i></dt>
271 <dd>Nothing</dd>
272 </dl>
273
274 <h4>Example</h4>
275
276 <pre class="lua">
277 RightButtonAttacks()
278 </pre>
279
280 <a name="RightButtonMoves"></a>
281 <h3>RightButtonMoves()</h3>
282
283 If you prefer fighters are moving by right clicking empty space.
284 This cancels any previous <a href="#RightButtonAttacks">RightButtonAttacks</a>.
285
286 <dl>
287 <dt><i>RETURNS</i></dt>
288 <dd>Nothing</dd>
289 </dl>
290
291 <h4>Example</h4>
292
293 <pre class="lua">
294 RightButtonMoves()
295 </pre>
296
297 <a name="SavePreferences"></a>
298 <h3>SavePreferences</h3>
299
300 Save the user preferences, i.e. the contents of
301 the <a href="#preferences">preferences</a> variable.
302
303 <dl>
304 <dt><i>RETURNS</i></dt>
305 <dd>Nothing</dd>
306 </dl>
307
308 <h4>Example</h4>
309
310 <pre class="lua">
311 SavePreferences()
312 </pre>
313
314 <a name="SetAllPlayersBuildingLimit"></a>
315 <h3>SetAllPlayersBuildingLimit(limit)</h3>
316
317 Set the limit on the number of buildings a player is allowed to have at one time.
318 The engine maintains a separate limit for each player,
319 and this function changes them all to the same value.
320
321 <dl>
322 <dt>limit</dt>
323 <dd>The maximum number of buildings a player can have.</dd>
324 <dt><i>RETURNS</i></dt>
325 <dd>The limit that was set.</dd>
326 </dl>
327
328 <h4>Example</h4>
329
330 <pre class="lua">
331 SetAllPlayersBuildingLimit(200)
332 </pre>
333
334 <a name="SetAllPlayersUnitLimit"></a>
335 <h3>SetAllPlayersUnitLimit(limit)</h3>
336
337 Sets the number of non-building type units a player can have.
338 The engine maintains a separate limit for each player,
339 and this function changes them all to the same value.
340
341 <dl>
342 <dt>limit</dt>
343 <dd>Number of non-building unit the player can have</dd>
344 <dt><i>RETURNS</i></dt>
345 <dd>The limit that was set.</dd>
346 </dl>
347
348 <h4>Example</h4>
349
350 <pre class="lua">
351 SetAllPlayersUnitLimit(200)
352 </pre>
353
354 <a name="SetAllPlayersTotalUnitLimit"></a>
355 <h3>SetAllPlayersTotalUnitLimit(limit)</h3>
356
357 Sets the total number of units a player may have, building or non-building.
358 The engine maintains a separate limit for each player,
359 and this function changes them all to the same value.
360
361 <dl>
362 <dt>limit</dt>
363 <dd>The number of units to set the limit to.</dd>
364 <dt><i>RETURNS</i></dt>
365 <dd>The limit that was set.</dd>
366 </dl>
367
368 <h4>Example</h4>
369
370 <pre class="lua">
371 SetAllPlayersTotalUnitLimit(400)
372 </pre>
373
374 <a name="SetBuildingCapture"></a>
375 <h3>SetBuildingCapture(boolean)</h3>
376
377 Enable or disable building capture.
378 When enabled, workers can capture low-HP enemy buildings by attacking them.
379 Here, "worker" means the unit is able to repair something
380 (its <a href="unittype.html#DefineUnitType.RepairRange">RepairRange</a> is not zero),
381 and harvesting does not count as attacking.
382
383 <p>SetBuildingCapture does not affect the other mechanisms
384 with which units can be captured:
385 the "capture" spell action in <a href="magic.html#DefineSpell">DefineSpell</a>,
386 the <a href="game.html#ChangeUnitsOwner">ChangeUnitsOwner</a> function used in triggers,
387 and the rescuable player types in <a href="mappresentation.html#DefinePlayerType">DefinePlayerType</a>.</p>
388
389 <dl>
390 <dt>boolean</dt>
391 <dd>true or false, depending on if you want building capture enabled.</dd>
392 <dt><i>RETURNS</i></dt>
393 <dd>Nothing</dd>
394 </dl>
395
396 <h4>Example</h4>
397
398 <pre class="lua">
399 SetBuildingCapture(true)
400 </pre>
401
402 <a name="SetClickMissile"></a>
403 <h3>SetClickMissile("missile-type")</h3>
404
405 Sets the missile to use for displaying when a player clicks on a location on the map.
406
407 <dl>
408 <dt>missile-type</dt>
409 <dd>The missile to use, as defined with <a href="magic.html#DefineMissileType">DefineMissileType</a>.</dd>
410 <dt><i>RETURNS</i></dt>
411 <dd>Nothing</dd>
412 </dl>
413
414 <h4>Example</h4>
415
416 <pre class="lua">
417 SetClickMissile("missile-green-cross")
418 </pre>
419
420 <a name="SetDamageMissile"></a>
421 <h3>SetDamageMissile("missile-type")</h3>
422
423 Sets the missile to use for displaying the damage done to units.
424
425 <dl>
426 <dt>"missile-type"</dt>
427 <dd>missile name to use to display the damage. It must be defined with
428 <a href="magic.html#DefineMissileType">DefineMissileType</a> and should
429 have Class = <a href="magic.html#DefineMissileType.Class.hit">"missile-class-hit"</a>.
430 </dd>
431 <dt><i>RETURNS</i></dt>
432 <dd>Nothing</dd>
433 </dl>
434
435 <h4>Example</h4>
436
437 <pre class="lua">
438 SetDamageMissile("missile-hit")
439 </pre>
440
441 <a name="SetDoubleClickDelay"></a>
442 <h3>SetDoubleClickDelay(delay)</h3>
443
444 Set the delay of double clicking the mouse.
445
446 <dl>
447 <dt>delay</dt>
448 <dd>The delay in ms.</dd>
449 </dl>
450
451 <h4>Example</h4>
452
453 <pre class="lua">
454 SetDoubleClickDelay(300)
455 </pre>
456
457 <a name="SetFogOfWar"></a>
458 <h3>SetFogOfWar(boolean)</h3>
459
460 If true, enable fog of war.
461
462 <a name="SetFogOfWarGraphics"></a>
463 <h3>SetFogOfWarGraphics(graphic)</h3>
464
465 Set the graphics used to render the borders of the view of the units.
466
467 <h4>Example</h4>
468
469 <pre class="lua">
470 SetFogOfWarGraphics("general/fog.png")
471 </pre>
472
473 <a name="SetGrabMouse"></a>
474 <h3>SetGrabMouse(boolean)</h3>
475
476 Enable/disable grabbing the mouse.
477
478 <a name="SetGodMode"></a>
479 <h3>SetGodMode(boolean)</h3>
480
481 Enable/disable god Mode, you do 255 damage, and take 0 damage. You are still vulnerable to spells.
482
483 <dl>
484 <dt>boolean</dt>
485 <dd>true for on, false for off</dd>
486 <dt><i>RETURNS</i></dt>
487 <dd>Nothing</dd>
488 </dl>
489
490 <h4>Example</h4>
491
492 <pre class="lua">
493 -- Set God mode on
494 SetGodMode(true)
495 </pre>
496
497 <a name="SetHoldClickDelay"></a>
498 <h3>SetHoldClickDelay(delay)</h3>
499
500 for the wanted hold-click delay (in ms)..
501
502 <h4>Example</h4>
503
504 <pre class="lua">
505 SetHoldClickDelay(1000)
506 </pre>
507
508 <a name="SetKeyScroll"></a>
509 <h3>SetKeyScroll(boolean)</h3>
510
511 enable/disable keyboard scrolling.
512
513 <a name="SetLeaveStops"></a>
514 <h3>SetLeaveStops(boolean)</h3>
515
516 Enable/disable stopping scrolling on mouse leave.
517
518 <h4>Example</h4>
519
520 <pre class="lua">
521 SetLeaveStops(true)
522 </pre>
523
524 <a name="SetMaxOpenGLTexture"></a>
525 <h3>SetMaxOpenGLTexture(number)</h3>
526
527 <p>Limit the size of OpenGL textures. If the game is slower with
528 OpenGL than without it, try setting 1024, 512, or 256 as the limit.</p>
529
530 <p>Bos Wars asks OpenGL how large textures it supports, and then
531 splits all of its graphics into pieces of that size or smaller. In
532 some computers however, OpenGL reports support for e.g. 4096x4096
533 textures but draws those much slower than smaller ones. You can then
534 set a smaller limit with this function. The new limit takes effect
535 on the next InitVideo call.</p>
536
537 <p>If the parameter is 0, or greater than the limit reported by
538 OpenGL, then Bos Wars uses the OpenGL limit instead.</p>
539
540 <h4>Example</h4>
541
542 <pre class="lua">
543 SetMaxOpenGLTexture(512)
544 </pre>
545
546 <a name="SetMaxSelectable"></a>
547 <h3>SetMaxSelectable(number)</h3>
548
549 Set the maximum number of selectable units.
550
551 <dl>
552 <dt>number</dt>
553 <dd>The number of units to set the limit to.
554 (must be positive value)</dd>
555 <dt><i>RETURNS</i></dt>
556 <dd>The limit that was set.</dd>
557 </dl>
558
559 <h4>Example</h4>
560
561 <pre class="lua">
562 SetMaxSelectable(18)
563 </pre>
564
565 <a name="SetMinimapTerrain"></a>
566 <h3>SetMinimapTerrain(boolean)</h3>
567
568 for minimap with/without terrain.
569
570 <a name="SetMouseScroll"></a>
571 <h3>SetMouseScroll(boolean)</h3>
572
573 enable/disable mouse scrolling.
574
575 <a name="SetMouseScrollSpeedControl"></a>
576 <h3>SetMouseScrollSpeedControl(speed)</h3>
577
578 Sets the speed of the mouse scrolling while control is pressed.
579
580 <dl>
581 <dt>speed</dt>
582 <dd>Set the number of pixels to scroll per mouse move of 1 pixel. negative = reversed</dd>
583 <dt><i>RETURNS</i></dt>
584 <dd>Nothing</dd>
585 </dl>
586
587 <h4>Example</h4>
588
589 <pre class="lua">
590 -- Set Mouse speed to
591 SetMouseScrollSpeedControl(4)
592 </pre>
593
594 <a name="SetMouseScrollSpeedDefault"></a>
595 <h3>SetMouseScrollSpeedDefault(speed)</h3>
596
597 Sets the speed of the mouse scrolling while the middle mouse button is pressed.
598
599 <dl>
600 <dt>speed</dt>
601 <dd>Sets the number of pixels to scroll per mouse move of 1 pixel. negative = reversed</dd>
602 <dt><i>RETURNS</i></dt>
603 <dd>Nothing</dd>
604 </dl>
605
606 <h4>Example</h4>
607
608 <pre class="lua">
609 -- Set Speed Scroll to 5
610 SetMouseScrollSpeedDefault(5)
611 </pre>
612
613 <a name="SetSpeedBuild"></a>
614 <h3>SetSpeedBuild(number)</h3>
615
616 Decrease the time to build a unit by this factor.
617
618 <a name="SetSpeedTrain"></a>
619 <h3>SetSpeedTrain(number)</h3>
620
621 Decrease the time to train a unit by this factor.
622
623 <a name="SetSpeeds"></a>
624 <h3>SetSpeeds(number)</h3>
625
626 Set all speeds.
627 This is equivalent to
628
629 <pre class="lua">
630 SetSpeedBuild(number)
631 SetSpeedTrain(number)
632 </pre>
633
634 <a name="SetTitleScreens"></a>
635 <h3>SetTitleScreens({tag = value, ...}, ...)</h3>
636
637 Change the default title screens.<br>
638 <br>
639 Possible tags:
640
641 <dl>
642 <dt>Image = "filepath"</dt>
643 <dd>Image or video to be displayed as title screen, this is the first screen
644 displayed. The image should be a png file with 640x480 8-bit indexed colormap.
645 </dd>
646 <dt>Music = "filepath" or "none"</dt>
647 <dd>Optional music to be played with the image or video. Use "none" to stop
648 previously playing music.
649 </dd>
650 <dt>StretchImage = boolean</dt>
651 <dd>If true (default), stretch the image so it fills the screen,
652 possibly changing the aspect ratio.
653 If false, display the image in its original resolution
654 in the center of the screen.</dd>
655 <dt>Timeout = number</dt>
656 <dd>The number of seconds we should show this title-screen
657 if the user does not dismiss it first.
658 If zero (default), then the timeout is very long.</dd>
659 <dt>Label = { {Text = "text", Pos = {x, y}, Font = "font-name"}, ... }</dt>
660 <dd>Optional text to be displayed. It's a list of elements with three tags:
661 <dl>
662 <dt>Text = "text"</dt>
663 <dd>The text string to render.</dd>
664 <dt>Pos = {x, y}</dt>
665 <dd>The text coords to render.</dd>
666 <dt>Font = FIXME</dt>
667 <dd>Font to use.</dd>
668 <dt>Flags = {tag, ...}</dt>
669 <dd>The flags that tell us how should be interpretated the pos coords.
670 Possible and only value is "center".
671 </dd>
672 </dl>
673 </dd>
674 </dl>
675
676 <h4>Example</h4>
677
678 <pre class="lua">
679 -- This is the default title displayed.
680 SetTitleScreens(
681 {Image = "video/int_logo_stratagus.avi", Music = "video/int_logo_stratagus.ogg",
682 Label = {{Text = "~white~Copyright &#xa9; 1998-2003 The Stratagus Project. All rights reserved.",
683 Pos = {0, 45}, Flags = {"center"}}} },
684 {Image = "video/int_logo_bos.avi", Music = "video/int_logo_bos.ogg"})
685 </pre>
686
687 <a name="SetVideoFullScreen"></a>
688 <h3>SetVideoFullScreen(boolean)</h3>
689
690 Sets the video to full screen or windowed mode
691
692 <dl>
693 <dt>boolean</dt>
694 <dd>true or false for full screen</dd>
695 <dt><i>RETURNS</i></dt>
696 <dd>Nothing</dd>
697 </dl>
698
699 <h4>Example</h4>
700
701 <pre class="lua">
702 -- Set Fullscreen
703 SetVideoFullScreen(true)
704 </pre>
705
706 <a name="SetVideoResolution"></a>
707 <h3>SetVideoResolution(x, y)</h3>
708
709 <p>Sets the resolution of the video display (in full-screen mode)
710 or the size of the game window (in windowed mode).</p>
711
712 <p>The engine tries to support whatever resolution you specify.
713 However, at resolutions smaller than 640x480, some things might not
714 fit on the screen; and at resolutions greater than 1920x1200,
715 background images might not cover everything they should.</p>
716
717 <dl>
718 <dt>x</dt>
719 <dd>Resolution in x.</dd>
720 <dt>y</dt>
721 <dd>Resolution in y.</dd>
722 <dt><i>RETURNS</i></dt>
723 <dd>Nothing</dd>
724 </dl>
725
726 <h4>Example</h4>
727
728 <pre class="lua">
729 -- Set Screen res to 1024x768
730 SetVideoResolution(1024, 768)
731 </pre>
732
733 <a name="SetGroupKeys"></a>
734 <h3>SetGroupKeys("0123456789`")</h3>
735
736 <p>Define the keys to use for selecting groups of units. Those should
737 normally be the digit keys; however, at least the French AZERTY layout
738 requires pressing Shift to get digits, and the engine then might not
739 automatically recognize those keys as digit keys. In such cases, you
740 should use this function to tell the engine what characters the keys
741 generate without Shift.</p>
742
743 <p>On Windows, the default setting is reported to work correctly even
744 with an AZERTY keyboard.</p>
745
746 <p>On X11 with GNOME 3 and SDL 1.2.15, the default setting works if
747 the first keyboard layout (i.e. first XKB group) uses unshifted
748 digits, even if some other keyboard layout is active.</p>
749
750 <p>We hope SetGroupKeys will become unnecessary when the engine
751 is changed to use SDL 1.3 or 2.0. The engine should then be able
752 to recognize the digit keys from the scancodes provided by SDL.
753 This cannot be easily done with SDL 1.2, which may use different
754 scancodes for the same key on different operating systems or
755 different X servers.</p>
756
757 <p>There is no GetGroupKeys function. Lua scripts that call
758 SetGroupKeys should also save the new value of the setting
759 in <a href="#preferences">preferences</a> so that the engine
760 will save it to disk.</p>
761
762 <dl>
763 <dt>keys</dt>
764 <dd>The keys to use for selecting groups of units.
765 The string should consist of 11 characters.
766 The first ten characters are for groups 0, 1, 2, ... 9.
767 The last character is for unselecting all groups;
768 typically, this is the key on the left of the 1 key.
769 </dd>
770 </dl>
771
772 <h4>Example</h4>
773 For french azerty, use :
774
775 <!-- Use &quot; rather than a plain double-quotation mark so that
776 font-lock of GNU Emacs 23 won't think that the string ends
777 there and that a new string begins at the real end.
778 To browsers, it makes no difference. -->
779 <pre class="lua">
780 SetGroupKeys("&#xe0;&amp;&#xe9;\&quot;'(-&#xe8;_&#xe7;&#xb2;")
781 </pre>
782
783 <h2>Variables</h2>
784
785 <a name="AStarFixedUnitCrossingCost"></a>
786 <h3>AStarFixedUnitCrossingCost = integer</h3>
787
788 <p>Cost to move over a unit that is standing still.
789 (Must be greater than 3.)</p>
790
791 <p>The pathfinder generally computes the total cost of each movement
792 step (whether straight or diagonal) in this way: 1 + (either
793 AStarUnknownTerrainCost or the cost from the map patch) + (possibly
794 AStarFixedUnitCrossingCost or AStarMovingUnitCrossingCost). However,
795 there are exceptions for flying units, and for units that span
796 multiple map fields.</p>
797
798 <a name="AStarKnowUnseenTerrain"></a>
799 <h3>AStarKnowUnseenTerrain = boolean</h3>
800
801 <p>Whether the pathfinder treats unknown terrain as visible when
802 calculating paths or not. Setting AStarKnowUnseenTerrain = false will
803 increase the amount the pathfinder is used at the start of a game
804 while the map is being discovered. If you need the performance, set
805 it true.</p>
806
807 <a name="AStarMovingUnitCrossingCost"></a>
808 <h3>AStarMovingUnitCrossingCost = integer</h3>
809
810 <p>Cost to move over a unit that is moving to somewhere.
811 (Must be greater than 3.)</p>
812
813 <a name="AStarUnknownTerrainCost"></a>
814 <h3>AStarUnknownTerrainCost = integer</h3>
815
816 <p>Extra cost to move on unseen terrain, makes units tend towards
817 known areas when finding paths.</p>
818
819 <a name="AlliedUnitRecyclingEfficiency"></a>
820 <h3>AlliedUnitRecyclingEfficiency</h3>
821
822 <p>What percentage of resources you get back
823 when recycling your buildings or other
824 <a href="unittype.html#DefineUnitType.CanHarvestFrom">harvestable</a>
825 units of allied players.</p>
826
827 <p>The value of this variable is a table.
828 The indices of the table are resource type identifiers,
829 i.e. integers between 0 and <a href="#MaxCosts">MaxCosts</a>-1
830 (even though indices typically start from 1 in Lua).
831 The values of the table are the percentages.</p>
832
833 <h4>Example</h4>
834
835 <pre class="lua">
836 AlliedUnitRecyclingEfficiency[MagmaCost] = 42
837 </pre>
838
839 <a name="EnemyUnitRecyclingEfficiency"></a>
840 <h3>EnemyUnitRecyclingEfficiency</h3>
841
842 <p>What percentage of resources you get when recycling enemy
843 buildings.</p>
844
845 <p>The value of this variable is a table in the same format as
846 <a href="#AlliedUnitRecyclingEfficiency">AlliedUnitRecyclingEfficiency</a>.</p>
847
848 <a name="Preference"></a>
849 <h3>Preference</h3>
850
851 <p>This variable refers to an object that has the following properties:
852 <a href="#Preference.ShowAttackRange">ShowAttackRange</a>
853 <a href="#Preference.ShowReactionRange">ShowReactionRange</a>
854 <a href="#Preference.ShowSightRange">ShowSightRange</a>
855 <a href="#Preference.ShowOrders">ShowOrders</a>
856 </p>
857
858 <a name="Preference.ShowAttackRange"></a>
859 <h4>Preference.ShowAttackRange = boolean</h4>
860
861 <p>Whether to show the attack range of the selected unit as a red circle.
862 See the <a href="unittype.html#variable.AttackRange">AttackRange</a> variable.</p>
863
864 <p>Even if the ShowAttackRange, ShowReactionRange, and ShowSightRange
865 properties are false, the player can display the ranges by holding the
866 left mouse button for a moment. In any case, the game never shows
867 ranges if the player has selected more than one unit.</p>
868
869 <a name="Preference.ShowReactionRange"></a>
870 <h4>Preference.ShowReactionRange = boolean</h4>
871
872 <p>Whether to show the reaction range of the selected unit as a blue circle.
873 See the <a href="unittype.html#DefineUnitType.ComputerReactionRange">ComputerReactionRange</a>
874 and <a href="unittype.html#DefineUnitType.PersonReactionRange">PersonReactionRange</a>
875 parameters of DefineUnitType.</p>
876
877 <a name="Preference.ShowSightRange"></a>
878 <h4>Preference.ShowSightRange = boolean</h4>
879
880 <p>Whether to show the sight range of the selected unit as a green circle.
881 See the <a href="unittype.html#variable.SightRange">SightRange</a> variable.</p>
882
883 <a name="Preference.ShowOrders"></a>
884 <h4>Preference.ShowOrders = integer</h4>
885
886 <p>How long to show the orders of selected units on the map,
887 after the player gives an order. Measured in seconds.
888 If this is negative, or the player presses the Shift key,
889 then the engine shows the orders no matter how old they are.</p>
890
891 <a name="preferences"></a>
892 <h3>preferences</h3>
893
894 This table contains the user preferences that
895 <a href="#SavePreferences">SavePreferences</a> will save.
896 The engine does not otherwise interpret the contents of this table.
897 Instead, when the engine is starting up, a Lua script should read
898 the preferences from this table and pass each preference to the
899 appropriate function so that it takes effect.
900
901 <hr>
902 All trademarks and copyrights on this page are owned by their respective owners.
903 <address>(c) 2002-2007 by <a href="http://boswars.org">
904 The Bos Wars Project</a></address></body></html>