An object designed to flexibly store and retrieve numbers and strings very quickly use key/value pairs.
In addition to any Entity having its own unique DataManager via Entity::Data a global one is always available through GameLogic::Data as well.
Data is persistant automatically, ie, saved between sessions. There are no size limits and lookups are extremely fast. (Internally, a binary search tree is used)
Using the Entity Properties Editor, you can also add/remove/modify data from within editor, in addition to normal script access.
| DataManager | An object designed to flexibly store and retrieve numbers and strings very quickly use key/value pairs. |
| Storing Data | |
| Set | |
| SetNum | |
| SetIfNull | |
| SetNumIfNull | |
| Retrieving Data | |
| Get | |
| GetNum | |
| GetNumWithDefault | |
| GetWithDefault | |
| Miscellaneous | |
| Exists | |
| ModNum | |
| Delete | |
| Clear |
boolean Set(string keyName, string value)
Store a string as a named piece of data to be retrieved later. Replaces data by this key name if it already exists.
| keyName | Any name you wish. |
| value | A string of any length with the text/data that you wish to store. |
True if a new piece of data was created, false if existing data was replaced.
boolean SetNum(string keyName, number num)
Similar to Set but saves the data as a number which saves space and is faster to access internally.
When <Get>is used with a number (instead of GetNum) it is automatically converted into a string.
Decimal points are ok to use. The accuracy maintained is that of a C “float”.
| keyName | Any name you wish. |
| num | The number you wish to store. |
True if a new piece of data was created, false if existing data was replaced.
string SetIfNull(string keyName, string value)
Similar to Set but stores the data only if the key didn’t already exist.
| keyName | Any name you wish. |
| value | The string data you wish to store. |
String that was set, or existed before.
number SetNumIfNull(string keyName, number value)
Similar to Set but stores the data only if the key didn’t already exist.
Like <Data:SetIfNull> but hints that we want it stored as a number, not a string.
| keyName | Any name you wish. |
| value | The number you wish to store. |
Returns the number that was set or existed before.
string Get(string keyName)
Retrieve a previously stored value by its key name.
| keyName | The key-name used when it was stored. |
The data in string form or a blank string if the key wasn’t found. Use Exists to verify if a key exists or not.
number Get(string keyName)
Like Get but returns the data as a number. If the data was stored as a number, this is the fastest way to access it.
If the data was stored as a string, an attempt to convert it to a number is made.
| keyName | The key-name used when it was stored. |
The number that was stored.
number GetNumWithDefault(string keyName, number defaultValue)
Like Get but allows you to also set the default data if the key doesn’t exist yet.
| keyName | The key-name used when it was stored. |
| defaultValue | If the key doesn’t exist, it will be created with this value. (this value will be returned as well) |
The value that was stored or created.
number GetWithDefault(string keyName, string defaultValue)
Like Get but allows you to also set the default data if the key doesn’t exist yet.
| keyName | The key-name used when it was stored. |
| defaultValue | If the key doesn’t exist, it will be created with this value. (this value will be returned as well) |
The value that was stored or created.
boolean Exists(string keyName)
| keyName | The key name used when it was stored. |
True if data with this key name exists.
number Exists(string keyName, number modAmount)
Modifies an existing key by a number. Creates the key if it didn’t exist.
//set hitpoints to 100
this:Data():SetAsNum("life", 100);
//remove 5
local curHitpoints = this:Data():ModNum("life", -5);
LogMsg("I only have " .. curHitpoints .. " hitpoints!");
| keyName | The key name used when it was stored. |
| modAmount | How much the number should be changed by. |
The new number that was stored.