Latest Updates and Getting Involved

Latest Updates and Getting Involved

Greetings everyone! I've got a monster of a blog for everyone today. We have pushed an update to Torque 2D's master branch, which warrants a post about all the changes you should know about. Some are flashy, some are basic, while others are going to completely change your work flow (in a good way). Before we get into all the details, here's a quick history lesson...

History of Open Source Torque 2D

Before I proceed with the update information, you can review the past history of Torque 2D MIT by reading these blogs:

Torque 2D MIT Coming Soon
The Future of Torque 2D is Open Source!
Open Call: Join the Torque 2D Steering Committee
Torque 2D MIT 2.0 Now Available!
Two Weeks Later
New Steering Committee
Android Support and More!
Editor Collaboration

Updates have been pushed to the master branch of the repository. If you ever want to use changes before they hit the master repo, you can always checkout from our development branch.

Finally, we have updated the the precompiled version of the repository, which you can download here: Torque2D-2.0.zip. Note that this is not hooked up to the GitHub repository. This is just an export. We are going to start making use of versioning numbers after this update, as a lot more is going to start changing.

Important Engine Changes

A full change log of all Torque 2D updates can be found here.

World Query
Breaking changes to WorldQuery were made. Now, the WorldQuery can pick by AABB, OOBB or Collision shapes. This has a slight breaking change that may require documentation changes in that the picking methods on Scene now have the following modes:

• Any (Same as before)
• OOBB (New!)
• AABB (Was previously named "Size")
• Collision (Same as before)

As you can see, picking by "Size" no longer works; its new name is "AABB". The default for all pick methods is OOBB which is probably the most sensible. We have also made modifications to the composite-sprite picking so that it picks the OOBB rather than the AABB which is far more useful.

Input Handling
We've added a simpler way to receive input event callbacks from the SceneWindow by allowing you to add any SimObject as an input-listener like so:

%obj = new ScriptObject()
{
   class="Foo";
};

SandboxScene.addInputListener( %obj );

This will allow you to receive any input events that the SceneWindow produces now (or in the future) on the specified object. If the object is deleted then the object is automatically removed as a listener so there's no need to remove it but you can do it explicitly if you wanted to stop receiving them like so:

SandboxScene.removeInputListener( %obj );

In the above, case you can define the methods you need like:

function Foo::onTouchUp(%this, %touchID, %worldPosition)
{
}


function Foo::onTouchDown(%this, %touchID, %worldPosition)
{
}

You are free to add as many objects as listeners as you wish! Technically this can be used to replace the more specialized code that allows you to ask for a SceneObject to receive it but we didn't want to break compatibility there. Also, that code generates a higher-level virtual input event on "enter" and "leave" which isn't a real device event so I left all that code as-is.

The Sandbox manipulation was updated to use this by simply adding the object that performs the manipulation as an input listener. This completely removes the need for it to defined a "function SandboxWindow::onBlahEvent( ... )".

We also removed the packages from all the toys that wanted input events as it was confusing and messy. Now any toy that is loaded will receive input events without you having to configure it. Just define the appropriate function and it'll work.

Collision Filters
We have changed the way contact filtering works:

• Changed the contact filter so that the contact rules is now such that a contact occurs if either A is configured to contact B OR B is configured to contact A. Previously both conditions (AND) were required which caused undue configuration.
• The contact rule above now also determines if an object gets a direct callback i.e. "onCollision()" and "onCollisionEnd()". To receive a callback you still need to have "CollisionCallback" set to true but if it is then the object only gets it if its configuration could cause a contact. This means that if, for instance, A was configured to collide with B but not B with A then A would get a callback but not B. Again, A would only get a callback if it had turned-on the collision-callback flag. Also note that if a contact is made then the "onSceneCollision()" and "onEndSceneCollision()" is always called.
• Updated the existing toys to take advantage of this improvement.

Schemas
Anyone who is editing XML files persisted by TAML is in for a special treat. Melv has made an amazing change to the engine that allows it to export an XML schema data file. What does that schema contain? Well, if you are using a tool that allows for intelligent XML editing, you can point to the path of the XSD and get a wealth of feedback.

As you are typing the XML code, you will get the following automatically:

• Auto-completions - Why always type out each letter of an object? As you are adding a Sprite, you will get a popup of all objects as soon as you start typing the word.


• Suggested children - If you are using notepad, nothing is going to tell you to not add a GuiControl as a child of a Scene. It will not work, but you are still able to type it out. If you use our schema, you will receive immediate feedback telling you a type is invalid for its parent.


• Type feedback - Everything in TorqueScript is a string. Text, numbers, IDs, and so on. Even in a tool like Torsion, you could be passing in bad data. If a function wants a vector2, you could pass "bob" and never know the problem until the engine breaks. With our schema, you will immediately be told what is valid expression and what is invalid.


• Validation - In addition to all of the above, if you miss a bracket, forget a quotation mark, or make any other syntactical error, a decent XML editor will let you know immediately. With the addition of the schema, you will receive in depth error checking based on the contents of the file.

To generat the scheme, you must do the following:

1. Set $pref::T2D::TAMLSchema variable to the name and path of the file you wish to generate, such as "Torque2D.xsd" or "/Applications/Torque2D.xsd"

2. Call generateTamlSchema(); from a script or the console after the above variable has been set

Additionally, after the schema variable has been set, any new XML files you generate via TAML will automatically have their schema field set to the correct file path of what was generated. You can even refresh existing assets to have the scheme path set automatically.

If this is all too confusing, fear not. I will be uploading a video tutorial covering all facets of using a schema while editing an XML file for Torque 2D. Hang tight, it should be ready shortly.

Bug Fixes

• Fixed the poly list values used when creating a Quad in ShapeVector::setPolyPrimitive. The previous values were resulting in a render that was twice the size of the actual AABB. This should resolve https://github.com/GarageGames/Torque2D/issues/43
• Fixed bad particle asset reference.
• Fixed-up a recent bad merge and implemented stubs for missing
• Fix for onCollision/onEndCollision - the parameters should have been and are now onCollision(this, other, details). They used to be onCollision(this, thisAgain, other, details)
• Fixed a minor problem with WorldQuery when picking AABB on objects OOBB.
• Fixed bug which caused an exception when the CompositeSprite culling was turned-off. - Fixed bug where an assert was issued when an invalid CompositeSprite layout was specified.
• Removed a dead assets - Fixed some broken asset references and added missing assets
• Fixed issue with WorldQuery when picking an area.
• Fixed bad default when writing the field SceneObject::PickingAllowed.
• Fixed script string corruption from "onCollision()" & "onEndCollision()" callbacks.
• Fixed XCode warnings.
• Fixed nesting issue for Schema.
• Fixed typo for getRevoluteJointMotor
• Fixed "getDebugOn()" to return all active options.
• Fixed a harmless warning from the asset-base.
• Fixed a bug in "onEndCollision()" callback on behaviors.
• Fixed-up the collision-groups in the TruckToy.
• Fixed field sub-component evalulation to be safer for string formatting. - Using the safer "vsnprintf()" rather than "vsprintf()" for string formatting operations.
• Fixed up some formatting issues only.
• Fixed bug in "SceneObject::setCollisionAgainst()" which was incorrectly merging the opposing objects collision-masks and not the scene-masks.
• Fixed bad formatting and warning under VS2010.
• Fixed SpriteBatch problem when turning-off the batch culling.
• Fixed typo in asset file

Experiments

Melv and I started working on the concept of experimental code. You can see an example of this in the source, located at engine/source/experimental/composites/WaveComposite. This class is similar to CompositeSprite. It has the same inheritance, then adds a few extra fields that will animate its internal sprites on a sin wave animation. The source is in 2d/experimental/composites. The toy is in modules/Experiments/WaveComposite.

The main purpose was to set the stage for implementing new technology without upsetting the core engine. Examples include Spine and Spriter, which will likely go down a similar route of what we showed with WaveComposite. In fact, we have taken this experimental concept to the next level in my own personal fork, where Kirk, Melv, and I have been collaborating on an official Spriter implementation.

New Modules

AppCore - This was pushed previously, but it should be mentioned in this blog. We added a new module called AppCore, which is the new entry point for a Torque 2D project. The responsibility for creating/initializing the Canvas, initializing OpenAL, and setting the necessary system variables has been moved from the Sanxbox into AppCore. If you want to start with a fresh Torque 2D project, you can delete all the modules except for AppCore. This will leave you with a blank window and initialized system. You can always remove AppCore, but you will need to then write your own script code to create the window and initialize everything.

CompoundObjectsToy - Melv added a "CompoundObjectsToy" into the development branch to demonstrate the CompositeSprite when used as a simpler multi-sprite object. Whilst the CompositeSprite has a lot of methods you can call on it, 90% of them are just the configuration options for a sprite i.e. its position, size, angle, color etc. A video for this new toy was posted at the top of this blog.

PickingToy - Added a basic example of picking that allows you to set the different picking modes of "point", "area", "circle", or "ray". It demonstrates the difference with the "size" picking the AABB only.



TropicalAssets - We split the assets for the AquariumToy into their own module. This is prepping for Charlie's behavior tutorial, which uses the assets but exists outside of the AquariumToy.

WaveCompositeToy - This is located in the modules/Experiments/ directory. It is a live demonstration of what I talked about earlier in the Experiments section of this blog.

Documentation Updates

Much of the documentation changes include updating older entries to match all the engine changes. However, we do have new tutorials and guides in the work. You should check out the Scripting Tutorial if you are wanting a crash course on creating a TorqueScript. We also have a large Behavior Tutorial doc that's been posted, but it still being reviewed. As always, the documentation is subject to change based on feedback, corrections, and engine changes.

Torque 2D is an open source project, meaning improving every facet is on all of us. If you are hesitant to make code improvements, contributing documentation is a huge help to everyone. There will never be enough documentation, so check out our examples and get cracking!

Until Next Time...

That's all for this update. The next blog will be a reaction to the editor collaboration post I created. In this next blog, I will present my plan for developing editors. As always, the content is subject to review by everyone who uses Torque 2D.

As usual, we still need your help with spreading the word. I have been getting involved in the Reddit community, particularly /r/gamedev. At least once a week someone posts a question about 2D engine choices. The usual suspects always show up, but Torque 2D has painfully been left out of the discussion. I try not to sound like a marketer when I post my suggestion, but I truly believes it should always be involved in the talks. Please help me continue to get Torque 2D back in the spotlight.

Regards,
Mich