Undertanding TGB MiniTutorial
by AzraelK · in Torque Game Builder · 09/19/2006 (12:52 pm) · 10 replies
I've noticed that the current tutorials dont explain how the TGB engine works "internally" which can be incredibly useful for someone trying to understand TGB, Im going to try my best on doing so here, so correct me If Im wrong please. BTW For space purposes Im setting "ludicrous speed" so dont worry If you are new and you dont catch something the actual tutorial will be fairly paced and include some pics.
Ok here goes:
- -
Understanding TGB
Intro:
Loving TGB so far? Good! we all do, however there are some details you may want to know in order to create your masterpiece in this wonderful engine. Some of them you may already know.
TGB is a 2D Game Delveloping suite, based on the Torque 2d Engine which was built using the Popular Torque Game Engine. Basically is the 2D version of a very popular and productive 3D engine made for rapid Game developing and shares several similiarities with it. (however is also different in certain aspects)
The Torque 2d engine as a whole was creating meeting important standards in stability, speed, ease of use and scalability so unlike several game engines, processed are a little more streamlined and complex than just pasting images to the screen, the internal mechanics used by the engine, ensure more efficient use of memory, CPU and therefore better rendering speed. While at the same time providing useful features like the use of object based Gui's and controls in the screen.
But how does it all work? ok heres the deal:
The TGB engine (just like its parent T3d) is a heavily Script based engine, that means we use scripts to call and modify functions within the internal engine source code API without any need to modify and recompile the source code itself (unless we want to modify the engine core) and even though the script is simple to use, it has almost all the functionality you would expect from a full blown language like C++ or C## since you can create and modify functions, classes, arrays, lists (simsets) etc. etc.
All scripts (although complex looking) are just regular text files, this includes the Code Script (CS) , particle effects(*.eff), levels(t2d), tilemap(lyr), the datablocks (CS) and the GUI files (GUI) which can be opened and edited in any text file editor (although we recommend the use of one that recognizes Torque Script such as Torsion for better understanding)
In order to ensure Speed the TGB itself compiles those text files into DSO files which are unreadable for a peeky final user who may try to "hack" our code, but still hold the same code we typed in our CS or gui file. :)
With the exception of Torque Script main code , the TGB features a level/gui/tile/datablock editor that allows us to visually edit and modify the code contained in the scripts needed for our game.
However (if needed) we can still view and modify the code "by hand" with any text editor by accesing in its folder. (p.s. some modifications may require to close and restart TGB in order to be recognized)
*the main.cs file
(short explanation of how the main.cs file loads the rest of the scripts)
*Datablocks
(explanation about how TGB loads resources)
--to be continued....
Ok here goes:
- -
Understanding TGB
Intro:
Loving TGB so far? Good! we all do, however there are some details you may want to know in order to create your masterpiece in this wonderful engine. Some of them you may already know.
TGB is a 2D Game Delveloping suite, based on the Torque 2d Engine which was built using the Popular Torque Game Engine. Basically is the 2D version of a very popular and productive 3D engine made for rapid Game developing and shares several similiarities with it. (however is also different in certain aspects)
The Torque 2d engine as a whole was creating meeting important standards in stability, speed, ease of use and scalability so unlike several game engines, processed are a little more streamlined and complex than just pasting images to the screen, the internal mechanics used by the engine, ensure more efficient use of memory, CPU and therefore better rendering speed. While at the same time providing useful features like the use of object based Gui's and controls in the screen.
But how does it all work? ok heres the deal:
The TGB engine (just like its parent T3d) is a heavily Script based engine, that means we use scripts to call and modify functions within the internal engine source code API without any need to modify and recompile the source code itself (unless we want to modify the engine core) and even though the script is simple to use, it has almost all the functionality you would expect from a full blown language like C++ or C## since you can create and modify functions, classes, arrays, lists (simsets) etc. etc.
All scripts (although complex looking) are just regular text files, this includes the Code Script (CS) , particle effects(*.eff), levels(t2d), tilemap(lyr), the datablocks (CS) and the GUI files (GUI) which can be opened and edited in any text file editor (although we recommend the use of one that recognizes Torque Script such as Torsion for better understanding)
In order to ensure Speed the TGB itself compiles those text files into DSO files which are unreadable for a peeky final user who may try to "hack" our code, but still hold the same code we typed in our CS or gui file. :)
With the exception of Torque Script main code , the TGB features a level/gui/tile/datablock editor that allows us to visually edit and modify the code contained in the scripts needed for our game.
However (if needed) we can still view and modify the code "by hand" with any text editor by accesing in its folder. (p.s. some modifications may require to close and restart TGB in order to be recognized)
*the main.cs file
(short explanation of how the main.cs file loads the rest of the scripts)
*Datablocks
(explanation about how TGB loads resources)
--to be continued....
#2
*Out of sight, out of mind.
So thats all theres to it right? well... not quite
for any regular 2d engine, the above mechanics will be more than enough features, but for TGB we are just getting started.
Imagine we made a shooter using TGB as we've seen so far, how would we manage to move the entire background objects just so we can provide the illusion of going forward, if we would do a platform game or an RPG where the screen could go anywhere we would have a whole lot of objects to move around would we?
Of course in TGB that is not the case ...
The CAMERA
Instead of moving our objects around, we have a CAMERA object, the camera simply tells TGB what to render in our T2Dscenewindow and transforms those objects from Scene Space to Camera space (and to Canvas space) and functions exactly like a real camera does, when you move the camera to the left you will see the entire level in the camera move right, revealing the left portion of your level. When you move the camera right, you will reveal the right portion, up, down, etc. I think you get the point.
Theres a nice plus to that, since we know we only have to draw what is seen by the camera, everything not in camera view can be clipped away! thus making our game more efficient, faster and our players happier ;)
(note:Theres just one detail to notice, if your camera size is not the same size that your targetted SceneWindow some scaling or clipping may occur, you may want to check on that.)
Scene Frames
Speaking of clipping: remember we mentioned we could have a whole lot of objects in our level? well as you may know, TGB can check for the collisions between all the objects in the level, as soon as they have their collision flag on. but what happens if we have an impossible collision?
Per example a football and a goal post all the way to the other side of the football field? of course you want to know if they collide (even if its not in the camera) but unless we live in a parallel universe theres little chance of the football colliding with the goal by simply standing there.
To prevent this from happening, each Scene is divided in something called "SceneFrames" think of it like a restriction grid where only objects inside a grid square are allowed to play with each other. That way you Will never check if the football standing at the beggining of the field can collide with the goal, they are not in the same grid square! they can only collide if the football moves all the way to the goal square per example when the ball is kicked by a player.
The sceneFrame is required for the OnCollision callback, the UpdateScene callback etc. The rest of the time is handled Internally but is good to know is there! isnt ?
*Levels
"Wait a minute! Ok I got the Canvas, GUi, SceneWindow thingie, I even understood the camera and the SceneFrame part, But where do I place my characters, players, how does TGB knows where those are at? and how can I change them to create the progression of a complete game?"
Ah! great question there, really easy to answer though, in order to accomodate your game characters, effects, tile maps, particles, etc. In the same way that will be shown to the player, TGB uses files called _levels_
Although levels may seem fairly complex, they are just a collection of instructions to place certain objects in a certain spot, the rest of the code is handled in our resources and datablocks
A single project may have a TON of levels which can be used to progress in your game (as scenes in a movie), or to display different locations (per example in an adventure game or an RPG)
by default each time you load TGB you load the level editor in the last level from the last project you were working on. thanks to this code in your main.cs file:
If you want to avoid that, all you have to do is to comment out this code, just remember you wont be able to use the editor without it.
Lets focus in the last part:
which actually calls this function in game.cs:
What that basically does is to load a level filename compiled (*.dso) or uncompiled to your targetted sceneWindow.
You can use this same code to load any level at any time during your game, just one thing. Since the level basically holds the whole structure your game is standing on, it is wise, to give it time to settle things before. laoding. So in order to load a level within a game you can schedule instead. like this:
What is that Schedule thing you say? oh we will get there right away.
*Busy Schedules.
(explaining schedules and its uses)
*Lets get Physical! (yeah I know, its corny)
(explaining physics slightly)
Outro:
Well thats it, with the knowledge of how things are handled internally in TGB and by following the tutorials over at TDN, you have all the knowledge needed to get you started , now is up to you. What is it you would like to do? the next coolest indie RPG? a great shoot em up? a visceral fighting game? the sky is the limit. And remember once you can, give back to the community. We can all make TGB better every day.
German Cons. (AzraelKans) 2005
-----------
So thats it, thats the first draft for the: "Understanding TGB" Sorry I couldnt make it a little less longer. I hope you like it, and point out any errors (except spelling please, I havent spell checked this :) ) , you may find, I intent to place this in the TDN once is done.
09/19/2006 (12:54 pm)
Part 3.*Out of sight, out of mind.
So thats all theres to it right? well... not quite
for any regular 2d engine, the above mechanics will be more than enough features, but for TGB we are just getting started.
Imagine we made a shooter using TGB as we've seen so far, how would we manage to move the entire background objects just so we can provide the illusion of going forward, if we would do a platform game or an RPG where the screen could go anywhere we would have a whole lot of objects to move around would we?
Of course in TGB that is not the case ...
The CAMERA
Instead of moving our objects around, we have a CAMERA object, the camera simply tells TGB what to render in our T2Dscenewindow and transforms those objects from Scene Space to Camera space (and to Canvas space) and functions exactly like a real camera does, when you move the camera to the left you will see the entire level in the camera move right, revealing the left portion of your level. When you move the camera right, you will reveal the right portion, up, down, etc. I think you get the point.
Theres a nice plus to that, since we know we only have to draw what is seen by the camera, everything not in camera view can be clipped away! thus making our game more efficient, faster and our players happier ;)
(note:Theres just one detail to notice, if your camera size is not the same size that your targetted SceneWindow some scaling or clipping may occur, you may want to check on that.)
Scene Frames
Speaking of clipping: remember we mentioned we could have a whole lot of objects in our level? well as you may know, TGB can check for the collisions between all the objects in the level, as soon as they have their collision flag on. but what happens if we have an impossible collision?
Per example a football and a goal post all the way to the other side of the football field? of course you want to know if they collide (even if its not in the camera) but unless we live in a parallel universe theres little chance of the football colliding with the goal by simply standing there.
To prevent this from happening, each Scene is divided in something called "SceneFrames" think of it like a restriction grid where only objects inside a grid square are allowed to play with each other. That way you Will never check if the football standing at the beggining of the field can collide with the goal, they are not in the same grid square! they can only collide if the football moves all the way to the goal square per example when the ball is kicked by a player.
The sceneFrame is required for the OnCollision callback, the UpdateScene callback etc. The rest of the time is handled Internally but is good to know is there! isnt ?
*Levels
"Wait a minute! Ok I got the Canvas, GUi, SceneWindow thingie, I even understood the camera and the SceneFrame part, But where do I place my characters, players, how does TGB knows where those are at? and how can I change them to create the progression of a complete game?"
Ah! great question there, really easy to answer though, in order to accomodate your game characters, effects, tile maps, particles, etc. In the same way that will be shown to the player, TGB uses files called _levels_
Although levels may seem fairly complex, they are just a collection of instructions to place certain objects in a certain spot, the rest of the code is handled in our resources and datablocks
A single project may have a TON of levels which can be used to progress in your game (as scenes in a movie), or to display different locations (per example in an adventure game or an RPG)
by default each time you load TGB you load the level editor in the last level from the last project you were working on. thanks to this code in your main.cs file:
// Remove the following four lines if you would like to start the game without running the
// level builder.
if ($runWithEditors)
{
toggleLevelEditor();
return;
}
// This is where the game starts. Right now, we are just starting the first level. You will
// want to expand this to load up a splash screen followed by a main menu depending on the
// specific needs of your game. Most likely, a menu button will start the actual game, which
// is where startGame should be called from.
startGame($levelEditor::LastLevel[$currentProject]);If you want to avoid that, all you have to do is to comment out this code, just remember you wont be able to use the editor without it.
Lets focus in the last part:
startGame($levelEditor::LastLevel[$currentProject]);
which actually calls this function in game.cs:
if( isFile( %level ) || isFile( %level @ ".dso"))
sceneWindow2D.loadLevel(%level);What that basically does is to load a level filename compiled (*.dso) or uncompiled to your targetted sceneWindow.
You can use this same code to load any level at any time during your game, just one thing. Since the level basically holds the whole structure your game is standing on, it is wise, to give it time to settle things before. laoding. So in order to load a level within a game you can schedule instead. like this:
sceneWindow2D.schedule(100,"loadLevel","yourGame/data/levels/levelX.t2d");
What is that Schedule thing you say? oh we will get there right away.
*Busy Schedules.
(explaining schedules and its uses)
*Lets get Physical! (yeah I know, its corny)
(explaining physics slightly)
Outro:
Well thats it, with the knowledge of how things are handled internally in TGB and by following the tutorials over at TDN, you have all the knowledge needed to get you started , now is up to you. What is it you would like to do? the next coolest indie RPG? a great shoot em up? a visceral fighting game? the sky is the limit. And remember once you can, give back to the community. We can all make TGB better every day.
German Cons. (AzraelKans) 2005
-----------
So thats it, thats the first draft for the: "Understanding TGB" Sorry I couldnt make it a little less longer. I hope you like it, and point out any errors (except spelling please, I havent spell checked this :) ) , you may find, I intent to place this in the TDN once is done.
#3
is scenegraph not sceneframe. sorry about that
Well.. Im going to assume no one is interested in this tutorial, since I havent got any comments.
Thanks for reading.
09/22/2006 (8:46 am)
Oops. big bug is scenegraph not sceneframe. sorry about that
Well.. Im going to assume no one is interested in this tutorial, since I havent got any comments.
Thanks for reading.
#4
10/08/2006 (5:18 pm)
I think this is a great mini tutorial... you should check out the TDN Mini Tutorials and how they are put together in the template and post one :) TDN is community and employee driven so you're always -more- than welcome to post great resources like this there :)
#5
If you really don't want to do any more with it, I would volunteer to get it into TDN so it's not lost effort.
- Don
10/08/2006 (6:37 pm)
Ooh, yeah, don't abandon this tutorial for lack of comment! This is the first time I've seen it, and I must say it's very nicely done. As an artist, it's taken me a long time to get my head around TGB and Torquescript, and this covers a lot of the concepts that I struggled to get to grips with.If you really don't want to do any more with it, I would volunteer to get it into TDN so it's not lost effort.
- Don
#6
Some suggestions:
Diagrams would really help, like something showing the hierarchy of TGB at various levels. Here's a quicky I made up on giffy (couldn't resist) for the canvas level hierarchy:
www.gliffy.com/publish/1082446/L
It's probably not correct, but you get the idea.
Also, if you want to move it over to TDN I'd be happy to proof it for you so it reads better.
10/08/2006 (8:21 pm)
This is the kind of information I wanted before diving into the tutorials. The current TGB tutorials are nice, but they all take a paint-by-numbers approach to teaching and I was always one of those kids that would paint one section 9 yellow and the other 9 green, just to see what it would look like. What you've started here feels more like a true art lesson, keep it up!Some suggestions:
Diagrams would really help, like something showing the hierarchy of TGB at various levels. Here's a quicky I made up on giffy (couldn't resist) for the canvas level hierarchy:
www.gliffy.com/publish/1082446/L
It's probably not correct, but you get the idea.
Also, if you want to move it over to TDN I'd be happy to proof it for you so it reads better.
#7
Thanks for the great comments, of course I will be very glad to place this in the TDN I just dont know how, if someone could start to post this over at tdn it would be a lot of help. Of course I wouldnt mind at all ;)
Once in TDN we can modify and add the info that is missing from here, the diagram posted by cameron is a great example of that.
Once this is posted at tdn please link it here so we can follow up the tutorial.
Once again thanks for the great comments. glad to help the torque community. ;)
10/11/2006 (11:17 am)
Wow, sorry for not answering I havent seen this thread in a while.Thanks for the great comments, of course I will be very glad to place this in the TDN I just dont know how, if someone could start to post this over at tdn it would be a lot of help. Of course I wouldnt mind at all ;)
Once in TDN we can modify and add the info that is missing from here, the diagram posted by cameron is a great example of that.
Once this is posted at tdn please link it here so we can follow up the tutorial.
Once again thanks for the great comments. glad to help the torque community. ;)
#8
The title didn't make the thread seem inviting to me... especially since it was in the getting started section. Something about the title made it seem like you wanted help understanding a minitutorial... and with that in mind the first sentence looked like you were about to go into a rant (something I've been guilty of more than once). I think that might reason for why this began so silent.
Keep plugging away and get it on TDN! Nice work and nice graphical contributions!
10/11/2006 (1:52 pm)
Easy to understand beginners' reference.The title didn't make the thread seem inviting to me... especially since it was in the getting started section. Something about the title made it seem like you wanted help understanding a minitutorial... and with that in mind the first sentence looked like you were about to go into a rant (something I've been guilty of more than once). I think that might reason for why this began so silent.
Keep plugging away and get it on TDN! Nice work and nice graphical contributions!
#10
10/11/2006 (5:37 pm)
Add this in TDN! Nice tutorial!
Torque Owner AzraelK
Part 2.
*The TGB GUI and the rendering Hierarchy.
The main base of all work in the T2dEngine is _the canvas_ as the name may imply this is where all our drawing will be done.
However in order to know what will be painted where, we need to have a layout of how each element in our screen This is called the GUI (Graphical User Interface) you usually set the GUI to the canvas with the:
setCanvas(GUIcontrol) command.
Inside the GUI we can place all kind of elements and controls such as buttons, bitmaps, texts, etc as well as their Z order (which one is on top of which) and even their behavior (for buttons per example)
However the most important element in the GUI is the t2dsceneWindow this is where all the rendering of our game objects (Dont confuse with GUI objects ) will take place. Think of it like a little monitor that show us a view of our game .
Our SceneObjects can be bitmaps, animated bitmaps, particles, tilemaps, 3d objects etc. they are automatically drawn in the SceneWindow each time a SceneUpdate occurs.
Since TGB is so flexible is posible to have more than one SceneWindow in one GUI it even is possible to have none (per example for your main menu screen) however most of the time the MainScreen Gui will have one Scene Window.
This is why when you create a new Scene Object you have to tell it which scene it belongs to.
So the BASIC hierarchy is:
CANVAS
-----GUI
-------GUIObject
-------SceneWindow
---------SceneObject
As I said TGB is very flexible so you can have as Many GUIs as you may want in each project.
Actually: you probably havent noticed, but each time you load TGB the editor you are seeing is a common GUI which was made for you to edit and modify your own games! you are using the same engine to Edit and Run your game! how cool is that?
--