From 0888f7691d8abfb9859db5e9c0fafb5a624ed5d4 Mon Sep 17 00:00:00 2001
From: mr-russ <>
Date: Fri, 4 Jun 2004 13:10:57 +0000
Subject: [PATCH] Added savegame.html for function relating to only savegame
internals.
Began adding functions and descriptions that are in the code that are
not in the documentation. Still many to go.
---
doc/scripts/game.html | 61 ++++++++++++++++++++
doc/scripts/index.html | 5 ++
doc/scripts/research.html | 2 +-
doc/scripts/savegame.html | 118 ++++++++++++++++++++++++++++++++++++++
doc/scripts/sound.html | 2 +-
5 files changed, 186 insertions(+), 2 deletions(-)
create mode 100644 doc/scripts/savegame.html
diff --git a/doc/scripts/game.html b/doc/scripts/game.html
index 63702ffc2..25b69611f 100644
--- a/doc/scripts/game.html
+++ b/doc/scripts/game.html
@@ -89,8 +89,10 @@
<a href="#SetDefaultMap">SetDefaultMap</a>
<a href="#SetDiplomacy">SetDiplomacy</a>
<a href="#SetGameCycle">SetGameCycle</a>
+<a href="#SetGameName">SetGameName</a>
<a href="#SetGamePaused">SetGamePaused</a>
<a href="#SetGroupId">SetGroupId</a>
+<a href="#SetLocalPlayerName">SetLocalPlayerName</a>
<a href="#SetObjectives">SetObjectives</a>
<a href="#SetSharedVision">SetSharedVision</a>
<a href="#SetThisPlayer">SetThisPlayer</a>
@@ -99,6 +101,7 @@
<a href="#ShowMapLocation">ShowMapLocation</a>
<a href="#SharedVision">SharedVision</a>
<a href="#SlotUsage">SlotUsage</a>
+<a href="#SyncRand">SyncRand</a>
<a href="#Unit">Unit</a>
<a href="#Units">Units</a>
<hr>
@@ -1036,6 +1039,24 @@ Set the current game cycle number.
SetGameCycle(100)
</pre>
+<a name="SetGameName"></a>
+<h3>SetGameName("name")</h3>
+
+Sets the name of the game so savegames, maps, settings and logs can be set
+differently for different games used.
+
+<dl>
+<dt>"name"</dt>
+<dd>The name the game has for loading and saving files</dd>
+</dl>
+
+<h4>Example</h4>
+
+<pre>
+ -- Set Name to bos, ~/.stratagus/bos is location of files
+ SetGameName("bos")
+</pre>
+
<a name="SetGamePaused"></a>
<h3>SetGamePaused(paused)</h3>
@@ -1073,6 +1094,24 @@ Pause or unpause the game.
SetGroupId()
</pre>
+<a name="SetLocalPlayerName"</a>
+<h3>SetLocalPlayerName("name")</h3>
+
+Sets the name of the player playing on this computer. Also saved in
+preferences, and a default used when the game is started.
+
+<dl>
+<dt>"name"</dt>
+<dd>The name of the player, limited to 16 characters"</dd>
+</dl>
+
+<h4>Example</h4>
+
+<pre>
+ -- Set Player Name to mr-russ
+ SetLocalPlayerName("mr-russ")
+</pre>
+
<a name="SetObjectives"></a>
<h3>SetObjectives(objective [objective ...])</h3>
@@ -1239,6 +1278,28 @@ Show an area on the map for the given player.
SlotUsage()
</pre>
+<a name="SyncRand"></a>
+<h3>SyncRand(number)</h3>
+
+Get a value from the Stratagus syncronized random number generator.
+Used to allow the AI to make syncronized choices with multiplayer, and
+during replays.
+
+<dl>
+<dt>number<dt>
+<dd>Number to create random from, eg 10 will return a number from 0-9</dd>
+</dl>
+
+<h4>Example</h4>
+
+<pre>
+ if(SyncRand(10) < 5) then
+ -- Do this
+ else
+ -- Do that
+ end
+</pre>
+
<a name="Unit"></a>
<h3>Unit()</h3>
diff --git a/doc/scripts/index.html b/doc/scripts/index.html
index 8cc22c8c7..cdea4b96c 100644
--- a/doc/scripts/index.html
+++ b/doc/scripts/index.html
@@ -52,6 +52,7 @@
<a href="magic.html">Magic</a>
<a href="pud.html">PUD</a>
<a href="research.html">Research</a>
+<a href="savegame.html">SaveGame</a>
<a href="sound.html">Sound</a>
<a href="tileset.html">Tileset</a>
<a href="triggers.html">Triggers</a>
@@ -484,8 +485,12 @@
<dd></dd>
<dt><a href="game.html#StratagusMap">StratagusMap</a></dt>
<dd></dd>
+<dt><a href="game.html#SyncRand">SyncRand</a></dt>
+<dd></dd>
<dt><a href="game.html#Unit">Unit</a></dt>
<dd></dd>
+<dt><a href="savegame.html#UnitAllocQueue">UnitAllocQueue</a></dt>
+<dd></dd>
<dt><a href="unittype.html#UnitType">UnitType</a></dt>
<dd></dd>
<dt><a href="unittype.html#UnitTypeArray">UnitTypeArray</a></dt>
diff --git a/doc/scripts/research.html b/doc/scripts/research.html
index bbea3b7fb..57dc6dc79 100644
--- a/doc/scripts/research.html
+++ b/doc/scripts/research.html
@@ -44,7 +44,7 @@
<a href="../faq.html">FAQ</a>
<a href="ccl.html">CCL</a>
<a href="pud.html">PREV</a>
-<a href="sound.html">NEXT</a>
+<a href="savegame.html">NEXT</a>
<a href="ccl-index.html">Index</a>
<hr>
<a href="#CheckDependency">CheckDependency</a>
diff --git a/doc/scripts/savegame.html b/doc/scripts/savegame.html
new file mode 100644
index 000000000..b9b9da674
--- /dev/null
+++ b/doc/scripts/savegame.html
@@ -0,0 +1,118 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html><head>
+<!--
+---- (c) Copyright 2004 by Russell Smith
+
+---- This program is free software; you can redistribute it and/or modify
+---- it under the terms of the GNU General Public License as published by
+---- the Free Software Foundation; only version 2 of the License.
+----
+---- This program is distributed in the hope that it will be useful,
+---- but WITHOUT ANY WARRANTY; without even the implied warranty of
+---- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+---- GNU General Public License for more details.
+----
+---- You should have received a copy of the GNU General Public License
+---- along with this program; if not, write to the Free Software
+---- Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
+---- 02111-1307, USA.
+-->
+ <title>Stratagus Configuration Language Description: Save Game Files</title>
+ <meta http-equiv="Content-Type" content="text/html; CHARSET=iso-8859-1">
+ <meta name="Author" content="johns98@gmx.net">
+ <meta name="Keyword" content="ccl,tileset">
+ <meta name="Description" content="">
+</head>
+<body>
+ <h1>Stratagus Configuration Language Description: Triggers</h1>
+<hr><pre width=80>
+ _________ __ __
+ / _____// |_____________ _/ |______ ____ __ __ ______
+ \_____ \\ __\_ __ \__ \\ __\__ \ / ___\| | \/ ___/
+ / \| | | | \// __ \| | / __ \_/ /_/ > | /\___ \
+ /_______ /|__| |__| (____ /__| (____ /\___ /|____//____ >
+ \/ \/ \//_____/ \/
+ ______________________ ______________________
+ T H E W A R B E G I N S
+ Stratagus - A free fantasy real time strategy game engine
+</pre>
+<p><b>(C) Copyright 2002-2003 by The Stratagus Project. Distributed under the
+<a href="../gpl.html">"GNU General Public License"</a></b>
+<hr>
+<a href="../stratagus.html">Stratagus</a>
+<a href="../readme.html">Readme</a>
+<a href="../faq.html">FAQ</a>
+<a href="ccl.html">CCL</a>
+<a href="research.html">PREV</a>
+<a href="sound.html">NEXT</a>
+<a href="ccl-index.html">Index</a>
+<hr>
+<a href="#SaveGame">SaveGame</a>
+<a href="#UnitAllocQueue">UnitAllocQueue</a>
+<hr>
+<h2>Intro - Introduction to savegame functions and variables</h2>
+
+Everything around save games. All of the functions below are primarily used
+in the creation and loading of saved games.
+<h2>Functions</h2>
+
+<a name="SaveGame"></a>
+<h3>SaveGame({SyncHash = x, SyncRandSeed = y, SaveFile = "file"})</h3>
+
+Basic outline of the savegame, include hashs for syncrand and where to load
+the rest of the game information from when loading. More information is planed
+for implementation, but currently only the above are used.
+
+<dl>
+<dt>SyncHash = x</dt>
+<dd>integer setting the Hash of the current game for Sync Purposes</dd>
+<dt>SyncRandSeed = y</dt>
+<dd>integer of the next value to be used when calling SyncRand</dd>
+<dt>SaveFile = "file"</dt>
+<dd>String containing the name of the file to load to get the rest of the gamedata</dd>
+</dl>
+
+<h4>Example</h4>
+
+<pre>
+SaveGame({
+--- "comment", "Generated by Stratagus Version 2.0",
+--- "comment", "Visit http://Stratagus.Org for more informations",
+--- "comment", "$Id$",
+--- "type", "single-player",
+--- "date", "Mon May 10 19:19:38 2004",
+--- "map", "",
+--- "media-version", "Undefined"--- "engine", {2, 0, 0},
+ SyncHash = 196009203,
+ SyncRandSeed = -220040269,
+ SaveFile = "data.wc2//campaigns/human/level13h.cm"
+
+--- "preview", "/home/devil/.stratagus/wc2/save/current-game.sav.pam",
+} )
+</pre>
+
+<a name="UnitAllocQueue"></a>
+<h3>UnitAllowQueue([Slot, x, FreeCycle, y]... )</h3>
+
+Allows reloaded Save games to be replayed in sync by reloading the released
+units back into the queue they were in when a game was saved.
+<dl>
+<dt>x</dt>
+<dd>The Slot Number for the unit that was in the release Queue</dd>
+<dt>y</dt>
+<dd>The Cycle that this unit is/was released in</dd>
+</dd>
+</dl>
+
+<h4>Example</h4>
+
+<pre>
+ -- No Units in the Released Tail queue when saving
+ UnitAllowQueue();
+</pre>
+
+<hr>
+Last changed: $Id$<br>
+All trademarks and copyrights on this page are owned by their respective owners.
+<address>(c) 2002-2004 by <a href="http://stratagus.org">
+The Stratagus Project</a></address></body></html>
diff --git a/doc/scripts/sound.html b/doc/scripts/sound.html
index 4d4e6b344..7ce008bd2 100644
--- a/doc/scripts/sound.html
+++ b/doc/scripts/sound.html
@@ -43,7 +43,7 @@
<a href="../readme.html">Readme</a>
<a href="../faq.html">FAQ</a>
<a href="ccl.html">Scripts</a>
-<a href="research.html">PREV</a>
+<a href="savegame.html">PREV</a>
<a href="tileset.html">NEXT</a>
<a href="ccl-index.html">Index</a>
<hr>