Debian Codegraph @

doc/scripts/savegame.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 <html><head>
3 <!--
4 ---- (c) Copyright 2004-2007 by 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: Save Game and Replay Files</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: Save Game and Replay Files</h1>
26 <hr>
27 <a href="../index.html">Bos Wars</a>
28 <a href="../faq.html">FAQ</a>
29 <a href="limits.html">PREV</a>
30 <a href="sound.html">NEXT</a>
31 <a href="index.html">LUA Index</a>
32 <hr>
33 <a href="#DefineAiPlayer">DefineAiPlayer</a>
34 <a href="#Log">Log</a>
35 <a href="#Missile">Missile</a>
36 <a href="#Player">Player</a>
37 <a href="#ReplayLog">ReplayLog</a>
38 <a href="#SaveGame">SaveGame</a>
39 <a href="#Selection">Selection</a>
40 <a href="#SetGroupId">SetGroupId</a>
41 <a href="#SlotUsage">SlotUsage</a>
42 <a href="#StratagusMap">StratagusMap</a>
43 <a href="#Unit">Unit</a>
44 <hr>
45 <h2>Intro - Introduction to saved games and replay logs</h2>
46
47 <p><b>Saved games</b> are Lua scripts that call the functions
48 described below. The engine generates calls to these functions when
49 it saves a game. When the saved game is loaded back, those calls
50 restore its state.</p>
51
52 <p><b>Replay logs</b> are Lua scripts to which the engine writes the
53 commands of human players during a game. You can later replay the
54 log and watch the game again. If a bug crashes the engine, the log
55 may help you reproduce the bug under a debugger or verify that it
56 has been fixed. The replay log does not contain any commands made
57 by AI players, because the engine assumes that the AI will behave
58 the same way each time the log is replayed. For that reason, replay
59 logs are typically not compatible between different versions.</p>
60
61 <h2>Functions</h2>
62
63 <a name="DefineAiPlayer"></a>
64 <h3>DefineAiPlayer(player-number, properties)</h3>
65
66 <p>Define an AI player. Saved games use this function;
67 map setup files should not.</p>
68
69 <dl>
70 <dt>player-number</dt>
71 <dd>
72 Number of the player, counting from 0.
73 </dd>
74 <dt>properties</dt>
75 <dd>
76 Properties of the AI player.
77 This list consists of tags and associated values.
78 These tags are available:
79 <dl>
80 <dt>"ai-type", string</dt>
81 <dd>
82 Identifier of the AI type. Matches the Ident field of the
83 table parameter of <a href="ai.html#DefineAiType">DefineAiType</a>.
84 </dd>
85 <dt class="obsolete">"script-debug", boolean</dt>
86 <dd class="obsolete">
87 <em>Obsolete since r5923 (2004-01-01):
88 The debug flag no longer affects the engine,
89 and scripts cannot read it.</em><br>
90
91 Whether to display the executed AI script commands.
92 The <a href="ai.html#AiDebug">AiDebug</a>
93 and <a href="ai.html#AiDebugPlayer">AiDebugPlayer</a>
94 functions also control this flag.
95 </dd>
96 <dt>"sleep-cycles", integer</dt>
97 <dd>
98 The number of the game cycle on which the AI will wake up
99 from <a href="ai.html#AiSleep">AiSleep</a>, or 0 if not sleeping.
100 </dd>
101 <dt>"force", {force, properties}</dt>
102 <dd>
103 Defines a group of units that should attack or defend together,
104 to overwhelm the enemy.
105 The value must be a list that contains two elements:
106 <dl>
107 <dt>force</dt>
108 <dd>
109 Number of the force. 0 - 9 is currently supported.
110 </dd>
111 <dt>properties</dt>
112 <dd>
113 Properties of the force.
114 This list consists of subtags and possibly values.
115 Some subtags do not allow a value and the others require a value.
116 These subtags are available:
117 <dl>
118 <dt>"complete"</dt>
119 <dd>
120 The force does not need more units.
121 This is the opposite of "recruit".
122 </dd>
123 <dt>"recruit"</dt>
124 <dd>
125 The force needs more units.
126 This is the opposite of "complete".
127 </dd>
128 <dt>"attack"</dt>
129 <dd>
130 The force is attacking.
131 </dd>
132 <dt>"defend"</dt>
133 <dd>
134 The force is defending a unit that was attacked.
135 After the enemies are dead, the force should return home.
136 </dd>
137 <dt class="obsolete">"role", string</dt>
138 <dd class="obsolete">
139 <em>Obsolete since r5923 (2004-01-01):
140 Roles of forces no longer affect the engine,
141 and scripts cannot read them.</em><br>
142 The role of the force, as set with
143 <a href="ai.html#AiForceRole">AiForceRole</a>.
144 </dd>
145 <dt>"types", {[count, unit-type-name]...}</dt>
146 <dd>
147 How many of each unit type should be in the force.
148 This is set with <a href="ai.html#AiForce">AiForce</a>.
149 </dd>
150 <dt>"units", {[unit-number, unit-type-name]...}</dt>
151 <dd>
152 List of units currently in the force.
153 The type names are ignored on load.
154 </dd>
155 <dt>"state", integer</dt>
156 <dd>
157 Attack state.
158 </dd>
159 <dt>"goalx", integer</dt>
160 <dd>
161 Attack point X tile map position.
162 </dd>
163 <dt>"goaly", integer</dt>
164 <dd>
165 Attack point Y tile map position.
166 </dd>
167 </dl>
168 </dd>
169 </dl>
170 <dt>"needed", {[resource-type-name, amount]...}</dt>
171 <dd>
172 FIXME
173 </dd>
174 <dt>"need-mask", {resource-type-name...}</dt>
175 <dd>
176 FIXME
177 </dd>
178 <dt>"last-can-not-move-cycle", integer</dt>
179 <dd>
180 FIXME
181 </dd>
182 <dt>"unit-type", {[unit-type-name, count]...}</dt>
183 <dd>
184 FIXME
185 </dd>
186 <dt>"building", {[unit-type-name, made, want]...}</dt>
187 <dd>
188 FIXME
189 </dd>
190 <dt>"repair-building", integer</dt>
191 <dd>
192 FIXME
193 </dd>
194 <dt>"repair-workers", {[building-unit-number, count]...}</dt>
195 <dd>
196 Number of workers that failed trying to repair a building.
197 </dd>
198 </dl>
199 </dd>
200 </dl>
201
202 <p>For an example of DefineAiPlayer, please look in any save file.
203 No example is provided in this document because Lua scripts for maps
204 should not call DefineAiPlayer.</p>
205
206 <a name="Log"></a>
207 <h3>Log()</h3>
208
209 <p>Parses a log entry and appends it to an internal list.
210 This function is used in both replay logs and saved games.</p>
211
212 <ul>
213 <li>Replay logs mainly consist of calls to the Log function. After
214 the engine has executed all of these calls, it starts actually
215 replaying the entries from the internal list.</li>
216 <li>Each saved game contains Log calls for all the log entries from
217 the beginning of the game to the time it was saved. When the game
218 is loaded, the engine copies these entries to a new replay log and
219 then begins appending any new entries to that. This way, the
220 replay log will start from the beginning of the game, even if the
221 game was saved and loaded multiple times.</li>
222 </ul>
223
224 <h4>Example</h4>
225
226 <pre class="lua">
227 Log({ GameCycle = 10420, UnitNumber = 252, UnitIdent = "unit-assault",
228 Action = "move", Flush = 1, PosX = 113, PosY = 104, SyncRandSeed = 614148735 })
229 </pre>
230
231 <a name="Missile"></a>
232 <h3>Missile(<var>tag</var>, <var>value</var>, <var>tag</var>, <var>value</var>, ...)</h3>
233
234 <p>Adds a missile on the map.</p>
235
236 <p>The function supports these tag-value pairs:</p>
237
238 <dl>
239 <dt>"type", <var>missile-type-name</var></dt>
240 <dd>The type of the missile. Declared with
241 <a href="magic.html#DefineMissileType">DefineMissileType</a>.</dd>
242 <dt>"local"</dt>
243 <dd>This missile is marked as local, and it's visible only to the player.
244 This is used for instance for cursor marks on the map.
245 The "local" tag is unusual in that no value follows it.
246 Either "local" or "global" must be specified.</dd>
247 <dt>"global"</dt>
248 <dd>This missile is marked as global, and it's visible to all players.
249 The "global" tag is unusual in that no value follows it.
250 Either "local" or "global" must be specified.</dd>
251 <dt>"pos", {<var>x</var>, <var>y</var>}</dt>
252 <dd>The current position of the missile.
253 Coordinates are in pixels, not tiles.
254 For example: "pos", {4500, 3450}</dd>
255 <dt>"origin-pos", {<var>x</var>, <var>y</var>}</dt>
256 <dd>The starting position of the missile.
257 Coordinates are in pixels, not tiles.
258 For example: "origin-pos", {4505, 3455}</dd>
259 <dt>"goal", {<var>x</var>, <var>y</var>}</dt>
260 <dd>The position of the missile's destination.
261 Coordinates are in pixels, not tiles.
262 For example: "goal", {4510, 3460}</dd>
263 <dt>"frame", <var>integer</var></dt>
264 <dd>Current sprite frame of the missile; complicated behavior.
265 A negative <var>integer</var> generally means the actual
266 frame number is -1 - <var>integer</var> and the sprite
267 should be mirrored in the X direction; but the effect depends
268 on <a href="magic.html#DefineMissileType.Flip">the Flip parameter
269 of DefineMissileType</a>.</dd>
270 <dt>"state", <var>integer</var></dt>
271 <dd>Current state of the missile. Used for a simple state machine,
272 dependand on the missile class.</dd>
273 <dt>"anim-wait", <var>integer</var></dt>
274 <dd>FIXME: Document this.</dd>
275 <dt>"wait", <var>integer</var></dt>
276 <dd>Wait this number of game cycles until the next state or animation
277 of this missile is handled. This counts down from
278 <a href="magic.html#DefineMissileType.Sleep">the Sleep parameter
279 of DefineMissileType</a> to 0.</dd>
280 <dt>"delay", <var>integer</var></dt>
281 <dd>Number of game cycles left until the missile is first shown on the map.
282 Please see <a href="magic.html#DefineMissileType.Delay">Delay in DefineMissileType</a>.</dd>
283 <dt>"source", <var>unit-reference-string</var></dt>
284 <dd>Number of the owner of the missile. Normally the one who fired the missile.
285 Used to check units, to prevent hitting the owner. Also used for kill and
286 experience points, and for giving the owning player score.</dd>
287 <dt>"target", <var>unit-reference-string</var></dt>
288 <dd>Number of the missile's target. Normally the unit which should be
289 hit by the missile.</dd>
290 <dt>"damage", <var>integer</var></dt>
291 <dd>Damage done by missile. Units next to it can receive some reduced splash
292 damage, this is the full damage.</dd>
293 <dt>"ttl", <var>integer</var></dt>
294 <dd>Time to live in game cycles of the missile, if it reaches zero
295 the missile is automatically removed from the map. If -1 the
296 missile lives for ever and the lifetime is handled by other means.</dd>
297 <dt>"hidden"</dt>
298 <dd>This marks the missile as hidden, until the
299 <a href="magic.html#DefineMissileType.Class">missile class</a>
300 decides to show it again.
301 The "hidden" tag is unusual in that no value follows it.</dd>
302 <dt>"step", {<var>current-step-integer</var>, <var>total-step-integer</var>}</dt>
303 <dd>The progress of the missile along its movement path.
304 Generally, <var>current-step-integer</var> starts
305 from zero when the missile is launched, and it then
306 increases until it reaches <var>total-step-integer</var>,
307 at which point the missile hits its target.
308 <a href="magic.html#DefineMissileType.Speed">The Speed parameter
309 of DefineMissileType</a> is the rate of increase,
310 and the value of <var>total-step-integer</var> is the distance
311 between the source and the target.
312 However, some missile classes may use these values differently.</dd>
313 </dl>
314
315 <h4>Example</h4>
316
317 <pre class="lua">
318 Missile("type", "missile-small-fire", "global", "pos", {1168, 1960}, "origin-pos", {1168, 1960}, "goal", {-16, -24},
319 "frame", 0, "state", 0, "anim-wait", 0, "wait", 8, "delay", 0,
320 "source", "U003B", "damage", 0, "ttl", -1, "step", {0, 0})
321 </pre>
322
323 <a name="Player"></a>
324 <h3>Player()</h3>
325
326 Used when loading games.
327
328
329 <h4>Example</h4>
330
331 <pre class="lua">
332 Player(0,
333 "name", "Player",
334 "type", "person", "ai-name", "ai-spacious",
335 "team", 2, "enemy", "_XXX_____", "allied", "_________", "shared-vision", "_________",
336 "start", {19, 19},
337 "production-rate", {"energy", 414, "magma", 174,},
338 "stored-resources", {"energy", 600000, "magma", 120000,},
339 "storage-capacity", {"energy", 600000, "magma", 120000,},
340 "ai-disabled",
341 "unit-limit", 200, "building-limit", 200, "total-unit-limit", 400,
342 "score", 18730,
343 "total-units", 48,
344 "total-buildings", 79,
345 "total-resources", {23339092, 9312165,},
346 "total-razings", 69,
347 "total-kills", 219,
348 "color", { 0, 0, 164 })
349 </pre>
350
351 <a name="ReplayLog"></a>
352 <h3>ReplayLog()</h3>
353
354 <p>Describes how the game was started.
355 This function is used in both replay logs and saved games.</p>
356
357 <ul>
358 <li>When replaying a log, the engine starts a new game in the same
359 way.</li>
360 <li>When loading a saved game, the engine copies this information
361 to a new replay log.</li>
362 </ul>
363
364 <h4>Example</h4>
365
366 <pre class="lua">
367 ReplayLog( {
368 Comment1 = "Generated by Bos Wars Version 2.6.0",
369 Comment2 = "Visit http://www.boswars.org for more information",
370 Comment3 = "&#36;Id: replay.cpp 9589 2009-05-30 18:09:56Z jim4 &#36;",
371 Date = "Sun Mar 21 21:26:57 2010",
372 Map = "Four against four on the island.",
373 MapPath = "maps/4on4.map/presentation.smp",
374 MapId = 444351,
375 Type = 1,
376 LocalPlayer = 0,
377 Players = {
378 { Name = "Player", Team = -1, Type = -1 },
379 { Name = "Computer", Team = -1, Type = -1 },
380 { Name = "Computer", Team = -1, Type = -1 },
381 { Name = "Computer", Team = -1, Type = -1 },
382 { Name = "Neutral", Team = -1, Type = -1 },
383 { Name = "Neutral", Team = -1, Type = -1 },
384 { Name = "Neutral", Team = -1, Type = -1 },
385 { Name = "Neutral", Team = -1, Type = -1 },
386 { Name = "Neutral", Team = -1, Type = -1 }
387 },
388 Resource = 3,
389 NumUnits = -1,
390 Difficulty = 3,
391 NoFow = false,
392 RevealMap = 0,
393 GameType = -1,
394 Opponents = -1,
395 MapRichness = -1,
396 Engine = { 2, 6, 0 },
397 Network = { 2, 6, 0 }
398 } )
399 </pre>
400
401 <a name="SaveGame"></a>
402 <h3>SaveGame({SyncHash = x, SyncRandSeed = y, SaveFile = "file"})</h3>
403
404 Basic outline of the savegame, include hashs for syncrand and where to load
405 the rest of the game information from when loading. More information is planed
406 for implementation, but currently only the above are used.
407
408 <dl>
409 <dt>SyncHash = x</dt>
410 <dd>integer setting the Hash of the current game for Sync Purposes</dd>
411 <dt>SyncRandSeed = y</dt>
412 <dd>integer of the next value to be used when calling SyncRand</dd>
413 <dt>SaveFile = "file"</dt>
414 <dd>String containing the name of the file to load to get the rest of the gamedata</dd>
415 </dl>
416
417 <h4>Example</h4>
418
419 <pre class="lua">
420 SaveGame({
421 --- "comment", "Generated by Stratagus Version 2.0",
422 --- "comment", "Visit http://Stratagus.Org for more informations",
423 --- "type", "single-player",
424 --- "date", "Mon May 10 19:19:38 2004",
425 --- "map", "",
426 --- "media-version", "Undefined"--- "engine", {2, 0, 0},
427 SyncHash = 196009203,
428 SyncRandSeed = -220040269,
429 SaveFile = "data.wc2//campaigns/human/level13h.cm"
430
431 --- "preview", "/home/devil/.stratagus/wc2/save/current-game.sav.pam",
432 } )
433 </pre>
434
435 <a name="Selection"></a>
436 <h3>Selection(numselected, unit0, ...)</h3>
437
438 Define the current selection.
439
440
441 <dl>
442 <dt>numselected</dt>
443 <dd>How many units are selected.
444 </dd>
445 <dt>unitX</dt>
446 <dd>slot number of the unit to add in the selection.
447 </dd>
448 </dl>
449
450 <h4>Example</h4>
451
452 <pre class="lua">
453 Selection(1, 0)
454 </pre>
455
456 <a name="SetGroupId"></a>
457 <h3>SetGroupId(id)</h3>
458
459 Set the current group id. (Needed for load/save).
460
461
462 <dl>
463 <dt>id</dt>
464 <dd>new group id.
465 </dd>
466 </dl>
467
468 <h4>Example</h4>
469
470 <pre class="lua">
471 SetGroupId(0)
472 </pre>
473
474 <a name="SlotUsage"></a>
475 <h3>SlotUsage(MaxSlot, [{Slot = Slot1, FreeCycle = Freecycle1}, ..])</h3>
476
477 Allows reloaded Save games to be replayed in sync by reloading the released
478 units back into the queue they were in when a game was saved.
479 <dl>
480 <dt>MaxSlot</dt>
481 <dd>The total Number of slot used.</dd>
482 <dt>Slot</dt>
483 <dd>The Slot Number for the unit that was in the release Queue</dd>
484 <dt>FreecCycle</dt>
485 <dd>The Cycle that this unit is/was released in</dd>
486 </dl>
487
488 <h4>Example</h4>
489
490 <pre class="lua">
491 SlotUsage(5, {2, 855})
492 </pre>
493
494 <a name="StratagusMap"></a>
495 <h3>StratagusMap(...)</h3>
496
497 <p>The state of the map, without units.
498 Much of this information is redundant with the map setup file.
499 However, the StratagusMap call also carries information on which parts of
500 the map each player has explored; that is of course not in the map setup.</p>
501
502 <a name="Unit"></a>
503 <h3>Unit()</h3>
504
505 Needed to save/load games.
506
507 <h4>Example</h4>
508
509 <pre class="lua">
510 Unit(0, "type", "unit-vault", "player", 0,
511 "tile", {116, 120}, "refs", 6, "stats", 0,
512 "pixel", {0, 0}, "seen-pixel", {0, 0}, "frame", 1, "not-seen", "direction", 0,
513 "attacked", 0,
514 "current-sight-range", 4, "seen-by-player", "X_______________",
515 "seen-destroyed", "________________",
516 "seen-state", 0, "active", "mana", 0, "hp", 1800, "xp", 0, "kills", 0,
517 "ttl", 0, "bloodlust", 0, "haste", 0, "slow", 0,
518 "invisible", 0, "flame-shield", 0, "unholy-armor", 0,
519 "HitPoints", {Value = 1800, Max = 1800, Increase = 0, Enable = true},
520 "Mana", {Value = 0, Max = 0, Increase = 0, Enable = false},
521 "Transport", {Value = 0, Max = 0, Increase = 0, Enable = true},
522 "Training", {Value = 0, Max = 0, Increase = 0, Enable = true},
523 "Resource", {Value = 0, Max = 0, Increase = 0, Enable = true},
524 "group-id", 0,
525 "last-group", 0,
526 "value", 0,
527 "sub-action", 0, "wait", 2, "state", 2,
528 "blink", 0, "rs", 35, "units-boarded-count", 0,"order-count", 1,
529 "order-flush", 0,
530 "order-total", 4,
531 "orders", {
532 {"action-still", "flags", 0, "range", 0, "width", 0, "height", 0, "min-range", 0, "tile", {-1, -1},},
533 {"action-none", "flags", 0, "range", 0, "width", 0, "height", 0, "min-range", 0, "tile", {0, 0},},
534 {"action-none", "flags", 0, "range", 0, "width", 0, "height", 0, "min-range", 0, "tile", {0, 0},},
535 {"action-none", "flags", 0, "range", 0, "width", 0, "height", 0, "min-range", 0, "tile", {0, 0},},},
536 "saved-order",
537 {"action-still", "flags", 0, "range", 0, "width", 0, "height", 0, "min-range", 0, "tile", {-1, -1},},
538 "new-order",
539 {"action-still", "flags", 0, "range", 0, "width", 0, "height", 0, "min-range", 0, "tile", {-1, -1},}
540 )
541 </pre>
542
543 <hr>
544 All trademarks and copyrights on this page are owned by their respective owners.
545 <address>(c) 2002-2007 by <a href="http://boswars.org">
546 The Bos Wars Project</a></address></body></html>