Author Topic: Package/Parent Syntax Tutorial  (Read 30089 times)

Badspot

  • Administrator
Someone type up a brief explanation of the package/Parent:: syntax for adding on to existing functions and I shall sticky it.  It's kind of required knowledge for modding Blockland.
« Last Edit: October 28, 2015, 11:04:10 AM by Badspot »

We all want to be able to make our own modifications to Blockland, whether to add new features, set or work around limitations, or change the way the game is played.  The problem is that all of the code that controls game play is stored in encrypted files.  One great feature that Blockland, and the Torque Game Engine it's based on, supports is encapsulation.  For those of you that are new to programming, encapsulation at its most basic level means storing one item within another.  Take a plastic Easter egg for example.  The plastic egg is the container (the 'Parent') and the pieces of candy within are its children.  You can't really change the way the egg (or 'Parent') works without destroying it, but you can change its candy (or children).

In Blockland, the Parent is the main game code.  All the code stored in those .dso files cannot be changed.  Now, when someone creates normal add-on code that does not overwrite any of the game's built-in functions, the creator's code becomes part of the main game code.  If you overwrite a built-in function (serverCmdPlantBrick), you might lose a very important piece of functionality.

How do we get around this?  Packages!  Here's an example package:

Code: [Select]
package NewPackage
{
function paintProjectile::onCollision(%this,%obj,%col,%fade,%pos,%normal)
{
                <any special actions you want performed when this projectile collides>
Parent::onCollision(%this,%obj,%col,%fade,%pos,%normal);
}
};

In the above example, our NewPackage includes a method that adds to functionality of the paint can's projectile collision.  Note that, after inserting our own, new code, we call the Parent (main game code) to run its normal collision code.  We pass to the Parent::onCollision() method the exact same number of parameters that our method receives.

Now, before you run off to try this on your own, there's one very important line of code you'll need to add here:

Code: [Select]
activatePackage(NewPackage);
Packages in Blockland or TGE can be enabled or disabled using activatePackage(<package name>) or deactivatePackage(<package name>).  If a package if not activated, you cannot make use of its specialized methods.

Well, those are the basics.  Just remember:

Parent (main game code.)
{
     Packages (collections of our methods that extend the ones built into the game.)
     {
          Methods (individual functions that we create.  must call Parent to retain original functionality.)
     }
}

packages aren't used inside code blocks...

basically they're only used for mods or to edit previously existing functions, and they don't necessarily contain methods...

The syntax was right, for the most part:

Code: [Select]
package <Package Name> {
    <Functions (or methods) go here>
};

after you activate a package, any functions you re-wrote inside the package (that already existed) overwrite the previously existing one. You can call the code in the previously existing function (i.e. the function that was created outside the package) by using Parent::

Packages always contain methods.  My syntax was completely right.  What do you mean by code blocks?

Quote from: Trader
Parent (main game code.)
{
     Packages (collections of our methods that extend the ones built into the game.)
     {
...
They're not necessarily methods, and a package isn't a child, so to speak, of Parent.

What i was trying to say was that this is more accurate:

Code: [Select]
// Some code here... (THIS is Parent)

function <a regular function>() {
   // ...
}

package <this is a package> {
   function <this is a function within the package>() {
     
   }

   function Player::<this is a method within the package>(%this) {
      echo("In package scope.");
      Parent::<now in global scope>(%this);
   }
};

« Last Edit: November 07, 2007, 05:17:02 PM by exidyne »

When you're overwriting methods, packages are children of main game code.  And function = method.  Packages contain methods.  Packages contain functions.

even i'm getting confused now.

it really doesn't even matter, i was just trying to make it a little bit more clear for people who actually need to understand what a package is and how to use it, which wasn't made very clear in your post.

Heh, evidently it was clear enough to get a sticky.  This topic requested an explanation of how to create packages that overwrite or extend existing functions (e.g. main game code).  My post provided that explanation almost 2 months ago and none have complained about its content.  I believe you're the only one confused.

In the case that you took me offensively,
I just wanted to clarify your post in more realistic and simple terms, which is the perspective you should take considering it's for people who are probably learning to script for the first time.
« Last Edit: November 07, 2007, 05:37:32 PM by exidyne »

There was no request for additional clarification.  Let's be done with this.

I haven't written anything since v8, and now a lot of things seem to resist packages. Sometimes a trace shows that the package isn't being called at all, and sometimes it says that the package is being called, but an echo on the first line of the function doesn't show up in the console.

Does anyone know what might be causing these issues?

Also: Something's broken on the forums; I get a "topic too old" error when I try to make a new topic.

Certain methods of certain objects cannot be packaged anymore for example you'll get errors if you try to package GameConnection::onConnect etc.


I didnt find this very helpful or clear.

Once we package it, then what? Do we eat it? Put it in Console? Zip it and stick it in addons? Help please

I didnt find this very helpful or clear.

Once we package it, then what? Do we eat it? Put it in Console? Zip it and stick it in addons? Help please

This is a reference for people who make add-ons.

ERROR: function declaration failed: GameConnection::authCheck