Why WAS Torque3D documentation so poor?
by Dark Tengu · in Torque 3D Professional · 03/02/2010 (6:38 pm) · 442 replies
I would really like to get back into Torque, but I am finding the documentation to be so poor. For example, where is the explanation of callbacks? If I remember correctly, callbacks are HIGHLY important in Torque. Its great that there is an explanation of Torque syntax, but honestly synatax is VERY easy to figure out for anyone who has done even a little C/C++.
Perhaps I am just missing the quality documentation, any help would be appreciated. The only documentation regarding Torque3D I have found is at the following link:
http://docs.torquepowered.com/torque-3d/official/index.html
Moderator Edit - You can download the draft version of the T3D Script Manual by clicking here
Perhaps I am just missing the quality documentation, any help would be appreciated. The only documentation regarding Torque3D I have found is at the following link:
http://docs.torquepowered.com/torque-3d/official/index.html
Moderator Edit - You can download the draft version of the T3D Script Manual by clicking here
#102
The thing is Sean, that everybody here is really in the known of your constant angry mood towards the world, and quite frankly, your out of place manners are totally boring by now.
You can stay and keep your catharsys going until someone gets really tired of you (you were near depleting patience a couple of times by now) or you can start seeing all your bitching as the real useless thing it is, and start thinking more constructively.
03/12/2010 (7:07 am)
Eric was answering specifically to pilot, who mentioned specifically that a week passed with no news. This is logic, as GG now is full headed to GDC.The thing is Sean, that everybody here is really in the known of your constant angry mood towards the world, and quite frankly, your out of place manners are totally boring by now.
You can stay and keep your catharsys going until someone gets really tired of you (you were near depleting patience a couple of times by now) or you can start seeing all your bitching as the real useless thing it is, and start thinking more constructively.
#103
03/12/2010 (9:33 am)
@Novack - I think there is just a massive amount of frustration with GG and documentation. I have been waiting years for quality documentation and they have yet to surface. I have faith in GG, they need docs sooner rather than later or they will lose even more market share to Unity.
#104
But right now, we have this scenario, where Eric and Michael are saying "we are working on it, but we need time, we need a couple of things to settle down".
People can choose what to do next, but I think only one option is really constructive, hence, smart. I just choose to believe them.
From that point, I dont seriously expect things to change in the lapse of a week, thats silly. Torque is a framework, one of the bests in its area, and so vast in their 'extension' that a serious documentation effort will take time.
03/12/2010 (10:32 am)
Jon D, I agree. Actually, I share that frustration.But right now, we have this scenario, where Eric and Michael are saying "we are working on it, but we need time, we need a couple of things to settle down".
People can choose what to do next, but I think only one option is really constructive, hence, smart. I just choose to believe them.
From that point, I dont seriously expect things to change in the lapse of a week, thats silly. Torque is a framework, one of the bests in its area, and so vast in their 'extension' that a serious documentation effort will take time.
#105
03/12/2010 (10:53 am)
Novack, I understand they are saying that they are working on it. GG have been saying that for the past 5 years and we still have little to show for it. I purchased Torque3D because they promised great documentation and we have yet to see documentation that I would even consider 'okay' documentation. The documentation is outright horrible and not even in close to thorough. I agree that we can't expect things to change in a week, but I think owners of T3D have the right to expect documentation sooner rather than later. It just isn't a priority to GG. Actions speak louder than words. They can say that they are working on it, but until I see the documentation, it will be hard for me to believe it. I have heard this excuse for over 5 years now. The only reason why I'm here, is because I believe in T3D. GG can't afford to fail.
#106
They have been announcing good documentation since the announcement of T3D, true. So they are the biggest mythomaniacs in the industry, or something else has happened, that delayed the docs.
I know for certain, that things happened. Change of CEO, change of city, change of manager, change of lead programmer, more people leaving, more people coming, Holydays, GDC... and in the middle, an engine that just *now* is development stable enough as to start considering documenting.
Can GG afford to fail? I dont know, Im not the one to jugde that, and those are not the terms in which I feel this debate should develop. I think we should do this, debate about our needs, but focusing in constructive feedback.
03/12/2010 (11:17 am)
So you are basically noticing no difference from 5 years ago to now?They have been announcing good documentation since the announcement of T3D, true. So they are the biggest mythomaniacs in the industry, or something else has happened, that delayed the docs.
I know for certain, that things happened. Change of CEO, change of city, change of manager, change of lead programmer, more people leaving, more people coming, Holydays, GDC... and in the middle, an engine that just *now* is development stable enough as to start considering documenting.
Can GG afford to fail? I dont know, Im not the one to jugde that, and those are not the terms in which I feel this debate should develop. I think we should do this, debate about our needs, but focusing in constructive feedback.
#107
I guess all I'm trying to say is they know what we need. I don't understand why it is too much to ask for $1000 software to get documentation for it. This is why Unity is having so much success, they made it easy and the word spread.
No amount of features in T3D will grow it at this point. It already has a lot of great features. What is hurting them is reading on game development sites that there is little to no documentation for the engine. This keeps a lot of potential buyers from making the leap into T3D.
I know a lot of people say that T3D is by far superior to Unity because of source access. With Unity you really don't need source access. It is a very easy to use and do what you want in its current form. Plus, how many hobbyists/indies have the resources to make massive source changes. With Torque3D you really do need the source, but that isn't the case with Unity.
In short, they just need to do it. All companies are limited by resources and time. They just need to do it like others have done it. No excuses.
03/12/2010 (11:26 am)
Very little difference actually. In fact, I have less than I had with TGE/TGEA now. I have scripting references for TGE/TGEA that are no longer up to date. Yes, those can get me 80% of the way there, but I need something that is up to date. I guess all I'm trying to say is they know what we need. I don't understand why it is too much to ask for $1000 software to get documentation for it. This is why Unity is having so much success, they made it easy and the word spread.
No amount of features in T3D will grow it at this point. It already has a lot of great features. What is hurting them is reading on game development sites that there is little to no documentation for the engine. This keeps a lot of potential buyers from making the leap into T3D.
I know a lot of people say that T3D is by far superior to Unity because of source access. With Unity you really don't need source access. It is a very easy to use and do what you want in its current form. Plus, how many hobbyists/indies have the resources to make massive source changes. With Torque3D you really do need the source, but that isn't the case with Unity.
In short, they just need to do it. All companies are limited by resources and time. They just need to do it like others have done it. No excuses.
#108
03/12/2010 (3:48 pm)
I've been here since 2006. The only change I've seen is video guides. We're not lying when we say there have been promises for years now. I'm waiting on action now since no more promises has been promised. And I'm very glad that I only dropped $100 to upgrade. Yep, unity costs a lot more, but since I've registered over there I've received about 3 emails or so pointing me to reference guides, solid tutorials, etc. And within 2 minutes I found the code to hook into a database. Not too shabby over there at unity.
#109
03/12/2010 (4:20 pm)
I think Torque3D is the better product, but Unity's customer service and education isn't even comparable. Unity as a company just seems to be more on the ball.
#110
The company as such, has little to do with the GG from two years ago, so: is even worth of something putting on the table the promises of 4 years ago, when we are talking about -virtually- a totally diferent company?
Thinking constructively push me to set aside history, to the pragmatism of the new situation: is all set, they need time now.
03/12/2010 (6:58 pm)
Just for reference, I wasnt asking if were changes in the docs, but in the context.The company as such, has little to do with the GG from two years ago, so: is even worth of something putting on the table the promises of 4 years ago, when we are talking about -virtually- a totally diferent company?
Thinking constructively push me to set aside history, to the pragmatism of the new situation: is all set, they need time now.
#111
Yes, they need time and they have time. Keep in mind that although T3D was released a relatively short time ago, T3D was announced over a year ago.(Jan 09 I believe) Documentation has been in the works since July of last year. JULY! That's a period of the last 8 months they've been working on documentation for an engine that's been in the works for the last 15 months, an engine which is really just an upgrade of their previous engine. if 8 months hasn't been long enough, just how long is it supposed to take? really? you can only string people along for so long until things come to a head.
understand this is not an issue of scope. as large as torque is, it definitely could've been documented fully within the last 8 months. at the very least, a full script reference couldve been done by now.
no, it's not the scope of the product which prevented documentation, its the mindset of the company and the low priority given to documentation. this is where the old company paradigm has clashed with the new company direction.
in the past, GG has encouraged people to build their torque games from a "mod" perspective. you swap out the main menu graphics with your own, swap out the loading screen, change the game rules, modify weapon scripts, etc. slowly, the default script base will morph into a unique game. the same goes for the engine source. you can use what's there or mod it to suit your needs.
this process works for the way torque is built, but it creates the legendary huge learning curve torque was always known for and diminishes the need for a reference api because you don't actually "build" your game code from scratch, but modify the existing code and add functionality if necessary. if you needed to make major changes to the engine, you were assumed to be at a certain advanced programming level.
fast forward to today. theyre now attempting to market the engine to newbies on the outside claiming it's easy to use, but still haven't changed their core paradigm from within. new users are actually being tricked because the engine is NOT easy or simple to use. documentation still sits at a very low level on the totem pole. this is why we haven't seen complete documentation of the engine, and most likely never will. even though the companys got a facelift, old habits are hard to break. for those of you waiting for comprehensive C++ engine documentation, I wouldn't hold your breathe.
however, they can and definitely should give us absolutely everything we need to know about the script layer, since this is what 95% of torque development will be.
03/12/2010 (8:59 pm)
Novack-Yes, they need time and they have time. Keep in mind that although T3D was released a relatively short time ago, T3D was announced over a year ago.(Jan 09 I believe) Documentation has been in the works since July of last year. JULY! That's a period of the last 8 months they've been working on documentation for an engine that's been in the works for the last 15 months, an engine which is really just an upgrade of their previous engine. if 8 months hasn't been long enough, just how long is it supposed to take? really? you can only string people along for so long until things come to a head.
understand this is not an issue of scope. as large as torque is, it definitely could've been documented fully within the last 8 months. at the very least, a full script reference couldve been done by now.
no, it's not the scope of the product which prevented documentation, its the mindset of the company and the low priority given to documentation. this is where the old company paradigm has clashed with the new company direction.
in the past, GG has encouraged people to build their torque games from a "mod" perspective. you swap out the main menu graphics with your own, swap out the loading screen, change the game rules, modify weapon scripts, etc. slowly, the default script base will morph into a unique game. the same goes for the engine source. you can use what's there or mod it to suit your needs.
this process works for the way torque is built, but it creates the legendary huge learning curve torque was always known for and diminishes the need for a reference api because you don't actually "build" your game code from scratch, but modify the existing code and add functionality if necessary. if you needed to make major changes to the engine, you were assumed to be at a certain advanced programming level.
fast forward to today. theyre now attempting to market the engine to newbies on the outside claiming it's easy to use, but still haven't changed their core paradigm from within. new users are actually being tricked because the engine is NOT easy or simple to use. documentation still sits at a very low level on the totem pole. this is why we haven't seen complete documentation of the engine, and most likely never will. even though the companys got a facelift, old habits are hard to break. for those of you waiting for comprehensive C++ engine documentation, I wouldn't hold your breathe.
however, they can and definitely should give us absolutely everything we need to know about the script layer, since this is what 95% of torque development will be.
#112
I have been following this engine since its conception (back when torque was called V12 and we didnt even have billboading) and every iteration has promised some level of improved documentation, and every iteration to date has failed, we have been given the same rehashed documentation time and time again, with a smattering of some good ideas that werent implemented well, TDN is one the comes to mind, heck TDN still labels TGEA as TSE, how long ago was this name changed? And many place holder pages were never updated.
My frustrations with torque at one point led me to Unity and today I have licenses to both Unity and T3d but still much prefer Torque (personal preference probably since ive been using torque for soooo much longer) though i used unity soley for a few years(during the TGEA days) until T3D came in and like many others was sucked in by the misleading wetness shader videos (though unlike some i am still very happy with the features provided for the price) and switched back to torque
I am by no means anything other then a hobbyist and in fact have had no programming experience outside what was required for my Bachelors degree in Civil Engineering and my Masters degree in Structural Engineering. so strong API documentation has been a long time wish and one of the reasons I dont venture too far into the source except for the few areas I feel comfortable with after so many years messing around and breaking things, and for the most part just stick to scripting which after reading a few very well done books on the subject from the TGE era feel very comfortable with
I am like many others understandably Skeptical that anything will happen to improve the intermediate to advanced level documentation but as it stands to anyone new to the engine regardless of programming ability there is a large amount of upfront time that has to be invested to really utilize and realize the full benifit of having the source code which makes engines like unity a better deal to the absolute programming beginner, especially in the new "I want it now but dont want to work for it" culture that seems to be poisoning our society.
In this culture If this company wants to stay viable against the competition delivering High level documentation is going to be a must and that means API documentation and quick start tutorials, Eric says actions not words, well its about time that torque starts walking the talk, And for a third time I am feeling optomistic based on the talk, I sure hope for a third time I wont have to feel disapointed with the prior product when the next paid update comes around, because i seriously doubt for a fourth time i will buy the "this time we got it right, look at the all the new features" marketing campaign.
03/12/2010 (9:35 pm)
I have been following this thread and there has been alot of positivity and negativity and I feel the need to chime in.I have been following this engine since its conception (back when torque was called V12 and we didnt even have billboading) and every iteration has promised some level of improved documentation, and every iteration to date has failed, we have been given the same rehashed documentation time and time again, with a smattering of some good ideas that werent implemented well, TDN is one the comes to mind, heck TDN still labels TGEA as TSE, how long ago was this name changed? And many place holder pages were never updated.
My frustrations with torque at one point led me to Unity and today I have licenses to both Unity and T3d but still much prefer Torque (personal preference probably since ive been using torque for soooo much longer) though i used unity soley for a few years(during the TGEA days) until T3D came in and like many others was sucked in by the misleading wetness shader videos (though unlike some i am still very happy with the features provided for the price) and switched back to torque
I am by no means anything other then a hobbyist and in fact have had no programming experience outside what was required for my Bachelors degree in Civil Engineering and my Masters degree in Structural Engineering. so strong API documentation has been a long time wish and one of the reasons I dont venture too far into the source except for the few areas I feel comfortable with after so many years messing around and breaking things, and for the most part just stick to scripting which after reading a few very well done books on the subject from the TGE era feel very comfortable with
I am like many others understandably Skeptical that anything will happen to improve the intermediate to advanced level documentation but as it stands to anyone new to the engine regardless of programming ability there is a large amount of upfront time that has to be invested to really utilize and realize the full benifit of having the source code which makes engines like unity a better deal to the absolute programming beginner, especially in the new "I want it now but dont want to work for it" culture that seems to be poisoning our society.
In this culture If this company wants to stay viable against the competition delivering High level documentation is going to be a must and that means API documentation and quick start tutorials, Eric says actions not words, well its about time that torque starts walking the talk, And for a third time I am feeling optomistic based on the talk, I sure hope for a third time I wont have to feel disapointed with the prior product when the next paid update comes around, because i seriously doubt for a fourth time i will buy the "this time we got it right, look at the all the new features" marketing campaign.
#113
My negativity is actually years of frustration with this issue.
Count me in that category...
Count me in this category as well...I will not give them another dime until I have full source and scripting documentation.
03/12/2010 (10:05 pm)
Quote:I have been following this thread and there has been alot of positivity and negativity
My negativity is actually years of frustration with this issue.
Quote:like many others was sucked in by the misleading wetness shader videos
Count me in that category...
Quote:I sure hope for a third time I wont have to feel disapointed with the prior product when the next paid update comes around, because i seriously doubt for a fourth time i will buy the "this time we got it right, look at the all the new features" marketing campaign.
Count me in this category as well...I will not give them another dime until I have full source and scripting documentation.
#114
@Sean, I think your post was great. I only disagree on the target audience (I dont feel they are promoting torque to newbies, that was part of the thinking behind the new price, to cut off the too-green sector).
Other than that, I think I agree with your recap, and appreciate the time you took to write that. That was totally towards the contructive direction.
@Ken, the same goes to you, good post!
03/13/2010 (7:10 am)
Hey guys, good posts!@Sean, I think your post was great. I only disagree on the target audience (I dont feel they are promoting torque to newbies, that was part of the thinking behind the new price, to cut off the too-green sector).
Other than that, I think I agree with your recap, and appreciate the time you took to write that. That was totally towards the contructive direction.
@Ken, the same goes to you, good post!
#115
I dont know if i would agree with a requirement for FULL source and scripting documentation, as it is for scripting there is alot of documentation out there on the subject and a couple books that can get you jump started plus torsion and with a little work you can be up and running fairly quickly, Full scripting docs would be nice,but isnt really all that neccissary, what is neccissary is API documentation which has never been documented properly.
03/13/2010 (10:16 am)
Quote:I will not give them another dime until I have full source and scripting documentation
I dont know if i would agree with a requirement for FULL source and scripting documentation, as it is for scripting there is alot of documentation out there on the subject and a couple books that can get you jump started plus torsion and with a little work you can be up and running fairly quickly, Full scripting docs would be nice,but isnt really all that neccissary, what is neccissary is API documentation which has never been documented properly.
#116
Summary - The next release of the engine does not go out without scripting and API documentation.
Full interview
:)
03/13/2010 (10:34 pm)
Just an update for those who missed the GDC interview with Eric and Michael.Summary - The next release of the engine does not go out without scripting and API documentation.
Full interview
:)
#117
According to Mich, on his first or second post, they aren't putting out 1.1 without the proper API, which to me is heaven. As Jon just mentioned (haven't watched the video, too late at night [or early in the morning] for that) it seems that it is official. There's just one thing that bothers me...the fact that people have been bashing when he stated that on page 1 or 2... (I didn't read the whole topic, but I read to about page 3 before posting)
edit: It was Mich's 5th post to be exact.
As for my opinions on tutorials and API, API is the overlord. I, myself, am a Manual reader, not 100% all the time with everything I recieve, if I said that I'd be lying. When I look for engine documentation, in all honesty, I'd prefer to skip over the "here's how you make a FPS" and "this is how you code a working gun". When I first started coding, yea, that's what I looked for, I wanted quick answers for what to do, but I learned something (with the help of a tutorial and a friend), it took me a bit but I learned that you don't look how to make a waterfall, you don't look for how to make a gun shoot, or a person move using WSAD (boy that one is really popular I know ;) ). You look for the API, you look for tracing (or raycasting in Torque), xyz movement functions, camera pointers and xyz pan tilt roll (or yaw...blah blah), scan functions, functions that give you the position of a vertex or bone(or node) and the like.
Once you learn the API, you have opened the box to doing whatever you want. I agree that there should be at least some simple tutorials for newbies, but that can also be given by the community, the API...well no, that is the documentation of the engine, obviously that is one of the most important things. Honestly it is a bit sad to me that there hasn't been API docs or so it seems, but as others mentioned there was no binary then. Yea, I'd be pissed to find out that I couldn't find out the "functions" without the docs years ago, and I was a bit upset to be honest until I noticed that post of Mich's.
Mich, if you are still reading this topic, if they haven't beaten you off with their pitchforks yet, I think you are cool. I think you are doing a good job so far, and I think the references to objects, variables, arrays, etc are good. I still have to learn to code with objects and stuff 'cause 3DGS A6 didn't have that, thankfully they did have excellent docs (in the area of API) so yea, I'm a noob to TS, but not a complete noob to coding. I'm looking forward to those new docs man, and the new level that will be coming out with 1.1. I was wondering when you guys would let us see that forest that you had hidden oh so well. And if you want more feedback from any of us, I'd be happy to provide some. Keep up the work Mich, and all you other guys.
Hopefully this was a helpful post, heh. Just my 2 cents. ;)
03/14/2010 (12:00 am)
Just chiming in:According to Mich, on his first or second post, they aren't putting out 1.1 without the proper API, which to me is heaven. As Jon just mentioned (haven't watched the video, too late at night [or early in the morning] for that) it seems that it is official. There's just one thing that bothers me...the fact that people have been bashing when he stated that on page 1 or 2... (I didn't read the whole topic, but I read to about page 3 before posting)
edit: It was Mich's 5th post to be exact.
As for my opinions on tutorials and API, API is the overlord. I, myself, am a Manual reader, not 100% all the time with everything I recieve, if I said that I'd be lying. When I look for engine documentation, in all honesty, I'd prefer to skip over the "here's how you make a FPS" and "this is how you code a working gun". When I first started coding, yea, that's what I looked for, I wanted quick answers for what to do, but I learned something (with the help of a tutorial and a friend), it took me a bit but I learned that you don't look how to make a waterfall, you don't look for how to make a gun shoot, or a person move using WSAD (boy that one is really popular I know ;) ). You look for the API, you look for tracing (or raycasting in Torque), xyz movement functions, camera pointers and xyz pan tilt roll (or yaw...blah blah), scan functions, functions that give you the position of a vertex or bone(or node) and the like.
Once you learn the API, you have opened the box to doing whatever you want. I agree that there should be at least some simple tutorials for newbies, but that can also be given by the community, the API...well no, that is the documentation of the engine, obviously that is one of the most important things. Honestly it is a bit sad to me that there hasn't been API docs or so it seems, but as others mentioned there was no binary then. Yea, I'd be pissed to find out that I couldn't find out the "functions" without the docs years ago, and I was a bit upset to be honest until I noticed that post of Mich's.
Mich, if you are still reading this topic, if they haven't beaten you off with their pitchforks yet, I think you are cool. I think you are doing a good job so far, and I think the references to objects, variables, arrays, etc are good. I still have to learn to code with objects and stuff 'cause 3DGS A6 didn't have that, thankfully they did have excellent docs (in the area of API) so yea, I'm a noob to TS, but not a complete noob to coding. I'm looking forward to those new docs man, and the new level that will be coming out with 1.1. I was wondering when you guys would let us see that forest that you had hidden oh so well. And if you want more feedback from any of us, I'd be happy to provide some. Keep up the work Mich, and all you other guys.
Hopefully this was a helpful post, heh. Just my 2 cents. ;)
#118
>>Summary - The next release of the engine does not go out without >>scripting and API documentation.
>>Full interview
>>:)
Excellent news!!! We need to start complaining about something new just to keep ahead of them :-) joking of course.
03/14/2010 (4:11 am)
>>Just an update for those who missed the GDC interview with Eric and >>Michael.>>Summary - The next release of the engine does not go out without >>scripting and API documentation.
>>Full interview
>>:)
Excellent news!!! We need to start complaining about something new just to keep ahead of them :-) joking of course.
#119
@Glen - Nope. I wasn't driven away. I read every single comment, just chose not to post. Why? You guys already heard me talk. Rather than posting constantly saying "it's coming", I just went straight to Eric and talked about action. As you saw in the video, we made a decision and announced it. Action vs words, and we all know which is more important.
03/14/2010 (11:03 am)
@Jon D - Thanks for posting the link. I was so exhausted by the time I got home I just crashed immediately.@Glen - Nope. I wasn't driven away. I read every single comment, just chose not to post. Why? You guys already heard me talk. Rather than posting constantly saying "it's coming", I just went straight to Eric and talked about action. As you saw in the video, we made a decision and announced it. Action vs words, and we all know which is more important.
#120
In the case of documentation... It's words, baby!
:winkee-smiley!
Glad ya made it home in 1 piece, Mich. Good show, nice booth.
03/14/2010 (11:25 am)
Quote:Action vs words, and we all know which is more important.
In the case of documentation... It's words, baby!
:winkee-smiley!
Glad ya made it home in 1 piece, Mich. Good show, nice booth.
Torque 3D Owner Sean H.
It doesn't really matter what we say here because this thread is in a private forum anyway, shielded from prospective buyers and thus won't affect any future sales. this is the only reason this thread hasnt been removed. I can guarantee that if this thread was in a public forum, it would've been removed a long time ago. as long as it's not going to affect sales, they can afford to take a stance of silent indifference.
This is a waste of time. We're obviously just adding to Eric's list of distractions at this point. with all the smart people at GG no one seems to be smart enough to come up with a solution for giving us updated documentation. it's sad really.