Official TGE Documentation Feedback

#21 Thanks, Matt and Michael, for pointing out TDN. I had actually started consulting TDN recently, but didn't realize that that was what was considered the "Wiki". TDN is helpful, but not really what I had in mind (unless I'm missing something in what's available in TDN).

When I was talking about a "Wiki", what I meant was something like the documentation that comes with TGEA (which was pretty good, but was - of course - not all inclusive). The big difference between the TGEA documentation and what I had in mind for a "Wiki" is that the documentation would be a website with a page for each topic. But in addition to that it would have a "forum-like" section similar to this right here where users could post, make comments, write their own documentation.

With TDN, from what I can see, it's just a place for users to post Torque related articles. But many of the articles are out of date or incomplete. The information was probably accurate 5 years ago when it was published, but after various updates and what not, it just isn't correct anymore. Or, it's written for TGE or TSE but I'm trying to figure out how it's different in TGEA. It would be nice if the user community could go in and edit the article, to correct it. I didn't see any place to do that. Or, if it doesn't seem to be a good idea to hack up someone else's article, perhaps just posting comments such as "line 23 in that script should read ..." or "This works in TGE but not in TGEA." or "This feature was depricated in version 1.7.0" or "To get this to work in TGEA you need to add this scripts in this directory..." Also, more strict orginization would be helpful too. For example, the documentation for TGEA was pretty well organized, but TDN is not quite so well organized.

Quite honestly, I've only been playing around with Torque for a couple of weeks (and more recently TGEA), so I'm still learning what IS out there as far as Torque documentation is concerned. And I have to also admit that I haven't even cracked open the source code; I've had enough trouble figuring out all the scripts, 3rd party tools, and out-of-of-the-box capabilities of TGE (and now TGEA). (I also may tend to get documentation for 3rd party tools confused with Torque documentation or forget that it IS a 3rd party tool with things like Constructor, L3DT, or Torsion.) I'm about half "scared" to even think about opening the source code. I have to say, the engine itself is pretty awesome (especially with shaders in TGEA), but it's only as good as the user's ability to use it, and that requires the user to understand it, which for something the size as Torque, requires extensive documentation.

Michael mentioned hating to write documentation. I loath writing documentation at work, so I feel for you guys. But that said, we as users of the product can't appreciate it's great capabilities if we can't figure out how to use them. So, your efforts are greatly appreciated.

#22 *Quick note:

Quote:Michael mentioned hating to write documentation

He is referring to my last blog where I stated that a lot of people hate writing documentation. In my blog I mentioned that there are a few of us that don't mind the task, and some weird people like me actually *enjoy* writing docs =)

@Brennen - Keep in mind that Constructor is a GG tool, not 3rd party. Other than that, all your statements are being read loud and clear =)

#23 A comprehensive description of all of the $pref variables would be nice. Far too many of them have no description or search results here, and it's painful to have to sift through lines of complicated C++ to try and guess what they're supposed to do. Just a thought.

#24 I appologize for the mis-quote. I'm glad SOMEBODY likes writing documentation. It's sure not me though. :-) (Although, I might not mind writing a few paragraphs in a Wiki or forum to explain something I've learned.) As for Constructor being a GG tool... see what I mean it's often difficult to remember what's 3rd party and what's not. And fairly or unfairly, it's easy to blame Torque for things that aren't really Torque.

#25 @Brennan
TDN is setup as a traditional Wiki. You can edit articles when logged in and engage in talk sessions about the articles as well. But that doesn't mean that the articles will necessarily get updated.

Which is one of the reasons that Michael is hitting documentation hard!

#26 Would love to see documentation covering


- opening, reading and writing to files server side
- opening , reading and writing to databases
- up to date tutorials / documents on scripting re: inventory management, gui editing, creating and adding spawns, characters, harvesting,crafting, combat etc. all the things us noobs search for but in one location

#27 @Phil - Good feedback, thanks! I've mentioned in the other feedback threads that a big part of the content generation phase will be writing tutorials and updating standard engine references. Your suggestion for updated tutorials and file writing fit perfectly in those categories.

However, your suggestion for database docs is a bit tricky. As far as I know, there is no database support (MS SQL, MySQL, SQL Lite, etc) in stock TGE. There are resources for implementing the feature, but the official docs will only be covering stock engines.

The only exception might be if we find a resource that makes a great tutorial, but requires integrating a new feature. If that happens, we will document the new implementation to the fullest.

#28 Script Callback Inquiry

MP - Posting here for my own future reference

#29 Big Announcement About Documentation

#30 "I would like, for each Torque C++ or TorqueScript function :

- a clear description of the parameters, with their units (think radian/degree) and their limits
- a clear description of their return values

- a clear description of the goal of that function

- some examples of uses

- a open space of discussion about this function (user's add-on to the documentation"

+1 on that what Nicolas Said.

And my addition

-all like said above for object classes, callbacks, variables,...

TDN:
better organisation


br

#31 @John - I'm thinking TDN needs to be organized the way TGB's section is. I think the TGB section on TDN is very organized and regularly maintained. That's definitely on my very long to-do list.

#32 Ditto on the examples.

but the biggest problem i run into is when searching for a function in the engine or script or whatever is the EMPTY docs that are there.

I do a search for a function and all i get back is a parameter list with types. I can easily get that from the source. Whats missing is the Why for said function. and eamples!


an example of some of the better docs I have run into:
http://www.garagegames.com/docs/tge/general/apds17.php
http://tdn.garagegames.com/wiki/TorqueScript_Console_Functions_3

And some bad examples:
http://tdn.garagegames.com/wiki/WorldBuilding/MissionEditor/fxshapereplicator
-- ok thats nice.. some syntax. but what do all the fields MEAN? ... Why are the values they way they are?

http://www.garagegames.com/docs/tge/engine/classfxFoliageReplicator_1_1tagFieldData.php
-- completely empty of comments

yes i know searching for those 2 classes gives other hits. but thats beside the point. the official documention should be the source, not other people's posts on forums.

#33 @Jon - Read loud and clear. I'll talk about this at a later point, but I've determined that documentation work is broken down into a few main categories. One such category is "generation". This process involves completely new content being added, either to fill in holes or add on to existing content.

I've found those empty documents too, so I'll do my best to fill them in. As you come across these holes, please post them here so I can create a list during the generation phase.

#34 I haven't read all of these posts as of yet, but I will soon.
For the moment, I have something to say about the documentation from GarageGames about TGE.
First of all, everything seems to be scattered all over the site, the forums, the TDN, etc.
Doing a search shows you a lot of (for me) useless information and there's no way to narrow the search down to TGE specifics.

The tutorials are lacking, in that the only useful official GG tutorial I have used is the PDF that comes with the engine. That one is useful because it walks you through a bunch of things in a certain order, whereas most other tutorials are simply short examples of code with an explanation to the code.
How about a tutorial that goes over different parts in a certain order? An Add-on for the PDF for example, that goes over how to set it up for multiplayer, how it works, etc.

Another thing is that GG claims that TGE has kickass networking capabilities, I'm sure it does, but there's no tutorials that goes through it and explains how to work it.

The most help I've gotten so far has been; "Go look at the examples, such as the starter.fps". Well, I have, but for a newbie to decipher all the scripts and figure out what does what is a nightmare.
The second help was hands-on from the IRC channel, where I wrote the problem and someone pointed me in the right direction.

For fun I decided to split up the server and client part of the starter.fps example that comes with TGE as I am working on a multiplayer game, but with the lack of documentation it's been half of a nightmare though I have now figured it out.


My suggestions;

Centrealise (Not sure how that is spelled, sorry) the documentations and tutorials in one place. Such as, if a community member writes a very informative tutorial, talk to the member and ask if it can be posted in a tutorial-section on the site where it is easy to find.

Make it easy to find specific information by narrowing search-options.

Get the blank pages written, there ARE links to them from the newbie section, yet they are blank.
If GG doesn't have the time, maybe someone in the community does?

I'll be writing some articles about how to use Houdini-HD with TGE and hope that it will be posted on the site when it is done, if deemed good enough.
Another thing about Houdini, is that apparently the version one can buy through GG is a beta?
I haven't looked into that but I've heard people complain about it.
If it is, ( can't check as I'm not at my normal computer) then it should be stated on the info page for that product.


Basically, clear up the mess.
Centrealise the documentation so it's easy to find and use, instead of having it scattered all over.
Mostly what I have written is in general, and about scripting-info.

I realize that this seems like a rant, and it is to some extent.
I like the TGE and will be using it for big projects, but I'm annoyed at the mess and how hard it can be to find useful information (The forum search for example, brings up a lot of other info that I don't need, such as TGB info.)

/Marcus "Daimon"

#35 @Marcus - Thanks for the list. Something I haven't really talked about yet is how I'm approaching all of the tutorials I'll be generating. Despite the years I've been using TGE, I will be tackling everything from a newcomer's perspective. I will still use the knowledge I have to be as detailed as possible, but I want everything that gets written from here-on-out to be simple enough for a newbie to use.

Now, this might not be the exact route I take with reference documentation, but I will always keep in mind the newbies and veterans alike.

Mess is probably a good word to use when looking at the organization of all the docs for all the engines. There is a lot of great content, but it is so scattered that it can be a time suck to try and find it all. Definitely working on that as well.

As far as you writing tutorials, keep me updated. When you feel you have a completed tutorial, send me an e-mail. I'll make sure it gets the spotlight it deserves, in some form or another. A Houdini-HD tutorial will probably be pushed through faster than any other tutorial, as new technology usually has the least amount of documentation (not all the time, obviously).

Good stuff! =)

#36 The tutorials will be in both text and hopefully video too.
And I'll get to it as soon as possible.
I'll keep you posted about it.

I'd like to point out that there is a ton of information on the GG site, it's mainly the organization I'm having issues with.

Thanks for the quick reply Michael, it's appreciated.

#37 There aren't many well written tutorials for TGE out there. They all rely on you figuring out the spaces they don't cover.3DPAi1 was a good step in the right direction, but let's face it, didn't cover anywhere near the areas it needed to, and completely drops you off around chapter 10. So what does this lead to, you might ask. Well, this tutorial should have a common thing that it is trying to achieve. 3DPAi1 one did this, keeping to the FPS genre. However, It didn't really teach you how to make one. It was more like a modeling tutorial. A tutorial needs to teach you, from ground up, how to get that game running, so you could code it without the book. So I'm going to give a "model" of what a tutorials should look like, a model that would give any reader the tools they need to be able to modify the code to give them. All code given to a reader must be accompanied by the skills needed to use it, and modify it how the reader needs it. I would make this tutorial myself, but there is no reason someone who actually knows TGE, and a lot better than I could learn it in 6-8 months. There should be a sample project to work with in each chapter, one that did everything from the last chapter, so the person is on the exact same page with the tutorial. The CD should include sample models and scripts from all the chapters, for the reader to compare with. Of course as you go by, you would keep a good client/server architecture, as if you were going to make a single/multiplayer game. I don't know torque script, but I know how it works well enough to make a template for a good tutorial.

Chapter 1: Introduction to 3D Game Development.
3DPAi1 did this correctly. It gives you a baseline for making a game.

Chapter 2: Introduction to programming.
3DPAi1 did this correctly. It gives you the general background for making a game.

Chapter 3: 3D Programming concepts.
3DPAi1 did this correctly. It gives you more background in coding, and hinting the client/server architecture would be good here.

This is where the usefulness of 3DPAi1 stopped. It just tells you to install an engine, and slightly add to it. This is bad.

Chapter 4: Basic landscape (includes the finishing product for the reader to compare with)
Completely teaches how to get the Torque Game Engine running, with a blank wireframe landscape
-Texturing the landscape
Teaches how to texture the landscape in the Torque Mission Editor, and teaches the many features of it.
-Terraforming the landscape
Teaches how to make canyons and hills with the Torque Mission Editor

Chapter 5: Server vs Client
Teaches the server vs client architecture of Torque.

Chapter 6: Adding detail to the world (Includes the finishing product from last chapter, for reader to work with.)
-Structures
Teaches how to make basic structures in MS3D and QuArK, and add them to the landscape, like houses and bridges.
-Rocks + Trees
Teaches how to make rocks and trees, and add them to the landscape.
-Water
Teaches how to add water into the landscape, and "waterblocks"

Chapter 7: Setting up the player (includes a sample file if the finishing product from chapter 5, for the reader to work with, I won't put this message anymore, but every chapter should contain a finished product from the previous chapter for the reader to work with)
-Modeling the player
Teaches how to model a person(The player).
-Adding the player to the game
Teaches how to add the player to the game, and documents the script needed to get him moving, and attaching the camera, ect.
-Animating the player
Teaches how to animate the player when we walks, jumps, falls, etc.
-Setting up the players health
Teaches how to set up a players health, etc

Chapter 8: Movement alterations (Thanks for the tip, Andrew.) //Ah yes, this is a subject none of the tutorials cover.
-Swimming
Teaches how to get the character to swim (not just sink, and be able to jump up and down at the bottom)
-Wind
Wind pushing the character.
-Moving platforms
I don't know if this is already supported, but make sure that the character moves with moving platforms.

#38 Chapter 9: Adding pickup-able objects into the world
-The objects
Teaches how to model a generic item, like a candy bar, and place it into the world
-Picking it up
Teaches how to "pick-up" the object
-Inventory
Teaches how to make an inventory and add picked up objects to it.
-Use-on-pickup items like med kits
Teaches how to make med kits, ect.

Chapter 10: Making a weapon
-The modeling
Teaches how to model the weapon
-Adding it to the world
Teaches how to add it to the world
-Picking it up
Teaches how to pick up the weapon
-Firing the weapon
Teaches how to script the weapon to fire, reload, ect.

Chapter 11: An NPC
-The modeling
Teaches how to model an NPC (Another human/ a beast)
-Adding it into the world
How to add it into the world
-Give it life
Make it move toward you when you get close enough
Fire at you on "sight", or if fired upon.

Chapter 12: Coins
-Modeling
-Adding it into the world
-Picking it up and adding it to money reserve

Chapter 13: Non hostile NPCs
-Modeling (if you want)
-Adding it to the world
-Give it life
Teaches how to talk to NPCs, and how to "buy" thing from them (Ammo, another weapon)

Chapter 14: Containers
-Chests
How to model and script a chest you can open up and take things from
-NPCs
How to make NPC containers when they die, allowing you to loot money, guns, ammo, ect from them.

Chapter 15: Quests
This chapter would teach how to make a little quest. It would have you talk to a non-hostile NPC and have you kill an NPC and take a certain quest object for it, and giving you a cash reward when you come back to the NPC with it.

Chapter 16: Making a vehicle
-Modeling
-Adding it to the world
-Scripting
Teaches how to script the vehicle, make it mount and unmountable, and how to modify its properties.

Chapter 17: Multiplayer
//Now would be a good time to explain how the client/server format works.
-Making a Multiplayer arena (Modeling, ect)
//Some of the aspects of a single player game we went over in previous chapters wouldn't make for a good multiplayer game
-Implementing dedicated and listen server features
-Multiplayer over online (Not just LAN, through game spy or something)

/* (not really needed)
Chapter 18: Non-"Ground up" Tutorials (This is good for showing the reader what he/she can do. This type of stuff won't build his base knowledge, but will build up higher, and show him/her he/she can build on the knowledge the reader has)
-Spectator mode for multiplayer games
-Scoring in multiplayer games
-AI path finding
-Making NPC have "goals"
-Other types of vehicles (ones that have treads, ones that hover, ect)
-Other modes for multiplayer (CTF, Bombing run, ect)
-Anti-cheat devices for multiplayer (Logical tester [Notices if someone is running super fast, doing too much damage, isn't taking damage, has too much health, shooting too quick, ect], vote kick [completely server driven, so they can't pull a "Warrock" on the vote kick,], ect)
-Structure "ownership" (could be an NPC or player)
-Making structures attack certain people or NPC (Like a turret)
-Making structures destroyable (Like the turret)
*/
Chapter 19: The end
Includes a list of resources for the reader to use , gives them some idea of where to go now, ect


In conclusion, a tutorial like this would build a reader's skills from the base, allowing him to be able to DESIGN an FPS game from the ground up, not modify some engine already coded like 3DPAi1 had us do. At the same time it would give him the skills to "dive" right into an advanced tutorial like the RTS starter kit. It is also based on a much more user-friendly teaching method. While 3DPAi1 teaches through Trial and Error, and trust me it does, this template actually makes the reader feel he/she is getting somewhere with learning the code, considering the reader is accually building his FPS while learing it, makes the learning process less soul-devouring. Of course he/she could always look at the examples of the chapters on the disk to make sure he/she is on the right track) Of course this tutorial would be hard to pick up for someone who doesn't have ANY code experience, but anyone who knows any code with some decency should be able to pick this up with relative ease.

#39 Might I suggest, that in chaper 7 of your templace, expand it to include movement alterations in general? Swimming, running, physical zones, jump pads, teleporters.

#40 @James - Wow, that's a pretty good model! =) That's gonna be very useful when I get to the actual tutorial writing.