Datablock Analogy

#1 The factory is kinda a good analogy. I should mention that if you later change a field on a datablock all objects created with that datablock will also inherit the change, unless the value on the object is different from that on the datablock. Also, you technically do create one instance of each datablock.

Other than that, either of those anagogies are fine.

#2 I usually like to think of datablocks as "sets of referenced data". Instead of duplicating this data the data is referenced via the datablock, that way you can share values as well as change a single data block and have it effect multiple objects.

#3 @ Thomas / Matthew:

Thanks a lot for pointing that out! That's a huge [important] point that really breaks the analogies to pieces. That was actually something I didn't know... nice!

Back to the drawing board, I guess...

Hmm....

#4 You can look at a datablock as a set of information (table of contents kind of) in a wiki.

Your objects are assigned a "link" to a datablock, and if you have 10 soldiers, they all are given the same link to the same datablock.

If someone goes and changes the information contained in the datablock wiki entry, then the soliders would all change as well, since all they have is the link, not the actual data.

NOTE: There are issues with even this analogy, because you shouldn't ever change values within a datablock as normal practice, but it underlines what Thomas and Matt said above.

#5 @Stephen: [Y]ou shouldn't ever change values within a datablock as normal practice...

Why? When would it be appropriate?

#6 In TGE and TGEA, datablocks are used mainly to pipe sets of data across the network. This is not the case with TGB. In TGB they are used exclusively as templates for creating objects with certain pre-defined values.

In a networked game in TGE/TGEA, if you change a value in a datablock it will generally only affect your local objects and not the ones on the other clients. I suspect this is why Stephen said you should never change datablock values.

In TGB it's perfectly reasonable to change a value in a datablock to affect a series of objects, as long as you're sure that you want all subsequent objects created with that datablock to reflect those changes. Still, in many cases it might be more appropriate to change the values on the objects themselves.

#7 Thanks for the clarification Thomas. That makes a lot of sense and is kind of the way I thought things worked.

So essentially there's nothing magical about Datablocks: their fields are just accessible from any other object that uses them. Interesting.

But what do you mean by "in many cases it may be more appropriate to change the values on the objects themselves"? Can you override Datablock-inherited values on a per-object basis? Or do you mean creating a differently-named variable for the desired dynamism? Or...?

#8 Any time you change a datablock initialized variable on the object itself, you will only be affecting the value on that object. It won't change anything in the datablock. Datablock values are not "just accessible from any other object that uses them." Datablock values are only accessible through a handle on the datablock itself. Objects have a view of this data which can be overridden. This quote from Thomas above is a reference to this behavior:

Quote:
I should mention that if you later change a field on a datablock all objects created with that datablock will also inherit the change, unless the value on the object is different from that on the datablock.

#9 That, too, is good to know. Thanks a lot, Ben!

So essentially the Datablock is a common pool of Data that objects can be aware of as long as they don't have their own versions of the data.

So a Datablock is kind of like a public library where each object can access a book that the library has. If someone writes something in the margins of one of the books (or overwrites it completely) then all objects are aware of that change. However, each object can also have their own copy of the book in their personal library and any modifications made to those books are not recognized by anyone visiting the public library. Objects prefer to look in their personal libraries before going to the public library because, well, they're lazy.

The networking side could be expressed by having a chain of libraries. New town? New public library that's a copy of the original town library. Any change made to the new public library, however, is not understood by the original... Unless a message is specifically sent back to the librarian, of course.

Better?

#10 Sorry man, those analogies don't a single one sound anything like datablocks to me ;) Sometimes with programming constructs you just have to try to understand them and analogies don't work. Think of recursion. Try explaining the difference between head and tail recursion to someone with no programming background. Watch their blank stare. Now try coming up with some analogy for it. Watch them pass out and blood start to drip from their nose...

#11 Funny that you say that! I'm going to attempt explaining tail-recursion in the fading tutorial I'm writing right now (possibly... we'll see if I can pull anything out of my behind or not).

As for Datablocks, my understanding of them has greatly expanded thanks to this discussion so it hasn't been a waste of time. I can see how they work within the TorqueScript language/framework now [err... I think]. The Library analogy might be stretching it a bit but it makes pretty good sense. Is there somewhere I've mistaken something in the analogy?

By the way, do we have access to a formal TorqueScript Language Definition document at all? Because... you know, that'd be nice...

#12 Yeah, a datablock is more like having a few pages of your favorite book that you have personally overwritten and every time you get the book from the library you tape your own copies of those few pages over the copies of the ones in the book. Also the book can be checked out of the library by every person in town at the same time. Additionally you restrict every person to only being able to check out one book at any given time. Plus you can write in the margin of a book you didn't check out but someone else did. Are you starting to see why these kinds of analogies don't really hold up? No, I agree it is not a wasted discussion, but the analogy can't really be pushed that far.

#13 Can you clarify these three points for me:

1) The book can be checked out of the library by every person in town at the same time.
2) You restrict every person to only being able to check out one book at any given time.
3) You can write in the margin of a book you didn't check out but someone else did.

My understanding/interpretation is as follows:

1) The datablock can be referenced by every object in the game simultaneously.
2) Objects are restricted to referencing no more than one datablock at any given time.
2b) If that's the case, objects can change the datablock to which they are associated?
3) An object can write to a datablock, even if it doesn't reference that datablock.

The point is not to make a 1:1 mapping of analogy:reality. The point is to find a foundation from which you can establish a basic understanding. From there, the learning comes in discovering the differences between the analogy and the reality. Were I to begin a tutorial on Datablocks I would probably start with something like the Library analogy (well, currently).

Also, Datablocks are objects within the Torque Engine. The Torque Engine is single-threaded so, yes, only one object can "check out" the datablock at a time. Many objects can simultaneously want the datablock or claim it as their "favorite" but they won't be looking at it at the same time. Even when another object that doesn't reference the datablock changes it, no other objects are simultaneously reading it.

I could try to explain Datablocks without an analogy but it would fall back on dry computer science terms. My understanding of them would lead me to start out with something like "Datablocks are objects whose member fields are inserted into the member fields of other objects upon reference/association with several (simple yet implicating) stipulations."

Here's another question: if I modify a Datablock, how does that modification get 'synched' with the objects that reference it? I've come to understand that an object can locally overwrite a variable it originally received from a Datablock. How, then, would you ask for the Datablock version? Or... would you have shot yourself in the foot by locally overwriting it?

This has been incredibly educational. Thanks for all the help thus far!

#14 I am coming into this late and am already suffering from analogy overload but let me throw my two cents in.

Think of the datablock more as an electronic book (to further dilute the analogy). I can easily make as many copies of the book as I want.

An object requests a copy of the ebook and now it ihas its own copy.

The object can make all the changes it wants to the ebook but it only effects its copy of the book.

When second object requests a copy of the ebook it get the copy of the orignal book not the one with the changes that the first object made.

An object under normal circumstances cannot change the original copy only its own copy.

Ok with that layed out lets see if we can address your other questions.

1) Yes. Everyone in town can get a copy because it is easy to replicate.
2) Yes. An object can only get data from 1 datablock (AFAIK i need to play with that)
3) No. The object has a copy and can only change its copy.

Part Duex
1) Yes potentially every object could get a copy (key word copy not a reference to the original) of the datablock.
2 ) See 2 above
2b) Yes and No. They can change their copy of the datablock not the original.
3) No. Under normal circumstances an object cannot change the original. There are ways to update the datablock, but the object that already has a copy won't recieve those changes without reinitializing it.

The dry cs version.

1) A datablock is an object class with all the fields (no methods) of the baseclass of the type of datablock you define (in my example below the datablock has all of the fields that a t2dSceneObject would have.
2) When a datablock is created it is treated as an object in TGB.
3) When an object uses a datablock it inherits the fields defined in the datablock. It works the same as any class inheritance.
4) A datablock is a shortcut for populating common fields in objects.

Some code. This is a datablock I am using in one of my projects.

datablock t2dSceneObjectDatablock(ringDatablock) {
	 	class = "ring";
		imageMap = "particles6ImageMap";
		frame = "1";
		canSaveDynamicFields = "1";
                                position = "0 0";
                                ringNum = "0";
                                ringRotation = "0";
		Layer = "15";
		UseMouseEvents = "1";
		blendColor = "1 1 1 0.25";
		linkList = "";
           };

//Then when I use the datablock in my object
%ring = new t2dStaticSprite("ring" @ %ringNum) {
                sceneGraph = $MYSCENE;
                Config = "ringDatablock";
		size = %ringDia SPC %ringDia;
		position = %ringPosition;
		ringNum = %ringNum;
		rotation = %ringRotation;
	    };

You can see that when I create my object I am overriding the position, ringNum and rotation I defined in the datablock.
Position and rotation are standard fields in a t2dStaticSprite object, ringNum is a dynamic field I use to store addtional info about the object.
When I change any of those values I am only changing them for the object not the datablock.


Not sure if I helped or hindered but I had to throw it up on the wall and see if it sticks anyways 8).

#15 @Guy: You misinterpreted what I meant by
3) An object can write to a datablock, even if it doesn't reference that datablock.

I meant that any object could have a function called "updateSuperDatablock()" in which the superDatablock would get updated even if the object calling it didn't have a reference. It was poorly said but I was interpreting what Ben said. Heh.

As for your clarifications... wow. Thanks a ton. That's the most succinct definition of a Datablock that I've ever read. And to tell you the truth I would equate datablocks to "Object Templates that are also Objects" given your definition.

Datablocks are kind of like Mannequins that artists use for drawing. You get the overall shape/outline from the mannequin and then customize your individual drawing from there. A standard mannequin, as pictured in the link above, is a simple human template. Every drawing made from that mannequin would start out with the same proportions in the same position. But, you could modify the mannequin: put one of the mannequin's arms in the air, accessorize it with a backpack, or even hack off a leg. Any drawing made using that mannequin would then take on those attributes. You could update your old drawings using that mannequin but you might have to erase everything and essentially start from scratch!

If you had another artist (client on a network) and you wanted him to make drawings based on the same mannequin, you could get a second mannequin and put it into the same position (with all accessories and what-not). You then ship this second mannequin to the other artist (send the datablock over the network) and they start working.

Really, the idea of it as a dynamic object template package of member fields (no methods) makes the most sense. To me at least...

Phew...

#16

Quote:
1) The book can be checked out of the library by every person in town at the same time.
2) You restrict every person to only being able to check out one book at any given time.
3) You can write in the margin of a book you didn't check out but someone else did.

My understanding/interpretation is as follows:

1) The datablock can be referenced by every object in the game simultaneously.
2) Objects are restricted to referencing no more than one datablock at any given time.
2b) If that's the case, objects can change the datablock to which they are associated?
3) An object can write to a datablock, even if it doesn't reference that datablock.

Ammended:
1) Yes, the datablock is meant to be referenced by n objects where (n >= 0)
2) Yes, an object can use n datablocks for its config where (0 <= n <= 1)
2b) Objects can change the datablock they reference, but not through any special permissions. They can change it the same way any other object can change it.
3) Yes, this is related to (2b) since being able to access a datablock has nothing to do with ownership and ownership affords no special privileges. Datablocks are public and all members are public. All you need is a handle and you can do anything to it you want.

#17 I don't understand why we should find an analogy.

Datablock are fairly simple to understand, the name "datablock" is pretty self-explaining.
It's sets of data (or property) on which objects can be based upon.
If an object is directly modified, it will differ from the datablock on the modified fields.

These two sentences should suffice to explain how it works, me think.

#18 I'll beat that analogy in two words or less: data template.

#19 @John: Well put.

I started down this worn and beaten path because the documentation regarding Datablocks has been nothing but absolutely horrid. Here is how the TDN entry on Datablocks begins:

Quote:Conceptually, a datablock is a construct that provides a central place to store information, such that other objects can refer to the datablock and share that information. A typical example is that a datablock will hold the filename for an art asset (let's say, a 3D model of a plane), then when we want to create a new plane in the game world, we instantiate the new plane object with a reference to the datablock. If we create multiple planes, we can have them all share the same datablock, and therefore all share the same 3D model.

Datablocks provide a convenient mechanism for sharing information amongst objects of the same type, and also provide performance benefits because the datablock only needs to be loaded once for all objects sharing that datablock.

What is all of this about "sharing" data? There's no sharing! The data is set when the object is initialized and life goes on. The above, to me at least, seems to infer that the data is 'occasionally referenced' instead of 'read-once-until-next-initialization'. This inference is deepened in the next sentence: it never talks about what happens when a datablock is referenced, just that it is. The tutorial goes on to say the following:

Quote:(To confuse matters, a Datablock is actually a special type of Object, but for the remainder of this discussion they will be treated as independent constructs.)

Hurray! Confusion!

Further, the first time I came across Datablocks was in the TorqueScript Overview with the following pearl:

Quote:Of all the features in TorqueScript, Datablocks are probably the most confusing. To make things worse, they are central to the creation of most objects, which means you need to understand them relatively early. I will give a summary of datablocks here, but because you need to understand some other more advanced topics prior to really jumping into datablocks I will defer the in-depth review till later....

Just a heads up to anyone writing a tutorial or manual: don't ever begin a section with anything resembling "This will confuse you." You set up the reader to become confused: even if you have thoroughly and succinctly explained your point, the reader will be expecting confusion. The best part about that entry is that three different interpretations of datablocks are given:

Quote:1) "Datablocks are special objects that are used to transmit static data from server to client." -- engine.overview.txt in the Torque Game Engine SDK.
2) "A datablock is an object that contains a set of characteristics which describe some other type of object." -- Joel Baxter
3) "A datablock is a(n) object that can be declared either in C++ engine code, or in script code ... Each declared datablock can then be used as a "template" to create objects..." -- Liquid Creations, Scripting Tutorial #2

None of those are even close to as succinct as this discussion thread has become. Finally... finally we get a succinct answer as we approach the end of the TorqueScript Overview:

Quote:OK, now I get it. Datablocks are templates and we use them to create new objects with the attributes specified by the template.

So here's a question: why not start with that? Why take me through the loops of confusion? Why not state clearly that Datablocks are "essentially blocks of data that act as a template. You use them to rapidly initialize objects in your game (settings like life-span, blend color, collision, etc.). Two huge benefits come with Datablock usage: 1) you need to send only a single object to initialize objects similarly throughout a network game and, 2) Datablocks are a special type of object allowing you to simulate inheritance with copy-constructors and namespaces."

These things really are extremely important (even the editor uses them when creating objects... a huge life saver). It's amazing to me that the documentation on them has been so... sub-par, to say the least. (Particularly considering they are used in all Torque produced Game Engines as I understand it...)

So forgive me if I spent a bit of time coming to grips with these things... I've found that they're incredible time-savers once you get a handle on how to use them! Metaphor/allegory happens to be one of the tools that I use to further my depth of understanding of something. I actually find that you learn more when you find out where metaphors break than where they work well (heck, see: above).

I <3 Datablocks.

#20

Quote:
So here's a question: why not start with that? Why take me through the loops of confusion? Why not state clearly that Datablocks are "essentially blocks of data that act as a template. You use them to rapidly initialize objects in your game (settings like life-span, blend color, collision, etc.).

Because unfortunately, it sets up a ton of connotations in people's minds that turn out to be patently false.

When you use words like "template", "initialize", and several other similar terms, it makes many programmers believe that datablocks are simply used by the constructor to copy over data, and that is blatently false. Unfortunately, many times that's how people use them, and the documentation reflects that.