T2D Tutorial using TorqueDB

Well here is tutorial with some steps on using the Torque DB resource I submitted in Torque 2D, if you choose to do so :)

first go to here and download the file attached ... or just grab the file from here

unzip the file into your example/T2D/cleint folder... (or in the folder you plan to use this in)

there will be a database folder with all the .cs files for TorqueDB... you only have to exec TorqueDB.cs to get it working though. There also should be a journal folder (which has the files for the journal example specified in the resource)

also a journalData folder is added... inside this folder is an example of the file outputs... journal.txt and config.txt are the encrypted versions... The copies are the plain text versions of the same file :) (note: the encryption is extremely simple lol)

now open up your client.cs and include the following exec line after the others

exec("./database/TorqueDB.cs");

save it and go to your new "database" folder ...

open up file.cs and change

torqueDBPath = "starter.fps/data/journalData/";

to

torqueDBPath = "T2D/client/journalData/";

that way it knows to load and save data into that folder

save the file.cs

now run T2D.exe... bring up the console with the "tilde" ~ key and type this command in

TorqueDB.debugInfo();

you should see something like this


if not retrace the steps :) Or ask for help lol

you can see the data loaded in the Torque db in the journal.txt in the format of config.txt... it parses config.txt first and then uses that to parse journal.txt... all dynamically set up



Ok... so lets start fresh

type these two commands in the console

TorqueDB.deleteClass("entry");
TorqueDB.deleteClass("item");

to delete the two classes

run this command to see the results

TorqueDB.debugInfo();

now it should be empty, besides $journalArrayCount... that was originally planned to be a total count of all actions entered, but pretty much stopped using it, lol... for internal uses it can be a reference number of maximum entries



[/b]Ok so we have a blank database now[/b]

Lets start adding info. First lets create an item table. That way we can have a basic table with all the items, there value, name, power, stats, whatever we want


to create a class you need to know three things... first the class name... lol ok thats simple enough ;) "item"... ok now we need a property to start out with... this should be something unique to each item... another simple one "name"... as long as we ensure we don't do duplicate names, right now it won't warn you if you do, though I could add functionality for that pretty simple (or you can do a quick search to check also, but we'll talk about "searching" later)...

ok so we have
class - "item"
property - "name"

the third thing is the first "instance" (or "entry") into this table... so we need to pass an "item" "name"... lets do "rod of death"
ok so create this class/table like this

TorqueDB.writeClass("item", "name", "rod of death");

you should get some echos, like this

CLASS RETURNED = 0
adding a basic instance
creating object

don't worry about those, I haven't tweaked console output completely yet.

now type

TorqueDB.debugInfo();

(as you can tell you'll be using that command a lot, I set it up to spit out all the DB info you'll need)

you should see something like this


ok, so what does all these numbers mean ?

$journalMainTags is the array that indexes the table names... as you can see we have $journalMainTags[0] equal to "item" now

$journalSubTags is a two dimensional scriptObject array that stores the properties for the classes... or you can think of them as "columns" for the "table". Since we only have one property to display it displays it...
the first 0 represents the class number, in this case its the first class so its "0"... the second represents the property number, its the first property so its "0" too
$journalSubTags.contents[0].contents[0] is equal to "name"... the one property we've added. The only limit on ammount of properties is 100 I beleive, though I might've fixed even that limit in the code, though most likely you won't need 100 properties. Feel free to test that limit and send me the results, that way I can take it off (not too much hassle taking off the limit if I haven't already).

ok now we have $mainValueArray... this keeps track of how many instances/entries are in one class/table... since we only have one instance in one class the "0" value is set to 1.

ok now we're at $subValueArray
this is the meat of the DB, a three dimensional array

the first number represents the class, the second represents the instance, the third represents the property...

so at 0,0,0 we have the "name" of our first instance... "rod of death"...

go to the original resource link to see some diagrams that I have that explains this layout a little better :)...

now on to "VARIABLES"

$journalArrayCount can be pretty much ignored... later I may get it working right, but this was originally meant as a max count to use in reference to the DB, every time a class/property/instance is stored it adds a count, though since then I've added specific counts to keep track of it better (theoretically it could still be used if you need an absolute "max" number possible, though off the top of my head I don't know why you couldn't use specific counts).

$mainTagCount keeps track of the classes/tables

$subTagCount is an array that keeps track of each classes/tables properties/columns...


ok so we have an "item" class (I will refer to it as class - since thats what I named it internally- though it is closer to a table), with one instance (it is closer to a table "entry" though again what I used internally so will refer to it as that, plus easier to relate to game data)... and one property (same as a column in a table)... just storing a name isn't too great, not too much use, so lets store some other info that we might want to look up when searching for the name... its an item class, so value should work well.

run this command to add the "value" property to the "item" class

(note: think of "write" commands as "add" commands, originally this was meant for a journal system so I labeled the functions "write"... though it also makes sense for a database)

TorqueDB.writeProperty("item", "value");

then run our friendly little "TorqueDB.debugInfo();" function... (*fortunately Torque keeps track of our recent commands so you can use your up arrow to get to this function again without typing*)

you should see something like this


under $journalSubTags we now have "value"... also notice our $subTagCount[0] is now equal to 2 :)

ok, so we have the property added to the class, but how do we write it to the instance... how do we set the "rod of death"'s actual "value"... you can use the "writePropertyValue" command... though there is more to this than the other functions... since we are writing an instances property value we need a way to pick the instance to write to... usual that "unique" property I mentioned is best, so "name" is a good reference...

so we want to write the "value" to (say) "500" of an instance in class "item" with property "name" equal to "rod of death"... we do that like this

TorqueDB.writePropertyValue("item", "name", "rod of death", "value", "500");

ok thats a lot of info but it is needed to write the correct values in the right place... you can create easier functions to access this one later, maybe that'll be the next tutorial ;)

now run our good "TorqueDB.debugInfo();" function again and you should see this


as you can see this sets the items value to "500"... ok... so we have name and value... not bad for now... lets add another item, this "rod of death" is getting pretty boring...

lets add another "item" with the "name" "staff of power"...

TorqueDB.addInstance("item", "name", "staff of power");

ok lets run debuInfo again

you should see something like this


here you can see the DB at work... 0 0 0 of the $subValueArray is "rod of death"... 0 1 0 is "staff of power"... I've tested this with 1000 entries in game (using a special way to add instances at once) as well as up to 100,000 entries out of game (this was running on Torque 3D)... look at the script files for examples of every function... look specifically at the "addInstance" function under write.cs... I have two ways to mass add items by passing it special info, I have full examples there :)

ok so now we have two items, lets try and save our info... type this command

TorqueDB.dumpFile();

now you should see your console spam with a bunch of uneeded info, its the very simple encryption working... normall you wouldn't want to see this, to turn debug messages off you would set

$debugMsg::journalDebug = false;

though right now for testing purposes and tutorial purposes I had it trigger on by default

go to your "T2D/client/journalData/" folder and open the "journal.txt" file

you should see this

<mknz5fk9>
-ryvsk95f=46wu5n wue0 5n5fvsnz0k
-59vsjzds5f=irgaga
</mknz5fk9>
<mknz5fk9>
-ryvsk95f=ginzvse0e0 wue0 8owu275f46
</mknz5fk9>

this is the encrypted info... I have included a function to dump files to plain text :) Even better you can modify the plain text and re-load that info back into the DB by editing the text file. so lets run this command

TorqueDB.dumpPlainFile();

now open the "journalPLAIN.txt" file

you should see this

<item>
-name=rod of death
-value=500
</item>
<item>
-name=staff of power
</item>

much more readable...

ok change

-name=rod of death

to

-name=sword of death

ok now go back to your console and type

TorqueDB.loadPlainFile();

again because the debug messages are turned on you will get a lot of spam from the parser lol :)

now if you do "TorqueDB.debugInfo();" you should see this


the name was loaded from the text file you changed :) pretty cool huh? Well you fellow data junkies might think so at least lol... now what you might be thinking is "can you add instances like that too?" If not then I thought it for you... the answer is yes... go back to your journalPLAIN.txt and add a couple entries to make it look like this

<item>
-name=sword of death
-value=500
</item>
<item>
-name=staff of power
</item>
<item>
-name=battle axe
-value=345
</item>
<item>
-name=Cleaver
-value=678
</item>
<item>
-name=Bow
-value=298
</item>

save it off and run "TorqueDB.loadPlainFile();" again

if you do debugInfo you should see this


it added all the info... very cool, so you can populate your data from a simple text file, load it in, and even save it back out encrypted... Now if you think this is cool then your really going to like this part... not only can you add instances etc in html/xml like syntax... you can added entire classes and properties too!... TorqueDB parses a file to parse a file (yeah that was a headache to script =/). Take a look at "configPLAIN.txt"

you should see this

<item>
-name
-value
</item>

thats the class you created. ok lets add another property... how about weight?

change the file too look like this

<item>
-name
-value
-weight
</item>

now go back to your journalPLAIN.txt file and add weight to a couple items... like this

<item>
-name=sword of death
-value=500
-weight=5.6
</item>
<item>
-name=staff of power
-weight=2.3
</item>
<item>
-name=battle axe
-value=345
-weight=8.9
</item>
<item>
-name=Cleaver
-value=678
-weight=2.8
</item>
<item>
-name=Bow
-value=298
-weight=1.7
</item>

make sure you save your files... and run the "TorqueDB.loadPlainFile();" command agian
run "TorqueDB.debugInfo();" and scroll up just a little and you should see this!


works like a charm :) Now that is pretty cool... ok lets have a little fun, see if we can confuse this little script creation I spawned, switch the order of the properties in journalPLAIN.txt! maybe like this

<item>
-name=sword of death
-weight=5.6
-value=500
</item>
<item>
-weight=2.3
-name=staff of power
</item>
<item>
-value=345
-weight=8.9
-name=battle axe
</item>
<item>
-name=Cleaver
-weight=2.8
-value=678
</item>
<item>
-weight=1.7
-name=Bow
-value=298
</item>

save the file and close it... now run "TorqueDB.loadPlainFile();"
run a debugInfo and this is what you should get


bah, smart little bugger aint it ;) now ensure you closed the "journalPLAIN.txt" file (and the config file too) and run this command "TorqueDB.dumpPlainFile();"

go back and open your "journalPLAIN.txt" file... and its all neat and clean again.

<item>
-name=sword of death
-value=500
-weight=5.6
</item>
<item>
-name=staff of power
-weight=2.3
</item>
<item>
-name=battle axe
-value=345
-weight=8.9
</item>
<item>
-name=Cleaver
-value=678
-weight=2.8
</item>
<item>
-name=Bow
-value=298
-weight=1.7
</item>

ok so far pretty cool... well it gets better... open up configPLAIN.txt again...
it should look like this

<item>
-name
-value
-weight
</item>

lets create a whole new class from text... lets call it "playerInventory" ... give it some properties... "slotNum" and "objectName"

so make your config file look like this

<item>
-name
-value
-weight
</item>
<playerInventory>
-slotNum
-objectName
</playerInventory>

save the config file and run "TorqueDB.loadPlainFile();"... then do a debugInfo();

scroll up a little and you should see this!


the class was added :) Also note that even though we are doing this through the text file the counters still keep accurate counts :)

ok go to your journalPLAIN.txt file and add some objects to player inventory... like this

<item>
-name=sword of death
-value=500
-weight=5.6
</item>
<item>
-name=staff of power
-weight=2.3
</item>
<item>
-name=battle axe
-value=345
-weight=8.9
</item>
<item>
-name=Cleaver
-value=678
-weight=2.8
</item>
<item>
-name=Bow
-value=298
-weight=1.7
</item>
<playerInventory>
-slotNum=0
-objectName=sword of death
</playerInventory>
<playerInventory>
-slotNum=1
-objectName=Cleaver
</playerInventory>

save the file and run "TorqueDB.loadPlainFile();"... then do a debugInfo();

you should see something like this... it added the isntances to the new class :)




Ok now you might be able to see how we can build systems with the DB and even reference eachother... right now if you searched for the "objectName" of "slotNum" "1" in "playerInventory" it would return "Cleaver" which then can be used to search for its item data... in fact, lets do that.

First we want to get the contents of slotNum 1... there are a bunch of search functions I've added (look in search.cs to see examples of every one in comments)... I have it so you can search by class, property, and even a couple "multiple" searches for properties... those would come in handy if you have more than one entry of a same value, for example if you had three items with a value of "500" and you wanted to search for all items with a "value" of 500, it would return all of those in a scriptObject array :). For now we just want it to return the one value though so do this

(There are two functions that would return the same value... .searchByProperty and .searchByPropertyWithClass... it is recommended you use the "WithClass" version since it saves processing power, but if you don't know the class then you can use the other one)

the function is laid out like this

TorqueDB.searchByPropertyWithClass(class, referenceProperty , referenceValue, PropertyToReturn);

$obj = TorqueDB.searchByPropertyWithClass("playerInventory", "slotNum", "1", "objectName");

now do this

echo($obj);

you should see this


so we got the object in slot 1... if it doesn't find the object matching your inquiry it will return a -1 so you can compare your searches against that... again look in search.cs under the database folder for all the searches with detailed examples

now we could even reference that value to get the objects "value" in a search on the "item" class/table... do this

$value = TorqueDB.searchByPropertyWithClass("item", "name", $obj, "value");

then

echo($value);

you should see something like this



ok one last thing in this tutorial (maybe I'll create a tutorial later on setting up entire systems using this, though you can get the idea)...

there is a TorqueDB.dumpHTMLFile(); function... which saves the database in a nifty little table in html so you can look at it easier... give it a shot then go to your journalData/ folder and check out the html file!

Well hope you enjoyed it, hopefully you can get some use out of TorqueDB... I've spent a lot of time scripting it... there are lots more functions to be used, check out the duplicate.cs... I've commented the script with examples for them all.

- Matthew "King Tut BoB" Langley