SD-ToolKit 1.22
by Stone-D ( Laga Mahesa )
For Civilization IV
Compatibility : 1.00+
Data Source   : 1.09
New Game Req  : N/A



Introduction
=-=-=-=-=-=-=
So what is this then?

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.


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.


Compatibility
=-=-=-=-=-=-=
This is intended to increase compatibility across various mods. I fully intend to make each new version backward compatible, but there are no promises. Should such an issue arise, I will let you know both in the readme and in the forums.


Merging with existing MODs
=-=-=-=-=-=-=-=-=-=-=-=-=-=
Wanna use this data in your MOD? Credit me prominently in your docs and any internal credit screens, that's it.


Contacting Me
=-=-=-=-=-=-=
Contact me at :  laga@tbi.co.id

I also have email addresses at yahoo, hotmail and gmail under the user lmahesa. However, I rarely remember to check them, so be prepared for a reply well after you've solved your issues yourself or no replies at all.

Also I occasionally dabble in the dark arts of Internet chatting. Usually Yahoo or MSN, mostly Yahoo.

Note though, I don't even vaguely understand German, Russian, Polynesian or Hindustani, so contact me in English please.  :)

Or Indonesian.  =|;'D


The Obligatory Disclaimer
=-=-=-=-=-=-=-=-=-=-=-=-=
Life being what it is at the moment for me, something is bound to happen. So :

You downloaded this.  You opened the zip.  You extracted the files.

You, and you alone are responsible.

If anything goes wrong, please tell me but in no way can you possibly consider me responsible.

I'm not MacDonalds you know.  ;)

Nor, for that matter, am I American, so you can't summarily sue me for ruining your gaming session. Nerrr!
