Call For Good Documentation

#21 Add my vote to a higher-level overview. It would be nice to know the bootstrap/startup process Torque uses, an overview of the different ways it handles geometry (terrain vs. other vs ?) the native file formats - a lot of these things I'm going on inference about right now. Also, a breakdown/list of what all the various files are for - I'm not expecting you to teach me how to implement a scenegraph solution or collision detection (that's what the source is for ;) but how exactly are we expected to know what gjk.cc does?

#22 Sergei Eliseev's point "5) Simple multiplayer game example with explanations;" is probably the best thing to implement for beginners.

The easiest way for me, and many others I assume, is to learn by doing. Yes, you can go through the code and look at all the source files and learn by doing that way, but it would take one tenth the time to go through a tutorial that has you build a simple game, such as pong.

Not only do you learn enough to start creating on your own, you would also get the satisfaction that you CAN do it on your own. Once you know you can build pong, you know you can eventually build a FPS, or a Strategy game.

I assume many here are in the same spot as I am, have job outside gamedesign, lots of other crap in our lives, and not much time to go headstrong into game development. It is hard to come back from work, sit down on my computer at home, look at the source code, and try to figure it all out. It would be easier and give me more incentive to learn it if there was as simple game creation example that would teach me the basics, while helping me create an actual game step by step.

Sorry I wrote so much on such a little thing... I really think an example project/tutorial would go so far... especially for people just starting out.

#23 @Matthew: There will be a pretty large overview document.

@Jeremy: Well, there's the sample fps game. ;) Between that and the docs we've written, I think it would be fairly straightforward to grasp how the engine works.

But if someone wants me to write a dead-simple sample game, like checkers or something, I suppose I could be persuaded... for a fee ;) I just don't have the time to do it for free at this juncture.

#24 Well, there is a difference between having to disect an already built game and learn that way than to follow steps to build your own very simple game (such as a pong, breakout, or checkers clone).

I know it sounds like needing to be spoonfed instead of learning on your own... but many have little time and trying to dive into an engine and its source is overwhelming.

I plan on going full steam into my game ideas once the guide comes out with or without the simple game creation step guide thing, just a suggestion that it may make things easier for many out there and give them the realization that they can make a game with the engine.

#25 @Jeremy: Ah, true. We'll probably get to that in the next round of docs (whenever that happens)... right now we're focusing on reference, but when that's done, we can focus on the tutorial side more.

#26 I'll second both of you - get the reference done, then an example tutorial. (The best are in multiple stages that build on the previous ones, i.e. - get the Shell up and running, then a basic terrain to run around in, then ...

One request for references, if possible/where applicable, please include examples. printf "TEXTSTRING"; I can understand, but somefunction(foo.bar,float booger(snotrag)); and such can get tough to understand (esp. if you're coding on little sleep ;)

#27 What the tutorial or document REALLY needs is a Walkthru to develop a very simple game. i.e.

take this sprite ( model) code this, connect to this, build this world, write this script, code this compile this, puyt in your world now....

I just bought and downloaded the SDK. and frankly I am dissapointed. Not in the engine or what i see i "WILL" be able to do but, WHERE DO I BEGIN!!!! obviosly one needs the models etc. but how to IMPLEMENT it.

There are exellent tutorials on how to build this light and that particle effect etc. but no SYSTEMATIC walkthru of how to go about it. If one is not experienced in all at this and wants to learn and get involved like the demo and the website makes one believe, Why is it so difficult for NOOBS to start?

If you look at something like 3dgamestudio a5/a6 they have tutorials and help files that gives you a walkthru.
Now I would really like TGE to have this.

After all, I did choose it on what it is capable of and the people behind it. Also that it states that it is a good "learning" engine aswell. I have to have a starting point.

This is by no meand meant to diss anyone but an outcry for someone who seriously want to start learning to try and later make their game come to life, after having done 4 months of research.

Thanks

#28 Nick,

Part of the problem with such a guide is that there are *many* different ways to "get started" with TGE depending on what you want to do. A scriptor, a modeller, a designer, a programmer, a level editor are all going to have different routes to tackle TGE and that doesn't even begin to account for the different game types they might be trying to implement (totally different starting points for a MMO than an RTS).

Honestly, the best way to "get started" is to look for those tutorials and resources that implement things you need (or are similar to) for your specific game and to go through them. Over time you will build up your game and start to understand more and more of TGE and its capabilities.

I highly recommend going to the irc channel and asking for help. There are plenty of experienced developers there who will help you "get started" down the right path for you.

#29 All these repies are very cool.
Thanks

But what I need is a document that explaines how all the tools fit together.

The task that I am trying to start with
(NB remember that I do not know C++ that Well)
is just building a simple model into the game engine like a Plane or spaceship.
I would like to know how all the things fit together (all the tools).
For example movement of one wing, damage to another wing etc. I would like to write c script to handle all this for me like props on an object.

Graphics for instance. Ok I can change a model to fit into the demo. But how do I create a new Level for instance an fit it with my C script etc.

How do I edit the gameplay?

I know its a lot of Q for this thread but if one is going to make documents/ tutorials this is what NOOBS like me need to know.

thanks

#30 P.S
I went through the tutorials that I find. I see all the elements of how to do stuff but nothing on actually getting all the parts to fit together.

OK the main thing I need is to create the level and sprite for the player and then to let my TGE script recognize them.

So I will create the level in gmax - now I have the level
the Player sprite I also created now I have a level and a player.
Now I write my C script so that the script can interact with the sprite and level.

NOW WHAT????

#31 Tourque Tourniquet

#32 YES!! Thanks a lot! this fills in a lot of the gaps/questions I have on the little things. Now if we can get a PDF on the Scripting it will be exellent I see that there is already a plan in place for that. Can't wait. Thanks a lot for the feedback and patience.

#33 Hi, I see that this thread is maybe starting to get old so I am not sure how well it is followed up. Anywayz, I must just add that I totally agree with Mr. Sergei Eliseev above with regards to his comments.

I am as well both a very experinced C++ programmer as well as a games programmer working in the industry for a decade now. Still I am breaking through in the engine, I felt that from the start that the documentation I found around really missed the point about describing the more abstract layers of the engine as well as individual parts.

There are so many tutorials and docs on how to add small but quite obvious features. Of course, this is good in some ways and is helpful to a curtain degree understanding the engine, but I think the features are in general so small that they just give small pin-points out of the total.

Of course, it seems like this is maybe what most ppl are interessted in; Using the engine "as is", adding small but neat features, creating own levels etc. What I am more interessted in, is to break down the engine and to use individual parts or rewrite other parts. For example, I find the network, GUI and scripting system incredible useful and still they are quite easy to isolate, I felt it was hard time figuring out what to use and not to use.

After spending 6 months with the engine, I know am able to break down this parts without any special problems. But in the beginning I found it really difficult to understand the relation of all of the classes.

So, I truly belive what Mr. Sergei Eliseev is writing above will be in big help for other ppl with the same aim as us.

#34 Did the overview in the Doxygen docs not meet your needs? If so, how did it fail?

I agree that there are a lot of areas in the docs that need to be shored up. To a certain extent, I think that you have to "just get" the engine - ie, there will come a point where a light will go on and you will understand how things work, a moment of revelation. Torque is very complex, and I think it will always be intimidating to newcomers.

But I do think that a lot can be done to soften the blow. :)

So... what did the overview not cover? Was it not high level enough? Too abstract?

#35 I will try to keep this post short but it will probably be a hard time doing so, so plz bare with me ;)

First, I must point out that I have no expectations to that ppl will open the sources of Torque for the first time and understand the hole architechture in a day or two as I think actually many hope for. However, the first step I feel that the documentation found on Torque first fails is related to exactly this as I do not believe that this is only someting for newcomers but also for more advanced users.

I myself have quite good expereinced with more advanced architechture on game engines, but I believe that this is the minority here that has. However, even with my experience I had hard times first understanding the philosofy and architechture behind the engine. What I missed here was a basic introduction to the architechture describing first with an illustration each layer/module/submodule of the engine. Then, without going into much details but still give enough information, describing in words each layer/module/submodule, what it do and what belongs in there. I know that for some parts it has been done but I think those parts also are missing to much and maybe I have missed something in the documentation, however, I still feel that this is someting important. Why? Because I think that there are a lot of ppl dealing with Torque, advanced as well as newcomers, that does not have extened knowledge to such advanced architechtures as games are using today even when they are being excellent C++ programmers. Of course, I do not mean that the documentation should learn in detalis about architechture of engines. What I mean is that I still feel it is important to explain the philosofy of just the Torque engine.

Not all ppl understands where this type of code belongs and that type of code belongs. To say it with other words, not all ppl are aware of the difference between game specific code and core engine code. For example, not all are aware of the difference for example on "checking user input" (i.e. state of input devices) and actually doing "handle the input" (which is more game specific). Of course, this two things are basic and simple things to quickly understand, but I am sure you understand my point. For example for me, it took me a good amount of time to really understand what the simulation layer really handled. I think I would have understood it much quicker with a more type of documentation described above. I am aware of that the docs generated with doxygen to a curtain degree explains it, but it is to abstract and let too much out, but again it should not go to much into details of course.

This thing is hard to explain I feel, specially without writing mile long posts and without being easily misunderstood but I hope you get my point and that I gave some answers to your question. Basiclly what I am saying is what Mr. Sergei Eliseev listed above.

-- contiune --

#36 -- contiune --

I still think I have seen the light though :) I have started to get very good control over the engine and successfully broken the engine apart to get even better understanding of it. I have been evaluating the engie for, hmmm, 6-7 months now and I must just say that I am impressed over the hole Torque. I think the main thing is just to hack-it-up and do what I have done, using different parts of Torque for other projects. This is the absolutly best way to learn from. I started on the GUI, rewrote the rendering of it supporting plain Win32 API and also a DirectX version. Then I moved onto the console system and further to the network part.

Today, we are with big success now using the Torque for 3 projects which are under development, 2 being game projects and the second a client/server applications.

1 game is a 3D game where we will use our own 3D engine which have been developed over some years. However, we found out that the world editor (which will not be used as a world editor in the game but is part of the in-game interface) in Torque was much better than ours and are now trying to implement it into our 3D engine (hard time doing so though :) ).

The second game is a manager game which we use the GUI, network and scripting system from Torque. However, we have rewritten the rendering of GUI.

The application is an advanced chat system for IVR with a lot of advanced features. Here we also use the GUI, scripting and network parts from Torque.

I hope to soon find some spare time, and I will then try to contribute to the community with some documentation that I have written while breaking down the Torque engine into individual parts which I learn extremly much of. I also hope that we will be able to release the code for some of the projects we are working on, but that I am not yet sure of.

Anyway, keep up the good work guys! I hope for other newcomes to Torque that it will come the documentation I personally was missing. But hey, that could be just me ;)

#37 We are currently working on a new push for tutorials and documentation outside of just the source code. Please email me (alexs@garagegames.com) if you are interested in contributing some of your own tutorials or documentation, or if you know of any really great work that has been overlooked in this thread.

Many thanks!

#38 Many of the concerns listed here (really simple examples / walkthrough of building a simple game) are now under development. Many of the other concerns, such a large scale overviews and abstractions of engine functions are on my list and I am looking for people with the expertise and time to work on them.

Once the documentation gets standardized and a bit more fleshed out, we'll release it to the community and let you tell us what is still missing.

Any suggestions of missing docs are welcome, though! Email me any time with your ideas. (see email above)