Official Torque X Documentation Feedback

#1 Please give some at least vaguely comprehensive look at the GUI system. I've pieced together an understanding of it through experimentation and the different methods used in the different demos, but there are still parts that remain mystical (for example, I can't get parents' visibility to affect their children, even though the docs say it should, so I'm probably not setting up the relationship correctly). Some document that explains good practices on how to set up a working GUI would be great.

#2 What I'd like to see is two FAQ-like lists:
Common Issues
Common Features

Common Issues would have things like:
Why are my 2d sprites disappearing?
Why is the screen purple?
How do I fix common exceptions during deserialization?

There are a number of little gotchas in Torque X that are addressed in the forums, but should be collected in a single document. For example, I recently read a code comment explaining that T2DSceneCamera.FarDistance needs to be set to a number greater than the number of objects in the scene. I'm pretty sure that's not in any documentation. (http://www.garagegames.com/mg/forums/result.thread.php?qt=71127)

'Halo' artifacts around sprites: http://www.garagegames.com/mg/forums/result.thread.php?qt=62168

Russell Bishop has collected some issues here:
http://www.garagegames.com/mg/forums/result.thread.php?qt=74059
http://tdn.garagegames.com/wiki/TorqueX/CommonModelProblems

--------------------------------------------------------------------------------------
Common Features would have a list of features people are likely to implement in their games that require some explanation. Some examples:

mouse input
http://www.garagegames.com/mg/forums/result.thread.php?qt=70642

3d content
http://www.garagegames.com/mg/forums/result.thread.php?qt=71472

adding 3d objects to 2d scenes:
http://www.garagegames.com/mg/forums/result.thread.php?qt=74853

From my perspective the tutorials are fine as they are, and what we need are more feature-specific TDN entries, like exploring GUIs as mentioned above.
--------------------------------------------------------------------------------------

Just having an official 'home' for this kind of stuff on TDN with an employee or associate gathering the information from the forums and verifying it with the engineers would be nice. And important code comments like "You need to set the camera's FarDistance if you have more than X objects in your scene" could be copied to the Common Issues list (or Things You Should Know list?) when those comments are written so they're not so obscure.

Biggest single 'fix' that could be made for Torque X documentation is to add the ability to limit garagegames.com searches to a specific product. Or at least see the product name in the list of Forum Thread results. There is so much information on all the other products compared to Torque X that searching without some kind of TorqueX-specific keyword just returns too many irrelevant results.

#3 @William - Great suggestion

@D. Robert - Great suggestions. Much thanks for providing those examples as well.


@Both - Awesome, awesome starting posts guys. Thanks =)

#4 It'd be nice to see a complete tutorial that doesn't use xml at all. It's more comforting as a coder to be able to handle everything in code.

#5 Another thing that would be useful to see documented is to have best practices, performance, and the limits covered.

This would include, what is the highest velocity that torque can handle before an object completely misses its world limits?
Max amount of objects with certain kinds of physics and collisions and how to maximized performance in these situations.
Are there any side effects to zooming the camera out to a 1024x767 extent if you just want to get a better idea for the boundaries of the camera.

#6 The number one thing I would like to learn about TorqueX is lighting. Everything else is pretty awesome.

Maybe include a simple game that shows people how to use the GUI library, and include a simple game that shows people the T2DPhysicsComponent (i.e. inverse mass, rotation scale, ApplyImpulse(), how to rotate a force once it's added, etc.).

A simple game that's specifically made to show off what you can do with lighting, GUI, or physics in TorqueX would be awesome.

#7 @rwillis: I seem to remember you discovering/being pointed to the 2D lighting demo--would that be a good place to start for the 2D side, or are you thinking about something different?

Of course, if my memory is incorrect, then, umm--you might want to check out the 2D lighting demo :)

#8 I checked it out. It was pretty good and let me get some light in the game, but it was hard for me to figure out what some of the specific fields were for. I tried playing around with them and sometimes I'd get something I was expecting, but then other times I would get something I was definitely unexpecting. But the 2D light demo was great for showing me how to put the lights in my scene and set the lights up (as in plug them in and turn them on). I just never understood some of the parameters. Usually I'd just tweak a value until it did something I was looking for. Although, for example, I never really figured out how to change the size of a light. Also, whenever I changed ConstantAttenuation to a value other than 1, it would do something much odder than if I had it at 1.

I think if there was a tutorial which just simply showed examples of how a light can be changed by adjusting the T2DLightComponents properties, then any person can just see that without having to dig around a bit (in a demo or code).

SO metaphorically speaking, I was able to put the light on stage and turn it on, but there was some buttons and levers that I didn't know how to work and that I could only get information about from a brief manual (the comments in code) or the engineering documents (the code).

#9 The first thing that comes into mind is a good search engine for the forums. Because the forums have such precious information but is soooo difficult to find it... Even using the search engine you offer at the top of the page. I always end up looking for info thread by thread and that is desperating.

Also, I think you should have a reference manual for the TX classes and methods. I've tried searching in TDN but it is very outdated.

#10 @Carolina - Definitely a much requested feature/improvement from the community. Unfortunately, that is more in line with the website design and functionality.

However, I can post that one goal is making documentation easier to find by way of consolidation and frequently updated links to sites and articles.

#11 Any documentation done, be it on the forums, TDN or in tutorials should always explain the 'why' and 'how' parts.

It is all well and good having a tutorial that has the code and shows you the specifics to do in order to create something, but if it isn't telling you the 'why it works' and 'how it works' part then it is hard for people to take that specific knowledge and apply it to their own ideas and coding.

Made up example:

Add this code to the xyz component in the movement secton to make your plane fly.

Code snippet.......blah blah


This would not be good enough to help beginers understand the underlying workings, so outside of the tutorial it would be useless to them as they would not understand how that translates to what they want to do with their program.

#12 Well I just installed TorqueX 2 last night so I haven't gotten very far but I got a sinking feeling when the very first page of the docs, included with the install, had incorrect information on it for how to get started.

"Select from the available Torque X templates: Tank Buster, Space Shooter, Split Screen, Torque Combat, Starter Game (a "Pro" in the template name means the template contains Torque X engine source code)"

Apparently those templates do not exist anymore. Now I can certainly understand out of date docs, things move pretty fast. However, out of date documentation and resources were one of the major things that drove me away from TGE 1.4 in frustration (this was prior to TDN) so an attempt to keep up has to be made. At the very least you should ensure that the getting started documentation that you include with the install of your product is up to date. That's the very first thing your customers and prospective customers will see, and if the getting started info is wrong, what faith are they going to have that the rest of it is OK?

No developer likes documentation but when your in the business of selling your products, you have to bite the bullet and just do it, not doing so translates into lost sales. I myself am hesitant to purchase now not only because of this doc glitch but the website glitches from my home ISP (I'm on of those who gets Service Unavailable from home but everything works fine from my workplace)

#13 @Mark - Thanks for jumping over to this thread so quickly.

Quote:
No developer likes documentation...

Not true...I love it =)

When a new engine is released, the first thing I do after I install is go straight to the documentation. Is it twisted that I drool over the docs instead of the tech? O.o

Creating new documentation is also the most rewarding for me. I'm at this weird point in my career where I'd rather help others than make my own games.

On a more serious note, thanks for the feedback. The feedback threads are being tracked with each new post, and so far the material is very helpful and being taken to heart.

#14 I want to second Williams request for better docs about the GUI. It would be very nice to have a little tutorial-project which would just creat some mainmenu, then a button to start the game and a button which would open an options GUI with some basic options that could be changed and saved, like screen resolution. I think this would help out all the beginners a lot because it would provide some kind of skeleton for a game.
Also i would appreciate a tutorial on how to save and load scenes and on how to change levels (scenes).
I liek current TGB docs very much, the TGB reference is quite useful. Would be cool to have something liek this as well for TX in the docs. Plus and most importantly the docs should reflect the current release, not like now.
so my list would be:
1.) Complete GUI Totorial
2.) TGB reference (ideally everything documented with a sentence about what it does).
3.) Some more examples of components

Generally i really like the move GG does now to improve the docs. The first TX docs for the 1.0 release where quite good, also the Tutorials that followed shortly after....so keep up the good work ;-).

#15 One thing to keep in mind with TX--since it's so tightly integrated with XNA and C#, and Visual Studio is required for development, reference docs that are generated by Visual Studio itself are extremely useful--you can serialize everything to XML automatically, and then turn it into a .chm file trivially as well.

I think a quick tutorial on how to generate user docs might be in order here, since this comes up from time to time.

#16 I think the documentation is ok. But there are loads of ways to improve them.

1. Create a online area with an FAQ about the engine like D. Robert said. Like when there is a major problem like the blurriness or the purple screen when the window is minimised. It should all be posted in one common area. Not the forum as it can be searched well. Simple as problem found and the solution to rectify it.

2.Also agree with the more tutorials. Just really small ones are the best. For example the save/load or the the GUI as said above. If they are small they can pretty much be integrated into the games, with minimal effort. No game in it, just the bit that it's explaining.

EDIT: Also long time users should be able to create document bits, which could then be integrated into the ref docs. Sort of helping out where they can :D

#17 Stephen,

If I wanted to get started generating docs for TX from Visual Studio, what is a good starting point?

#18 How about better keyword search capability?

Since the entire community uses Visual Studio or has used it at some time, I'm AMAZED this hasn't been an issue forever. I want to be able to look up TorqueX Object/Class/Component definitions just like I do for any other Microsoft SDK Object/Class/Component.

I want a search box where I can type in "Move()" and at least ONE option in the results takes me to the "Move()" class, where it spells out all that class's dependencies for building, the class's properties and methods along with hyperlinks to drill deeper as needed, and a "see also" section where I can jump off into related subjects.

I'm not asking that you integrate your help with Visual Studio so I can hover over class names and click them and press F1 to go straight to them, but as close to that as possible would be appreciated. Since TorqueX is only usable with Visual Studio, such integration shouldn't be out of the question though.

One area that's completely lacking on documentation is the Physics engine. What is a T2DForce component and how would I know whether or not I should use one? What units to the Physics components use/assume?

I think in general T2D and TX rely FAR too much on a few code samples. A lot of your potential customer base doesn't necessarily understand what those programs are doing but WOULD understand a simple breakdown of Classes, their Properties & Methods, and a brief synopsis of their intended usage.

Cheers,
ALF

#19 @ALF - Thanks for the feedback. The offline documentation does have a search box. Have you used that yet? If so, what is your opinion of it?

#20 The offline documentation's search box is as useful as it can be - the amount of information in both Torque X and Torque X Builder documentations is very limited! I agree with Anthony (as you can see in my previous post) that there should be class reference documentation describing classes, their dependencies and methods and variables. This is a must have for any SDK. And by my experience working with Torque X, this is something that would have been soooo useful for me. I had to bang my head on code samples trying to guess how to adapt that to my needs. And I think this is ridiculous - this is not good programming. I don't enjoy having to limit myself to existing code samples or having to guess what other classes do because they aren't documented anywhere.
About Torque X Builder - this is a payed tool, therefore I think you should at least produce a reference manual about the components you offer (as T2DPhysicsComponent, etc). The other day I needed to create some materials that dropped from the sky. Despite trying to understand the T2DForceComponent I eventually gave up and used some values someone suggested in a forum... In TXB documentation the only help for T2DForce component was
"If you add this component you will have the ability to add arbitrary forces to your object. There are several types of forces that can be added (force types are: Force, MasslessForce, DragForce, DragForceDirectional, and DragForceBidirectional. Any number of forces can be added and removed during the course of the game. You can also control the strength of given forces, allowing the player to control, for example, the thrust of a space ship or the acceleration of a car."
There is no explanation about each of the referred forces!

Again about the search box - I do think it is very useful (inside the limited information). But it has another problem: it doesn't return results if the keyword is inside a code sample between dots (ex: search by AddComponent returns 0 results in TorqueX Documentation, although the word appears a lot inside code samples)

I congratulate you for trying to understand the needs of your end users. I hope you'll be able to implement all the ideas you've been retrieving (although it might be too late for me).

Keep up the good work.