Torque 3D Development - Documentation
by Michael Perry · 07/08/2009 (7:11 pm) · 33 comments
Greetings GG'ers! The Torque 3D team is working hard on Beta 4. With Brett unable to post this week's development blog, I was asked to write a substitute entry. For this round, we are going to pull back the curtain on Torque 3D's documentation.
Normally, whenever Brett writes a blog about new features, he usually includes a short bio of the developer involved. Let's go ahead and get the awkward moment out of the way...
Mich's Bio
"I was born and raised in South Carolina; the majority of that time spent in Greenville. After high school, I moved around on the east coast from Boston, MA to Naples, FL. I finally landed in Orlando, where I obtained my BS in game design and development at Full Sail University. It was there that I met my wife and discovered GarageGames.
A fortuitous trip to GDC '08 resulted in an impromptu meeting with Matthew Fairfax, which led to a discussion of Torque documentation. After a few months of contract work, the offer to become official Documentation Engineer was offered and accepted without hesitation.
In addition to writing Torque 3D documentation, I'm a part of the iTorque development team."
When you get down to it, game development is all about the tech. More polys, more shaders, new code, better tools, shiny features, and so on. Anyone with a pulse that has been following Brett's previous Torque 3D blogs has to admit that Torque 3D is the highest quality engine GarageGames has ever produced.
That same level of expectation is being applied to Torque 3D's documentation. The easiest route would have been to take the best docs from TGE and TGEA, sprinkle some new content on top, and call it done. Sure, this might be better than nothing. I would definitely be coasting right now if that were the case. However, in the forums and here in the office, everyone came to the same conclusion: "That's not good enough!"
I agree 100%. The goal for Torque 3D's documentation has evolved over time. Initially, we simply wanted Torque 3D to ship with complete documentation with a consistent format that covers all the new features. As the weeks rolled by, the goal eventually became something much bolder: Provide the highest quality documentation with the most amount of content, superior to any of our previous tech. By the time the final page is written, it should surpass what is available for ANY engine you can find.
Is this a feasible goal? You tell me. Let's take a look at how Torque 3D's documentation, in beta, stacks up to our previous flagship engines.
TGE 1.5.2
*Link - TGE Official Documentation
*Number of pages (excluding doxygen dump) - 73 unique html pages
*Number of images used in docs - 177 at 10.2 MB
TGEA1.8.1
*Link - TGEA Official Documentation
*Number of pages (excluding doxygen dump) - 121 unique html pages
*Number of images used in docs - 200 at 18.MB
Torque 3D Beta
*Link - Torque 3D Official Documentation
*Number of pages (excluding doxygen dump) - 130 unique html pages, if incomplete guides are included.
*Number of images used in docs - Currently 85 images with resizing and tooltips
Since Torque 3D is in beta, I can only estimate what the final numbers might be. My conservative estimate, based on my road map and placeholders, is as follows:
*Number of unique html pages - Approximately 200
*Total page count if you were to print - Between 300-500 pages, with images
If overall page counting does not impress you, let's get real specific. Both TGEA and Torque 3D have a real time Terrain Editor. Both ship with corresponding docs.
Terrain Editor Documentation
TGEA: 18 pages with large images
Torque 3D: 23 pages with small images that resize
OK. So we improved old docs by rewriting them and tackling every tiny detail. What about the gaps in previous documentation? Perform a search on this site and the official docs, TGE or TGEA, for any articles pertaining to the Sun object. I'll wait here...
Find anything good?
Torque 3D's Sun Documentation
Breakdown: 12 pages with small screenshots that resize, covers all properties, demonstrates common uses, and explains the real world application of azimuth and elevation.
I'm sure you are probably wondering about the new Torque 3D features and objects. Newcomers and veteran Torque users are in the same boat when it comes to using our new Scatter Sky. We have a guide for that:
Scatter Sky Guide
Breakdown: 17 page guide explaining usage, properties, and the complexity of Rayleigh and Mie scattering, simplified just for you.
Until the release, and shortly after, the documentation is going to lag behind the tech. There have been times where I completed a doc in the morning, which became outdated by the end of the day. That's how fast Torque 3D development is moving. The plan is to continue writing Torque 3D documentation for about three months after the official engine release.
On release day, I'm expecting to have the following completed:
* Full World Editor documentation, covering interface, all tools and objects
* Full GUI Editor documentation, covering interface and most used elements
* Walkthrough for core engine modules: GFX, SFX, ConObject->PlayerObject, and PhysX
* TorqueScript walkthrough, with overview, syntax, ConsoleFunction list, and samples
* COLLADA exporting guides for the major modeling applications
* DTS exporting guides for the major modeling applications
* PhysX asset creation guides
As I said before, the documentation chases the tech. If you come across a doc with outdated screenshots or descriptions, we have you covered. Head over to our Official Documentation Feedback Thread. Documentation updates and fixes will begin rolling in rapidly after the initial engine release.
More development blogs to come. This is post #26.
Torque 3D development blogs:
- Post #1 - Kickoff
- Post #2 - Apparatus and Warrior Camp
- Post #3 - Luma's racing kit
- Post #4 - Josh Engebretson and Web Publishing
- Post #5 - Pricing and Licensing
- Post #6 - Pricing and Licensing CONTINUED
- Post #7 - Wetness & Precipitation
- Post #8 - Screeen Space Ambient Occlusion (SSAO)
- Post #9 - Matt Langley and the Torque Launcher
- Post #10 - Chris Robertson and Collada
- Post #11 - Depth of Field
- Post #12 - Advanced Lighting
- Post #13 - Soft Particles
- Post #14 - World Editor
- Post #15 - Pricing and Licensing ANNOUNCED!
- Post #16 - GDC Live Edition
- Post #17 - River & Road Editors
- Post #18 - Beta is UP!
- Post #19 - Light Rays, Undercity, and the Material Editor
- Post #20 - Mass Market Hardware
- Post #21 - Beta: Part Deux
- Post #22 - Marching Towards Beta 3
- Post #23 - pureLIGHT
- Post #24 - Lighting, Terrain, and Cloth
- Post #25 - Beta 3!
- Post #26 - Documentation
- Post #27 - Coming Soon!
About the author
Documentation Engineer for Torque
#22
07/09/2009 (12:17 pm)
Michael, GG couldn't have made a better hire. You have done an awesome job with the official docs. Thanks for all your hard work and keep it up. We all really do appreciate it. :-)
#23
As far as the physics implementation, we are starting with PhysX. That does not mean other implementations are not possible. What if we went with Havok? Do they also support plug-ins for the other modeling applications you are talking about? ODE?
These are the kind of things the doc writers have to learn on the fly, and sometimes faster than what is usually expected of the end user.
As far as ShowToolPro goes, I do not see that happening due to the complexity of the physics layer added to Torque 3D and its dependencies. If I were an artist, I think I'd prefer to go straight from my modeling application to the engine. Having to use a 3rd, "middle man", app would frustrate me. That's speaking in regard to testing the physics adjustments. I would want to see that in a real game play situation.
Thanks for the feedback, though. If you do not mind reposting this in the feedback thread, I would be appreciative.
@Mike - Much thanks =)
Keep in mind that there are other contributors to the docs. Lara Engebretson, Sickhead Games, Chris Robertson, and the other devs supplying e-mails detailing new modules. Without their help I would be quite a bit behind.
07/09/2009 (1:32 pm)
@Thomas - Well, since the docs are not finished there is still time to add more details to the artist docs. I kind of have to lean on artists to help me in that area since I lack the knowledge and expertise.As far as the physics implementation, we are starting with PhysX. That does not mean other implementations are not possible. What if we went with Havok? Do they also support plug-ins for the other modeling applications you are talking about? ODE?
These are the kind of things the doc writers have to learn on the fly, and sometimes faster than what is usually expected of the end user.
As far as ShowToolPro goes, I do not see that happening due to the complexity of the physics layer added to Torque 3D and its dependencies. If I were an artist, I think I'd prefer to go straight from my modeling application to the engine. Having to use a 3rd, "middle man", app would frustrate me. That's speaking in regard to testing the physics adjustments. I would want to see that in a real game play situation.
Thanks for the feedback, though. If you do not mind reposting this in the feedback thread, I would be appreciative.
@Mike - Much thanks =)
Keep in mind that there are other contributors to the docs. Lara Engebretson, Sickhead Games, Chris Robertson, and the other devs supplying e-mails detailing new modules. Without their help I would be quite a bit behind.
#24
@Ken - Thanks to you too, man. You see it in progress daily, and here the venting during smoke breaks. The internal support is what has made this happen.
07/09/2009 (2:05 pm)
@Brett - Thanks. I was worried I would not be able to produce a Torque 3D worthy blog, since your's have brought Torque blogging to a new level.@Ken - Thanks to you too, man. You see it in progress daily, and here the venting during smoke breaks. The internal support is what has made this happen.
#25
Great work, guys!
07/09/2009 (2:16 pm)
The Torque Documentation is probably the only software documentation I've ever seen that was, well, helpful.....Great work, guys!
#26
What really missing in the documentation is little examples on how to use any functionality (like in MSDN), including (one of the important) the scripting examples. Sometimes a scripting function description is not enough until you see how it ties with other functions, or/and needs other functions to be called first (otherwise nothing happens).
07/09/2009 (6:11 pm)
Documentation was always a weak spot of TGE, TGB, TGEA... Sorry to rain on the parade, but it's quite useless - you get more just reading the code, if the code reading is not helpful, then you are stuck, unless there is a person on the forums who magically found a combination of function calls to make it work... Hopefully T3D will improve in that area as well, however the T3D Beta docs are so generic, they are just useful for real noobies (which is helpful for them, I guess).What really missing in the documentation is little examples on how to use any functionality (like in MSDN), including (one of the important) the scripting examples. Sometimes a scripting function description is not enough until you see how it ties with other functions, or/and needs other functions to be called first (otherwise nothing happens).
#27
http://www.garagegames.com/community/forums/viewthread/95197/
Thanks.
07/11/2009 (2:12 am)
Is this feature going to be added into the T3D Beta 4?http://www.garagegames.com/community/forums/viewthread/95197/
Thanks.
#28
@ysun - I'm not sure about that. The next blog should address Beta 4
07/13/2009 (6:21 am)
@Tau - That's the planned final result. Still working through all the high level stuff, and as the days go by I'll be getting into the more specific stuff.@ysun - I'm not sure about that. The next blog should address Beta 4
#29
07/13/2009 (2:23 pm)
@Michael Perry - good luck! documentation is hard and tedious job (I do it myself quite often), I hope you'll be able to move the mountain and T3D will be a helpful read ;) 
#30
07/14/2009 (8:22 am)
Looks great; I'm excited about the doc stuff as this is definitely important for faster learning curve :-)
#31
07/14/2009 (8:29 am)
PDF is good: oh, just thought I'd throw out my plug that it would be cool if there is a format/version of the doc that is really easy to throw on an eBook (like Kindle) (such as PDF) (at least if it's not a significant distraction from actual content) 
#32
07/14/2009 (7:41 pm)
reading this interesting blog I was wondering how long it will take until t3d to be released officially? I know the answer is "when it's ready" but approximately how long? 3 , 6 , 9 months ?
#33
@Picasso - With the exception of a couple core modules, we are close to being feature complete and will be moving into the polishing phase very shortly.
07/14/2009 (8:06 pm)
@Peter - Previously I was completely against PDF due to the nature of the docs and how the are built. Another community member has recently provided me with some useful utilities that might make the conversion possible, so I'm not ruling the format out yet.@Picasso - With the exception of a couple core modules, we are close to being feature complete and will be moving into the polishing phase very shortly.
Torque Owner Thomas Bang
The topics "TSShapeConstructor" and "3DS MAX PhysX Guide 1/2" were very interesting but unfortunately also a matter of concern.
The nVidia PhysX DCC Plugin is only available for Max, Maya and Softimage.
But what do all the other user who work with Lightwave, Modo, Blender and so on? Did Garagegames think about?
Realtime physics is the next point, where a new ShowToolPro would make sense. We could do the physical simulation inside of ShowToolPro and nobody is dependent on Autodesk.