Multiplayer Tetris in Two Days

#1 When I link to your video it crashes firefox.

#2 That's a real pity. :)

You can try this wmv:
www.sethwillits.com/temp/MegaUltraTetris20XX.wmv

#3

Quote:
The only problem is that the documentation is severely lacking in some areas. It's so hard to find information.

Could you give more specifics on this?

--What product version were you using?
--What was your primary way for looking for information you needed?
--Were you looking for reference documentation on specific functions/methods/callbacks, tutorial information on techniques and best practices, examples of use within a project, or something else?

Thanks!

#4 I'm using 1.7.2.

I wish I had written down what documentation was hard to find (or simply missing) and how I went about trying to find it. I'll give it my best shot to remember everything...

--

So first off, I went to the wiki (which is a bit hard to find from the GarageGames site if you don't already know where it is). Maybe I should have started with the included docs. I'm very accustomed to having the same docs available offline available online, in addition to other content via a wiki etc.

At any rate, I wanted to do a tutorial and there were four tutorials smack in the middle of the page. I've done asteroids games far too many times so I chose breakout, and did that in just a few hours and had a pretty good experience. Part 6 and 7 aren't done and I skipped 5 because it was late at night. But overall, this was pretty quick and painless; The tutorial was well formatted, easy to follow, and I didn't have any problems.

The next day we decided to have a mini contest with the requirement to create a networked game. I just had a fun time with TGB and was glad to see the editors were full featured and working now, so I decided to do networked tetris. Since it's networked, the first thing I decided to do was look up how the networking worked.

So I went back to the wiki. This time, I'm looking in the TGB section for anything on networking. The funny thing is, I don't see "documentation" mentioned anywhere on the page. Down at the bottom is the section "The Archive" which has mini tutorials, more tutorials, and "TGB Reference Listing." Reference sounds already to me, so I go to the reference section; There are several pages on TorqueScript, and then the two most promising links are TGB Reference Guide and Torque 2D Reference Guide. The latter is basically just that old original PDF documentation so I skipped that one.

Next I looked in TGB Reference Guide ("The complete guide to all TGB console classes, with appendices devoted to miscellanea, along with a glossary") and I see nothing related to networking at all except two dead links to NetConnection and GameConnection. Hmph.

If you look in the offline documentation, there's no mention of networking anywhere except in the Checkers Tutorial. A tutorial is fine and dandy but I want documentation.

At this point I just started searching with the search box on the wiki and in the forums to find information on networking because I *knew* that TGB supported it, but where the heck are the docs? I found some posts in the forums which you explain what TGB's networking can and can't do. It wasn't what I thought, but it was enough to convince me I'd do just fine, especially with tetris.

In a nutshell, I think I ended up scanning through the checkers tutorial to find the code that dealt with networking so I could at least use better terms in my searches (but I never went through the tutorial from end to end) and came across commandToClient and commandToServer. I did more searching on the GarageGames website where I found TGE documentation on what those functions are (http://www.garagegames.com/docs/tge/general/ch06s11.php), but still nothing super helpful with TGB. On the wiki I found the hellotgbnetwork tutorial (http://tdn.garagegames.com/wiki/TGB/Getting_Started/hellotgbnetwork) which I then fiddled with for 20 minutes or so and understood the extreme basics of how TGB's networking works.

So from there I simply started searching all three places (offline, GarageGames, and TDN) and only found forums posts that were minimally helpful.

I did find this page of console functions (http://tdn.garagegames.com/wiki/TorqueScript/Console:_Functions) which listed a lot of the callbacks, but none of them are documented. Anything networking related is just simply undocumented. "connectToServer" doesn't even show up in the TGB offline documentation at all!

Now, I know TGB is based on the TGE code, so I expect a lot of the documentation to be the same, but I don't expect to have to go explicitly look in TGE's documentation to find out how to use TGB. For starters it's annoying, and who knows if what I'm looking at in the docs are actually even in TGB or not. Even still, the only other page on networking I found helpful was this one (http://tdn.garagegames.com/wiki/Torque/Networking/ConnectionSequence) which is really far too low level and didn't include enough discussion about the highlevel methods in scripting.

When I started digging around on my own, in the common folder and searching all of the included scripts I started finding some of the callbacks and networking functions there. So I spent a long time looking at the code and reading it to figure out what gets called and when. It was a pain. I have no idea why any of this isn't documented. Certainly it *must* be *somewhere*!


So anyway, more or less, with a *lot* of trial and error, I got my tetris networked fairly quickly. It would have gone a heck of a lot faster had the methods been documented!

After I had gotten that all done I was trying to figure out how the master server works. Let me tell you, this was _not_ easy. There is absolutely *NO* documentation I could find on the master server at all. Some forum posts pointed in me in the right direction but again it simply came down to me rifling through the code, finding the call to queryMasterServer in script, and then from there I had to open the TGB C++ source code and dig through that to figure out what was going on. I still don't know what the game type and mission "query" syntax is, but I finally figured out enough to get the server list to only show my game.

--

One other thing that caught me offguard was that simply calling sceneWindow2D.loadLevel was crashing TGB... Long (and I emphasisze long) story short I figured out (by way of the Asteroids tutorial simply including a single line of code) that you have to do level changes in the callback of a call to schedule. I can see why, but it wasn't even explained, and I couldn't find mention of it anywhere. (I have since added an explanation to the tutorial.) Interestingly, if you search for "loadLevel" in the offline docs, there are no results. I can't find the method anywhere in the docs..... *loadLevel* for crying out loud. Kind of important.

--

As far as the actual T2D objects go, mostly the documentation is sufficient enough to get by. When I added a camera shake, I found the method by searching the wiki and coming across it on this page: (http://tdn.garagegames.com/wiki/TGB/Reference:_t2dSceneWindow_Camera_Methods). It says:

startCameraShake(%magnitude, %time)
Purpose: Starts shaking the camera.
%magnitude - Float: The magnitude of the shaking.
%time - Float: The duration of the shake effect.

The same method in the offline documentation:

startCameraShake(shakeMagnitude, time)
Description: Starts the camera shaking.

Why are these not the same? And why does neither of them say what "time" is? Is it milliseconds, seconds, microseconds?

--

So overall, the networking documentation is completely missing, and the rest of it there, but not ideal.

#5

Quote:--Were you looking for reference documentation on specific functions/methods/callbacks, tutorial information on techniques and best practices, examples of use within a project, or something else?

I think the tutorials are ok. Between the "current" tutorials and the ones in the archive, I think figuring out how to use most of TGB's features are covered (but of course I haven't tried to use most of them, so I'm not entirely sure yet). As I said above, the reference is lacking, but what is missing most of all are the "guides" that explain concepts and practices. There should be a guide on every major system which explain is role and use; not as a tutorial (short examples are of course good) and not as mere reference and lists, but in concepts and goals. I just saw Melv wrote a huge detailed description of how the collision system works: wonderful! Far beyond anything I'd expect. It'd be awesome if a mere tenth of that effort could be done with each system.

#6 Excellent feedback, thanks :)

The 1.7.3beta installer has updated reference documentation on a majority of the c++ callbacks and console methods, but does not include the sections you mention (specifically networking and networking techniques), so I'll add it to the list of sections that could use follow-up.

Something to note: The wiki is, as always, user maintained, so unless someone is 100% on top of things and has the wiki updated within a short period of time of a release, the documentation is almost always more up to date from the installer itself.

#7 I'm sure you've thought about it before, but it would be awesome if the documentation could also be in the wiki itself, so users could add to it directly. Something.

#8 I agree with Seth that the networking docs have been a little insufficient.

I mean, one thing I'm very ignorant on is just the different ways one can even implement networking. Let's say I want to take an existing simple game, like chess, and pass the moves back and forth on the network. How do I do it? I tried upgrading the "Hello World" example and ran into an odd disconnect error.... that nobody on the forum could answer.

And then additionally, let's say for the future I don't want to "retrofit" games for networking, but want to design for networking from the ground up. Here I think the checker's example would help.... but it needs a little bit more rationale / design explanations around it.

Now... how to persuade Seth to update the Wiki with his knowledge? :)

#9

Quote:I agree with Seth that the networking docs have been a little insufficient.

That's a polite way of putting it. :)

Quote:Now... how to persuade Seth to update the Wiki with his knowledge? :)

I'm certainly no expert yet. I've figured some things out and plan on updating a page on the wiki when I get a chance (maybe later today), but there's a lot I still have to learn. I'd love it if Tom Bampton or someone else could write up a short article on this stuff.

#10 Seth,

Very nice work. I never thought I'd ever become a spectator to two people playing Tetris (Sethtris?) but I ended up watching the whole video.

Again, great work for such a short time period (in seconds). ;)

Melv.

#11 Melv: It's a lot more fun to play than watch! The next step will be to make it work for more than two players. It's going to be fantastic, I think :)

And funny you should say Sethris. My game-dev buddies have all been saying the same thing :)

I of course went for the obligatory cliche.

Edit: Silly forums cut off my accented e!

#12 I'm sure it is fun to play competitively, I just wanted to yank your crank ;)

Seriously though, very nice work.

Melv.

#13

Quote:I'm sure you've thought about it before, but it would be awesome if the documentation could also be in the wiki itself, so users could add to it directly. Something.

Ah, that's a good idea, Seth. I think it'd be great to have the full documentation in the wiki. It could provide a place for people to clarify and expound on areas of the documentation. Perhaps contributing to the version provided with the installer.