Considerations extracted from first (real-..)game chat

...with additional thoughts spurred from which...

Interface

• show players (names, pics, association to colored piece)
• display whose turn it is (and note "your turn" or "waiting for player __")
• display your current speed (and others' speeds?)
• and re: current speed - show a little compass of -x/+x and -y/+y directions

Instructions

How to interact with the interface:

• click on circle to select move
• gameplay is turn-based so you must wait for other players' moves
• other players' circles are NOT clickable to you when it's not your turn

Gameplay:

• goal is to be first around the track
• how your speed is allowed to change for each turn, and that the game calculates this for you and shows you your available moves
• when you go out of bounds, you lose every other turn for the duration of turns you are out of bounds
• boundaries of track (both inner and outer) are considered in-bounds
• cannot occupy same gridpoint as another player at the same time, but can occupy another player's previous gridpoint

Implementation stuff

• handle out-of-bounds (lose every other turn)
• handle off-the-grid
• detect when a player crosses the start line again (i.e. the winner!)
• don't let players be on the same point at the same time
• display something differently about the optpos when it's out of bounds

First game played against another real person!!

My wonderful friend volunteered to test-play my game!  I happily report that everything worked as it should, and we were able to play the game as fully as possible given the state of the code.  (Some things are missing, including: losing a turn when you're out of bounds, detection of a player winning the game, detection of a player going off the edge of the grid entirely -- this last issue did not come up in our game, but it's rather important to make sure I can handle that somehow.)

First I'll post a screenshot of our finished game.  I'm the blue player and my friend is the red.

Following the screenshot, I'm including a transcript of our chat conversation during the game (with my friend's permission, and mildly edited for relevance).  It's very helpful to know his thoughts during gameplay, particularly in the areas of: the rules of play, interaction with the interface, and information to be displayed during gameplay.

Our game:

Chat transcript:

me: alright let me instruct you what to do
friend: ok
me: you're still on the page?
friend: absolutely
me: ok refresh it
me: and you should see "game #20" on available games to start
friend: yeah click it?
me: i mean to join
me: yes
me: ok i can see tha tyou joined lol
friend: i'm in baby
me: now does the track show up?
friend: yes
me: alright it's my turn lol
me: i'm blue and your'e red
friend: how do i move it?
me: you have to wait for me to go first
me: i'm player 0
friend: ok
me: you're player 1
me: cuz i started this particular game
friend: ok
me: do you see my move?
friend: you moved up one space
friend: yeah
me: yes
me: now you can click any of the red circles to move there
me: we're trying to go around the track. lol
friend: i gotcha
me: so that's all... lol
friend: can we occupy the same space?
me: not at the same time
friend: ooh
friend: intersting
me: but you can only select from the circles to move to
friend: can i go right on top of the inner black line?
me: they show you where you can move based on the rules
me: yeah that should work
friend: ok
friend: your move
me: yes i know
me: i'm trying to explain lol
friend: hehe
me: cu zi realized you don't know the rules
me: but yeah it's pretty simple
friend: i gotcha
friend: oh now we can move two spaces up
me: the rule is
me: on each turn, you can change your x speed by -1, 0, or 1
me: and same for y speed
me: make sense?
me: so try not to go out of bounds
friend: so how do i change the speed?
me: you are changing it by selecting one of the option circles
friend: ahhh i see
me: middle circle = no change
friend: i getcha
friend: like a turn-based game
me: all the others are a change of some kind, in one or both directions
me: it is turn based yes lol
friend: i dont see why it's letting you take the inside route
friend: and why the spaces closest to the edge wasnt available to me
me: you always have an x/y speed.
me: like i said
me: in each turn you can change one or both of those by: -1, 0, 2 for each
me: but the game is doing the work of tracking your speed and available changes by showing you the options for your move
me: that's all haha
friend: ok fine
me: do you understand it?
friend: for now
me: you manage your acceleration
me: so you should start slowing down in the x-direction
friend: so what's the advantage of a slowing down
me: lol....
me: if you keep going so fast in x-direction
me: you won't be able to stay inside
friend: i getcha
me: b/c you can only slow down by 1 each turn
friend: ahhh ook ok
friend: play on
me: oh shit
me: lol i'm out of bounds hahha
me: right now i don't actually have any implementation for handling that case.
friend: so what does that mean, game over for you/i win?
me: no
me: i haven't coded this part yet
friend: oh ok
friend: so it's stuck
me: but when yor'e out of bounds you lose every other turn
me: so you get slowed down a lot in comparison to the other players
me: no it's not stuck i can just move normally haha
me: see the upper right, the game knows i'm out of bounds
friend: oh ok
me: but it's not going to do anything about it
me: sorry haha i'm technically cheating right now
friend: ahh i see
friend: ok i'm trying to go more down and less righgt
me: mhm
friend: so was that the right move to make
me: yeah that's the right strategy for the moment
me: but don't go flying downwards too fast
me: cuz you will have to slow down again
friend: cause i gotta make the turn
me: it's acutally harder than it looks lol
friend: i go tit,
me: yay
friend: lets see if i can do it
friend: haha
me: dude, you have no idea, i'm so excited right now
friend: ok so one thing
friend: i gotta start goign left
friend: how do i tell it to do that
me: you can't "tell" it to do anything
friend: right
me: you can just choose from the options
me: you'll see
friend: well how do i change my velocity
friend: to go -x
me: it'll just do it for you
friend: based on what
me: as long as you are selecting one of the left-hand-column circles to move to, you're changing your horizontal speed by -1 each time
friend: ah haa
me: just keep clicking lol
friend: ok
me: now your'e out
me: of bounds
me: but you can keep playing like i did lol
friend: yeah
friend: didnt have much of an option
me: see you are going -x now
friend: yeah i see
me: but now watch the inside bound
friend: it's just
friend: reactive
me: haha
me: it's like driving
friend: how do i know what my current "x" is
me: right now you have to count it, sorry
me: i'll make a display for that
friend: haha ok
friend: that's the only thing
friend: keeping track
me: yeahh sorry!
friend: shoulda slowed my Y a bit sooner
me: lol, yeah
me: oh and please try not to go off the board
me: i don't have anything to deal with that right now in the code lol
friend: i'm working on it
friend: but i kidna dont remember how much -Y i put in
me: you can count from your previous dot to your X now
friend: oh forget that
me: okay...
me: crap i might go out
friend: hee
me: i didn't slow x early enough
friend: you nooob
me: right sure.
me: yeah shit
me: haha i'm flyyying off the track there.
friend: hahah
me: you should aslo slow x now
me: by the way it's not goign to detect the winner..
friend: yeah i finally see the x slowing
me: ok i'm gonna stop there ok?
friend: ok so you won then
me: well i was out of bounds so
me: who knows haha
me: hey
me: can i ask you a huge favor
friend:
so it's supposed to skip yoru turn
friend: but it seem like it didnt
me: i know, i told you i didn't code the turn-losing yet
friend: oh ok
me: yeah..
friend: sorry osrry
me: lol it's ok
friend: just trying to get it striaght
friend: ok huge favor
friend: go ahead
me: yeah def.
me: so would you mind if i posted (most of) this conversation with you on my project blog?
friend: sure
me: this is the first time i've played wiht someone else on another computer.
me: i won't put your name
friend: just, know that i'm not educated
friend: haha
me: lol,
me: i like our conversation b/c you pointed out stuff that would be confusing to someone who's never played before
me: which are things i should consider when i write the instructions, etc
friend: ah i see

me: thank you soo much!

The Facebook API battle/disaster night

I thought it would be fairly simple...

I had worked on a Facebook iframe application once before, and I remembered that the addition of requiring Facebook login and then being able to render XFBML components was not very complicated at all.  It was a matter of pasting in some code in a few different places, and magically, the page would request you to log in and add the application, and then it could show you your Facebook picture and name.  (By the way: FBML = Facebook Markup Language, and XFBML is the version you can use on off-site pages, i.e. your pages in an iframe, or on Connect app pages.)

Well, there I was, just over a year later.  I began delving into the wiki/documentation on authentication etc., and what I began to realize is that everything seemed to be in transition.  There was this new "graph API", and OAuth authentication, and a new Javascript API -- or at least, these all appear to be new, based on the look of the pages and what I could gather from the descriptions.

I really only wanted to be able do 3 things: require login and authentication of the app, pull/display users' names, and pull/display users' profile picture thumbnail.

Many long hours of confusion later, I had gone through stages something like this:

1. using the wrong new stuff (a PHP API which I now think is supposed to be for Connect apps?);
2. trying to use the old PHP library, cross-domain receiver file, XFBML, and iframe resizing... I don't even remember what didn't work in this combination, but some piece didn't;
3. trying to combine the old PHP library and XFBML paste-in code with some of the newer stuff, I think? I don't even remember;
4. attempting to manually implement the OAuth redirection cycle (things like obtaining a key and this and that), which actually almost worked...;
5. deciding to give up on making this an iframe application that's actually within the Facebook chrome, and instead, switching it over to a Connect app, using the easy authentication/login via the new Javascript API and all of which is luckily still compatible with XFBML.

...wow.  It was a long, tiring, frustrating struggle.  Much of it was due to over-documentation, if you will, and a lack of clarity in terms of marking pages regarding at which level of API/platform transition the information and code on that page would still be relevant and functional.


And now for the bombardment of a list of links.  Here are some of the many Wiki pages/sections I tried to use to figure this out...

(Note: seems like they are really in transition currently - some of the links may not work or will give a message saying the content is moved/updated)


New (pages are in the theme of the new documentation)

Overview guide to apps (new)

Authentication (new)

Graph API (new)

JavaScript SDK (new)

Old REST API - apparently the precursor to the new Graph API


Old, but seems to still apply / be compatible with new stuff

XFBML (including tag list)


Old, and seems to not apply / not be compatible with new stuff

API (old?)

PHP (old?)

FB_RequireFeatures (old?) - for dynamically loading components of the JS API (via FeatureLoader.js.php)

Authorization and Authentication for Canvas Page Applications on Facebook - matches with the old(?) PHP library

Extended Permissions

Connect/Setting up your site - including XFBML rendering (but uses the FeatureLoader.js.php)

Features to implement by presentation day

A rough list for the moment; probably to be updated as I go...

Definitely:

• Select from 4 different provided tracks to play on
• Communication between Actionscript and Javascript on the page, so that various information about the game state (whose turn it is, players going out of bounds, etc.) can be displayed on the page... This will replace the "log" text box I currently have sitting in the middle of the track.
• Players should lose every other turn while they are outside the track bounds -- see this discussion.
• Displaying lines (options thereof?) connecting the dots of players' previous moves (maybe just the last move, to highlight it; probably all moves once the game is over, to show the overall trajectory)
• Finish the database setup for real... because so far I've just been adding fields and tables along with adding corresponding features to the game.  I should probably redraw/re-post a new ER diagram too.
• Facebook login required to get to the app (because right now I'm pretty sure you can just go to the page and see it); and consequent storage of app users in the database, including whether they are currently online.
• Display on the main (index) page of your Facebook friends who are currently logged in to the app
• [maybe] primitive inviting of your friends to join games
• Obviously, the entire interface needs a nice layout and lots of CSS...
• Some sort of about/help page(s)

Optimally would be nice to have these, but no guarantees:

• AI opponent so you can play single-player
• allow players to draw their own tracks
• ...and save them for subsequent use?
• public/private games or allowing the game organizer to moderate (real-time) other players' joining

Multi: -player, -game, -track support

Comprehensibility of the following bullet-point lists is questionable, unless you're me and therefore intimately familiar with this project's code...

Multiplayer support:

• Games support 1, 2, 3, or 4 players.  Having just one player right now makes no sense because there is no AI opponent.
• Gameplay page polls (Javascript AJAX calls) database to discover additional players joining the game.
• Player who initiated the game can decide to stop the polling and start the game; alternatively, the game will automatically be started if 4 players have joined (since that's the maximum it supports).
• Once the game is to be started, it's set to in_play = true in the database, and the flashvars string is sent to the AS (including: game_id, track_num, pid, numPlayers...yeah for variable-name inconsistency!)

Multi-game support:

• Can start a new game from the index page - game_id is sent through the querystring as -1 to indicate a new game should be started; PHP figures out the current highest game_id number and inserts a new game to the db with the next-highest id number.
• Index page displays a list of games that have been initiated but are not yet in play (i.e. are open for more players to join) - these have not yet been closed by their organizer and still have fewer than 4 players.  One need simply click to join; game_id is passed in the querystring and retrieved in the PHP via the global $_GET variable.
• The game_id is sent to AS through flashvars as mentioned above.

Multi-track support:

• I made a MovieClip object called 'tracks'.  Each of 4 keyframes will eventually display a different track I've drawn, but right now they all show the same one.
• When you are starting a new game from the index page, thumbnails of the 4 options for default tracks are shown, and you simply select one before you click the 'go' button to head to the playgame.php page.   The track number you've selected is submitted via a form POST.
• For new games, the playgame.php page pulls the selected track number from the form POST and inserts it as one of the fields when adding the new game to the database.
• For existing games (that you're joining), the page queries the database based on the game_id provided in the querystring and thereby pulls the track_num.
• The track number is then passed to the AS as one of the flashvars.  Since this number refers to the keyframe of the instance of the 'tracks' MovieClip, I simply pass it as a parameter to display the correct track: realtrack.gotoAndStop(track_num).
• NOTE: I've currently not implemented support for players drawing their own tracks... If I get to that, I'm not sure if I will be able to associate the track number to each game by just storing it as one of the attributes in the Games table.  My original database design includes a separate table for tracks, and I imagine storing custom tracks somehow would require this table, BUT, right now, with only my 4 possible default tracks it works just fine to have an id number (1 - 4) as an attribute for each game.

Well this post feels a bit disorganized and haphazard... I will try to post a screen-capture video of all this stuff soon.

Non-retangular tracks will work after all

Dear Joe: I don't think I'm capable of writing a short post.

So you know how in the past, the "track" has always been two concentric rectangles?  That's because I was simply drawing it as a Shape object.  To be able to call hitTestPoint on it (to check whether players' pieces were inside the track), I added a fill to the track space, but set alpha = 0 for those pixels so they would be transparent but still register as hits.

Well, no one wants to play this game on a rectangular track all the time.  So it's finally time to make more complex tracks work.  I didn't want to try to draw a curving track by piecing together arcs using the drawing API, so instead I made a new MovieClip object to add to the library.  I called it 'tracks' and am thinking I'll make several tracks, each one on a keyframe.  The user will somehow be able to select one, and then I'll just call gotoAndStop(frame#) on the one instance of the tracks object, and add it to the main scene.

For now I just drew one track using the pen tool and smoothing out the corner joints (vertices) between line segments.  If you go into the menu (Modify -> Shape -> Advanced Smooth...) you find a function that'll create curvature-editing handles for the vertices.  It's not exactly what I was expecting based on experience with Illustrator, but it came out decent enough.  Luckily, I was able to add a transparent fill within the track area (just using the fill tool), just like I'd done programmatically with the rectangle track.  And the bounds testing using hitTestPoint works = one hurdle easily cleared.

[Next steps: multiple tracks to choose from; users drawing their own tracks...!]

Resizable iframe

As I mentioned in my post about setting up the Facebook app, I selected the option to allow the iframe (which holds all of my content -- it pulls my app pages from toryg.net) to be resizable.  I didn't really know what that meant when I was setting it up, but now I've realized: if my content is longer vertically on the page than what's seen in the browser window, the content just gets cut off.  (Thanks to Firebug, I found the css command that was setting the iframe to have overflow: scroll; -- so when I was testing two instances of the swf on one page, I would simply go into Firebug and cancel that line so I was able to scroll the iframe and see everything.)

Today I decided to figure out how to actually fix this.  Thanks to the resizable iframe page (on the Developers' Wiki), I found out I had to set up two things first:

• allow for cross-domain JavaScript communication (between my server and Facebook's server)
• load in the JavaScript client library, which is simply a call to pull a script stored on Facebook's servers

Then in JavaScript I had merely to call up the CanvasUtil features, set the location of the xd_receiver.htm file, and call a library function (startTimerToSizeToContent()) which watches changes in the canvas content and automatically resizes the iframe appropriately.  (In other words, I copied the several lines of code from the resizable iframe page.)

The only hitch I had was that at first I was placing those few lines of Javascript up in the head of the page, and then that hidden div in the body hadn't been created yet when the script was trying to initialize.  Thus, unfortunately, I have to stick the script in the body, right after that div.  But it works now, so that no matter how vertically-long my content is, the iframe changes to accommodate it and I can scroll freely and see everything.

Quick note on the database engine

I met up with Jeff Nimeroff briefly because I thought I was about ready to set up the actual database tables and start using those in place of the test tables with which I'd been working.  I'd forgotten which engine he had suggested to use, and why, from a previous discussion.

Though there are a number of engines that MySQL supports, Jeff explained that the two main engines used are MyISAM and InnoDB.  The key difference between them is that MyISAM locks entire tables during queries, whereas InnoDB only locks at the level of a single row.  The functions of my game require running various polling functions that query the database so that players check for and receive updates on each others' actions.  Therefore it probably does not make sense to lock entire tables when, for example, up to 4 client instances of the game are making calls to the same table at once.  Thus he suggested I go with the InnoDB engine.

However, because this is a turn-based game, for the most part only one client can be making an update or insertion query at a time.  Therefore it's not totally critical to avoid table-locking.

Finally, he informed me that I can switch the database engine at any time--I'd thought it was set in stone, which is why I'd wanted to check in with him about which to use prior to creating the "real" database tables.

Multiplayer WORKS! (separate instances updating through the database)

Joe gave me permission to make the blog posts short and sweet.  I'm going to try to keep this one more at an overview level.

The goal I set out to accomplish was to separately run multiple instances (i.e. one per player) of the swf with each one keeping itself updated on the actions made (turns taken) by the others.

How it works:

• In the HTML for the embed/object elements, the FlashVars parameter provides (a) the total number of players in the game, and (b) with which player number that particular swf instance is to be associated.
• As the "whole document" class (TraceRace) is a DisplayObject, its Actionscript constructor uses its LoaderInfo instance to grab the values of the FlashVars.
• When it's a player's turn, that swf will both show and allow clicking on the options for the next turn.  Upon the click of an option, the URLVariables/URLLoader/etc. classes send off this data to a PHP handler script, which sends a MySQL query to input a row in the database table.
• When it's not a player's turn, that swf will show the other player's turn options, but they are not clickable (so that you can't go taking someone else's turn).  The swf uses the same URL[whatever] classes to poll for other players' turns showing up in the database: every two seconds, a POST is made which is handled by a PHP script.  If the script returns the other player's turn data (since it has been entered in the database), it stops polling, and this swf updates the other player's move visually and in its own state (variables).  If the other player's turn has not been entered into the database yet, the script just returns a boolean indicating such, and it initiates the next polling request.

Problems:

• After I thought I'd figured them out last time, turned out I still was having issues with booleans.   I'm now sending booleans through PHP echoes as 1 (true) or 0 (false), because the AS can easily convert them to actual booleans, whereas the word strings "true" and "false" are not so easily converted.
• During debugging I ended up trying to be pretty precise with types, even though I'm not always sure if that was causing a bug or not.  For example, I cast variables parsed from PHP-echoed name/value strings to, say, a Number or a uint.  I also cast a piece to a piece when I pull it out of an array, since I don't think arrays are designated to hold a certain single type.
• It looks like AS isn't happy with my passing an argument as 'null' (since I was going to retrieve the necessary object a different way, once inside the function).  Then I tried using two parameters with default values, but since you can only leave out arguments at the end of the list, I can't input the 2nd and drop the 3rd in one call while doing the reverse in another call.  Eventually I just wrote a getter function so I could access the object before the problematic call.
• One of the weirdest problems I've had yet, I actually managed to create myself.  By initializing an Array with a specific length, and subsequently pushing more elements into it, I ended up with empty spaces prior to the pushed elements.  This actually makes pretty decent sense.  But since previously I hadn't initialized the array with a length, the pushed elements just added/filled spots from the beginning.  I finally realized what was going on and now add the elements by accessing the array slots via indices.

Now for the cool part.  I took a screencast video (thanks Screencast-O-Matic!!!) to show how this actually all operates in my testing setup.