Official TGEA Documentation Feedback

#21 @Trent - Thanks for the catch. I thought I had a good system going for catching the missing images problem. I can't believe that got past me =(

I'll take care of it when I get back to Orlando.

As for get the Getting Started.pdf of ol', I'm thinking a new "Hello World" Torque tutorial that uses a few more of TGEA's features is due. Probably safe to keep the old one, but through in some new ones while we are at it.

What were the dead links you found Trent?

#22

Quote:The reason for commenting out those shaders is because they have been replaced by shaders that allow for dynamic lighting on Atlas, and refactored to reside in /common instead of /client/scripts. By commenting them out, you are allowing the correct (new) ones to be unimpeded when they load in from the /common directory.

Thanks. :) That's more understandable then just leaving it off.

#23 Definitely a valid point, and I'll get that modified for next point release.

#24 @Michael

The original ones I was talking about have been fixed, as I posted this before I saw the release announcement!

But...

looking again, I could be wrong and might just not understand what I'm looking at but:

Engine Overview -> Networking:
- SimDataBlock links to Sim3DAudioEvent
- NetObject links to NetStringHandle
- Net links to NetAddress
- NetAddress links to NetAsync
- SimDataBlockEvent links to SimComponent

Let me know if its just me and if not I'll keep double checking for you.

#25 Hi all, I just wanted to formally introduce myself since this is my first forum post on GarageGames.

My name is Ray Lutton, I'm a Computer Scientist/software developer in California, married with 4 children, age 38, U.S. Marine combat veteran, now employed at a U.S. national security lab. I have a B.S. in Business Information Systems, so much of my skills, knowledge and experience lie in business applications development (Oracle database, some java & web, data warehousing and business intelligence, etc).

For a long time I have been interested in the challenge of developing my own game but of course the commitment required to doing so is no small matter with a full-time career and a busy family life (both of which I am very thankful for). Lately for some reason, the satisfaction of "just playing games" has ebbed for me so I have decided to seek greater pleasure and a longer-lasting sense of satisfaction in pursuing "game development" as a hobbie. I place all responsibility on my own shoulders and will endeavor to learn on my own and tackle the issues as they come (with little complaining along the way). Adversity is my friend! I will avail myself of all materials and help found here in the Torque community and I look forward to becoming more involved in the TGEA community of developers. I have no prior experience with game programming or using Torque but it is my hope that I will become proficient over time. My wife is holding me to it, after $295. =)

I purchased the TGEA 1.7.0 SDK Indie License last week and I have everything setup and running perfectly.
My thoughts on the "Official Documentation" that came with the TGEA 1.7 SDK:


The GETTING STARTED section.
The" Getting Started" instructions were awesome and I couldn't be more happy since my tools are all working fine:

TGEA 1.7.0 SDK (Indie) / Visual C++ 2008 Express / Windows SDK / DirectX SDK (March 2008) / Updated Nvidia driver / also using the L3DT Pro 90-day trial :) / Blender.

I can successfully build, compile & run all of the TGEA GameExample demos that were shipped with the engine. These demo's do provide working examples of the many components involved so seeing this functionality is real helpful.


The ENGINE OVERVIEW section.
I have read (glanced over some sections) of the "Engine Overview" section and I appreciate the detailed explanations found there. This information is critical since I am coming into this as a beginner; all of the core C++ subsystems may eventually hit me broadside in the development process, but AS A BEGINNER, I really need to start at a more basic level such as starting with a blank project and building a simple "Hello World". So, For ME, I feel that it would be premature to dive into all of the subsystems at this early stage, and rather just content myself with a broad understanding of the core systems which this section details for me. I will make more use of this Engine Overview AFTER I get past the basic "Hello World" & TorqueScript examples (moving from simple to complex).

The "Official Doc" discusses two levels of difficulty when approaching game development:

[To script or not to script, that is the question. In general, Object Implementation (the second layer) is performed in C++, while Gameplay Implementation (the third layer) is performed in TorqueScript, but this is only a rule of thumb, and different games (and different game developers) will require different strategies. Generally speaking, TorqueScript is an excellent choice for most Gameplay implementation.]

I understand. I should try to become more familiar with the easier aspects of Gameplay & TorqueScript first and then once I am comfortable with that move onto the more difficult C++ systems.


The MISSION EDITOR section.
I read through the "Mission Editor" section and mentally followed along with the steps taken to explain and demonstrate the mission editor tools, windows, etc which used the "T3D" GameExample demo. I found this useful however not worth the time to actually step thru all of the steps as the documenter did. Not being disrespectful, I just feel the "overview" did its job. This section is isolated from other aspects of a project so I don't really have a full picture yet as to what I would need to do BEFORE I get to this point. I will refer to this later though once I figure out how to start a new project (of my own creation). Is there a starter tutorial or a "New Project Template"?


The GUI EDITOR section.
I read through this section too and found it very helpful. I will definitely refer to this later. But still it is dealt with in isolation from the other parts of a project and it uses the "T3D" demo, which to me works well for this section, but not so much for me YET since it assumes SO MUCH - like I know how to do everything that came before the GUI creation.

I haven't read much beyond this in the "Official Doc". But I would like to close with my overall impressions and my current status.


MY OVERALL IMPRESSION OF THE TGEA 1.7 SDK OFFICIAL DOC
The getting started section was near PERFECT! And it really had to be otherwise I would be really frustrated right now. Thankfully I followed the instructions and installed, configured and prayed hard enough that everything seems to be working for me. A+, hot, hot, hot! Give that person a raise! ;-)

Wow, I am sure the Engine overview is surely appreciated by the more experienced Torque developers and it will be for me too soon enough. At this early stage, with just getting started, I need an easier path forward that demonstrates how to start a new project from scratch (or if this is not the normal "Torque way of doing it" - show me how YOU do it!!). I really need a step-by-step tutorial that shows me, with screen-prints, how to create a new project with the minimum amt of folders, files. It should then show the compiling, rendering, and basic pointers to adding advanced features.

The Mission Editor and GUI Editor - I know how to get into them now but again the doc treats them as separate subjects.

So.....from my beginner perspective.... The docs are very detailed and cover a lot of topics that will surely impact me eventually. I know the docs are targeting both beginners and experienced developers however I feel that "one size does not fit all" in this case. As a beginner I really don't know where to go from here.

It seems like a hacker's way to actually get started to just copy and paste the "T3D" project to my

C:\Torque\TGEA_1_7_0\GameExamples\

directory and hope that I properly delete all of the correct folders & files in order to start with a clean, blank project. How can I possibly know which files are needed and which ones aren't, let alone knowing which code to edit in the given files that are supposed to remain for me to use.


QUESTIONS & CONCERNS
Is this how experience developers begin? Is there a better, cleaner way? Can anyone direct me to a "New Project Template" or something which tells me how to get started creating my own game? Thanks in advance. It would be really cool to see a streaming web-video (like adobe/macromedia developers use) of a Torque guru walking us through his/her own development of a mini torque app!!! This would be a much faster method of communicating to the masses.

I will persevere in combing thru the TDN and forums. If I understand it right, as a TGEA user, I should AVOID any material about the TGE and the TSE right? If true, I really lack resources to help get me started since I haven't found many TGEA tutorials that actually start from the beginning.

I didn't expect it to be easy; this is all fun for me anyway (except for typing this much). Ugh! I am done.

I hope my feedback helps.... Now I will continue reading the official docs.

Kind Regard's all,
Ray Lutton.

[Michael Perry helped me out this morning concerning the thread about the "New Project Template Missing" and also referred me to Stephen Zepp's advice on how to start to a blank project.] Thanks Michael!

#26 Wow! Now that's what I call some feedback! =)

Thanks for all that information Ray, and welcome to the community. It would take far too long for me to reply to all your points individually, as I tend to be over verbose and ramble a lot. Just know I've taken all your comments into consideration in regard to the sections of the doc I'm working with.

I can comment on one thing specifically:

Quote:
The Mission Editor and GUI Editor - I know how to get into them now but again the doc treats them as separate subjects.

Well, they are separate subjects and for good reason. The functionality of the editors is drastically different from each other, as well as the rest of the technology. I get what you are saying though. As the documentation on the editors receives more "love," you will start to see why they are separate.

Thanks again! =)

#27 Hi

I'd just like to take a leaf out of Raymond Lutton's book, and give you a full "Torque n00b user report".

I've got over 11 years professional game development under my belt, but Torque is still daunting to me - especially since, like Raymond, I'm fitting in my Torque development in between the various pulls of a busy lifestyle...

Over the years I've spent a lot of time blundering around inside codebases I know nothing about armed only with a debugger trying to dechipher them & I've got pretty good at it; I rarely need more than a working day to get my head around the fundamentals of a system - but after a few hours of messing about with Torque I'm still feeling like I'm only scratching at the surface.

The last thing that gave me this much trouble was RenderWare Studio - which, unsurprisingly, was a pretty similar product (though several orders of magnitude more expensive!).

I've mostly been looking at the T3D example, and in all honesty I've found that the sheer amount of the game that is written in script was a huge issue in terms of being able to make sense of the T3D example from the C++ code - as a result I purchased Torsion which (based on the quick test drive I've given it) I'm sure will help immensely...

Whilst there does seem to be a very large, active, friendly, and sharing community built around the GarageGames website it's a daunting task to have to search forums and wikis to find tutorials - and very frustrating to not be able to find a coherent set of "how to start from the beginning" tutorials dealing with the TGEA (maybe I've just not looked hard enough yet... ;) )

In an ideal world, I'd like to see an official set of tutorials available within the installed documentation that starts from a bare bones Torque game (i.e. a more or less empty main loop), and slowly introduces each of the major components (e.g. at least everything that calls Process::notify() ) giving a detailed overview of its purpose and behaviour, and linking to the relevant detailed documentation where appropriate.

Once all the major code sub-systems have been explained, it would be good to step through creating a simple C++ class that interacts with torque script, show how to get it saved to and created from script (e.g. using the mission editor or gui editor), and maybe end up with instances of the class being kept up to date over a network from server to client (stopping off at whatever intermediate points you think fit - I'm just saying how far I'd like to see the tutorial go ;) ).

I guess this might be a little heavy duty for an "average" Indie Torque user, but it would be invaluable to me :) I think Raymond's idea of doing video tutorials is totally on the money for this sort of thing...

Please don't think I'm moaning - Torque has so far surpassed my expectations in pretty much every way so far, it'd just be great to have a bit more yellow brick roading in the documentation ;)

Alex

#28 As a general philosophy/rule, I think GG docs should be conscious not to slip into a "well you should know that" kind of attitude. The very nature of Torque, its price point and its marketing, are aimed towards non-game professionals: "indies" and hobbyist. These people, by definition, will have a knowledge "hole" when it comes to general "known concepts" and practices as far as the game development industry goes. The problem is, these people can't tell the difference between knowledge that is "common" for game developers and something that is specific to Torque. Therefore, Torque documentation should (at least) link to solid external documents that explain common topics.

For example, lets look at the Materials documentation. TDN and the TGEA docs state the transluscentZWrite controls whether the texture writes to the Z Buffer. Is that documenting the feature as far as TGEA is concerned? Sure, if you already know what a Z Buffer is and what it does. However, I'm betting that the "average" TGEA user won't know what a Z Buffer is or how it affects their choice on whether to activate this on their Material. That is where (at best) people fiddle into they get the result that they want, which can lead to configurations that Torque never anticipated would exist because they are "unthinkable" if one knows how the system should work in the first place, but may seem completely logical if someone is figuring things out from a "guess and test" method.

The other thing to keep in mind when writing docs is what I call the "so this means that..." phrase. Many manuals and docs are good at providing information, but many people have difficulty understanding how that affects them or how they use that information. By inserting a wrap-up "so this means that" kind of sentence, a good doc can save the reader/user hours of more frustrating "guess and test" if the don't completely understand how to use the information presented.

Those are some of the thing I like to keep in mind while writing up technical documentation.

#29 @Darbotron -

Quote:I'd like to see an official set of tutorials available within the installed documentation that starts from a bare bones Torque game (i.e. a more or less empty main loop)

This is where i was stuck myself when i started working with Torque years ago. How do i tear everything appart and begin from a empty main loop?

The trick is to understand that you never start a Torque project from an "empty main loop" as Torque (at least at the moment) is not modular enough to be broken apart that way. Instead you start from one of the example projects and start molding it into your own game.

The "getting started" docs should make a big point of this. Explaining not only where to start, but why you start a Torque project this way.

#30 Hi Mark & Tom,

Thanks for taking the time to reply - it's really appreciated :)

Quote:
The trick is to understand that you never start a Torque project from an "empty main loop" as Torque (at least at the moment) is not modular enough to be broken apart that way. Instead you start from one of the example projects and start molding it into your own game.

I totally get that there's not really such a thing as an "empty main loop" with Torque; but in in order to properly understand what's happening in any game system you need to be able to start from the root update function and work outwards. If we just replace the "empty main loop" I mentioned with "all core components of Torque" and keep the part about explaining all the core modules that are updated by each call to Process::processEvents() then all of what I said is still valid IMHO :)

I guess what I'd like from the documentation in an ideal world is essentially a fairly heavy "Torque Orientation Guide for Programmers". This would take one of the examples, say T3D, and supply (heavily) annotated call graphs for the following situations:
1) Torque Initialisation (i.e. StandardMainLoop::init() )
2) A typical (but obviously massively simplified) game frame in the "menu" (i.e. an iteration of StandardMainLoop::doMainLoop() before "Play Game" is clicked / selected in T3D)
3) What happens when the player clicks / selects "Play Game" (good place to introduce the gui editor, and how it ties in with code, and what happens when the game loads)
4) A typical (but obviously massively simplified) "in game" game frame (probably leaving out the modules that also get called in the "menu" if their behaviour is not significantly different in-game).
...
I'm sure you get the idea.

The joy of this is that parts of this wil naturally fall out into TorqueScript tutorials that span the gaps in the current totorials in the same way that these code ones will (e.g. what happens when the player clicks / selects "Play Game") and those people (not me!) lucky enough to exist without codebase understanding OCD will benefit too :)

I guess one huge factor in this equation is the fact that you can only learn your way around something once - unless you have one of those flashy-pen things out of men in black... After that, the ability to put oneself in the place of the "reader with no knowledge" again is more or less out the window - so maybe someone in my position is actually the best placed person to do this sort of tutorial...

Hope I managed to make my point a little better this time; but either way you people at GarageGames are doing a great job - the stuff I'm quibbling over is just the difference between above average generic documentation and "ideal for what I need" documentation ;)

cheers,

Alex

#31 Out of curiosity, have you read the Engine Overview document in the documentation provided with the installer? It's definitely an overview, but was written to put things in perspective for the new developer, and especially one experienced with "from main loop out" concepts, and how to adapt to Torque.

#32 @Darbotron:
as a baseline, might look into setting trace(1); in the root main.cs file. That one prints out calls and entries as it goes along. Doesn't explain the conceptualization behind the methodologies, but it's a start. Same with %someobject.dump(); wich gets value/function lists on a per-object instance (datablocks or actual objects) basis.

Do realise that's purely _script_ end, but half a loaf, as they say...

Realise it's been said before, but just to re-inforce the point from my own perspective:
Haven't really wanted to push for it too hard mself, since it seems the two newest subsystems are still in a state of flux but: there is an underlying assumption in the older portions of the documentation that you a- know what youre looking for, and b- understand wich of the various methodologies for fricasseeing a feline was picked for any given implementation. In other words, the docs are good for an index right now, but not something to be treated as an explaination for _why_ it do them things it do. Just what. Just something to consider next time it comes time for a full-bore code-review, I guess.

#33 Stephen:
Yeah I've read the docs that are linked from the install and done the tutorials and stuff...

As I mentioned in my first post, I'm honestly not trying to say that the documentation is inadequate - just pointing out the ways which (in my opinion...) it could be improved :)

Kirk:
cheers for the heads up - I've actually bought Torsion too (seems excellent BTW) so I'll be going to town stepping through everything and seeing what's going on in the script. I actually managed to set it up so that I'm getting C++ breakpoints and TorqueScript breakpoints and I can see exactly what's calling what and from where.

Thanks for your help!

Alex

#34 Keeping in mind that you are a bit ahead of the general user power curve in some ways with your experience level (11 years of pro game dev experience), I'd still like to go over what specifically can be enhanced documentation wise to provide what you're looking for--without completely getting newer/less experienced users bogged down in details they shouldn't worry about early on in their learning curve.

Quote:
1) Torque Initialisation (i.e. StandardMainLoop::init() )
2) A typical (but obviously massively simplified) game frame in the "menu" (i.e. an iteration of StandardMainLoop::doMainLoop() before "Play Game" is clicked / selected in T3D)
3) What happens when the player clicks / selects "Play Game" (good place to introduce the gui editor, and how it ties in with code, and what happens when the game loads)
4) A typical (but obviously massively simplified) "in game" game frame (probably leaving out the modules that also get called in the "menu" if their behaviour is not significantly different in-game).

1) Torque Initialization

I think what you are looking for is a combination of the underlying raw boot up experience (which quite frankly in my opinion is beyond the level of detail even someone of your experience level should worry about, but that's me personally) which doesn't currently exist in a documented format, combined with an overview of the server/client stand up and connection sequence.

The server stand up isn't fully documented, but the connection sequence information can be found on TDN: Text based sequence overview and Diagram based sequence overview.

Can you give some feedback on that set of documents? And do you think they should be part of the "introduction" docs directly, or simply referenced for further study?

2) A typical (but obviously massively simplified) game frame in the "menu"

-- honestly, not much at all is going on here :) the Engine Overview section labelled "GUI" is designed to describe this segment of operations.

Before you start playing the game, the engine and environment is simply handling windows operating events in accordance with the "Low Level Process Flow" section of the Engine Overview--and since no server or client has been stood up, the only thing that actually applies is the above mentioned GUI system rendering, and the input event handling which is described briefly in the Input Model section.

Again, specific feedback on how these two sections could be enhanced would be awesome.

3) What happens when the player clicks / selects "Play Game"

--the Engine Overview section labelled "GUI" is designed to describe the first part of this sequence.

The design of the ServerQuery system (combination of script and c++), handles the transition to the server and client standups here, which isn't fully documented anywhere I'm aware of.

Once the server is stood up, the connection sequence overview I think covers most of this information.

I can see the benefit of an article describing the mechanics of the ServerSelect/Query system for sure--anything else that would help here?

4) A typical (but obviously massively simplified) "in game" game frame

--The "Low Level Process Flow" covers the basics of the loop, and combined with the Networking, Input Model, GFX Rendering, and Time Processing sections cover the major operations within a single "frame".

Does this need to have an overview diagram or sequence chart that ties the system descriptions together more directly, or some other way to link the "frame" as a whole to the supporting documentation?

#35 Hi Steven,

If it's ok with you I'll reply to your public email address instead of to this forum :)

Alex

#36 That's fine :)

#37 The documentation lists the old script sound function names (alxPlay, alxStop, etc). These are now sfxPlay, sfxStop, etc.

#38 So far you're focussing on beginners and getting started sections. How about a more advanced section?
Although for more advanced people, it still shows you some better examples.

Things that might be usefull is:
1) How to create a GUI control in VS2005 (give it a breakdown the same way Melv did with the fxRenderObject resource)
2) Didnt see the fxRenderobject from Melv in the Docs. This is a pretty crucial Tutorial.
3) GFX calls Explained. Give a rundown of what all the calls do, and the parameters (constants) they take.
This can be really intimidating at first:

GFX->setBaseRenderState();
   GFX->setZEnable(false);
   GFX->setZWriteEnable(false);
   GFX->setCullMode(GFXCullNone);
   GFX->setTextureStageMagFilter(0, GFXTextureFilterLinear);
   GFX->setTextureStageMinFilter(0, GFXTextureFilterLinear);
   GFX->setTextureStageColorOp(0, GFXTOPModulate);
   GFX->setTextureStageColorOp(1, GFXTOPDisable);
   GFX->setTextureStageAddressModeU(0, GFXAddressClamp);
   GFX->setTextureStageAddressModeV(0, GFXAddressClamp);

4) Do the same (as in 3) for the Sound Layer.
5) By now I know that GG want people to get into indy game development (but with some experience). I feel if you start from the beginning more people will come. A person wanting to learn from scratch shouldn't have to go and learn OPENGL or Direct3D before coming to GG's doorstep. Why not have simple right from the start tutorials using the PrimBuilder? Like how to draw a line using TGEA. How to texture a cube using TGE, etc. Just an Idea.

I really like what you guys have done with the Docs so far and glad you're taking a serious look at it.

#39 I would agree with James about the GFX system and expand it to also include an examples of how to replace old calls with the new GFX. I have been trying to find any information on how texture coordinates are handled with the new call vs openGL. Since this is a drastic change from what most of were use to I would say the GFX system needs to be heavily documented.

#40 @Jaimi - Good catch

@James - Excellent suggestions, thanks =)