Why WAS Torque3D documentation so poor?

#61 @Eric,

nice to hear about the lab, sounds excellent.

definately it will help a lot.


one more thing that T3D really needs in my opinion, and some other engines are doing is to create mini games samples in different genres to jump start beguiners.

for instance like UDK is doing, they have a crew which are dedicated to build mini games, small team if not an individual who creates a single small level in a genre specific mini game and make it available to users to jump start on your project with developement blog to explain how it was done.
nothing too elaborate but something that could be done in 2 weeks


I must say this is what I really love about UDK. escellent documentation plus step by step tutorial on mini games demos.


I think this will make an excellent feature instead of the empty desert level shipped with T3D which des not look nothing appealing at all, which needs to be made eye candy to inspire new customers.

liike I said and in my case as many others I believe that I am a visual kinda guy, as an eye candy looking things will definately fall for them.
as well as a example follower kinda guy, rather learn from examples even if they are small mini games but are easy learn from them instead of going thru painfull start from scratch.

is al about visual and simpleness, at least for me.

Just my .02 cents.

#62 Great feedback p-cap. I think many others share the sentiment about visual examples.

#63 Indeed, I think in my opinion will make a huge step on the market,

as in my example of UDK, which I dont want to highjack the thread writing about it, as its documentation is so huge and hundreads of video tutorials found on 3dbuzz along with the minigames is what makes it more appealing. and the engine is free to use in some way as in the initial invest kinda way, what else can you ask for.

But.....
why did I buy T3D? instead to go for UDK ans all of its nice features?

well, the answer is simple, for some reason I believe in T3D,
Note: I am not a fan of T3D, BUT there is something about it that makes me want to stick with it instead of other options.

I speak for myself, but regarding this thread it looks like many T3D members here share the same feeling as I do, and we are starving to learn more about T3D, instead of turning around and look somwhere else.
we all share the same feeling, we like it and we want to stick with it.

T3D has lots of potential, and I know it will eventually shine if not it is already doing it by now.

it just needs to be polished, making it eye candy, documentation, example minigames, video tutorials etc....

I know this is too much and is hard work to accomplish in a short period of time.


BUT.....
maybe some sort of contest among the community to develop minigames in different genres, or mini game video tutorials and offering some sort of gratification to winner, it will help insanely and time saving for T3D employees, so original T3D devs focus on the engine so developement and or bug fixing wont fall behind.

#64 @Eric:
I think the idea of dedicating an entire facility/team to QA on T3D is a great development. For a long time it feels like there's been a solid split between the people who make the engine and the people who use it, with the GG team being understaffed to the point where they never really get to attempt to build anything in the technology they've developed. That's led to a lot of excellent features that really never made it to a polished state or were simply hidden in the engine and forgotten. I think having a department focused on trying these things out from the user's perspective will help make the engine more usable, whether it results in actual documentation or not.

@The whole discussion:
I still feel like there are a lot of expectation issues, but either way it sounds like the team is trying to get on top of the situation, which is a good sign.

RE: Database access examples (etc):
This is a case, in my opinion, of "not actually a T3D issue." It's not a specific Torque issue, this is more of a general programming knowledge thing. If you've built the mySQL SDK into 1 app, you know what to do here. If the question was "how do I make script functions that can access my code-integrated database SDK," then we might have an issue for T3D docs in a less specific form (ie, how to make consolemethods/consolevars and tie them to code).

It's the same as expecting the engine to teach you HLSL shader code from the ground up. That's an external skill. Now, teaching the users the specifics of *T3D's HLSL* code, that is appropriate.

In my opinion, reference docs are more valuable than detailed how-to's (though those can also be important - for example, I found the stuff in the docs about using the new rendering system extremely valuable, and that was well beyond a function reference). Realistically, if we could start to get a full index of what exists in the engine and put it in some kind of wiki format, users would begin to fill in examples when the devs can't get to it.

@What is T3D?
I guess the real debate hidden here is about which way T3D should go from a marketing standpoint.

Torque is either a game engine or a game toolkit. Technically it's both, but it's always been sort of a 70/30 split favoring "engine." I always picked Torque over other options because I wanted an engine, a commercial grade piece of software that just throws the code in front of you wide open, "make my game" buttons be damned. You want to install ODE on your own with no actual support? Go for it. Need to rewrite the core rendering code? You're crazy, but feel free.

These days, more and more people seem to be expecting a "game maker" software, as if it were some kind of "Adobe GameKit CS4." IMO the problem with such a piece of software is that, while the hobbyist might find it more useful, serious programmers(or whatever) tend to find it limiting.

Personally, I'd like to see Torque continue to remain a technically powerful engine with appropriate integrated tools, not become a closed-box SDK you make mods for. But, I'm just 1 guy, and I probably don't speak for the common software buyer... in the end the engine needs to make money, and while $1000 is still a great deal for this codebase, it brings it into competition with packages that have less S and more DK.

I feel like I'm just repeating myself at this point, so I'm going to bail out now.

#65 I'd be happy with a dozen or so RTS Prototype style examples. Examples that covers a nice range of typical uses. If I could make enough small games following such examples, some of the basic concepts that still seem foreign and daunting to my artistically-slanted brain will be easier to digest.

I've got a very nicely detailed design document shaping up for my pet project, but only a few elements can I even begin to understand how to program/script. I don't need my hand held for each of my specific ideas, but if I can start my project in earnest with having created a number of examples (like the RTS prototype), I can spend more time making my game, and less time forum fishing.

On that note, I miss the concept of the TDN wiki. I don't see why it can be tried again, only merge it with the rest of the site so it has a chance to be seen/used.

All that said, for what they are, I love the current documents. The topics they cover are covered very well and I have absolutely no trouble following them. Great work!

#66 @Eric: I greatly appreciate the personal attention to our class. I'll definitely pass along the request to my instructor. So far, we're the first group in the history of the school to successfully create a turn-based strategy with one of GG's 3D engines. Perhaps with your help, the school's projects can break out of the FPS/RPG rut that they've been stuck in for so long because of the issues we've discussed in this thread.

@Phillip: If you reference my other posts, I mentioned that I'm a student of game design, currently completing what is essentially a capstone piece for my portfolio alongside a team of other students. This engine was not a choice for us. We were required to purchase it regardless of where our proficiencies lie. While I would like to be a proficient programmer, my aspirations lie in the game design/level design areas and, as a result, I probably would have gone with UDK (not because I consider it a superior engine, but because it really is perfect for what my portfolio needs to consist of: short, pretty levels made with someone else's assets).
My college chose to use T3D because of the access we have to source and the ability to continue to make projects outside of school and sell them on the PC platform with no other royalties or costs needing to be paid to GG. But because there's no help for beginners, the overwhelmingly vast majority of projects that come back to the instructors are of the FPS genre, and no students really utilize the engine after they graduate.
The thread was started to hopefully influence the priority level of documentation as a whole. Of course APIs should be foremost, but to continue to stay competitive and gain more market share, GG needs to keep barreling out the docs, trickling it down to beginner tutorials, video tutorials, and code examples.

@All: While there has been talk of how great UDK's docs and vids are, we have to remember that Epic has some seriously ridiculous money to allocate to any one to a dozen goals at a time. What they don't have is the ability to allow for comparatively fast change as their customers request it. Eric came right down to our level to talk to us directly and address our concerns. If you were to complain about one of UDK's failings on the forums, the best you could hope for is an intelligent response from another member. But you're more likely to get flammed instead.

#67 I notice that a lot of people would like genre specific tutorials, while I think those are useful, it is unrealistic to expect GG to produce those no charge. I think it absolutely essential we get API documentation only.

Now to satisfy the genre specific tutorial needs of some, why not do something similar to what Luxology offers with their low cost topic specific tutorials. I think that if GG did something similar to this, it would give people a great option and provide additional revenue for GG. Sure, they may not make a profit from it, but they may cover costs and develope good will with the customers.

Luxology Modo Training

#68 @Black: I agree. While I'm still pulling hard for beginner tutorials as well as API, genre specific is a bit unrealistic.

@Eric: On that note, my team and I are just finishing the alpha level development of a turn-based strategy game with T3D that, while still in the alpha stages, seems to be working just fine. After some more refinement and perhaps some discussion with GG, I'd be happy to work with you to see about development of a genre kit for turn-based strategy games.

#69 I think genre-specific is not only a valid goal, but an eminently necessary and highly desirable one--it is important to show what the engine can do, and some quick modifications to the existing starter levels could go quite some ways towards showing that T3D is the right platform for building whatever a potential customer has in mind.

T3D is an FPS as shipped--weaponry, inventory, chat and even network play--is FPS down to the bone. The quibbling over mouselook is a case in point. Not a few people make it their first question these days--which to me is an strong indication that they had no intention of building an FPS coming in, given that they right-off-the-bat seek the means to disable the traditional camera of the genre.

FPS is part of the gaming sphere, but it is certainly not the only, or I suspect the majority of the types of game being built these days, and such a strong genre identification with a particular engine can be helpful or hurtful.

It is helpful if that is the focus of the engine maker and their message to the potential base: we are *the* choice for this genre.

It is hurtful if a developer in that potential base wants to build an RPG, or an RTS, or a MMO, and gets the impression from the start that an engine is the wrong choice as a platform. It is perfectly possible that this is entirely the fault of their own ignorance--or "newbishness" if you absolutely must--it doesn't change their perception of the engine product one tiny jot.

Torque, oddly enough, seems to have a history of shipped games which are not FPS shooters--which means each and every one of those games' developers had to rip out the FPS at its heart and only then could start to build their game. Poker, marbles, kachinko, golf, mobile marbles, mazes, an MMO or two, several RTS.

I suggest instead throwing together three example builds; each with a single mission, some simple assets, and the appropriate scripts needed for an example camera for an "RTS", a "network RPG", and the "traditional FPS". I would select these three for broad applicability to a range of potential users, and because a large part of the simpler things to do are already written out--for example, the RTS camera is done in Michael's T3D docs, as is the simple scripting needed to make a click-to-move AI player--all are available but scattered between TGE/TGEA/T3D forums, resources, TDN, and the official docs.

#70 "RTS" covers moving a puppet with a mouseclick, navigating a map, and points out hooks where AI should logically go--it doesn't have to provide the AI, but should provide some solid texts (not links--they date horribly, and the bad links in the forums are legion, and another rant) to refer to. It costs almost nothing to point people towards good solid references for beginners, and surprisingly, even in this age of Google, some people struggle with finding them--Matt Buckland's Programming Game AI by Example seems to be a favorite here, to point one out, as I've seen several references to it in forum threads. It seems an easy place to add value--provide a solid list of places to explore further.

"Network RPG" covers shared worlds, and is the starter point for an MMO, but doesn't require building out all the scability and backend coding needed for implementation--that is not the engine maker's purview; it really is beyond the scope of a tutorial and hugely specific to the needs of individual games.

In any case, providing a starting point for the game genre generating massive developer interest at the moment shouldn't be ruled out for an engine provider--the network code is already there, and is one of Torque's remaining strengths.

Instructions on how to log straight into a mission and bypass the FPS-style "join game" dialog need to be included, as this is easy to do in script, hitting both the Binary and Pro bases in the same effort. Right mouselook camera, too. Simple backpack-style inventory (which Michael has written already, as the GUI inventory tutorial). Maybe substitute a particle effect for a bullet, as a "spell".

If you wanted to be thorough, incorporate the changes to the engine needed to support HTH melee so that Binary users could add hand to hand in script. This is a little more work, and a big break with "Torque Tradition" but I would wager that it would pay off very well in new user interest and open up T3D to a fighting game subgenre--which brings us full circle to....

"FPS". I believe this one is little to no effort at all, except a little polish, like a character selector (again sharable with the other genre styles) for multiple body types--that's pretty standard issue these days in games.

T3D does FPS genotypically out of the box, and it's really not my field, so I'll leave it to the experts to talk about what is "essential" and what is not to a beginner in this genre beyond this.

The "cool I did something" factor has to be present right away. It simply isn't possible to stress that enough. T3D is much, much improved over TGEA in terms of getting directly to "do" something--the mechanism of the Toolbox helped this, at least, along immensely. Previously, one had to root around for a bit to figure out where the missions were--the addition of a visual list of example missions and a Play button was a huge leap forward for those new to the engine.

I'm sure the more advanced users will disagree. And I cede they have earned that privilege--none of these suggested efforts on the behalf of the inexperienced above is of immediate benefit to them. I'd also point out that none of the above in any way should detract or distract from the production of a thorough API reference for the long-term, sophisticated user--that has to be of equal priority and their needs should not be slighted or ignored. I would note however--with the utmost deference--that if my concern was to attract new users those who have already bought the engine several times over are perhaps the wrong sounding board for this subject.

(BTW-1000 word limit is fail)

#71 I agree with Black. somehow, the course of this discussion has seemed to move away from api references and toward customer experience and tutorials.

I'm not sure how a QA lab with a bug tracking architecture or data retention system is going to give me the list of callbacks that gui objects use. in fact, im pretty sure it wont.

and for the life of me I can't understand how these guys have enough money to create f*^&ing research labs, but can't pay someone a week's worth of full-time pay to pump out a reference list.

OK, two weeks at the most.

and on a side note, can I just say that I *hate* all of torque's so-called video tutorials. heres a news flash, theyre not tutorials! theyre just propaganda showing off features of the engine. please stop referring to those as tutorials, it twists the meaning of what a true tutorial is supposed to be.

I WANT my callback lists. and i want console functions added to the CHM.

#72 Yeah, the whole research lab is great to a certain point. I really feel like the quality of Torque3D has reached a certain level of quality to be used commercially. Don't get me wrong, I would love to see more quality assurance in all of my software that I use.

With the current quality level, it is time to help the customer base who hasn't been using Torque for the last 5+ years, learn how to get up to speed quickly. A good CHM with console methods and callbacks would help a lot.

Like Sean said, a guy on docs full time should be able to get a lot done in two weeks or so if truly dedicated to doing so.

#73 Netwyrm said:

Quote:I think genre-specific is not only a valid goal, but an eminently necessary and highly desirable one...[and all the rest]

Hear, hear!

#74 @netwyrm: I wasn't saying they shouldn't develop genre-specific tutorials, just that it's unrealistic for them to prioritize that above API. Your point about non-FPS games is valid, but it serves to reinforce the point that we need more source code related docs so people can effectively and efficiently create products in those genre.

#75 here is where the issue is, well is not an issue tho but T3D is marely First person shooter genre out of the box,


so if not enough documentation, trying to make a game other than FPS will be marely impossible if you are new to torque3D, maybe people that has already had experience with it and or people who have had torque for several years, they might say the contrary for obvious reasons.

but other than that if you are new to it, with poor references, then it might take you months to even understand or learn on how to do game other than FPS.


thats why minigames startups kits tutorials will become handy along with well documentation, will get you up the speed to develop your game.


Devs have implemented too many goodies to torque3d lately, and they are adding stuff like crazy to make it feature rich, but I guess is time in my opinion to slow down and instead adding more stuff to it to work on polishing the engine.

there is so much areas that really needs to be polished.

1- bug fixing. simple bugs that may be carried over and over to each version and havent been fixed. which ones? dont know, but Ill bet you there will be quite some.
ie: I assume on release 1.0 the fog color issue, you setup your fog color on the level, save you level , and open back again to play mode then fog color gone, it defaults to white fog color. so color does not saves, you might see it for as longest you are in the editor but after you go to play mode or save and reopen level fog color is gone and resets to white.

on version 1.01 the same bug or issue was carried over and never got fixed,

question: I wonder if this fog issue has been fixed on v 1.1 beta 1, or if it is still being carried over, if it has been fixed then disregard this example of bug.

but devs keep on adding new stuff to it, new features, just keep on throwing new stuff to the engine like if it was a race.




2- to polish advanced lightning, dont know if this same situation was on 1.0 release but ohh boy, dont even want to start there, it even makes me angry when i switch from BL to AL, AL is so expensive (computer resources wise) to turn on. specially on mid end pc boxes.
one of my mid end pc box is getting 80's to 100's FPS on Basic lightning, not bad.
but when turn on Advance lightning it knocks it down to 20's to even 12's FPS, men this is insane. and what difference do i notice? just water effect, nice pretty water, but swtich to BL, water looks way poor, DX7 style water looking,
have to tweak the settings to get decent water looking on BL, but no foam on BL???, makes it even worse, squary edges on shore, Devs really needs to work on at least add foam to BL, to cover those ugly squary edges of water while on BL


all the rest I see no difference of whats so ever with AL, at leat havent got to the point to make good use of it yet.


is all about polishig, polishing and bug free. as Black Tengu mentioned above, T3D has reached a certain level of quality, so its time to polish it. educate users to make the most out of it, instead of looking outside the community forums or documentation for other resources examples or tutorials on youtube.

I think is time for Torque devs to stop adding new stuff to it and work on the documentation, tutorials, minigames, polishing, fixing bugs, getting it to shine.

just my opinion.

cheers

#76

Quote:but devs keep on adding new stuff to it, new features, just keep on throwing new stuff to the engine like if it was a race.

It is a race...or more like an arms race with Unity3D. Unfortunately, the kids out there looking to make the next WoW killer are more focused on features rather than documentation. Plus, bug free and polished are a lot harder to market to those type of people. In the end, it is all about $$$$ and growing the customer base.

I think that GG knows that we need documentation and I believe that they are working on it. Plus, earlier Eric has said that they are going to have a QA lab real soon. That should help a lot with the stability and bug issues we are having.

I do agree with you about the Advanced Lighting. I think the AL rendering is mediocre at best. It doesn't look as good as Leadwerks deferred renderer and doesn't perform half as well. I came back to Torque because ultimately, products that have a lot of money invested in them have to succeed. GG can't afford to fail with Torque. Leadwerks is a one man show and doesn't have the resources to compete in the long run, no matter how good their product is.

Give it time and Torque3D will be something very special.

#77 @Jon D - Very level headed and well said.

#78 @Michael - I'm trying to stay more level headed. I hope that I didn't sound negative towards Torque in my post. I'm trying to see things from both angles.

Like I said, Torque could/should be something very special. Just a little more time and I think it will outshine the others by far.

#79 I think engine team should contribute to documentation more. For example, Rene Damm did a good job here .He wrote the features AND explain it thoroughly.

#80 Hey guys,

I thought I'd add to this thread as it's a subject that's very dear to my heart! As a Senior Lecturer at a University (and the programme Director for games related courses) I pride myself in the production of quality, structured learning materials and more than occasionally have to deal with individual complaints regarding areas various of lecture/tutorial notes that may be up to expectations etc.

In truth, it's incredibly hard to build complex sets of lecture/guidance notes and materials (AND keep it all up to date!?). So trying to cater for the needs of individual customers is something that for the most part out of the question - I fully feel and understand the pain of Michael's task!

With respect to Torque - I would be willing to PAY for quality documentation and/or training if needs be. Professional training is common in the IT world, but usually very expensive!

I want my students to have access to people with the correct skill set and quality learning materials so they are able to build products that are worth showing off. In the end - it benefits my course portfolio just as much as Torque Powered's!

The books that are currently available still mostly base their content on the older TGE product line, so while the Torque Script stuff is still very relevant, a lot of the additional "tutorials" are not. T3D is so new it'll be a while before we see up to date text's (which as an academic is a big pain! Uni regulations love their subject texts!).

In terms of tutorials, I'm sure there must be a wealth of "sample" applications and/or tutorials available at the various Universities using T3D (my place included). Perhaps the Torque-Uni relationship could/should be a little more two-way ? Just an idea!

From the 'noobs point of view, what we are talking about is the development of intro training materials - which, at the end of the day is what absolute beginners thrive on. Is professional training something that Torque Powered is considering for the future ?

Cheers,

Rich H.