Torque 3D Documentation Discussion
by Michael Perry · in Torque Game Engine Advanced · 01/10/2009 (11:15 am) · 28 replies
Torque 3D Documentation Discussion
Introduction
Hello everyone. Since the announcement of Torque 3D, and especially in the Torque 3D Sidebar .plan, there has been a lot of emphasis placed on documentation.Both Tech & Tools and the community have been very vocal about how much influences docs will have on the success of Torque 3D. Through various posts and my own .plans, I have made the following statements:
* Torque 3D will ship with the most polished and useful set of docs for any Torque Engine to date
* I will make the documentation project as transparent as possible
* The new documentation will be written from scratch, with only the most useful older docs copied in if necessary
* You, the community, will have direct influence on what and how I write
Drawing From Existing Sources
Primarily, I will be reviewing the TGEA Documentation Feedback Thread and reading through the most recent comments made in the aforementioned .plans. Recently, there have been two major meetings about documentation at GG. I first had a sit down with Matt Fairfax, project lead for Torque 3D. The second meeting involved developers, marketing, business, QA, and project lead. Currently, I have a very tight schedule and a list of the major subjects to generate content from.Purpose Of This Thread
This is the difficult part you guys. In my past feedback threads, I've given free reign for suggestions and discussion. What I need now is for everyone to provide SPECIFIC information. Here's a fictitious example:Not Helpful:
Quote:Better documentation of the engine modulesPreferred:
Quote:Better Documentation the Console (con::) Namespace
Not Helpful:
Quote:Starting from scratch tutorialPreferred:
Quote:Tutorial that will start a user with a blank project, show how to load a main menu, how to load a single terrain, how to add a single interior, and how to add in a moveable player objectSee what I'm getting at? I need details. Your posts can be as long or as short as you need them to be, but remember scope. You will have a better idea of what "scope" means in regard to documentation as I release more information.
About the author
Programmer.
#2
At a minimum, it only needs to be a paragraph or two about the basic purpose of the class and how it is intended to be used. Is it meant to be added to a mission directly, or is it only used by other classes? In some cases it would also be good to see a bit about how the class relates to other classes. For instance, how is ParticleEmitter related to ParticleEmitterNode?
Also, some white-paper style articles on some of the more significant parts of the engine, such as terrain, would be very helpful. This is a good example of the sort of article I am thinking of.
01/31/2009 (5:41 pm)
I refer to the class hierarchy a lot when I'm trying to understand something. But too few of the classes have anything beyond the auto generated member details. Some of them have a basic overview of the class, and I would like to see more of that, particularly for the classes derived from SceneObject.At a minimum, it only needs to be a paragraph or two about the basic purpose of the class and how it is intended to be used. Is it meant to be added to a mission directly, or is it only used by other classes? In some cases it would also be good to see a bit about how the class relates to other classes. For instance, how is ParticleEmitter related to ParticleEmitterNode?
Also, some white-paper style articles on some of the more significant parts of the engine, such as terrain, would be very helpful. This is a good example of the sort of article I am thinking of.
#3
How does the following look:
= Objects =
ConsoleObject
SimObject
SceneObject
GameBase
ShapeBase
Player
AIPlayer
TerrainBlock
Interior
= Datablocks =
SimDataBlock
GameBaseData
ShapeBaseData
PlayerData
= Console =
Con Namespace (con::)
ConsoleMethod
ConsoleFunction
= Systems =
GFX
Delegate
SFX
Sky
Camera
= GUI =
guiControl
guiCanvas
You can see a fair amount of chunks missing, but one will inevitably lead to another that's not on the list. If you can think of a few major classes in the existing TGEA engine to detail, go ahead and list them.
01/31/2009 (7:00 pm)
@Tony - Thanks for the suggestion and example white paper. I already planned for creating something similar to this. It will take me a while to finish completely, so the initial documentation will not have the full breakdown of every class. However, I've already drafted up an initial list of classes to start with. I will probably get a few more in before the engine ships.How does the following look:
= Objects =
ConsoleObject
SimObject
SceneObject
GameBase
ShapeBase
Player
AIPlayer
TerrainBlock
Interior
= Datablocks =
SimDataBlock
GameBaseData
ShapeBaseData
PlayerData
= Console =
Con Namespace (con::)
ConsoleMethod
ConsoleFunction
= Systems =
GFX
Delegate
SFX
Sky
Camera
= GUI =
guiControl
guiCanvas
You can see a fair amount of chunks missing, but one will inevitably lead to another that's not on the list. If you can think of a few major classes in the existing TGEA engine to detail, go ahead and list them.
#4
For that matter, there doesn't appear to be anything about lighting either, so fxLight and its offspring should probably be on the list too.
01/31/2009 (7:22 pm)
That all looks OK, but I would point out that there is currently nothing at all in the docs about the particle system (at least I don't think there is; the docs search function is broken). If the particle-related classes were not in the class hierarchy there would be nothing to suggest that there even was a particle system. It seems like a pretty major omission.For that matter, there doesn't appear to be anything about lighting either, so fxLight and its offspring should probably be on the list too.
#5
Because of the information type, I'm pretty sure there will be practically no tutorial-based screenshots for this portion of the documentation. At most there may be some diagrams, charts, or a screen capture of a system at work. These docs will much more closely resemble technical articles, as read in Havok documentation (awesome) and your example.
01/31/2009 (7:28 pm)
@Tony - I think I will include lighting after GFX, or create an entire section on special effects or environment. What you see above is a very "core" centric approach to the game engine. Pretty much everything derives from the above classes, but I think lighting and particles will have their own spot. I just need to wait for those system to be fully committed before I start documenting them.Because of the information type, I'm pretty sure there will be practically no tutorial-based screenshots for this portion of the documentation. At most there may be some diagrams, charts, or a screen capture of a system at work. These docs will much more closely resemble technical articles, as read in Havok documentation (awesome) and your example.
#6
Oh, and here's another thought. Maybe I'm unusual in this, but when I'm learning a new API or programming language, I often find that the most useful information I can find is related to the design intent of whoever made the system I'm trying to learn. If I can understand a bit about why something was implemented the way it was, and what alternative implementations were considered, it often gives me a much better grasp of the big picture. Occasionally I see comments in these forums from GG developers that give a bit of this kind of insight into parts of Torque, and some of those comments are hugely enlightening. So, in the articles you're planning, I hope that you'll include a bit about the Whys, as well as the Whats and Hows. Perhaps in the form of sidebars written by the developers themselves?
01/31/2009 (8:39 pm)
Fair enough.Oh, and here's another thought. Maybe I'm unusual in this, but when I'm learning a new API or programming language, I often find that the most useful information I can find is related to the design intent of whoever made the system I'm trying to learn. If I can understand a bit about why something was implemented the way it was, and what alternative implementations were considered, it often gives me a much better grasp of the big picture. Occasionally I see comments in these forums from GG developers that give a bit of this kind of insight into parts of Torque, and some of those comments are hugely enlightening. So, in the articles you're planning, I hope that you'll include a bit about the Whys, as well as the Whats and Hows. Perhaps in the form of sidebars written by the developers themselves?
#7
We hope we can squeeze two of these in, but that might be a good start to your idea.
01/31/2009 (10:09 pm)
@Tony - That's an interesting idea, and I think I might be able to pull that off. I've noticed that a lot of people do not like to write documentation. It's hard enough just to get people to write comments in code. Thanks to Tom Spillman's suggestion and Matt Fairfax's direction, we are having a first ever "documentation day." All of the Torque 3D developers will stop coding for one day and write comments/docs for the project.We hope we can squeeze two of these in, but that might be a good start to your idea.
#8
02/01/2009 (7:59 am)
Tony's idea is a great one. My biggest hurdle to overcome is the "why in the world did they do this this way" question. (that and "how the heck does that work?")
#9
For me, there are 2 major ways of discovering features in a SDK :
02/02/2009 (1:00 am)
Hi Michael,For me, there are 2 major ways of discovering features in a SDK :
- you search something and find it : you know what to do with it
- you wander throw the SDK to discover something new. When I find something new, before asking myself "Why do they make it this way ?", I may ask myself "Why do they make it ?". What is the purpose of each functionality. And then, each purpose can be illustrated with examples.
Quote:The second meeting involved developers, marketing, business, QA, and project lead.Be carful : marketing guys are generally irresponsible and dangerous ! ;-)
#10
Nicolas Buquet
www.buquet-net.com/cv/
02/02/2009 (4:42 am)
Could you elaborate a doc that explain how a frame is drawn : what happens between the end of frame N and the end of frame N+1 : - is there checks done before starting a new frame state ?
- how the "world" state is tested
- how the sceneGraph is "traversed"
- how the state of the objects is updated
- how the culling is done
- what is the render pipeline for each type of object
- how the "scene" image is composited
- how the screen space shaders are applied, what data structures are they using
- is there any post "draw frame" checks
- [li]each point in a very few lines in simple words to get the main concept
- each point in a page for a more in depth review
- each point with their hooks in the engine : structures and methods used
- and the next level is up to us : diving into the source code with strong guidance, to fully understand what happens in the inside
Nicolas Buquet
www.buquet-net.com/cv/
#11
I think the best way to document what happens between frames is to pick beginning and an end:
Beginning:
SceneState::renderCurrentImages() calls gRenderInstManager->render()
End:
The Sky class's rendering function is Sky::renderObject(...)
Trace the rendering calls from SceneState::renderCurrentImages() to Sky::renderObject(...)
Is that what you are thinking would be most useful?
02/02/2009 (10:40 am)
@Nicolas - Going off your suggestion, we will have to stay in the engine completely (no scripts). For TGEA 1.8, I wrote a description of the major render managers and what they are responsible for. It was a very high level approach, but I did not step through each rendering function that gets called.I think the best way to document what happens between frames is to pick beginning and an end:
Beginning:
SceneState::renderCurrentImages() calls gRenderInstManager->render()
End:
The Sky class's rendering function is Sky::renderObject(...)
Trace the rendering calls from SceneState::renderCurrentImages() to Sky::renderObject(...)
Is that what you are thinking would be most useful?
#12
In fact, the skeletal of this doc would be the frame rendering, from start to finish of a frame.
Through this linear description, we can :
We could have the same method used on the main loop of the game, for collection inputs, network update, memory management…
I'm at your disposal if you want to go deeper in this.
02/02/2009 (12:22 pm)
@Michael : yes, I was asking this from an engine point of view only.In fact, the skeletal of this doc would be the frame rendering, from start to finish of a frame.
Through this linear description, we can :
- enumerate the different types of objects that compose a scene
- then, how are they related to each other (the scenegraph I think…)
- how can we access them (structure of the scenegraph)
- what data are they storing and why
- what are their functionality
- where does their data come from and what can modify them (network interaction…)
- …
We could have the same method used on the main loop of the game, for collection inputs, network update, memory management…
I'm at your disposal if you want to go deeper in this.
#13
02/02/2009 (12:58 pm)
@Nicolas - Interesting. I think I might put this on the major "to-cover" list for "Doc Day". I'd like for a dev with more knowledge in this area than myself to make sure the code path is accurately described.
#14
I will follow this with great interest and continue to over-read GG forums to learn.
02/03/2009 (1:36 am)
I'm glad I made a constructive submission !I will follow this with great interest and continue to over-read GG forums to learn.
#16
02/03/2009 (9:37 am)
@Glen - I think our documentation is currently a little cleaner than that, but I see where you are going. Torque 3D will have online and offline documentation. They will look identical and have the same content. The only thing that is different is the search method, which is beneath the surface.
#17
02/04/2009 (9:02 am)
Nice to hear. It's just that I'd like to see a big explanation of all the functions available in T3D like that manual has, which is what I meant by it. It is nice to hear that you're working on it Michael, look forward to seeing your work accomplished. :)
#18
02/08/2009 (11:16 am)
Keep the discussion going folks. I've sticked this thread to grab attention of other future Torque 3D developers.
#19
02/11/2009 (7:05 am)
Another one: An in depth explanation of the source that can make it easier to edit.
#20
- Rendering Flow
- Core Systems
- Particle System
What about the engine source, specifically, do you suggest I explain in depth?
02/11/2009 (9:18 am)
@Glen - Could you explain a little further? We already mentioned in previous posts which parts of the source should be documented:- Rendering Flow
- Core Systems
- Particle System
What about the engine source, specifically, do you suggest I explain in depth?
Employee Michael Perry
ZombieShortbus
What To Expect From Me
I am going to be very "heads down" for a while. You will not see me very much posting in the usual forums. I am dedicating my attention to threads and blogs related to documentation ONLY. This will change when I get to the point where I can come up for air. I will still respond to e-mails, but you should expect a delayed reaction.If all goes well, I will release documentation early when appropriate. Brett Seyler is doing a fine job of talking about new features in his Torque 3D Development Blogs. If he or Matt releases information about a feature, I will see if I can release a doc page about it early. This will allow you to better prepare yourself and your project for development.
Not every request will make it into the launch documentation. However, when Torque 3D launches, I will not slow down. I have already planned for the doc cycle to go beyond initial release. Notifying you of post-launch changes is being worked out, but we can discuss that later.
Conclusion
Polished documentation for Torque 3D is paramount. I have made some hefty claims, but I plan on living up to them. The only thing that might change in our plans is that we surpass our own expectations. The ball is already rolling. If you are unsure of where to begin, start by reading my past 5 blogs and feedback threads.Note - This thread will be unlocked when I post my next blog. This will most likely happen within two weeks. For now, read through this first post so you can start formulating suggestions and questions.