[Python] : SD-ToolKit

[Stone-D]

(Also posted on CivFanatics)

Well, for a start, it isn't something for a regular player to use, so if you're not a python modder, stop now.

During my python escapades, I've had cause to make a small number of global functions that I believe others will benefit from, especially end users. This is NOT a standalone mod. It is a python module that can be incorporated into other projects. The major function of this library allows modders to store data without conflicting with anything else.

I felt that this was something that needed to be addressed sooner or later.

The following is a brief API :


Basic Utilities
===============
sdEcho( string )
Outputs 'string' to the python debug log AND onto the screen.
Either output mode can be toggled using two boolean variables inside the function definition.

sdGetTimeInt( turn_int )
Converts a year string of the form "1234 AD" or "1234 BC" to an integer. BC is negative.

sdGameYearsInt()
Returns the total span of years a given game should last, irrespective of victory conditions.
Standard Firaxis gamespeeds cover exactly 6,050 total years, but others do not - for example, my SD-Glacial mod covers 6,200 years.


Data Storage
============
Internal Functions :
sdModInit( 'MyModName_string' )
Initializes a central reservoir of custom variables for your mod's use.
For internal use. You should not need to actively use this function.

sdModFixCase( 'MyModName_string', Mod_dictionary )
For internal use. You should not use this function.

sdModLoad( 'MyModName_string' )
Loads previously initialized data from the central reservoir.
For internal use. You should not need to actively use this function.

sdModSave( 'MyModName_string', Mod_dictionary )
Saves a mod's entire variable data to the central reservoir.
For internal use. You should not need to actively use this function.

MOD Functions :
sdEntityInit( 'MyModName_string', 'UniqueName_string', Entity_dictionary )
Initializes a unique data entity (city, unit, plot).
UniqueName_string = Any string used to indentify the entity, such as 'Alcatraz' or '5435' or 'Warrior55'
Entity_dictionary = A python dictionary containing the data set for the 'Entity', such as {'var1' : 56, 'var2' : 'My Rectum', 'var3' : [1, 2, 3]}

sdEntityWipe( 'MyModName_string', 'UniqueName_string' )
Removes an entity that has been previously initialized by sdEntityInit.
An entity can be anything that contains a set of data... a city, a unit or your dog's name. Use your imagination.

sdEntityExists( 'MyModName', 'UniqueName_string' )
Checks whether or not an entity has been initialized by sdEntityInit.
Returns bool False on failure, bool True on success.

sdGetVal( 'MyModName_string', 'UniqueName_string', 'VariableName_string' )
Fetches a specific variable's value from the entity's data set.
Will raise an exception on failure.

sdSetVal( 'MyModName_string', 'UniqueName_string', 'VariableName_string', any_value )
Stores a specific variable's value within the entity's data set.
Returns bool False on failure, bool True on success.

sdDelVal( 'MyModName_string', 'UniqueName_string', 'VariableName_string' )
Removes a specific variable from the entity's data set.
Returns bool False on failure, bool True on success.

sdGetGlobal( 'MyModName_string', 'GlobalVariableName_string' )
Fetches a specific variable's value from the mod's global data set, which is automatically initialized.
Will raise an exception on failure.

sdSetGlobal( 'MyModName_string', 'GlobalVariableName_string', any_value )
Stores a specific variable's value within the mod's global data set, which is automatically initialized.

sdDelGlobal( 'MyModName_string', 'GlobalVariableName_string' )
Removes a specific variable from the mod's global data set.
Returns bool False on failure, bool True on success.


To clarify, the saved data is stored with saved games and will be restored when a game is reloaded by the user. Saved data will not clash with other mods using this toolkit.


History
=-=-=-=

v1.00 :
Initial Release.

v1.10 :
BASIC-UTILITIES Addition : sdGetTimeInt( turn )
BASIC-UTILITIES Addition : sdGameYearsInt()
SD-DATA-STORAGE Addition : sdModFixCase( 'MyModName', Mod_dictionary )
SD-DATA-STORAGE Addition : sdEntityWipe( 'MyModName', 'UniqueName_string' )
Now checks for changed case in mod names.
Changed all defs so the leading characters are lower case.

v1.20 :
Some minor cleanups and optimizations.
Added comments to the functions with examples and descriptions.
SD-DATA-STORAGE Addition : sdEntityExists( 'MyModName', 'UniqueName_string' )
SD-DATA-STORAGE Addition : sdDelVal( 'MyModName', 'UniqueName_string', 'VariableName_string' )
SD-DATA-STORAGE Addition : sdGetGlobal( 'MyModName', 'GlobalVariableName' )
SD-DATA-STORAGE Addition : sdSetGlobal( 'MyModName', 'GlobalVariableName', any_value )
SD-DATA-STORAGE Addition : sdDelGlobal( 'MyModName', 'GlobalVariableName' )
Boolean return values added to some functions. See API section.

v1.21 :
Fixed a major bug in sdDelGlobal.

v1.22 :
Fixed another bug in sdDelGlobal.

[Xerxes712]

Can this store data for re-use upon a reload of a saved game?

IE This allows for storing variables data permentately instead of losing the data dynamically after I quite the game engine, but it stores the data with the savegame?

I hope that question makes sense.

[Stone-D]

Yep, it does make sense, and yep it does get saved. Here's some evidence, a pruned PythonDbg.log :

WBSave done

PY:Religion : 4000 BC : Christianity founded by Barbarians.
PY:Religion : Christianity tech given to Roman Empire.
PY:Religion : Christianity tech given to American Empire.
PY:Religion : Christianity tech given to Russian Empire.
PY:Religion : Christianity tech given to Barbarian State.
PY:Religion : 4000 BC : Holy City for Christianity set to Ghuzz.
PY:City Built Event: Washington
PY:City Built Event: Moscow
iTurn: 0

PY:Mod Data Initialized : SdCultureConquest True
PY:Entity Initialized : Washington
PY:Entity Initialized : Moscow
PY:Entity Initialized : Ghuzz
iTurn: 1

PY:OnPreSave
PY:City Ghuzz's culture has expanded
iTurn: 2

PY:Religion : 3904 BC : Holy City for Christianity NOT set. Founded 4000 BC.
PY:Ghuzz captured by Roman Empire. No unknown techs found.
PY:City Acquired Event: Ghuzz
PY:City Moscow's culture has expanded
iTurn: 3

PY:Conquest : Ghuzz (Barbarian) was captured by the Roman Empire.
PY:Conquest : Ghuzz Culture is 5 (WAS 15, 9 at capture)
PY:Conquest : Ghuzz has been captured 1 times.
PY:OnPreSave
PY:OnUnInit
UnInit Python


Initializing Python

PY:OnInit
load_module CvAppInterface
WBSave done

load_module CvGameInterface

PY:City Ghuzz's culture has expanded
iTurn: 2

PY:Ghuzz captured by Roman Empire. No unknown techs found.
PY:City Acquired Event: Ghuzz
PY:City Moscow's culture has expanded
iTurn: 3

PY:Conquest : Ghuzz (Barbarian) was captured by the Roman Empire.
PY:Conquest : Ghuzz Culture is 5 (WAS 15, 9 at capture)
PY:Conquest : Ghuzz has been captured 1 times.
PY:OnPreSave
PY:OnUnInit
UnInit Python

[PJayTycy]

Hmm, I'm interested to know more exactly how to save extra data in a save game.

[Stone-D]

The key is with using pickle and cramming everything into a single string buffer inside cygameinterface.

Note that units and citys also have this string buffer, but I discovered that the buffer for cities is reset upon capture, rendering it useless. Using the global one for everything is more elegant and more predictable.

Hence this module.

[Stone-D]

Just uploaded version 1.1. See the first post for details.

[Stone-D]

Just uploaded version 1.2. See the first post for details.

[Stone-D]

Uploaded 1.21, bugfix.

[Kinjiru]

Thank you for your efforts SD. Very nice of you to donate your hard work to the community.

[Stone-D]

Hehe, not much effort really. I'm really hoping the SDK makes this obsolete... but some attempt at forcing inter-mod compatibility has to be done or Civ is gonna go down as one of 'those' games. :P

[Stone-D]

Uploaded version 1.22, another bugfix. :P

[Gramphos]

Please submit this to the Python category in the directory.

http://apolyton.net/dir/index.php?cat=355&t=sub_pages

[Stone-D]

Gramphos: Done, but I have to say that the procedure is confusing and kind of encourages the laziness in people. It would be better if it was an all-in-one comprehensive submission form - upload the file and submit the 'link' at the time.

Also, I scoured the place looking for something like "Add Entry" "Submit Mod"... "Add Link" wasn't too intuitive. Many people will just give up at this point.

[Gramphos]

Posting a mod from the user frontend is easy compared to posting it from the admin pages. Especially if I am to try to add it as another user than myself.

[MarkG]

Originally posted by Stone-D
Also, I scoured the place looking for something like "Add Entry" "Submit Mod"... "Add Link" wasn't too intuitive. Many people will just give up at this point.

point taken