summaryrefslogtreecommitdiff
path: root/src/script/api
diff options
context:
space:
mode:
authoralberth <alberth@openttd.org>2015-01-04 15:14:13 +0000
committeralberth <alberth@openttd.org>2015-01-04 15:14:13 +0000
commit7023819d4978cd33b6c4af4d0e8d6a71319a1ebe (patch)
treeb5d88a3e1cbe4f69ca375e2c22f82453c1d87792 /src/script/api
parent4c19f93b342f45aac5040e9a73b4851d7058a5df (diff)
downloadopenttd-7023819d4978cd33b6c4af4d0e8d6a71319a1ebe.tar.xz
(svn r27111) -Doc: Extend script documentation with Save and Load functions.
Diffstat (limited to 'src/script/api')
-rw-r--r--src/script/api/script_controller.hpp68
1 files changed, 67 insertions, 1 deletions
diff --git a/src/script/api/script_controller.hpp b/src/script/api/script_controller.hpp
index 10fd48dcd..9bdbe9ab7 100644
--- a/src/script/api/script_controller.hpp
+++ b/src/script/api/script_controller.hpp
@@ -18,8 +18,32 @@
/**
* The Controller, the class each Script should extend. It creates the Script,
- * makes sure the logic kicks in correctly, and that GetTick() has a valid
+ * makes sure the logic kicks in correctly, and that #GetTick() has a valid
* value.
+ *
+ * When starting a new game, or when loading a game, OpenTTD tries to match a
+ * script that matches to the specified version as close as possible. It tries
+ * (from first to last, stopping as soon as the attempt succeeds)
+ *
+ * - load the exact same version of the same script,
+ * - load the latest version of the same script that supports loading data from
+ * the saved version (the version of saved data must be equal or greater
+ * than ScriptInfo::MinVersionToLoad),
+ * - load the latest version of the same script (ignoring version requirements),
+ * - (for AIs) load a random AI, and finally
+ * - (for AIs) load the dummy AI.
+ *
+ * After determining the script to use, starting it is done as follows
+ *
+ * - An instance is constructed of the class derived from ScriptController
+ * (class name is retrieved from ScriptInfo::CreateInstance).
+ * - If there is script data available in the loaded game and if the data is
+ * loadable according to ScriptInfo::MinVersionToLoad, #Load is called with the
+ * data from the loaded game.
+ * - Finally, #Start is called to start execution of the script.
+ *
+ * See also http://wiki.openttd.org/AI:Save/Load for more details.
+ *
* @api ai game
*/
class ScriptController {
@@ -46,6 +70,48 @@ public:
*/
void Start();
+#ifdef DOXYGEN_API
+ /**
+ * Save the state of the script.
+ *
+ * By implementing this function, you can store some data inside the savegame.
+ * The function should return a table with the information you want to store.
+ * You can only store:
+ *
+ * - integers,
+ * - strings,
+ * - arrays (max. 25 levels deep),
+ * - tables (max. 25 levels deep),
+ * - booleans, and
+ * - nulls.
+ *
+ * In particular, instances of classes can't be saved including
+ * ScriptList. Such a list should be converted to an array or table on
+ * save and converted back on load.
+ *
+ * The function is called as soon as the user saves the game,
+ * independently of other activities of the script. The script is not
+ * notified of the call. To avoid race-conditions between #Save and the
+ * other script code, change variables directly after a #Sleep, it is
+ * very unlikely, to get interrupted at that point in the execution.
+ * See also http://wiki.openttd.org/AI:Save/Load for more details.
+ *
+ * @note No other information is saved than the table returned by #Save.
+ * For example all pending events are lost as soon as the game is loaded.
+ *
+ * @return Data of the script that should be stored in the save game.
+ */
+ SquirrelTable Save();
+
+ /**
+ * Load saved data just before calling #Start.
+ * The function is only called when there is data to load.
+ * @param version Version number of the script that created the \a data.
+ * @param data Data that was saved (return value of #Save).
+ */
+ void Load(int version, SquirrelTable data);
+#endif /* DOXYGEN_API */
+
/**
* Find at which tick your script currently is.
* @return returns the current tick.