TGE poorly documented
by Arild Pihl · in Torque Game Engine · 03/28/2007 (4:33 pm) · 83 replies
I'm hoping someone out there can prove me wrong, but in my opinion Torque is very poorly documented. The only documentation that came with the engine, are scattered comments in the code and scripts, and a 16 page PDF file that tells us how to create a terrain, put a Torque logo in, and how to make a script that enables the player to pick up the logo. The tutorial also mentions that the onCollision function is automatically called by the engine when two objects collides. But are there other functions like this? I've been searching for a complete list of all functions, parameters and stuff like that, but as far as I can tell, there aren't any. I have bought both "3D game programming all in one" and "The game programmers guide to Torque", but I'm still having problems finding the information I need. I feel both these books have a "If you write this, this will happen"-approach to teaching. "The game programmers guide to Torque" does have an appendix on the disc that comes with it, and the "Quick Reference" is the closest to any proper documentation I've found. The TDN that I've supposedly paid $150 to, is in fact only partly completed, and in addition, on the top is a note that says it "will all be replaced with content from Elixir very soon. So it is unnecessary to further expand this article.". This comment is dated October 2005. Not really impressive either. The link to the Elixir page works, but links to an article about why Elixir was chose over Wiki.
Of course we have these forums. But after reading them, I often encounter people with questions like "Where are the engine, I can only find the Torque Demo", and this tells me that there definitely are others out there that could use better documentation too.
The problem I have now is WheeledVehicle. I have made a new simple DTS object to use as a Vehicle, and another one for the tire. Then I changed the car.cs file so that these two objects where loaded in stead, hoping that it would be that easy. But no. This resulted in the car bouncing around uncontrollably, so I started changing the variables in the WheeledWehicleTire, WheeledWehicleSpring and WeeledVehicleData. But that only resulted in either more uncontrollable bouncing/shaking, the car bouncing off into outer space, or the car actually falling straight through the terrain and continuing down. And since I have no documentation, I have very little idea what the variables should be set to! For instance, one article I have read says that the "antiSwayForce = 1.0" will make the car come to a standstill in one second. But I have read through other peoples examples, and found values as high as 3000!
Hopefully someone will understand my frustration and give me a link or a file, or something magical that I must have overseen while reading books and forums for the past month or so.
Any help will be greatly appreciated!
A.P.
Of course we have these forums. But after reading them, I often encounter people with questions like "Where are the engine, I can only find the Torque Demo", and this tells me that there definitely are others out there that could use better documentation too.
The problem I have now is WheeledVehicle. I have made a new simple DTS object to use as a Vehicle, and another one for the tire. Then I changed the car.cs file so that these two objects where loaded in stead, hoping that it would be that easy. But no. This resulted in the car bouncing around uncontrollably, so I started changing the variables in the WheeledWehicleTire, WheeledWehicleSpring and WeeledVehicleData. But that only resulted in either more uncontrollable bouncing/shaking, the car bouncing off into outer space, or the car actually falling straight through the terrain and continuing down. And since I have no documentation, I have very little idea what the variables should be set to! For instance, one article I have read says that the "antiSwayForce = 1.0" will make the car come to a standstill in one second. But I have read through other peoples examples, and found values as high as 3000!
Hopefully someone will understand my frustration and give me a link or a file, or something magical that I must have overseen while reading books and forums for the past month or so.
Any help will be greatly appreciated!
A.P.
Thread is locked
#62
04/11/2007 (9:45 pm)
We often will give out free licenses of GG products to those who contribute, especially to documentation :) I guess we could be more public about it, though we try to ensure its more quality documentation than just spam. 
#64
04/11/2007 (10:13 pm)
Berserk, I wasn't saying you had. I was saying that all of the features you listed are resourced there, which make example code, even if piece-meal, friendly. 
#65
After reading this post I went over to the Unity website, just to see the difference and I couldn't believe how well documented it was at least for some one who is completely unfamiliar with it, and that's just on their main website. Now in saying that, according to MB6019 we should have to buy 3 different books to get documentation on the engine we all bought. I know every little question cant be answered, but the Torque documentation should be at least updated from version 1.3 or earlier.
Speaking of updated things, why is it that I have the commercial version, but I don't have the "commercial" tag like everyone else?
04/11/2007 (10:17 pm)
Well, as a fairly new person in Torque, I'll have to agree with the others here and say Torque isn't very well documented. I have the commercial version of TGE and for the money I paid, along with finding out that the RTS kit was unsupported "after" I purchased it, I'm a bit disappointed at the documentation. Don't get me wrong, I'm happy so far with Torque. The community for the most part is very helpful. After reading this post I went over to the Unity website, just to see the difference and I couldn't believe how well documented it was at least for some one who is completely unfamiliar with it, and that's just on their main website. Now in saying that, according to MB6019 we should have to buy 3 different books to get documentation on the engine we all bought. I know every little question cant be answered, but the Torque documentation should be at least updated from version 1.3 or earlier.
Speaking of updated things, why is it that I have the commercial version, but I don't have the "commercial" tag like everyone else?
#66
04/11/2007 (10:20 pm)
@MB6019 - Something that is already free is very little insentive to those with knowledge. Very nice of GG though. ;)
#67
it is solely mac based, which is a problem
what other new games engines created within the last few years has good documentation?
I would like to compare
thanks
04/12/2007 (3:27 am)
I heard the unity engine mentioned, the documentation looks goodit is solely mac based, which is a problem
what other new games engines created within the last few years has good documentation?
I would like to compare
thanks
#68
04/12/2007 (3:53 am)
In my opinion its not the lack of docs. The problem is that almost all docs and resources are WAYYY obsolete... I mean most of the things are from 2005-2006... for torque 1.5 there is almost nothing... I'm happy with torque in general but I have to agreed that in doc/resources torque is way behind that some competition...
#70
Ofcourse, you can find most of this info after some searching, but it's not anywhere in an easy to find place. Instead, one of the docs shipped with the engine "recommend" modifying the example games. I really wouldn't recommend that as the examples are incomprehensible spaghetti code for anyone new to the concepts and jargon of the engine.
If any documentation were to be written I'd focus on a new beginners doc. Step one, how do I compile without the examplegame? Step two, how do I initialize the engine without all the "common" stuff? Step three, what is the concept behind the "canvas" and how do I make my first GUI/button and what controls are available?
All simple and trivial things, but they add up to a better understanding of the engine.
Perhaps a tutorial series at a level of nehe.gamedev.net. Simple, trivial things, but incredibly valuable as a resource to learn the concepts.
04/12/2007 (5:45 am)
Personally I am missing a comprehensible overview about the basic operation and concepts of the engine. Which callbacks are made to the TorqueScripts and when? How is the initialization of the engine done in script? How do I mount objects to other objects? What are the limitations of mounting? Things like that.Ofcourse, you can find most of this info after some searching, but it's not anywhere in an easy to find place. Instead, one of the docs shipped with the engine "recommend" modifying the example games. I really wouldn't recommend that as the examples are incomprehensible spaghetti code for anyone new to the concepts and jargon of the engine.
If any documentation were to be written I'd focus on a new beginners doc. Step one, how do I compile without the examplegame? Step two, how do I initialize the engine without all the "common" stuff? Step three, what is the concept behind the "canvas" and how do I make my first GUI/button and what controls are available?
All simple and trivial things, but they add up to a better understanding of the engine.
Perhaps a tutorial series at a level of nehe.gamedev.net. Simple, trivial things, but incredibly valuable as a resource to learn the concepts.
#71
04/12/2007 (7:11 am)
People who defend it buy saying buy a book are a little crazy. When you buy other products do you expect to get them home and then go where's the docs? Oh I have to go buy 3 books to use this now. No. That isn't how bussiness is done. It is a poor defense (I know it's coming from users and not GG) and can't ever understand people who go ya that makes sense. I wouldn't ever buy a product of any kind if people told me ahead of time you have to then buy 3 books to know how to use it. 
#72
04/12/2007 (7:15 am)
That is the point, Sears. People pull all kinds of arguments just because they think they have to defend something, when not even the ones they defend claim the same things. I call them fanboys, but I am sure there is a better word for it.
#73
UDN
Written by the makers, and cover all basics for utilizing the engine and its functions.
Cover the editors and even, some times 3d apps for setting up models ETC..
Don't take my comments as saying that you need to teach people how to user there 3d app of choice, im talking about everything after that, such as where to place your model, what scripts to change ETC.
- Setting up your character in *** modeling app to export the following proper data:
-- model mesh data
-- texture data
-- detail levels
-- collision data
-- bounds
-- animation data
All of the above is documenting your proprietary model format, every other engine has this....
- Placing the .dts and texture data in the proper location
- Modify the player scripts in case do/don't have external .dsq animations
- Modify the datablock scripts reference the player mesh
This is all engine specific documentations, and the very basic of what needs to be documented.
None of this is documented other than piecing together things from the forums.
And i hate to say it, or to be rude. But how long has the engine been in the hands of GG?
I think its been about what, 4-6 years now? When are you guys going to "Sacrifices" the time to wright some decent docs?
Just sayin'
04/12/2007 (8:15 am)
@Matthew Langley UDN
Written by the makers, and cover all basics for utilizing the engine and its functions.
Cover the editors and even, some times 3d apps for setting up models ETC..
Don't take my comments as saying that you need to teach people how to user there 3d app of choice, im talking about everything after that, such as where to place your model, what scripts to change ETC.
- Setting up your character in *** modeling app to export the following proper data:
-- model mesh data
-- texture data
-- detail levels
-- collision data
-- bounds
-- animation data
All of the above is documenting your proprietary model format, every other engine has this....
- Placing the .dts and texture data in the proper location
- Modify the player scripts in case do/don't have external .dsq animations
- Modify the datablock scripts reference the player mesh
This is all engine specific documentations, and the very basic of what needs to be documented.
None of this is documented other than piecing together things from the forums.
And i hate to say it, or to be rude. But how long has the engine been in the hands of GG?
I think its been about what, 4-6 years now? When are you guys going to "Sacrifices" the time to wright some decent docs?
Just sayin'
#74
... and so do we:
www.garagegames.com/developer/torque/artist/
also some of these same docs have been in the older official area as well, here:
www.garagegames.com/docs/tge/general/pt05.php
It's also on TDN
tdn.garagegames.com/wiki/DTS/3dsmax/Creating_a_Simple_Character
The above TDN article talks about this, also the previous tutorials (at least the Max one that Joe did a while ago, includes files that nicely allow you to switch out the player model and scripts for your tutorial/test ones.
Really? I guess I must've made up what I just linked to within the past few minutes.
My point wasn't that we didn't cover that, my point was that you listed it as an easy and simple thing, yet it is far from it...
This is why I don't typically respond to these posts, I was in the community 1 1/2 - 2 years before coming to GG (over half of GG interned as well)... I definitely know what you are talking about. I learned TGE the hard way as well... in fact most of the docs that are here now weren't there when I was learning. I learned how to export characters from Max and Blender (boy was that painful), scripting, modifying the source, making a game demo, etc... Believe me, I know the docs are lacking in many ways, I have said it multiple times (please actually read my posts)... though the docs simply are not as bad as some people say. To prove my point you said:
In 5-10 minutes I found the docs that apparently didn't exist... maybe instead of complaining about things that might be there try looking for them. To those th at represent the concern in a valid way I can relate, again I learned the engine the hard way too, thats why I've been so dedicated to improving our docs on the TGB front. Docs take a lot of time... and we aren't saying they aren't important, we are saying that we know they are and we do want to do them, though obviously we just haven't had the chance to do so... I haven't created a single TGE doc, I've been working on TGB docs... TGB is a much lower level and more entry level engine, it needs more solid docs.
04/12/2007 (8:36 am)
Quote:All of the above is documenting your proprietary model format, every other engine has this....
... and so do we:
www.garagegames.com/developer/torque/artist/
also some of these same docs have been in the older official area as well, here:
www.garagegames.com/docs/tge/general/pt05.php
It's also on TDN
tdn.garagegames.com/wiki/DTS/3dsmax/Creating_a_Simple_Character
Quote:This is all engine specific documentations, and the very basic of what needs to be documented.
The above TDN article talks about this, also the previous tutorials (at least the Max one that Joe did a while ago, includes files that nicely allow you to switch out the player model and scripts for your tutorial/test ones.
Quote:None of this is documented other than piecing together things from the forums.
Really? I guess I must've made up what I just linked to within the past few minutes.
My point wasn't that we didn't cover that, my point was that you listed it as an easy and simple thing, yet it is far from it...
This is why I don't typically respond to these posts, I was in the community 1 1/2 - 2 years before coming to GG (over half of GG interned as well)... I definitely know what you are talking about. I learned TGE the hard way as well... in fact most of the docs that are here now weren't there when I was learning. I learned how to export characters from Max and Blender (boy was that painful), scripting, modifying the source, making a game demo, etc... Believe me, I know the docs are lacking in many ways, I have said it multiple times (please actually read my posts)... though the docs simply are not as bad as some people say. To prove my point you said:
Quote:
None of this is documented other than piecing together things from the forums.
In 5-10 minutes I found the docs that apparently didn't exist... maybe instead of complaining about things that might be there try looking for them. To those th at represent the concern in a valid way I can relate, again I learned the engine the hard way too, thats why I've been so dedicated to improving our docs on the TGB front. Docs take a lot of time... and we aren't saying they aren't important, we are saying that we know they are and we do want to do them, though obviously we just haven't had the chance to do so... I haven't created a single TGE doc, I've been working on TGB docs... TGB is a much lower level and more entry level engine, it needs more solid docs.
#75
04/12/2007 (8:44 am)
Well, I agreed that almost all the docs DO exist. But... most of them are way outdate and to work some need a major revamp.... When I say docs I mean offical docs and also resources because most of the resources are way to old so that a beginner can modify them to fit the new versions of torque, but this is something outside the responsability of GG of course.
#76
I (and other GGers) completely agree :)
What I usually find funny (not implying you Fallen) is when people think we are ignorant to issues we may have, especially when in fact we have recognized it for quite a while but simply are waiting until we have the time/resources to dedicate to it.
04/12/2007 (8:47 am)
Quote:most of them are way outdate and to work some need a major revamp
I (and other GGers) completely agree :)
What I usually find funny (not implying you Fallen) is when people think we are ignorant to issues we may have, especially when in fact we have recognized it for quite a while but simply are waiting until we have the time/resources to dedicate to it.
#77
all things considered, I think GG does a decent job of easing new developers into torque without overwhelming them.
04/12/2007 (8:53 am)
One of the reasons torque is hard to fully document is because it's so big. if someone were to *fully* document torque this "torque superbible" would have to give detailed explanations of all script functions, object classes/methods(including all bazillion of the different gui classes), datablocks(including explanations for all datablock parameters), gui profiles, callbacks, export options and practices for all supported modeling programs, export-dependent functionality like animations and ifl's for all supported modeling programs, and last but not least, torquescript language syntax. add on top of that torque-specific intermediate concepts like blend animations vs non-blended, datablock inheritance, and server vs client commands. anyone who knows torque well must realize that this document would be huge. and ya know what, that's not even including the source code! add in a detailed explanations of all the source code and you're probably talking about a document astronomical in size. would people here really prefer that?all things considered, I think GG does a decent job of easing new developers into torque without overwhelming them.
#78
Making docs is actually a lot of work, and we are working toward making them not only useful, but setting ourselves up to be able to maintain them well.
It was decided early on not to try to work on on the docs for all the engines at once. Not knowing the resource requirements, and not wanting to get everything half done and call it good, we chose to attack the creation of the newer docs sequentially.
As had been stated before, we are not ignorant of the problem, nor are we sitting around not doing anything about it. We had a plan to get great docs for TGB, and we executed on it (actually Matt executed on it). When we started, we did not know how long it would take, or what the issues were, but we learned, and in fact, we learned enough to use the same doc framework for TorqueX.
We have heard what everyone is saying here, and we are working on getting there.
04/12/2007 (8:59 am)
Just wanted to add some comments here. Go take a look at the TGB docs and the TorqueX docs. This is the direction we have been going. Both TGB and TorqueX were much smaller undertakings in terms of creating the documentation, and were actually good testbeds for us to understand the scope of a doc or tutorial, as well as issues relating to keeping them updated and current.Making docs is actually a lot of work, and we are working toward making them not only useful, but setting ourselves up to be able to maintain them well.
It was decided early on not to try to work on on the docs for all the engines at once. Not knowing the resource requirements, and not wanting to get everything half done and call it good, we chose to attack the creation of the newer docs sequentially.
As had been stated before, we are not ignorant of the problem, nor are we sitting around not doing anything about it. We had a plan to get great docs for TGB, and we executed on it (actually Matt executed on it). When we started, we did not know how long it would take, or what the issues were, but we learned, and in fact, we learned enough to use the same doc framework for TorqueX.
We have heard what everyone is saying here, and we are working on getting there.
#79
BTW, i had already read those, and most were not there when i started, and they still don't help anyone but those able to afford 3ds MAX.
I have written some TDN articles myself, that answer specific questions with specific applications, and generically cover a method or topic usable for any application.
When i say "Its poorley documented" im placing myself in the position of the new user, who, is completely disappointed that this stuff is so scattered, and generally, not usefully.
I don't think the issue is that people think your ignorant of the situation, i think its has more to do with nothing has been done.
Currently, the best, and most useful documentation is provided by 3ed party authors, not by GG. Mabye this is a marketing thing, i don't know.
But theres an issue, and its been brought up many, many times...so it evident it persists...
TGE needs documentation and tutorials on par with UDN.
On the flip side, GG will get better games, more often and every one wins.
Take a look at the feedback in this thread, and make a non-defensive decision.
04/12/2007 (9:00 am)
If every time someone says that the lack of documentation is bad you say "Stop complaining". I can see why people keep bringing it up. BTW, i had already read those, and most were not there when i started, and they still don't help anyone but those able to afford 3ds MAX.
I have written some TDN articles myself, that answer specific questions with specific applications, and generically cover a method or topic usable for any application.
When i say "Its poorley documented" im placing myself in the position of the new user, who, is completely disappointed that this stuff is so scattered, and generally, not usefully.
I don't think the issue is that people think your ignorant of the situation, i think its has more to do with nothing has been done.
Currently, the best, and most useful documentation is provided by 3ed party authors, not by GG. Mabye this is a marketing thing, i don't know.
But theres an issue, and its been brought up many, many times...so it evident it persists...
TGE needs documentation and tutorials on par with UDN.
On the flip side, GG will get better games, more often and every one wins.
Take a look at the feedback in this thread, and make a non-defensive decision.
#80
In my opinion (and I know that I don't have the facts to support my idea) is that GG have too many projects for the size of the company... TGE, TGB, TA, RTS kit (my dear ... I hate GG for this one...eheh), etc, etc...
I know that's the way a company make money, without new products the cash flow will fall. But I think that is time to make a revamp on the docs and so... but again... theoretically is simple to do this, hold the projects and do the revamp, but... its not that easy to make a company be profitable... I think we all have to wait and hope for a revamp on something's. Just keep a good pace working ;)
04/12/2007 (9:03 am)
Time... that horrible thing that passes by without trace... In that case I'm with the gg employees (and I'm not a GG fun boy). In my opinion (and I know that I don't have the facts to support my idea) is that GG have too many projects for the size of the company... TGE, TGB, TA, RTS kit (my dear ... I hate GG for this one...eheh), etc, etc...
I know that's the way a company make money, without new products the cash flow will fall. But I think that is time to make a revamp on the docs and so... but again... theoretically is simple to do this, hold the projects and do the revamp, but... its not that easy to make a company be profitable... I think we all have to wait and hope for a revamp on something's. Just keep a good pace working ;)
Torque 3D Owner Dark Tengu