Persisting data (Civ5) - Revision history

DonQuich at 12:12, 25 September 2012

2012-09-25T12:12:31Z

← Older revision		Revision as of 12:12, 25 September 2012
Line 45:		Line 45:


	== Addressing performances problems ==		= Addressing performances problems =
	The {{Type5\|ModData}} you get is implemented through a database table. This means that every value read/write will generate a request string, this one will have to be parsed, etc. If you frequently read or write values, this can greatly hinder the game's performances.		The {{Type5\|ModData}} you get is implemented through a database table. This means that every value read/write will generate a request string, this one will have to be parsed, etc. If you frequently read or write values, this can greatly hinder the game's performances.

DonQuich at 12:12, 25 September 2012

2012-09-25T12:12:03Z

← Older revision		Revision as of 12:12, 25 September 2012
Line 4:		Line 4:
	This article explains how to store data that are persisted when the user saves his game, or at anytime for mods settings.		This article explains how to store data that are persisted when the user saves his game, or at anytime for mods settings.

	== Opening or creating a storage space ==		= Opening or creating a storage space =

	Mods can store data in the following containers:		Mods can store data in the following containers:
Line 25:		Line 25:


	== Using the storage space ==		= Using the storage space =
	=== Get or set value ===		=== Get or set value ===
	Once you retrieve a {{Type5\|ModData}} instance, this one exposes the following methods:		Once you retrieve a {{Type5\|ModData}} instance, this one exposes the following methods:
Line 110:		Line 110:


	== Alternatives ==		= Alternatives =

	=== Using the script data (mostly deprecated) ===		=== Using the script data (mostly deprecated) ===

DonQuich at 11:07, 24 September 2012

2012-09-24T11:07:29Z

← Older revision		Revision as of 11:07, 24 September 2012
Line 148:		Line 148:

	[[Category:Civ5 API]]		[[Category:Civ5 API]]
			[[Category:Civ5 Tutorials]]

DonQuich at 10:52, 24 September 2012

2012-09-24T10:52:44Z

← Older revision		Revision as of 10:52, 24 September 2012
Line 37:		Line 37:
	=== Dealing with default values ===		=== Dealing with default values ===
	Since it is not possible to know whether the value you just did read already existed before, you need to deal with the default nil values you will encounter. Here are some examples:		Since it is not possible to know whether the value you just did read already existed before, you need to deal with the default nil values you will encounter. Here are some examples:
	<~~pre~~>		<div class="civ5-example"><syntaxhighlight lang="lua">
	local db = Modding.OpenSaveData()		local db = Modding.OpenSaveData()
	local trueByDefault = db.GetValue("trueByDefault") ~= "false" -- False if "false", true otherwise		local trueByDefault = db.GetValue("trueByDefault") ~= "false" -- False if "false", true otherwise
	local falseByDefault = db.GetValue("falseByDefault") == "true" -- True if "true", false otherwise		local falseByDefault = db.GetValue("falseByDefault") == "true" -- True if "true", false otherwise
	local oneByDefault = db.GetValue("oneByDefault") or 1 -- 1 if nil or false, the value otherwise		local oneByDefault = db.GetValue("oneByDefault") or 1 -- 1 if nil or false, the value otherwise
	</~~pre~~>		</syntaxhighlight></div>


Line 50:		Line 50:
	=== Using a local cache ===		=== Using a local cache ===
	Dealing with the reads is pretty easy, we only need to create a local copy of the properties, as demonstrated in the G&K scenarios. Instead of calling {{Func5\|ModData\|GetValue}} and {{Func5\|ModData\|SetValue}} directly, we will use the following wrappers:		Dealing with the reads is pretty easy, we only need to create a local copy of the properties, as demonstrated in the G&K scenarios. Instead of calling {{Func5\|ModData\|GetValue}} and {{Func5\|ModData\|SetValue}} directly, we will use the following wrappers:
	<~~pre~~>		<div class="civ5-example"><syntaxhighlight lang="lua">
	g_SaveData = Modding.OpenSaveData()		g_SaveData = Modding.OpenSaveData()
	g_Properties = {}		g_Properties = {}
Line 66:		Line 66:
	g_Properties[name] = value		g_Properties[name] = value
	end		end
	</~~pre~~>		</syntaxhighlight></div>


Line 75:		Line 75:
	* No identity preservation: if a sub-table is stored twice in the provided table, it will be deserialized as two different tables.		* No identity preservation: if a sub-table is stored twice in the provided table, it will be deserialized as two different tables.
	* It has not been tested, there may be errors.		* It has not been tested, there may be errors.
	<~~pre~~>		<div class="civ5-example"><syntaxhighlight lang="lua">
	function ToLuaCode(item)		function ToLuaCode(item)
	if type(item) == "nil" then return "nil" end		if type(item) == "nil" then return "nil" end
Line 102:		Line 102:
	return g_Properties[name]		return g_Properties[name]
	end		end
	</~~pre~~>		</syntaxhighlight></div>

	=== Just-in-time writes ===		=== Just-in-time writes ===
Line 125:		Line 125:

	Here is an example where we store magic points for some units (untested):		Here is an example where we store magic points for some units (untested):
	<~~pre~~>		<div class="civ5-example"><syntaxhighlight lang="lua">
	-- Create table if not already done on mod loading		-- Create table if not already done on mod loading
	if not GetPersistentProperty("MyMod_initialized") then		if not GetPersistentProperty("MyMod_initialized") then
Line 144:		Line 144:
	DB.Query(query)		DB.Query(query)
	end		end
	</~~pre~~>		</syntaxhighlight></div>


	[[Category:Civ5 API]]		[[Category:Civ5 API]]

DonQuich at 15:02, 22 September 2012

2012-09-22T15:02:55Z

← Older revision		Revision as of 15:02, 22 September 2012
Line 118:		Line 118:
	* Those data are shared between mods so this is a frequent cause of conflicts.		* Those data are shared between mods so this is a frequent cause of conflicts.
	* There were more of those "SetScriptData" methods in the past, on other objects, but they have been removed on May 2012 by Firaxis. It is possible that Firaxis also removes the last three ones at a later point.		* There were more of those "SetScriptData" methods in the past, on other objects, but they have been removed on May 2012 by Firaxis. It is possible that Firaxis also removes the last three ones at a later point.
			* Users interested in this solution should give a look at the [http://forums.civfanatics.com/showthread.php?t=392958 SaveUtils] library from Whys.


	=== Using a custom table ===		=== Using a custom table ===
	If you want you may use a custom data table, although it has few advantages. It's not very convenient and if you were using it to store one row at once, you would encounter the same performances problems as {{Type5\|ModData}}. However writing one or thousands of values at once in a data table makes small difference in the execution time so you could use it for batch updates and get good results. This can be an alternative to the table persistence method explained before. This can be done through <code>DB.{{Func5\|DB\|Query}}('''variant''' data).</code>.		If you want you may use a custom data table, although it has few advantages. It's not very convenient and if you were using it to store one row at once, you would encounter the same performances problems as {{Type5\|ModData}}. However writing one or thousands of values at once in a data table makes small difference in the execution time so you could use it for batch updates and get good results. This can be an alternative to the table persistence method explained before. This can be done through <code>DB.{{Func5\|DB\|Query}}('''variant''' data)</code>. Users interested in this solution should also give a look at the [http://forums.civfanatics.com/showthread.php?t=442249 TableSaverLoader] library from Pazyryk.

	Here is an example where we store magic points for some units (untested):		Here is an example where we store magic points for some units (untested):

DonQuich: moved Persistent data storage (Civ5) to Persisting data (Civ5)

2012-09-22T13:03:35Z

moved Persistent data storage (Civ5) to Persisting data (Civ5)

← Older revision	Revision as of 13:03, 22 September 2012
(No difference)

DonQuich at 12:33, 22 September 2012

2012-09-22T12:33:39Z

← Older revision		Revision as of 12:33, 22 September 2012
Line 105:		Line 105:

	=== Just-in-time writes ===		=== Just-in-time writes ===
	The ~~local described in the~~ previous ~~section~~ unfortunately ~~does~~ not address the ~~long write times~~. A good idea in theory would be to detect when the user is going to save his game so that you only write data at this point. Unfortunately there is no event for this circumstance and while it is possible to hijack the "quicksave" hotkey and the "save" menu, '''this creates a whole bunch of incompatibilities with other mods'''. Use it in last resort. If you want to see an implementation example, look at the R.E.D. WWII mod.		The previous tricks unfortunately do not address the problem entirely if you need frequent writes (for example anytime a unit moves). A good idea in theory would be to detect when the user is going to save his game so that you only write data at this point. Unfortunately there is no event for this circumstance and while it is possible to hijack the "quicksave" hotkey and the "save" menu, '''this creates a whole bunch of incompatibilities with other mods'''. Use it in last resort. If you want to see an implementation example, look at the R.E.D. WWII mod.

	Another alternative is to use custom tables, as described in the next section.		Another alternative is to use custom tables, as described in the next section.

DonQuich at 12:31, 22 September 2012

2012-09-22T12:31:07Z

← Older revision		Revision as of 12:31, 22 September 2012
Line 104:		Line 104:
	</pre>		</pre>

	=== ~~Last~~-~~chance~~ writes ===		=== Just-in-time writes ===
	The local described in the previous section unfortunately does not address the long write times. A good idea in theory would be to detect when the user is going to save his game so that you only write data at this point. Unfortunately there is no event for this circumstance and while it is possible to hijack the "quicksave" hotkey and the "save" menu, '''this creates a whole bunch of incompatibilities with other mods'''. Use it in last resort. If you want to see an implementation example, look at the R.E.D. WWII mod.		The local described in the previous section unfortunately does not address the long write times. A good idea in theory would be to detect when the user is going to save his game so that you only write data at this point. Unfortunately there is no event for this circumstance and while it is possible to hijack the "quicksave" hotkey and the "save" menu, '''this creates a whole bunch of incompatibilities with other mods'''. Use it in last resort. If you want to see an implementation example, look at the R.E.D. WWII mod.

DonQuich at 12:30, 22 September 2012

2012-09-22T12:30:39Z

← Older revision		Revision as of 12:30, 22 September 2012
Line 117:		Line 117:
	* Strings are retrieved through Player:{{Func5\|Player\|GetScriptData}}, Plot:{{Func5\|Plot\|GetScriptData}}, and Unit:{{Func5\|Unit\|GetScriptData}}		* Strings are retrieved through Player:{{Func5\|Player\|GetScriptData}}, Plot:{{Func5\|Plot\|GetScriptData}}, and Unit:{{Func5\|Unit\|GetScriptData}}
	* Those data are shared between mods so this is a frequent cause of conflicts.		* Those data are shared between mods so this is a frequent cause of conflicts.
	* ~~Many~~ of those "SetScriptData" methods have been removed on May 2012. It is possible that Firaxis also ~~remove those~~ last ~~methods~~ at a later point.		* There were more of those "SetScriptData" methods in the past, on other objects, but they have been removed on May 2012 by Firaxis. It is possible that Firaxis also removes the last three ones at a later point.

DonQuich at 12:20, 22 September 2012

2012-09-22T12:20:52Z

← Older revision		Revision as of 12:20, 22 September 2012
Line 103:		Line 103:
	end		end
	</pre>		</pre>


	=== Last-chance writes ===		=== Last-chance writes ===