Beta Documentation Feedback
by Michael Perry · in Torque 3D Public · 03/28/2009 (8:03 pm) · 329 replies
=========================================================================
This was the official feedback thread for the Torque 3D beta.
It is now locked.
Please make post any new documentation feedback in the official thread:
Official Torque 3D Documentation Feedback
=========================================================================
6/16/09 Update Changed title of thread to Torque 3D Beta, instead of Official Torque 3D. When the final release ships, I want to have a clean thread for new users to be able to search through and post in. This thread will be archived.
7/17/09 Update: Tooltips work. Component Tutorials work in certain browsers. CLICK HERE for SVN Change Log.
9/31/09 Update: Posted full TOC for docs, using WIP template to hold spot for final docs to be written. CLICK HERE for SVN Change Log.
This was the official feedback thread for the Torque 3D beta.
It is now locked.
Please make post any new documentation feedback in the official thread:
Official Torque 3D Documentation Feedback
=========================================================================
6/16/09 Update Changed title of thread to Torque 3D Beta, instead of Official Torque 3D. When the final release ships, I want to have a clean thread for new users to be able to search through and post in. This thread will be archived.
7/17/09 Update: Tooltips work. Component Tutorials work in certain browsers. CLICK HERE for SVN Change Log.
9/31/09 Update: Posted full TOC for docs, using WIP template to hold spot for final docs to be written. CLICK HERE for SVN Change Log.
About the author
Associate Producer / Project Manager for GarageGames
Thread is locked
#182
06/26/2009 (10:54 am)
New set of docs are online (including the first PhysX guide). Still trying to get all the stuff I finished last week converted. 
#183
Before I begin, let me say that if you already know and are dealing with the issue I am about to bring up (as I am pretty sure you are), please don't take it as an insult on your common sense...take it as coming from an end user who is just beginning to learn T3D and is feeling a bit overwhelmed.
I think this is an appropriate time for this post in light of all the new features being added with each Beta.
I understand enough about many of these features to be excited about them. However, at the same time, as a beginner, even though I have a grasp of what these feature are for, I have, in many cases, little to no idea of how to implement them. Foliage Replicator, zones, portals, and ground cover come to mind. I feel like I am understanding fewer and fewer of the total number of features available.
I know that documentation is forthcoming on those, but my concern is that even in many of the features that I do know how to use, such as Scatter Sky and terrain block, I am not always able (yet) to figure out the meaning of all the fields in the inspector panel.
Example: Terrain block. I can successfully import a terrain block thanks to the docs. However in the Inspector panel there are many things that I do not understand how they will impact my terrain such as...screen error, or the dynamic fields for example. In Scatter Sky what do interpolation start, viewer height, etc mean? How are they used, and when should they be used?
So, basically, what I am wondering/requesting/seeking reassurance of is: that you intend to document the basic(I'm not expecting you to make me an expert) use and meaning of each and every field in the inspector panel for each feature available from the object editor library. (I haven't gotten much past the object and terrain editors to worry about all these other new editors yet!)
I know many T3D users don't need this level of documentation, but I feel like there must be plenty of us who do.
Well, I could go on, but I think this covers my concerns. Thank you for listening.
06/26/2009 (11:31 am)
Hi Michael;Before I begin, let me say that if you already know and are dealing with the issue I am about to bring up (as I am pretty sure you are), please don't take it as an insult on your common sense...take it as coming from an end user who is just beginning to learn T3D and is feeling a bit overwhelmed.
I think this is an appropriate time for this post in light of all the new features being added with each Beta.
I understand enough about many of these features to be excited about them. However, at the same time, as a beginner, even though I have a grasp of what these feature are for, I have, in many cases, little to no idea of how to implement them. Foliage Replicator, zones, portals, and ground cover come to mind. I feel like I am understanding fewer and fewer of the total number of features available.
I know that documentation is forthcoming on those, but my concern is that even in many of the features that I do know how to use, such as Scatter Sky and terrain block, I am not always able (yet) to figure out the meaning of all the fields in the inspector panel.
Example: Terrain block. I can successfully import a terrain block thanks to the docs. However in the Inspector panel there are many things that I do not understand how they will impact my terrain such as...screen error, or the dynamic fields for example. In Scatter Sky what do interpolation start, viewer height, etc mean? How are they used, and when should they be used?
So, basically, what I am wondering/requesting/seeking reassurance of is: that you intend to document the basic(I'm not expecting you to make me an expert) use and meaning of each and every field in the inspector panel for each feature available from the object editor library. (I haven't gotten much past the object and terrain editors to worry about all these other new editors yet!)
I know many T3D users don't need this level of documentation, but I feel like there must be plenty of us who do.
Well, I could go on, but I think this covers my concerns. Thank you for listening.
#184
Hover over the orbit properties. The tooltips that pop up have a quick description of what the fields are (type) and what they do (description). Any tooltips I write for the docs get ported over to the engine, so when you click on a field while editing you will see the same thing. For the less intuitive stuff, such as how azimuth and elevation work, I created a section in the Sun article to explain them.
I'm trying to do this with every World Editor object, but unfortunately things keep changing. For example, I was trying to figure out what "samples" does in Scatter Sky. I asked the developer who worked on it, and found out it does nothing right now and will most likely be removed for the final release.
That's the least of the challenge. The most difficult part is when objects are removed, split, or added. For instance, we originally had a Sky object. Then a Skybox object was added. Then a Scatter Sky was added, and Sky removed. We have a Cloud Layer object now, but they will be creating a new cloud object soon.
While this is going on, I have to switch gears and try to documenting something that has been completed. Rest assured, the final docs will cover the major properties of objects and how to appropriately use them. The video tutorials will also provide context on how to create specific scenes, such as sunset in the mountains or twilight in a swamp.
06/26/2009 (12:02 pm)
@Steve - I have been doing just that. As an example, go back to the Sun doc: Sun ArticleHover over the orbit properties. The tooltips that pop up have a quick description of what the fields are (type) and what they do (description). Any tooltips I write for the docs get ported over to the engine, so when you click on a field while editing you will see the same thing. For the less intuitive stuff, such as how azimuth and elevation work, I created a section in the Sun article to explain them.
I'm trying to do this with every World Editor object, but unfortunately things keep changing. For example, I was trying to figure out what "samples" does in Scatter Sky. I asked the developer who worked on it, and found out it does nothing right now and will most likely be removed for the final release.
That's the least of the challenge. The most difficult part is when objects are removed, split, or added. For instance, we originally had a Sky object. Then a Skybox object was added. Then a Scatter Sky was added, and Sky removed. We have a Cloud Layer object now, but they will be creating a new cloud object soon.
While this is going on, I have to switch gears and try to documenting something that has been completed. Rest assured, the final docs will cover the major properties of objects and how to appropriately use them. The video tutorials will also provide context on how to create specific scenes, such as sunset in the mountains or twilight in a swamp.
#185
Shame on me, I did not realize that the tool tip pops up were all active. You are right, there is quite a bit of exactly the type of info I need in them.
Meanwhile, in browsing the docs again I found the following small things:
End of Terrain Painter section it says: "Click to begin reading skybox" but there is no link to click.
When you mouse over the Sun Doc Inspector Panel for the tooltip, the tooltip box is so large that you can not see the bottom of it, it gets cut off. There is no way to read the last entry (at least on my system).
06/27/2009 (7:01 am)
Michael -- thanks for your reply. I understand (theoretically, at least) what a difficult job you have undertaken, and I have no problem at all waiting for as long as it takes to get the final docs. I only wanted to express my concern about what is necessary for me to succeed with T3D, and you have set my mind at ease.Shame on me, I did not realize that the tool tip pops up were all active. You are right, there is quite a bit of exactly the type of info I need in them.
Meanwhile, in browsing the docs again I found the following small things:
End of Terrain Painter section it says: "Click to begin reading skybox" but there is no link to click.
When you mouse over the Sun Doc Inspector Panel for the tooltip, the tooltip box is so large that you can not see the bottom of it, it gets cut off. There is no way to read the last entry (at least on my system).
#186
06/27/2009 (10:49 am)
@Steve - Ah. Thanks for the dead link find. I was worried about the length of some of the fields, like the Advanced Lighting one. Is that the tooltip you are referring to? What is your monitor resolution?
#187
06/27/2009 (11:41 am)
Yes, the Advanced Lighting is the one. I forgot my fonts are set at 14 point, It fits ok at 12, which I guess would suit most people.
#188
Artist section / collada / supported functionality: geometry link to:
http://sourceforge.net/products/colladarefinery bad link
world editor / adding terrain / terrain block properties / misc
tool tip for basetexsize = "size of base texture size per meter" this is a bit confusing
tool tip for screen error = "not implemented yet" . It does do something if you click on it in editor mode, not sure if working as intended.
06/28/2009 (7:02 am)
couple more touch up candidates:Artist section / collada / supported functionality: geometry link to:
http://sourceforge.net/products/colladarefinery bad link
world editor / adding terrain / terrain block properties / misc
tool tip for basetexsize = "size of base texture size per meter" this is a bit confusing
tool tip for screen error = "not implemented yet" . It does do something if you click on it in editor mode, not sure if working as intended.
#189
The more difficult sections, such as azimuth and elevation for the Sun doc, require a little extra explanation that is not quite Torque 3D exclusive. Perfect example: rayleigh and mie scattering.
Google those terms and see what you come up with. Holy crap, a ton of scientific calculations and papers. If the rayleigh field in Scatter Sky was called something else, like "blueSkyChanger", my job would be a little easier. But it's not...it's rayleigh, which some people do not even know the definition of (I did not until writing the doc). So, here's how I'm treating those sections, which should make you happy:
06/29/2009 (1:06 pm)
@Steve - Thanks for another error find. I want to jump back to a previous post about the explanation of object properties. Some properties require very little explanation, such as how the night color affects Scatter Sky. I do go into how to get to that point, by setting the orbit to 200 (which puts the sun below the horizon, also explained in the Sun doc).The more difficult sections, such as azimuth and elevation for the Sun doc, require a little extra explanation that is not quite Torque 3D exclusive. Perfect example: rayleigh and mie scattering.
Google those terms and see what you come up with. Holy crap, a ton of scientific calculations and papers. If the rayleigh field in Scatter Sky was called something else, like "blueSkyChanger", my job would be a little easier. But it's not...it's rayleigh, which some people do not even know the definition of (I did not until writing the doc). So, here's how I'm treating those sections, which should make you happy:
#190
The scientific concept of scattering and how it affects your level is somewhat complex. The rayleighScattering and mieScattering values are extremely sensitive, and it is important that you have an understanding of how they work. The simplest way to explain scattering is to answer a child's question: "Why is the sky blue?"
In reality, beyond the sky's atmosphere is blank space, obviously. When you look up at the night sky, you can see the black of space and the stars it contains. However, during the day you can only see a blue sky. This is due to the light waves traveling from the Sun.
Light travels in wave lengths, similar to vibration that creates sound. When you hear a sound, that is the interaction between the air and objects with the vibratory wave. The shorter the wave length, the greater the effect. This works with light as well.
With light traveling as a wave length toward Earth, the air molecules that make up the atmosphere will interact with the light. This scattering and interaction is what creates the color of the sky. The shortest wave lengths have a blue hue. Since shortest wave length has the greatest impact on an interaction, the sky will be more blue during the day time.
The simplest explanation of these effects in Torque 3D is that mieScattering affects the appearance of light waves projected from the sun object. rayleighScattering affects how blue your sky will be.
Let's proceed to see the adjustment of these properties in action. Reduce the mieScattering field to a small value, such as 0.0005.
[[Image:LessMieField.jpg]]
You should notice that the scattering of the light around the sun object has been drastically reduced, resulting in a smaller and smoother sun.
''(click to enlarge)''
[[Image:LessMieScene.jpg]]
Reset the mieScattering back to the default value (approximately 0.0045). Lower the rayleighScattering field to 0.0006, which has the same affect of reducing the interaction of the atmosphere to much shorter wave lengths.
[[Image:LessRayleighField.jpg]]
The sky's atmosphere should now be a darker shade of blue, since the reduction of the rayleighScattering is only allowing shorter wave lengths: more blue equals darker blue.
''(click to enlarge)''
[[Image:LessRayleighScene.jpg]]
At some point, you can reduce the value only so far before you hit a shade of blue that is almost completely black. This does not mean you are actually seeing the black of space, rather you are seeing the darkest shade of the shortest wave length.
Let's go in the opposite direction. Begin increasing the rayleighScattering until you hit a value of 0.008. What we are doing is allowing longer wave lengths to interact with the atmosphere.
[[Image:MoreRayleighField.jpg]]
The effect is that a greater spectrum of light waves is interacting with the atmosphere, allowing a broader range of colors.
''(click to enlarge)''
[[Image:MoreRayleighScene.jpg]]
If you go too high with the value, your sky will eventually become black. This is due to the allowance of all wave lengths to interact with the atmosphere. This is where the simple rules of colors come into play: white is the complete lack of color (light interaction) and black is the presence of all colors.
If you have become confused, there are quite a few resources in the library and Internet you can look up to learn more. If you have gotten this far, but wish to keep it simple, remember the following:
*mieScattering - Higher equals bigger and more scattered Sun. Lower equals smaller, smoother Sun.
*rayleighScattering - Higher equals less blue sky. Too high equals black sky. Lower equals more blue sky. Too low equals black sky.
06/29/2009 (1:06 pm)
Taken from the Scatter Sky Guide (minus screen shots):The scientific concept of scattering and how it affects your level is somewhat complex. The rayleighScattering and mieScattering values are extremely sensitive, and it is important that you have an understanding of how they work. The simplest way to explain scattering is to answer a child's question: "Why is the sky blue?"
In reality, beyond the sky's atmosphere is blank space, obviously. When you look up at the night sky, you can see the black of space and the stars it contains. However, during the day you can only see a blue sky. This is due to the light waves traveling from the Sun.
Light travels in wave lengths, similar to vibration that creates sound. When you hear a sound, that is the interaction between the air and objects with the vibratory wave. The shorter the wave length, the greater the effect. This works with light as well.
With light traveling as a wave length toward Earth, the air molecules that make up the atmosphere will interact with the light. This scattering and interaction is what creates the color of the sky. The shortest wave lengths have a blue hue. Since shortest wave length has the greatest impact on an interaction, the sky will be more blue during the day time.
The simplest explanation of these effects in Torque 3D is that mieScattering affects the appearance of light waves projected from the sun object. rayleighScattering affects how blue your sky will be.
Let's proceed to see the adjustment of these properties in action. Reduce the mieScattering field to a small value, such as 0.0005.
[[Image:LessMieField.jpg]]
You should notice that the scattering of the light around the sun object has been drastically reduced, resulting in a smaller and smoother sun.
''(click to enlarge)''
[[Image:LessMieScene.jpg]]
Reset the mieScattering back to the default value (approximately 0.0045). Lower the rayleighScattering field to 0.0006, which has the same affect of reducing the interaction of the atmosphere to much shorter wave lengths.
[[Image:LessRayleighField.jpg]]
The sky's atmosphere should now be a darker shade of blue, since the reduction of the rayleighScattering is only allowing shorter wave lengths: more blue equals darker blue.
''(click to enlarge)''
[[Image:LessRayleighScene.jpg]]
At some point, you can reduce the value only so far before you hit a shade of blue that is almost completely black. This does not mean you are actually seeing the black of space, rather you are seeing the darkest shade of the shortest wave length.
Let's go in the opposite direction. Begin increasing the rayleighScattering until you hit a value of 0.008. What we are doing is allowing longer wave lengths to interact with the atmosphere.
[[Image:MoreRayleighField.jpg]]
The effect is that a greater spectrum of light waves is interacting with the atmosphere, allowing a broader range of colors.
''(click to enlarge)''
[[Image:MoreRayleighScene.jpg]]
If you go too high with the value, your sky will eventually become black. This is due to the allowance of all wave lengths to interact with the atmosphere. This is where the simple rules of colors come into play: white is the complete lack of color (light interaction) and black is the presence of all colors.
If you have become confused, there are quite a few resources in the library and Internet you can look up to learn more. If you have gotten this far, but wish to keep it simple, remember the following:
*mieScattering - Higher equals bigger and more scattered Sun. Lower equals smaller, smoother Sun.
*rayleighScattering - Higher equals less blue sky. Too high equals black sky. Lower equals more blue sky. Too low equals black sky.
#191
I have read plenty of docs from other engines that skim over concepts, providing a simple 1 sentence treatment of a very complex system. Sometimes a doc person has to bite the bullet and go a little further for the users. We cannot promise that every field will get this level of treatment, but hopefully this plays into the promise of providing the best documentation you will find for a game engine (Torque or otherwise)
06/29/2009 (1:10 pm)
Is that overkill? Maybe...I simplify and summarize in between certain sections, specific to Torque 3D. However, some developers and artists seek absolute fidelity and might want to know the real correlation between Torque 3D objects and their real life counter parts.I have read plenty of docs from other engines that skim over concepts, providing a simple 1 sentence treatment of a very complex system. Sometimes a doc person has to bite the bullet and go a little further for the users. We cannot promise that every field will get this level of treatment, but hopefully this plays into the promise of providing the best documentation you will find for a game engine (Torque or otherwise)
#192
I am following the documentation as it is written from beginning to end. I'm at the World Editor section now. So far I have not seen information on the MAC version of the shortcuts to open and close editors, for example on my mac pro i have tried F11, and in combination with cmd, alt, ctrl, shift keys in many ways but no matter what modifier key I hold down as soon as I press F11 OSX things come up like audio options, audio volume and other things
Could you include a list of working keys shortcuts for MAC OS X 10.5.7 (leopard)? If you do know what they are, please reply with the info here so I can start using them as well :)
F5 and F6 work, the other F keys don't.
Also, when in edit mode I can only move left/right/forward and backward, I can't find on my MAC keyboard modifier keys to rotate/pitch the camera when using my one button mouse
Any of this type of MAC specific info in the documentation would be great (unless it is there already but I didn't see it yet so far)
06/29/2009 (1:41 pm)
Hi,I am following the documentation as it is written from beginning to end. I'm at the World Editor section now. So far I have not seen information on the MAC version of the shortcuts to open and close editors, for example on my mac pro i have tried F11, and in combination with cmd, alt, ctrl, shift keys in many ways but no matter what modifier key I hold down as soon as I press F11 OSX things come up like audio options, audio volume and other things
Could you include a list of working keys shortcuts for MAC OS X 10.5.7 (leopard)? If you do know what they are, please reply with the info here so I can start using them as well :)
F5 and F6 work, the other F keys don't.
Also, when in edit mode I can only move left/right/forward and backward, I can't find on my MAC keyboard modifier keys to rotate/pitch the camera when using my one button mouse
Any of this type of MAC specific info in the documentation would be great (unless it is there already but I didn't see it yet so far)
#193
When they are finalized, I will add a section to the World Editor Interface about Windows Hotkeys and Mac Hotkeys.
06/29/2009 (2:07 pm)
@Hokuto - They are still working on the hotkey assignments, so I will not update or document that portion until release or post-release. It's too much hassle to go back through and constantly update the shortcuts.When they are finalized, I will add a section to the World Editor Interface about Windows Hotkeys and Mac Hotkeys.
#194
so right now all I can do is move horizontally left/right/forward and Back; I cannot move vertically up and down, rotate left and right or pitch the camera. Also no hotkeys to go in and out of play mode, call editors from play mode.
ouch, that makes it painful right now to navigate in your levels and place objects when using a MAC. For example if I press the Play Game icon then if I want to go back to the level I have to quit the level then reload it clicking on world editor from the tool box.
hopefully all these features will be working with documented hotkeys ASAP or it will drive me nuts.
Cheers
06/29/2009 (2:17 pm)
ah ok thanks,so right now all I can do is move horizontally left/right/forward and Back; I cannot move vertically up and down, rotate left and right or pitch the camera. Also no hotkeys to go in and out of play mode, call editors from play mode.
ouch, that makes it painful right now to navigate in your levels and place objects when using a MAC. For example if I press the Play Game icon then if I want to go back to the level I have to quit the level then reload it clicking on world editor from the tool box.
hopefully all these features will be working with documented hotkeys ASAP or it will drive me nuts.
Cheers
#195
I think that I see now that the best approach for me is to have patience with the process. I see now how very many changes must be made in the docs even since Beta 2. I will continue to comb thru the docs, pointing out minor bugs.
May I also point out stuff that is confusing or insufficiently explained (from my point of view) for your consideration to add to it? Or is it premature to do that?
Lastly: You probably already know but TSShapeConstructor documentation is out of date now. How much, I don't know, but I understand it's not a datablock anymore, at least.
06/29/2009 (3:24 pm)
Michael -- for me , no it's not overkill, it would be more appropriate to call it "good info"! On the other hand, I can see why every field will not get this level of treatment. I don't think it would be reasonable to expect that (but maybe from the book it would!).I think that I see now that the best approach for me is to have patience with the process. I see now how very many changes must be made in the docs even since Beta 2. I will continue to comb thru the docs, pointing out minor bugs.
May I also point out stuff that is confusing or insufficiently explained (from my point of view) for your consideration to add to it? Or is it premature to do that?
Lastly: You probably already know but TSShapeConstructor documentation is out of date now. How much, I don't know, but I understand it's not a datablock anymore, at least.
#196
Lot's of info in this thread. Not sure if this is listed or not. Under beginner guide>Adding Terrain>Importing a Heightmap the file listed is not available for download. If the files are there might be a good idea to list where a new user would find them. The way it is worded, sounds like they may be mixed in with the regular files:)
06/29/2009 (3:49 pm)
@Micheal,Lot's of info in this thread. Not sure if this is listed or not. Under beginner guide>Adding Terrain>Importing a Heightmap the file listed is not available for download. If the files are there might be a good idea to list where a new user would find them. The way it is worded, sounds like they may be mixed in with the regular files:)
#197
If you are referring to the HERE link, it seems to be working for me.
06/29/2009 (4:08 pm)
@Randy - Are you talking about this: If you use the Full Template in a new project, you should already have these terrain files. If not, click HERE to download a .zip file containing all of the assets you need for this tutorial. If you are referring to the HERE link, it seems to be working for me.
#198
The requested URL /t3d/official/content/documentation/Beginner Guide/World Editor/TerrainFiles.zip was not found on this server.
Here is where the actual I have is going to. Note yours is going to tourque-3d while mine is going to t3d... Am I using the wrong links again:)
http://docs.garagegames.com/t3d/official/content/documentation/Beginner%20Guide/World%20Editor/TerrainBlock.html#HeaderLink7
06/29/2009 (4:22 pm)
Yep. That's it. Not working for me in FireFox...The requested URL /t3d/official/content/documentation/Beginner Guide/World Editor/TerrainFiles.zip was not found on this server.
Here is where the actual I have is going to. Note yours is going to tourque-3d while mine is going to t3d... Am I using the wrong links again:)
http://docs.garagegames.com/t3d/official/content/documentation/Beginner%20Guide/World%20Editor/TerrainBlock.html#HeaderLink7
#199
06/29/2009 (4:29 pm)
Ah. We are in the process of moving the docs to a different URL. That should be fixed sometime this week.
#200
Ignore the man behind the curtain.
06/29/2009 (8:32 pm)
It also helps if I scroll down a little further.. Found the names:)Ignore the man behind the curtain.
Torque 3D Owner Brett Williams
Beginner Guide > Getting Started > Toolbox > Package Project
After the Packaging Advanced Settings Screenshot