Sunday, April 10, 2011

Reviving the Ancient Game of Liubo 六博 as an HTML5 Multiplayer App with Google AppEngine on Python and the Channel API

What is Liubo(六博)?


One of the oldest recorded board games, Liubo, 六博, literally "six sticks" in Chinese, has a mysterious origin and even more mysterious disappearance. Emerging early in Chinese history, it was the most played game during the Han Dynasty and remained so until the emergence of Go, 围棋, in ancient China. In spite of its abundant preservation in the archeological record, and numerous historical writings describing the game, the exact rules of the game remain unknown to this very day.




Liubo: Resurrection


Fortunately, we need not leave this game in perpetual obscurity. Jean-Louis Cazaux, an author of many books on the history of chess and ancient board games, has done an extensive study of the historical and archeological record and posited a reconstruction of the rules. Furthermore, he has subjected these rules to extensive playtesting to discover a game that is quite entertaining to play.
After some exchanges with the author I've been able to implement the game he envisioned on the web with both multiplayer and AI capability.

To play the game, you first sign in using an OpenID such as Google or Yahoo. Then you press "Play" and you will be placed into the game queue for another opponent. If you wish, you may press "Skip to AI" and play the AI instead. Then you will randomly play as either white or black, white goes first as in chess. Two sets of yin-yang sticks are then thrown automatically on the right side of the screen, one mark for yin and two marks for yang. Total the yang plus one for each set of three sticks, and you have your move number, for instance 3-2. This means you move 3 the first move, then 2 the second. To move, you may either enter a stone onto the board at the move number, or if the piece has not moved this turn, you may advance the stone. Advancements go counter-clockwise around the board; press the Moves button to see the move order. At two special positions, numbers 6 and 11, you may move inward towards the center and across the board. If you land directly on the center, your piece is promoted to an "owl" if you don't have one already. This owl can then capture other pieces and put them into your prison; for regular stones, captures only return the piece to the other player. You may have only one owl at a time. Capture all the opponent stones and you win; capture the opponent owl if you have no owl and you also win; have five stones on the board and no owl while your opponent has an owl and you also win; let the other side run out of the 10 minute move clock and you also win. After each game, your elo rank and that of your opponent (including the AI, "SiliconDragon") is adjusted. You may see the top rated players with the Ratings button. You can find the game here:

Click to Play Liubo 六博


HTML5 Multiplayer Design


When starting the design, I first did a static layout of the board in HTML and CSS. I wanted a design that would scale to different screen sizes so I could use it on iPad as well as various desktop sizes. Also I wanted it to work on various browsers including IE8, so I focused on using CSS drawing techniques with borders and screen percentages and tested it on various platforms. Using gradients and fallback CSS I was able to make the board, throwing sticks and pieces without using any images at all.



Once the layout was done, there remained the huge effort of programming. There are many options in creating an interactive HTML5 app today, from WebSockets, to Flash compilation to Canvas, to game-specific libraries such as Impact.js. For speed and compatibility, I chose to use div-based HTML5 javascript with jQuery. Although node.js shows promise, I prefer the established ease of use of Google AppEngine and its python backend, so I went with that. Linking the client and server is the newly released Google Channel API.


Implementing a Google Channel API Client


The trickiest part of the whole project was getting the Channel API to work properly. My first mental reset was realizing it is a unidirectional, not bidirectional, API. That is, the Channel API requires that the server give a channel token to a client and then the client connect to the server, however only the server is allowed to send messages to the client. The client is not allowed to send messages to the server over the channel. Instead, the client must use normal HTTP requests to the server which then must be matched to a client token whereby the server can send a response over the channel.


Illustrating this procedure, first here is a python snippet initiated by client request for a new channel. It runs on the appengine and creates a new channel, stores it to the datastore, and then returns the channel token along with other user data in a JSON:

def put_channel(self, user, profile):
   profile.channeltoken = 
      channel.create_channel(make_channel_id(user.federated_identity()))
   profile.channeldate = datetime.now()
   profile.put()
   profile_json = {
      'screenname': profile.screenname,
      'character': profile.character,
      'rating': profile.rating,
      'rank': compute_rank(profile.rating),
      'numgames': profile.numgames,
      'dateadded': profile.date_added.strftime('%Y-%m-%d'),
      'logoutURL': users.create_logout_url('/'),
      'channeltoken': profile.channeltoken
   }
   self.response.out.write(simplejson.dumps(profile_json))


On the javascript side, we receive this channeltoken, set our channel id to this token, and then create a new channel. We then open a socket and setup socket handlers. The socket open handler requests a new game to join. The socket message handler processes each message sent from the server, such as starting a multiplayer game and receiving moves from an opponent.

self.channel = new goog.appengine.Channel(self.channelid);
self.socket = self.channel.open();
self.socket.onopen = self.socketOnOpened;

self.socketOnOpened = function() {
   // give it a chance to startup
   setTimeout(game.requestJoin, 5000);
};

self.socketOnMessage = function(message) {
   // console.log('received message data:'+message.data);
   var messageArray = $.parseJSON(message.data);
   if (!messageArray) {
      alert('invalid message received: ' + message.data);
      return;
   }
   for (var i=0; i<messageArray.length; i++) {
      var messageline = messageArray[i];
      var command = messageline.shift();
      var data = messageline;
      self.commandProcessor.processCommand(command, data);
   }
};

Going again back to the server-side python code, we create a simple function for sending messages to the client via the channel. When creating a game, we first create a unique gamekey, then send it to the channel. Another important point to note about the Channel API is illustrated here: the server must have a different unique channel to each client it wishes to connect to. There are no broadcast channels or multiple subscribers; it is strictly one-to-one. So the server has created two channel ids, one for the white side and one for the black side, upon client connect. Then as the game progresses, messages are sent from the server to each client via its own respective channel. A unique gamekey, sent by each client during a request, allows the server to connect a request to a particular game, and thus provide a link between two clients in a multiplayer game:


def send_message(self, channelid, json):
   logging.info('sending message to:%s payload:%s',
      channelid, simplejson.dumps(json))
   channel.send_message(channelid, simplejson.dumps(json))

def create_game(self):
   self.create_gamekey()
   game = Game(parent=gamezero)
   game.gamestatus = 'WJ' # waiting for join
   game.gamecreated = datetime.now()
   game.gamekey = newline_encode(self.gamekey)
   game.gamestatus = 'GS' # game started
   game.gamestarted = datetime.now()
   game.put()
   self.send_message(self.black_channelid, [['PB'],
      ['OP',game.white_playername],['GS',self.gamekey]])
   # game started, white's move
   self.send_message(self.white_channelid, [['PW'],
      ['OP',game.black_playername],['GS',self.gamekey],['WM']])


Again returning to the client javascript side, we receive the new gamekey and begin the game. Each time after the client player moves, an HTTP POST request is sent to the server. This request contains the gamekey and the moves for this turn. We don't wait for any reply from the server to our request; instead, our previously established socket listener waits for any commands to be received via the channel API, namely, the other players moves. This methodology is how the Channel API is meant to be used in interactive applications.


self.startGame = function(data){
   $('#gamejoinstatus').html('Starting game...');
   clearTimeout(self.joinTimeout);
   game.gamekey = data[0];
   game.startGame();
}

self.sendMoves = function(moves) {
   var params = {
      gamekey: self.gamekey,
      moves: $.JSON.encode(moves)
   };
   // console.log('POST moves to server:'+params.moves);
   $.post('/games', params)
   .error(function(){
      $('#throwturn').html('Unable to send move');
   });
}

Returning to the python server side, we find our move processor. After receiving the HTTP POST request from the client with the game key and validating moves, we simply relay the move to the other player via the other player's channel id. In addition, we check for a validated game over condition:


def post(self):
   self.user = users.get_current_user()
   self.request.get('gamekey'), self.request.get('moves'))
   self.gamekey = self.request.get('gamekey')
   if not self.user or not self.gamekey:
      self.error(403)
   elif self.request.get('moves'):
      self.moves = simplejson.loads(self.request.get('moves'))
   if self.decode_gamekey():
      self.process_moves()
   else:
      self.error(403)

def process_moves(self):
   # just relay moves to the other side
   self.send_message(self.other_channelid(), self.moves);
   for move in self.moves:
      command = move[0]
      if command == 'GO': # gameover
         status = move[1]
         winner = move[2]
         reason = move[3]
         self.process_gameover(status, winner, reason)
         break

Lastly, let's see how we actually process moves on the client side. I've adopted a simple json-based symmetrical send/receive protocol, so all messages back and forth are sent as json-encoded lists. Each item in the list is itself a list, consisting of a two-character string command code and zero or more data items. The heart of this is the client command processor that receives each different command type from the server and then dispatches it to the appropriate handler:


self.processCommand = function(command, data) {
   // console.log('Command and data received: '+command+' '+data);
   switch (command) {
      case 'WJ': self.waitForJoin(); break;
      case 'OP': self.setOtherPlayer(data); break;
      case 'PW': self.setPlayer('white'); break;
      case 'PB': self.setPlayer('black'); break;
      case 'GS': self.startGame(data); break;
      case 'GO': self.gameOver(data); break;
      case 'WT': self.receiveThrow('white', data); break;
      case 'BT': self.receiveThrow('black', data); break;
      case 'WM': self.takeTurn('white'); break;
      case 'BM': self.takeTurn('black'); break;
      case 'WS': self.moveStone('white', data); break;
      case 'BS': self.moveStone('black', data); break;
      case 'WP': self.promotionMove('white', data); break;
      case 'BP': self.promotionMove('black', data); break;
      case 'WB': self.receiveBonusThrow('white'); break;
      case 'BB': self.receiveBonusThrow('black'); break;
      case 'NR': self.newRating(data); break;
      default:
   }
};




That pretty much covers how to use the Google Channel API in a multiplayer game. The good thing is I found it worked across all the platforms I tested, and at lower volumes it's completely free to use on the Google AppEngine. So you can get something up and running without spending any cash, only if it takes off do you need to front up some mulah. There are many other aspects to the game which I could elaborate if readers desire, but this has provided a good introduction to using the Channel API in your own game. Try it out:



Click to Play Liubo 六博


PS: I recommend the site HTML5Games to see the latest in HTML Indie Gaming.

65 comments:

  1. if i share this blog weblogic Server Training in Chennai aims to teach professionals and beginners to have perfect solution of their learning needs in server technologies.Weblogic server training In Chennai

    ReplyDelete
  2. if learned in this site.what are the tools using in sql server environment and in warehousing have the solution thank ..Msbi training In Chennai

    ReplyDelete
  3. i wondered keep share this sites .if anyone wants realtime training Greens technolog chennai in Adyar visit this blog..performance tuning training In Chennai

    ReplyDelete
  4. As your information sybase very nice its more informative and gather new ideas implemnted thanks for sharing this blogsybase training In Chennai

    ReplyDelete
  5. i gain the knowledge of Java programs easy to add functionalities play online games, chating with others and industry oriented coaching available from greens technology chennai in Adyar may visit.Core java training In Chennai

    ReplyDelete
  6. I have read your blog and I got very useful and knowledgeable information from your blog. It’s really a very nice article Spring training In Chennai

    ReplyDelete
  7. fantastic presentation .We are charging very competitive in the market which helps to bring more oracle professionals into this market. may update this blog . Oracle training In Chennai which No1:Greens Technologies In Chennai

    ReplyDelete
  8. Wonderful article, very useful and well explanation. Your post is extremely incredible. I will refer this to my candidates
    SAP Training in Chennai

    ReplyDelete
  9. Thank you for sharing such a nice article here. And please keep update like this information here.

    SAP MM Training in Chennai

    ReplyDelete
  10. Everything is fine, am happy about your blog. Thanks admin for sharing the unique content, you have done a great job I appreciate your effort and I hope you will get more positive comments from the web users.

    Regards,
    Aamala

    SEO Training in Chennai

    ReplyDelete
  11. The programming was very easily understand and more important coding are provided on this post and this is very valuable in my studies,all coding easily understand and develop more skills,thanks for sharing this post.
    digital marketing training in chennai

    ReplyDelete
  12. Excellent post, some great resources with the execution models. Styling your blog the right way is key. This information is impressive..I am inspired with your post writing style & how continuously you describe this topic. After reading your post,thanks for taking the time to discuss this, I feel happy about and I am eager to learn more about this topic.

    digital marketing training Chennai

    ReplyDelete
  13. Another interesting articles and i find more new information,i like that kind of information,not only i like that post all peoples like that post,because of all given information was very excellent.
    ios training in chennai

    ReplyDelete
  14. About the python information really very excellent and i find more new information,i like that kind of information,not only i like that post all peoples like that post.
    Oracle SQL Training in Chennai

    ReplyDelete
  15. Wow amazing i saw the article with execution models you had posted. It was such informative. Really its a wonderful article. Thank you for sharing and please keep update like this type of article because i want to learn more relevant to this topic.

    Web Designing Training in Chennai

    ReplyDelete
  16. In each game shows your name and a small capture what awaits you when you enter it.
    Unblocked Games at School
    Unblocked Games circle

    ReplyDelete

  17. Great and useful article. Creating content regularly is very tough. Your points are motivated me to move on.


    Truly a very good article on how to handle the future technology. After reading your post,thanks for taking the time to discuss this, I feel happy about and I love learning more about this topic.


    SEO Company in Chennai

    ReplyDelete

  18. Excellent incredible blog layout! How long have you been blogging for? you make running a blog look easy. The overall glance of your website is magnificent, let alone the content!

    Corporate Training in Chennai

    ReplyDelete
  19. Truely a very good article on how to handle the future technology. After reading your post,thanks for taking the time to discuss this, I feel happy about and I love learning more about this topic. keep sharing your information regularly for my future reference. This content creates a new hope and inspiration with in me. Thanks for sharing article like this. The way you have stated everything above is quite awesome. Keep blogging like this. Thanks.
    Digital Marketing Company in Chennai
    Digital Marketing Services in Chennai

    ReplyDelete
  20. Wow post.. Thank you sharing this kind of interesting and amazing post which will provide more information

    SMO Services Chennai

    ReplyDelete
  21. Great post!I am actually getting ready to across this information,i am very happy to this commands.Also great blog here with all of the valuable information you have.Well done,its a great knowledge.

    Branding Services in Chennai

    ReplyDelete
  22. your app report is really awesome and it is very much interesting i like the features and it is very well to get about the clear concept.

    Online Reputation Management

    ReplyDelete

  23. All are saying the same thing repeatedly, but in your blog I had a chance to get some useful and unique information, I love your writing style very much, I would like to suggest your blog in my dude circle, so keep on updates.


    Online Reputation Management

    ReplyDelete
  24. thank you for sharing such a nice and interesting blog with us. hope it might be much useful for us. keep on updating...
    SEO Company In Chennai

    ReplyDelete
  25. Really a very well information here. And actually Python is a easiest language that can support at all platform than Java. I am interested to know more about this.

    Email Marketing Chennai

    ReplyDelete
  26. Provides great information about the concept.It helps an individual to gain knowledge on new techniques.Keep on giving this type of information.
    Dot net Training in Chennai

    ReplyDelete


  27. What an awesome post, I just read it from start to end. Learned something new after a long time.


    Informatica Training in Chennai

    ReplyDelete
  28. Great information shared in this blog. Helps in gaining concepts about new information and concepts.Awsome information provided.Very useful for the beginners.
    SEO Training in Chennai

    ReplyDelete
  29. Your procedure and way of idea is really good and thus it is very much interesting, i came too know more information about your blog.


    Android Training in Chennai

    ReplyDelete
  30. wow great,nowadays this type of blog id more important and informative technology,it was more impressive to read ,which helps to design more in effective ways


    Java J2ee training in chennai

    ReplyDelete
  31. Thanks for sharing article like this. The way you have stated everything above is quite awesome. Keep blogging like this. Thanks a lot.


    Best Dot Net Training Institutes in Chennai

    ReplyDelete
  32. very useful information provided in this blog. concepts were explained in a detailed manner. Keep giving these types of information.
    SEO Training in Chennai

    ReplyDelete
  33. your blog is really awesome and you have clearly explained many more topics and it is really good thus it is very much interesting and really nice too.

    Best Informatica Training Institute in Chennai

    ReplyDelete
  34. Superb. I really enjoyed very much with this article here. Really it is an amazing article I had ever read. I hope it will help a lot for all. Thank you so much for this amazing posts and please keep update like this excellent article.thank you for sharing such a great blog with us. expecting for your.
    Digital Marketing Company in India

    ReplyDelete
  35. Thank you for sharing such a nice and interesting blog with us. Hope it might be much useful for us. keep on updating...!!
    seo company in india
    digital marketing company in india

    ReplyDelete
  36. Thank you for sharing such a nice and interesting blog with us. Hope it might be much useful for us. keep on updating...!!
    seo company in india
    digital marketing company in india
    seo company in chennai
    digital marketing company in chennai

    ReplyDelete
  37. Thank you for sharing such a nice and interesting blog with us. Hope it might be much useful for us. keep on updating...!!
    seo company in india
    digital marketing company in india
    seo company in chennai
    digital marketing company in chennai

    ReplyDelete
  38. Superb. I really enjoyed very much with this article here. Really it is an amazing article I had ever read. I hope it will help a lot for all. Thank you so much for this amazing posts and please keep update like this excellent article.thank you for sharing such a great blog with us. expecting for your.
    seo company in india

    ReplyDelete
  39. Truely a very good article on how to handle the future technology. After reading your post,thanks for taking the time to discuss this, I feel happy about and I love learning more about this topic.keep sharing your information regularly for my future reference

    Dataware Housing Training in Chennai

    ReplyDelete
  40. Great post! I am see the programming coding and step by step execute the outputs.I am gather this coding more information. It's helpful for me my friend. Also great blog here with all of the valuable information you have.
    Study in Canada Education Consultants in Chennai

    ReplyDelete
  41. Great Article… I love to read your articles because your writing style is too good, its is very very helpful for all of us and I never get bored while reading your article because, they are becomes a more and more interesting from the starting lines until the end.

    Fresher Jobs in Mumbai
    Fresher Jobs in Pune
    Fresher Jobs in Noida
    Fresher Jobs in Hyderabad

    ReplyDelete
  42. A very nice guide. I will definitely follow these tips. Thank you for sharing such detailed article. I am learning a lot from you.

    Best Dental Clinic In Vellore

    Best Dental Clinic In OMR

    ReplyDelete
  43. This idea is mind blowing. I think everyone should know such information like you have described on this post. Thank you for sharing this explanation.Your final conclusion was good. We are sowing seeds and need to be patiently wait till it blossoms.

    Hadoop Training in Chennai

    Base SAS Training in Chennai

    ReplyDelete
  44. A very nice guide. I will definitely follow these tips. Thank you for sharing such detailed article. I am learning a lot from you.

    SEO Company in India|Digital Marketing Company in Chennai

    ReplyDelete
  45. Very nice post here thanks for it I always like and search such topics and everything connected to them.Excellent and very cool idea and the subject at the top of magnificence and I am happy to comment on this topic through which we address the idea of positive re like this.

    Car Wash Services in Mumbai

    ReplyDelete
  46. I am not sure the place you are getting your information, however good topic.I needs to spend some time studying more or understanding more.Thank you for wonderful information I was in search of this info for my mission.

    HR Consultancy in Chennai
    Recruitment Consultancy in Chennai
    Manpower Consultancy in Chennai

    ReplyDelete
  47. Great Article… I love to read your articles because your writing style is too good, its is very very helpful for all of us and I never get bored while reading your article because, they are becomes a more and more interesting from the starting lines until the end.

    Digital Marketing Company in Chennai

    ReplyDelete
  48. Great site for these post and i am seeing the most of contents have useful for my Carrier.Thanks to such a useful information.Any information are commands like to share him.
    Web Development Company in India

    ReplyDelete
  49. That is very interesting; you are a very skilled blogger. I have shared your website in my social networks..!

    Payday loans in Alabama
    Title loans in South Carolina

    ReplyDelete
  50. AS python is important for the calculating purpose in th similar way SQl and Plsql are very basic and very needy languages for Data base management.

    Oracle SQL Frequently Asked Questions

    ReplyDelete

  51. Its very useful to me. Wonderful blog.. Thanks for sharing informative Post.

    Installment loans
    Payday loans
    Title loans

    ReplyDelete
  52. Great post! I am see the great contents and step by step read really nice information.I am gather this concepts and more information. It's helpful for me my friend. Also great blog here with all of the valuable information you have.
    Weblogic Training in Chennai

    ReplyDelete
  53. you are posting a good information for people and keep maintain and give more update too.
    seo company in india

    ReplyDelete
  54. Excellent goods from you, man. I’ve understand your stuff previous to and you’re just too excellent. I actually like what you’ve acquired here, certainly like what you are stating and the way in which you say it. You make it enjoyable and you still take care of to keep it sensible. I can not wait to read far more from you. This is actually a tremendous site..
    Architectural Firms in Chennai
    Architects in Chennai

    ReplyDelete

  55. Its a wonderful post and very helpful, thanks for all this information. You are including better information regarding this topic in an effective way.Thank you so much

    Personal Installment Loans
    Title Car loan
    Cash Advance Loan

    ReplyDelete
  56. Interesting blog which attracted me more.Spend a worthful time.keep updating more.
    Digital marketing company in Chennai

    ReplyDelete
  57. This information is impressive; I am inspired with your post writing style & how continuously you describe this topic.


    Pawn Shop

    Pawn Loans

    Pawn Shops

    Pawn Loan

    Pawn Shop near me

    ReplyDelete
  58. Its a wonderful post and very helpful, thanks for all this information. You are including better information regarding this topic in an effective way.Thank you so much
    cloud computing training in chennai

    ReplyDelete