Torque Script - datablocks - very confusing

It took me quite a while to really understand datablocks in Torque. All the books say exactly the same thing.

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 think all the books plagiarized this from the official documentation on datablocks.

Datablocks are just shared objects that contain static data that doesn't change from one object to the next. So the engine can send it once over the network and reference it by id from then on. I get this and I think every explanation made this perfectly clear. The problem is that all the callbacks from the engine into the script code comes through these datablocks. For instance:

datablock StaticShapeData(SomethingData)
    {
    // Basic Item properties
    shapeFile = "./mymodel.dts";
    };
function SomethingData::onCollision(%this, %obj, %col)
    {
    // your code here
    }

This really confused me and I was trying to create my own object types to no avail. The code above creates a type SomethingData which will show the 3d model contained in the file mymodel.dts. This is fine, but the call to onCollision is done on the datablock object (SomethingData) versus the object itself which in this case ends up being a StaticShape. Since the datablock is static and shared across all instances I couldn't figure out why or how you kept data in individual objects.

I finally had an epiphany when I noted that %obj is always passed into the callbacks and is the actual object instance. Individual changes and values can be made in this object. Seems simple enough now, but this killed some brain cells for me.

So I placed this comment in one of my pieces of sample code for class.

function SomethingData::onCollision(%this, %obj, %col)
{
  /*   * MANTRA - REPEAT OVER AND OVER UNTIL DATABLOCK UNDERSTANDING SETS IN
   * 1. %this is the datablock   * 2. %obj is the object instance
   *
   * of much less importance
   * 3. %col is the object colliding

Here is the lecture where I tried to explaing this. I think the notes are still a little jumpy, but the in person version seemed to clear things up for students. Your fuel economy may vary.

Torque Script - Behind The Scenes

Torque script is the scripting language behind all of the Torque Engines is a simple, but robust scripting language that is very easy to learn. All game engines include a scripting engine and Torque is no different. For non-game developers, the idea of a scripting language may seem like a negative, but there aren't any commercial games that don't use a scripting language.

Most non-game developers may at first think that this means the source to parts of your game are shipped with the game, but this is not the case. Torque script is compiled into a bytecode format and saved to a separate file (.dso extension). Everytime the game engine runs it does a date comparison between the source (.cs) and the compiled files. If the source is newer, it re-creates the bytecode file. If the source file does not exist, it simply uses the bytecode file. You simply ship your final version without the source files.

This is transparent and very fast. When you are developing games using this system you never see the compile taking place. One drawback of this system with Torque is that it isn't blatent when compile errors happen and you have to go back and look in the logs when you've made a bunch of changes. In most cases I've seen it will simply use the older .dso file and you'll be caught wondering why that echo/printf you just put in the code isn't appearing. As with most tools, once you get used to it, it is not really a problem. There is an editor called Torsion that will check/monitor your syntax, but I have not tried it. Everything I've read says it is highly recommended.