Torque 2D MIT (Part 3)

This is part 3 of my technical blog, welcome back!

Part 1 of this blog can be found here.
Part 2 of this blog can be found here.

CompositeSprite

In legacy t2d there was a tile-map that contained tile-layers. It was awesome at first but eventually failed (in my opinion) because it tried to be too flexible. It allowed windowed scroller and its own physics tile brushes and lots of other stuff. It just grew and grew in complexity but unfortunately the performance it provided was terrible. Not only that but it was stuck to rendering a regular fixed-grid of tiles (rectilinear) and didn’t address isometric tiles.

At first, because time was at a premium, I simply wired all the immediate rendering of the tiles into the batching system I described previously and performance shot-up as expected however, there was still a lot of costly stuff going on inside it and it was showing its age. Not only that but it was one of the final objects to still use the old custom binary persistence alongside the particle system. This custom binary persistence needed to be removed and replaced with Taml usage but time was against me.

In the end, the opportunity arrived for me to sort this out. What I did was just scrap the old tile-map and tile-layer stuff completely. After all, rendering “tiles” is not rocket science.

What I wanted to achieve however wasn’t so easy:

• Have a single scene-object that used batching and render sorting (described previously)
• Have it handle thousands of sprites, each individually configurable for orientation, size, static and animated imagery, blending, scene-depth, sort-point, named etc.
• Have it use Taml for persistence.
• Have it allow for multiple layout modes including custom ones i.e. Rectilinear, Isometrics, Arbitrary (free-form positioning) and custom.
• Allow a logical positioning system to be used to more easily address individual sprites
• Allow the attachment of meta-data for each sprite

It took a little time to figure this out but with many of the system I’ve described previously in-place I only had to focus on how to organize this so that it was not only fast but also made sense from a TorqueScript API point-of-view.

Originally it wasn’t called a composite-sprite but before I even started writing code I realized that this was exactly what I was designing. It was to be a sprite (by name) that was a composite of multiple other sprites “inside” it. These sprites can be placed in any location and can be of any size, orientation, blending, sort-point, scene-depth etc but also, if the user so chose, they wanted to add sprites at “logical positions” when used as a tile-layer i.e. add a sprite a tile location (10, 5) and have that map to a specific position. I realized that this was simply an exercise in sprite-layout.

The final composite sprite is an awesome beast. It allows you to add, remove and configure individual sprites that have pretty much most the features that a standard scene-layer sprite would have including using static images or animations, blending, layer-control etc. You can also set the composite sprite into one of the following layout modes:

• No layout - The logical position you specify is a physical position (no transformation)
• Rectilinear layout - The logical position you specify is mapped to a rectilinear position
• Isometric layout - The logical position you specify is mapped to an isometric position
• Custom layout - The logical position you specify is mapping (via a TorqueScript callback) to a custom position

This provides everything you’d ever need and that’s a bold statement. The reason why I’m pretty confident is that these logical positions, whilst typically numeric, are not required to be. If you want to write a custom TorqueScript function that takes the logical arguments and maps them to a physical position then you are free to use whatever you like i.e you could have a logical position using the arguments “10, 20, snow”. If that means something to your custom function that all you need to do is return the appropriate stuff in the Torque callback.and the composite-sprite will do the work for you.

Composite-sprites are not just for tile-mapping though. They can (and should) be used for creating complex composite “characters”. For instance, imagine that you have a character that is composed of several sprites including a sprite that’s coloured (probably blended) to indicate health or maybe to indicate a “team”. You can easily set this up as a composite-sprite and use it as a discrete object that can move just like a scene-level sprite.

Not only that but you can configure multiple collision shapes for physics including sensors etc. That’s part of the Box2D integration which I’ll come to shortly.

Composite-sprites are fast. They not only use batching but they also allow very fast changes to any property of any sprite contained within them including position and orientation. They also provide fast render clipping for when the composite-sprite is large has lots of off-screen sprites.

The isometric video shown earlier was done using the composite-sprite. It actually only took a few lines of code to set this up, basically a few lines to create the composite-sprite and set it to “iso” mode and a couple of nested loops to add the tiles at a logical position.

The composite-sprite has a bright future. Not only did I design this so that it performed well in varying use-cases but I also wanted to ensure that some future use-cases were available to it. One of those would be movement animations. It’s actually not difficult at all to animation the properties of the sprites within a composite-sprite which obviously includes its position and orientation. It’s actually something I’d love to work on and it’s be awesome to be able to apply an animation to a composite-sprite. Not only so you can provide articulating characters but also so you can do some nice stuff like have moving tile platforms or other stuff. In other words, be able to apply multiple overlapping animations to a composite-sprite.

A composite sprite in a very familiar layout, rectilinear:




A composite sprite in rectilinear but showing that each sprite can be orientation (amongst a bunch of per-sprite configuration):




A composite sprite with no layout where the sprites are placed at arbitrary positions:




Finally, a composite sprite in “iso” mode:



What’s completely hidden here is that the above composite sprite is a 1000 x 1000 sprite system! Sure, it takes around 18 seconds on my machine to initialize it but when it runs, the performance is directly related to how many tiles need rendering. This is even true if the composite sprite is moving as there’s no overhead on it moving/rotating.

To show this, I zoom out and try to get most of the 1 million tiles rendering knowing that my system is about to chug:



So it’s pushing 875,012 render requests here through 79 draw-calls with 78 of these because the vertex-array limit was reached resulting in 5.9 FPS. Not too bad for what it’s doing.

Box2D

So I wrote the custom physics system for the legacy T2D and it worked well but it was pretty complex and it wasn’t without its issues. This was actually a really early piece of work but it was also the most destructive change. I won’t go into the deep changes required to make this happen but it’s sufficient to say that it significantly changed the API.

Fast-forward to now. Box2d is not only integrated but it’s also been tried and tested a lot. It’s also had the advantages of Taml and the batching system to supplement its use and it’s an awesome feature.

I’ll start by saying that every single feature of the latest Box2D head is in T2D. That includes all collision shape types and their properties i.e. Circle, Polygon, Edge and Chain shapes. Also all joints and their properties i.e. Distance, Rope, Revolute, Weld, Wheel, Friction, Prismatic, Pulley, Motor and Target (mouse) joints. I was also careful to ensure that folks who already know Box2D were not alienated by my integration of Box2D. To ensure that this was the case, I wanted to ensure that T2D used Box2D as it was intended and that, where reasonable, things have the same name. There were a few exceptions here but not many.

The net result is that taking a standard Box2D test-bed application and trying to create that in T2D is crazy simple because everything has an analogy. You can take the Box2D manual and change some of the names and it’d be pretty close.

So in T2D, any SceneObject can have a Box2D body (or can make multiple ones). This also means that you can have an unlimited number of collision shapes, each with their own properties. Absolutely everything is exposed to TorqueScript allowing you complete freedom to do what you like and all of it is supported by Taml. It’s even human readable in XML allowing fast prototyping outside of code if you so desire.

Joints themselves live on the scene and they bind two bodies together just like in Box2D. This is done because a joint never belongs to a body and therefore a scene-object. The scene is analogous to the Box2D world and indeed, the Scene actually owns the world. The scene is therefore where you set gravity should you want it.

I’ve also exposed all of the Box2D functionality that exposes applying forces and torque and obviously with the joints you have access to motors etc.

The contact system is wired slightly differently than Box2D but Box2D provides the ability to provide a C++ callback that allows you to specify what can contact what. In T2D I stayed with the notion of controlling contacts between objects with groups and layers, each having 32. By default everything can contact everything. All the other functionality has gone, the stuff that confused a lot of folks with its bi-directional contact control i.e. sending/receiving collisions.

The new system not only provides callbacks for when objects collide i.e. when a contact is made but also when a contact stops. Of course, these callbacks are not on by default as performs hundreds or thousands of contact callbacks would be expensive but you can turn this on for individual objects you’re interested in.

You can set any scene object to use either static, dynamic or kinematic body types as well.

There’s a huge amount of control here which I won’t go into but as I’ve tried to do everywhere, the day-to-day use is really simple. There are nice helpers as well for saying that you want to one object to collide with another and other stuff like that.

Various other utilities are now available similar what was in legacy T2D but now they’re not only faster but much more intuitive. For instance, there’s a whole new picking system that allows you to pick objects by their size and/or collision shape(s) using geometric queries like point, rectangular area and ray-casting. This isn’t like before however, it uses a much faster way of returning the results. In this case there’s a whole picking sub-system called the World-Query system. With this system you generate a query object and perform the pick operation(s). You can then iterate the query object for the individual results. This saves time iterating strings for the results.

The final thing to say is that T2D adds very little overhead on Box2D. In other words, if you turn off the rendering or just render wireframe then you’ll get similar performance to the Box2D test-bed. For complex scenes you’ll get it much faster because of the batching system used instead of the immediate debug drawing used in its test-bed.

Here’s an example showing not only some of the Box2D stuff but also one thing that was asked for many times: camera rotation. In the truck toy in the Sandbox the camera is mounted to the truck body keeping it perfectly horizontal whilst the rest of the scene moves. Warning: This one might make you feel a little giddy! Finally, the video also shows you the sandbox which I’ll discuss shortly.

Particle System

The particle system was one of the final things to use the binary persistence system and so it was removed. It was working with the batching system a fair while ago and that massively boosted performance but a real problem with it was that the way it worked was awkward. By this I mean that the particle player actually handled the particle state and the particle state contained all the scene-object stuff like position etc. It also meant that to play a particle you had to touch the disk because you essentially loaded the binary persisted particle from the disk.

We originally announced that we were not going to push a particle system out because of time constraints and I was also considering writing a new particle system but luckily, various planets aligned so that I could work on this.

What I did was to separate the particle state from the particle player. More specifically I needed to generate a new particle asset which contains all the particle state defining a particle. I then created a ParticlePlayer scene-object that you can add to a scene. This provides the position and playing, pause, stop (etc) features. Essentially this:

// Create and add a particle player.
%particlePlayer = new ParticlePlayer();
%scene.add( %particlePlayer );

// Assign it a particle asset.
%ParticlePlayer.particle = “ParticlePack:Explode”;

// Play the thing already.
%particlePlayer.play();

All the previous features of the particle system plus a few more are available. This time however, it’s a lot faster in all areas and as you can see, you can assign a particle without any need to load it up each time as the particle state is an asset and uses the normal asset rules.

So the new particle system is hot-off-the-press so I’ve not had a chance to create any nice particle effects to show off so I’ll focus on showing you the performance here. You can expect all the features and flexibility of the last system but in a much better package.

Here’s a stress-test of a particle playing an asset that pumps-out 1000 particles/sec and each particle lives on-screen for 10 seconds resulting in approximately 10,000 particles on-screen at all times. The previous system would have caused any system to fail around 2-3K particles.

The example below shows you 10,000 particles being rendered reaching around 233 FPS. When I simply make the particles invisible but still have the particles updating then the FPS shoots up to 4307 FPS showing the massively reduced overhead of processing particles. The final image shows the metrics where approximately 10,000 particles are being handled. In this image the particles are still hidden and the FPS drops to 1097 FPS but that’s because rendering the full metrics overlay eats cycles.



A few final things I’ll mention about this new system is that it has a whole bunch of new features for the particles. Not only are the emitters (which are part of the asset) easy to configure but you can clone them and work with them directly from TorqueScript. This is handy for copying emitters between effects. In putting particles around your scene, there’s also a new “camera idle distance” setting that allows you to set the distance from any camera beyond which the particle should go idle. This means you can have hundreds of particle players thrown in your level and only those within the specified distance actually get processed.

Also, each emitter can be placed in its own local-space offset and orientation and even have its own size. Each one also has a choice of emitter geometries as shown here:



This is one particle asset but it has 6 emitters. They are individually configured with an offset, orientation and size as well as their own geometry. You now have "Point", “Line”, “Box”, “Disk”, “Ellipse & “Torus”.

Here’s s simple particle effect that I created by editing Taml directly. It’s nothing special but it’s just so much fun creating them, even without an editor yet:

Sandbox

In closing, T2D is being released without an editor but we didn’t want to release it as a raw API as that would be brutal of us so I went ahead and generated a sandbox application that uses modules to generate isolated toys you can play with. These toys are categorized into categories like “Stress Testing”, “Fun”, “Features” etc. The idea is to use the module system so that each toy is a self-contained.

If you understand the module stuff above, you’ll know that this means that you can take a module from a friend and just copy it into the sandbox folder and it’ll appear in the sandbox. Also, if you have a problem with T2D then you can quickly show this using a toy i.e. a module that shows the problem. Zip it up and send it to someone to look at. The module can contain all the script and assets. You are also free to split-up a toy into multiple modules and set-up their dependencies if that’s better for you but a single self-contained module is nicer.

So the idea is that these toys and the sandbox serves multiple purposes. It can show off the features of T2D, it can be used to report problems, it can be used to stress-test and compare performance across hardware and OS etc.

You’ve already seen the Sandbox in one of the previous videos but it is a WIP and stuff like setting up touch controls for iOS needs working. Also we're hoping to get lots and lots of toys in there and being as toys can be categorized we'd like to get stress-tests, feature-examples, fun stuff etc and as many as possible. Now that the hard part of T2D is over I'm hoping we can all contribute by not only helping to find and fix any bugs but also to contribute in the form of toys. Toy can be used to demonstrate problems so hopefully it'll be a feature we'll all grow to love and love to grow.

Conclusion

In this three-part blog I’ve discussed many features and I’ve focused somewhat on performance but Torque 2D MIT is not just about raw numbers. The new systems that have been created are about addressing real issues when making games because after all, this is what the engine is all about. Modularity of scripts, powerful asset handling, improved performance, sandbox to get you started with simple, concise examples and much more.

I’d like to say that I’ve put my heart and soul into most of this code. It has been a labour of love and I really do hope that you find that it gives you many hours, if not years of pleasure. I think the price is certainly about right, free, you can’t beat that for value.

Enjoy it, I know I will.