Board Game Arena - Felhasználó közreműködései [hu]

Súgó

2013-01-11T16:02:09Z

Een:

An issue? A question?

* [[Faq|Frequently asked questions]] could probably help you.

* [http://forum.boardgamearena.com Forums] are also helpful to get information.

== Help contents ==

* [[Faq|Frequently asked questions]]
* [[About Board Game Arena|About Board Game Arena]]
** [[About us|About us]]
** [[Club Board Game Arena|Club Board Game Arena]]
** [[Contact us|Contact us]]

=== Detailed help ===

* [[Getting started|Getting started]]
* [[Referral|Referral]]
* [[Browser support|Browser support]]
* [[Moderation and grades|Moderation and grades]]
* [[Game clock|Game clock]]
* [[Rating|Rating]]
* [[Reputation|Reputation]]
* [[Translation guidelines|Translation guidelines]]

Támogatott böngészők

2013-01-03T16:00:30Z

Een:

[[Category:Help]]
<h3>For the best experience, we recommend:</h3>
* '''Google Chrome 10+''' [http://www.google.com/chrome Windows] [http://www.google.com/chrome?platform=mac Mac] [http://www.google.com/chrome?platform=linux Linux]
* '''Mozilla Firefox 4+''' [http://www.mozilla.org/products/firefox/ Windows] [http://www.mozilla.org/products/firefox/ Mac] [http://www.mozilla.org/products/firefox/ Linux]

Board Game Arena takes advantage of the most recent web technology to make it possible for you to play without installing anything on your computer: no software to download or update, no plugins to install, etc.
Consequently, to play you need to use a modern web browser. Generally speaking, the more recent your web browser is, the more pleasant your game experience on Board Game Arena will be.

This website makes intensive use of Javascript and your browser's graphics capabilities. Thus, if you want to have the best gaming experience with Board Game Arena, you should use one of the browsers listed above. However, we officially support the following browsers:

* Google Chrome 4+
* Mozilla Firefox 3.5+
* Internet Explorer 9+
* Safari 4+

(Note: We do NOT support playing on iPads or similar tablets.)

Gamehelpgomoku

2012-12-24T12:55:06Z

Een: Created page with " == Goal == Create an unbroken row of exactly five stones of your color horizontally, vertically, or diagonally. Overlines (rows of 6 stones or more) do not count. == Vari..."

== Goal ==

Create an unbroken row of exactly five stones of your color horizontally, vertically, or diagonally.

Overlines (rows of 6 stones or more) do not count.

== Variant ==

In Gomoku+ (also named Caro) in order to win your row of five stones must be free at both ends.

This balances the game differently and gives more defensive power to the white player.

== Openings ==

Black always play first.

With the 'standard' (free) opening, black has got a distinct advantage over white who is directly put 'under attack'.

The 'tournament' opening aims to even the odds between the black and white players:
* black lays the first stone at the center of the board
* white lays the second stone in one of the spaces adjoining to the center of the board (horizontally, vertically or diagonally)
* black lays the third stone at least three spaces away from the center of the board.

Studio FAQ

2012-12-23T17:18:00Z

Een: /* Some frequent errors */

This is a place where we will collect and answer frequently asked questions.

== What should I use to access the files through SFTP? ==

There is a lot of tools to do that. Use the one you are the most comfortable with.

On Linux, you can for example use the 'Connect to server' function of the Nautilus file management system, or use sshfs.

On Windows, there is for example the WinSCP client.

== I can't access the Studio back-office, I get a 'Not authorized' error message? ==

You should first connect to the Studio website (with any of your <developer name><number> accounts). As the authentication is shared with the back-office, then you will be able to access it.

== I don't know the name to use to commit my game, what name should I use? ==

The game name for committing is the name of the game in lower case and without spaces or special characters (ex: puertorico).
It is the same name as the name used for the game folder in your SFTP access.

== It's pretty annoying to log in with multiple users to start a game. Is there some easier way? ==

You can use the 'Express start' function. It will automatically make the specified number of players join the game (using the first of your ten player accounts available) and start the game.

During the game, there is a red arrow on the right of each player name, that you can use to open a tab from this player's perspective.

You can also end the game in two clicks by clicking the 'End game' button then selecting 'Express game stop' in the popup.

== What is the working language on BGA studio? ==

Working language is '''English'''.

Variables and functions must be named with English words.

Comments must be written in English.

Game interface strings and game logs must be written in English.

== How can I provide translation in my language? ==

BGA administrators will translate the game in French before the game release.

After the game release, the collaborative translation interface can be used to translate into other languages.

== Is there a special way to declare the strings that must be translated? ==

Yes. This declaration is made through transparent functions, that depend on the context.

In javascript files, you should use _( 'My string to translate' ).

In php files, you should use self::_( 'My string to translate' ) when the string can be translated on the server side (ex: title included in the game layout) and clienttranslate( 'My string to translate' ) when the string must be translated on the client side (ex: message for the game log).

== I updated the images in the 'img' folder of my game, but they don't show? ==

On BGA Studio, there is the gameserver you are developing on, and the main site server that is used to launch the games. The game icon, box and the publisher logo are hosted on the main site server, so they are not immediately available when you modify them on the gameserver. To deploy them on the main site, you have to use the [[Studio back-office]] to do a commit.

If the images still don't show after that, please try emptying your browser cache and reloading the page.

== I added some game options / some game statistics, but they don't show? ==

An extra deployment action from the BGA administrators is needed to activate new game options and statistics. Please contact us.

== Is there a quick way to access the database for my current table? ==

Yes! While playing a game on studio, you have a "Go to game database" link at the bottom of your game. This link will bring you directly to the database for the current table.

== What is the best way to debug? ==

On the server side (PHP), you can use one of these:
* die(var_dump( $variable_to_inspect );
* throw new BgaUserException(var_dump( $variable_to_inspect );

On the client side (Javascript), we recommand installing Firebug for Firefox (or using the 'Developer tools' with Chrome that have about the same functionalities), then:
* console.log( variable_to_inspect ); will give you the object structure of the variable in the Firebug console, without blocking the execution. It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.
* alert( variable_to_inspect ); will popup what you wish and pause the execution until you click ok. This won't be useful for complex structures, only native types will get plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.

In general for debugging, think of using the 'Save & restore state' functionality. It enables you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong. You can save up to 3 different states.

=== Some frequent errors ===

; The following error occurs when launching the game "Fatal error during creation of database ebd_quoridor_389 Not logged."
: Check that you didn't use $g_user or getCurrentPlayerId() in setupNewGame() function or in an "args" function of your state. As these functions are not consequences of a user action, there is no current player defined. As a general rule, you should use getActivePlayerId() and not getCurrentPlayerId(). See the [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine presentation on the game state machine] for more information.

Studio FAQ

2012-12-23T17:17:40Z

Een: /* What is the best way to debug? */

This is a place where we will collect and answer frequently asked questions.

== What should I use to access the files through SFTP? ==

There is a lot of tools to do that. Use the one you are the most comfortable with.

On Linux, you can for example use the 'Connect to server' function of the Nautilus file management system, or use sshfs.

On Windows, there is for example the WinSCP client.

== I can't access the Studio back-office, I get a 'Not authorized' error message? ==

You should first connect to the Studio website (with any of your <developer name><number> accounts). As the authentication is shared with the back-office, then you will be able to access it.

== I don't know the name to use to commit my game, what name should I use? ==

The game name for committing is the name of the game in lower case and without spaces or special characters (ex: puertorico).
It is the same name as the name used for the game folder in your SFTP access.

== It's pretty annoying to log in with multiple users to start a game. Is there some easier way? ==

You can use the 'Express start' function. It will automatically make the specified number of players join the game (using the first of your ten player accounts available) and start the game.

During the game, there is a red arrow on the right of each player name, that you can use to open a tab from this player's perspective.

You can also end the game in two clicks by clicking the 'End game' button then selecting 'Express game stop' in the popup.

== What is the working language on BGA studio? ==

Working language is '''English'''.

Variables and functions must be named with English words.

Comments must be written in English.

Game interface strings and game logs must be written in English.

== How can I provide translation in my language? ==

BGA administrators will translate the game in French before the game release.

After the game release, the collaborative translation interface can be used to translate into other languages.

== Is there a special way to declare the strings that must be translated? ==

Yes. This declaration is made through transparent functions, that depend on the context.

In javascript files, you should use _( 'My string to translate' ).

In php files, you should use self::_( 'My string to translate' ) when the string can be translated on the server side (ex: title included in the game layout) and clienttranslate( 'My string to translate' ) when the string must be translated on the client side (ex: message for the game log).

== I updated the images in the 'img' folder of my game, but they don't show? ==

On BGA Studio, there is the gameserver you are developing on, and the main site server that is used to launch the games. The game icon, box and the publisher logo are hosted on the main site server, so they are not immediately available when you modify them on the gameserver. To deploy them on the main site, you have to use the [[Studio back-office]] to do a commit.

If the images still don't show after that, please try emptying your browser cache and reloading the page.

== I added some game options / some game statistics, but they don't show? ==

An extra deployment action from the BGA administrators is needed to activate new game options and statistics. Please contact us.

== Is there a quick way to access the database for my current table? ==

Yes! While playing a game on studio, you have a "Go to game database" link at the bottom of your game. This link will bring you directly to the database for the current table.

== What is the best way to debug? ==

On the server side (PHP), you can use one of these:
* die(var_dump( $variable_to_inspect );
* throw new BgaUserException(var_dump( $variable_to_inspect );

On the client side (Javascript), we recommand installing Firebug for Firefox (or using the 'Developer tools' with Chrome that have about the same functionalities), then:
* console.log( variable_to_inspect ); will give you the object structure of the variable in the Firebug console, without blocking the execution. It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.
* alert( variable_to_inspect ); will popup what you wish and pause the execution until you click ok. This won't be useful for complex structures, only native types will get plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.

In general for debugging, think of using the 'Save & restore state' functionality. It enables you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong. You can save up to 3 different states.

=== Some frequent errors ===

; The following error occurs when launching the game "Fatal error during creation of database ebd_quoridor_389: Not logged."
: Check that you didn't use $g_user or getCurrentPlayerId() in setupNewGame() function or in an "args" function of your state. As these functions are not consequences of a user action, there is no current player defined. As a general rule, you should use getActivePlayerId() and not getCurrentPlayerId(). See the [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine presentation on the game state machine] for more information.

Studio

2012-12-11T14:48:31Z

Een: /* How do I register? */

[[File:Bga_studio_small.jpg]]

Note: Please DO NOT translate Studio Documentation, so that there can be one place where you can find the last information available.

== What is this? ==

'''Board Game Arena Studio''' is a platform to build online board game adaptation using the Board Game Arena platform.

It is open to any gamer with development skills :)

See announcement here:
http://forum.boardgamearena.com/viewtopic.php?f=10&t=1973

== How can I develop a board game on BGA Studio? ==

Check these presentations first:

* [http://www.slideshare.net/boardgamearena/5-reasons-why-you-should-use-bga-studio-for-your-online-board-game 5 reasons why you should use BGA Studio for your online board game]
* [http://www.slideshare.net/boardgamearena/the-8-steps-to-create-a-board-game-on-board-game-arena The 8 steps to create a board game on Board Game Arena]
* [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance]
* [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine]
* [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines]

== How do I register? ==

Registering is done by e-mail at '''studio(at)boardgamearena.com'''.

Please provide the following information:
* your player user name on BGA
* your developer user name to be used on “BGA Studio” (for technical reasons, no space, number or special character);
* your real name;
* your e-mail address;
* your postal address.

We also drafted a quick [http://en.doc.boardgamearena.com/images/0/02/BGA_TC_Dev_en.pdf 'terms & conditions' document]. It's very light, so as to get to the fun part faster.

To be valid, the registration e-mail must contain this document as an attachment, with the following sentence in the mail body: 'I agree with the terms & conditions for developers on BGA Studio joined as an attachment'.

And of course, we also encourage you to tell us about which games you would love to develop on BGA!

== Ok, I registered, what do I get? ==

First, from time to time you will get by e-mail the names of some of the games we have an agreement to develop, so that you can tell us 'Hey, this game is great! I want to develop it!' (please keep these names confidential, or it would ruin our tradition to make players guess the name of the next game on the forum)

<pre>NB: during the BETA pĥase, to smooth things up and make sure that everything is working correctly,
we will work only with 3 fearless developers on 3 simple games.</pre>

Second, once we have discussed together and are fixed on a game you'll take charge of, we'll create your studio account and you will get:
* one login / password to access files through SFTP
* ten logins with numeric suffixes from 0 to 9 and a common simple password to test games on the studio website while developing.

Once logged in to your SFTP root folder, you will find:
* a 'resources.html' file with the URLs to use and some extra connection information
* three folders containing the three simple games provided as examples
* a folder for the game you will be developing initialized after our 'EmptyGame' template, providing the game structure (and comments! and examples!)

Then... that's all, you can start!

== Great, I'm in! ... How should I start? ==

If you didn't already, check the presentations at the top of this page to get the basics.

After that, we would advise you to take a peek at one or both of these two game creation tutorials:
* [[Tutorial reversi]]
* [[Tutorial gomoku]]

Then start editing files and see what happens! ;)

If you have any questions, please ask them on the [http://forum.boardgamearena.com/viewforum.php?f=12 development forum].

== Other resources ==

[[Studio FAQ]]

[[Studio file reference]]

[[Studio function reference]]

[[Studio back-office]]

[http://forum.boardgamearena.com/viewforum.php?f=12 Development forum]

[http://forum.boardgamearena.com/viewforum.php?f=4 Bugs forum]

Studio FAQ

2012-12-09T20:46:36Z

Een: /* What is the best way to debug? */

Studio FAQ

2012-12-09T20:42:02Z

Een: /* What is the best way to debug? */

This is a place where we will collect and answer frequently asked questions.

== What should I use to access the files through SFTP? ==

There is a lot of tools to do that. Use the one you are the most comfortable with.

On Linux, you can for example use the 'Connect to server' function of the Nautilus file management system, or use sshfs.

On Windows, there is for example the WinSCP client.

== I can't access the Studio back-office, I get a 'Not authorized' error message? ==

You should first connect to the Studio website (with any of your <developer name><number> accounts). As the authentication is shared with the back-office, then you will be able to access it.

== I don't know the name to use to commit my game, what name should I use? ==

The game name for committing is the name of the game in lower case and without spaces or special characters (ex: puertorico).
It is the same name as the name used for the game folder in your SFTP access.

== It's pretty annoying to log in with multiple users to start a game. Is there some easier way? ==

You can use the 'Express start' function. It will automatically make the specified number of players join the game (using the first of your ten player accounts available) and start the game.

During the game, there is a red arrow on the right of each player name, that you can use to open a tab from this player's perspective.

You can also end the game in two clicks by clicking the 'End game' button then selecting 'Express game stop' in the popup.

== What is the working language on BGA studio? ==

Working language is '''English'''.

Variables and functions must be named with English words.

Comments must be written in English.

Game interface strings and game logs must be written in English.

== How can I provide translation in my language? ==

BGA administrators will translate the game in French before the game release.

After the game release, the collaborative translation interface can be used to translate into other languages.

== Is there a special way to declare the strings that must be translated? ==

Yes. This declaration is made through transparent functions, that depend on the context.

In javascript files, you should use _( 'My string to translate' ).

In php files, you should use self::_( 'My string to translate' ) when the string can be translated on the server side (ex: title included in the game layout) and clienttranslate( 'My string to translate' ) when the string must be translated on the client side (ex: message for the game log).

== I updated the images in the 'img' folder of my game, but they don't show? ==

On BGA Studio, there is the gameserver you are developing on, and the main site server that is used to launch the games. The game icon, box and the publisher logo are hosted on the main site server, so they are not immediately available when you modify them on the gameserver. To deploy them on the main site, you have to use the [[Studio back-office]] to do a commit.

If the images still don't show after that, please try emptying your browser cache and reloading the page.

== I added some game options / some game statistics, but they don't show? ==

An extra deployment action from the BGA administrators is needed to activate new game options and statistics. Please contact us.

== Is there a quick way to access the database for my current table? ==

Yes! While playing a game on studio, you have a "Go to game database" link at the bottom of your game. This link will bring you directly to the database for the current table.

== What is the best way to debug? ==

On the server side (PHP), you can use one of these:
* die(var_dump( $variable_to_inspect );
* throw new BgaUserException(var_dump( $variable_to_inspect );

On the client side (Javascript), we recommand installing Firebug for Firefox (or using the Developer tools with Chrome which has about the same functionalities), then:
* console.log( variable_to_inspect ); will give you the object structure of the variable in the Firebug console, without blocking the execution. It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.
* alert( variable_to_inspect ); will popup what you wish and pause the execution until you click ok. This won't be useful for complex structures, only native types will get plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.

In general for debugging, think of using the 'Save & restore state' functionality. It enables you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong. You can save up to 3 different states.

Studio FAQ

2012-12-09T20:21:23Z

Een: /* What is the best way to debug? */

This is a place where we will collect and answer frequently asked questions.

== What should I use to access the files through SFTP? ==

There is a lot of tools to do that. Use the one you are the most comfortable with.

On Linux, you can for example use the 'Connect to server' function of the Nautilus file management system, or use sshfs.

On Windows, there is for example the WinSCP client.

== I can't access the Studio back-office, I get a 'Not authorized' error message? ==

You should first connect to the Studio website (with any of your <developer name><number> accounts). As the authentication is shared with the back-office, then you will be able to access it.

== I don't know the name to use to commit my game, what name should I use? ==

The game name for committing is the name of the game in lower case and without spaces or special characters (ex: puertorico).
It is the same name as the name used for the game folder in your SFTP access.

== It's pretty annoying to log in with multiple users to start a game. Is there some easier way? ==

You can use the 'Express start' function. It will automatically make the specified number of players join the game (using the first of your ten player accounts available) and start the game.

During the game, there is a red arrow on the right of each player name, that you can use to open a tab from this player's perspective.

You can also end the game in two clicks by clicking the 'End game' button then selecting 'Express game stop' in the popup.

== What is the working language on BGA studio? ==

Working language is '''English'''.

Variables and functions must be named with English words.

Comments must be written in English.

Game interface strings and game logs must be written in English.

== How can I provide translation in my language? ==

BGA administrators will translate the game in French before the game release.

After the game release, the collaborative translation interface can be used to translate into other languages.

== Is there a special way to declare the strings that must be translated? ==

Yes. This declaration is made through transparent functions, that depend on the context.

In javascript files, you should use _( 'My string to translate' ).

In php files, you should use self::_( 'My string to translate' ) when the string can be translated on the server side (ex: title included in the game layout) and clienttranslate( 'My string to translate' ) when the string must be translated on the client side (ex: message for the game log).

== I updated the images in the 'img' folder of my game, but they don't show? ==

On BGA Studio, there is the gameserver you are developing on, and the main site server that is used to launch the games. The game icon, box and the publisher logo are hosted on the main site server, so they are not immediately available when you modify them on the gameserver. To deploy them on the main site, you have to use the [[Studio back-office]] to do a commit.

If the images still don't show after that, please try emptying your browser cache and reloading the page.

== I added some game options / some game statistics, but they don't show? ==

An extra deployment action from the BGA administrators is needed to activate new game options and statistics. Please contact us.

== Is there a quick way to access the database for my current table? ==

Yes! While playing a game on studio, you have a "Go to game database" link at the bottom of your game. This link will bring you directly to the database for the current table.

== What is the best way to debug? ==

On the server side (PHP), you can use one of these:
* die(var_dump( $variable_to_inspect );
* throw new BgaUserException(var_dump( $variable_to_inspect );

On the client side (Javascript), we recommand installing Firebug for Firefox (or using the Developer tools with Chrome which has about the same functionalities), then:
* console.log( variable_to_inspect ); will give you the object structure of the variable in the Firebug console, without blocking the execution. It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.
* alert( variable_to_inspect ); will popup what you wish and pause the execution until you click ok. This won't be useful for complex structures, only native types will get plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.

In general for debugging, think of using the 'Save & restore state' functionality (NB: currently non functional, will be ok with the next studio update). It enables you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong. You can save up to 3 different states.

Studio FAQ

2012-12-09T20:19:37Z

Een:

This is a place where we will collect and answer frequently asked questions.

== What should I use to access the files through SFTP? ==

There is a lot of tools to do that. Use the one you are the most comfortable with.

On Linux, you can for example use the 'Connect to server' function of the Nautilus file management system, or use sshfs.

On Windows, there is for example the WinSCP client.

== I can't access the Studio back-office, I get a 'Not authorized' error message? ==

You should first connect to the Studio website (with any of your <developer name><number> accounts). As the authentication is shared with the back-office, then you will be able to access it.

== I don't know the name to use to commit my game, what name should I use? ==

The game name for committing is the name of the game in lower case and without spaces or special characters (ex: puertorico).
It is the same name as the name used for the game folder in your SFTP access.

== It's pretty annoying to log in with multiple users to start a game. Is there some easier way? ==

You can use the 'Express start' function. It will automatically make the specified number of players join the game (using the first of your ten player accounts available) and start the game.

During the game, there is a red arrow on the right of each player name, that you can use to open a tab from this player's perspective.

You can also end the game in two clicks by clicking the 'End game' button then selecting 'Express game stop' in the popup.

== What is the working language on BGA studio? ==

Working language is '''English'''.

Variables and functions must be named with English words.

Comments must be written in English.

Game interface strings and game logs must be written in English.

== How can I provide translation in my language? ==

BGA administrators will translate the game in French before the game release.

After the game release, the collaborative translation interface can be used to translate into other languages.

== Is there a special way to declare the strings that must be translated? ==

Yes. This declaration is made through transparent functions, that depend on the context.

In javascript files, you should use _( 'My string to translate' ).

In php files, you should use self::_( 'My string to translate' ) when the string can be translated on the server side (ex: title included in the game layout) and clienttranslate( 'My string to translate' ) when the string must be translated on the client side (ex: message for the game log).

== I updated the images in the 'img' folder of my game, but they don't show? ==

On BGA Studio, there is the gameserver you are developing on, and the main site server that is used to launch the games. The game icon, box and the publisher logo are hosted on the main site server, so they are not immediately available when you modify them on the gameserver. To deploy them on the main site, you have to use the [[Studio back-office]] to do a commit.

If the images still don't show after that, please try emptying your browser cache and reloading the page.

== I added some game options / some game statistics, but they don't show? ==

An extra deployment action from the BGA administrators is needed to activate new game options and statistics. Please contact us.

== Is there a quick way to access the database for my current table? ==

Yes! While playing a game on studio, you have a "Go to game database" link at the bottom of your game. This link will bring you directly to the database for the current table.

== What is the best way to debug? ==

On the server side (PHP), you can use one of these:
* die(var_dump( $variable_to_inspect );
* throw new BgaUserException(var_dump( $variable_to_inspect );

On the client side (Javascript), we recommand installing Firebug for Firefox (or using the Developer tools with Chrome which has about the same functionalities), then:
* console.log( variable_to_inspect ); will give you the object structure of the variable in the Firebug console, without blocking the execution. It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.
* alert( variable_to_inspect ); will popup what you wish and pause the execution until you click ok. This won't be useful for complex structures, only native types will get plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.

In general for debugging, think of using the save/restore functionality (NB: currently non functional, will be ok with the next studio update). It enable you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong.

Studio

2012-12-06T22:29:11Z

Een: /* Great, I'm in! ... How should I start? */

[[File:Bga_studio_small.jpg]]

== What is this? ==

'''Board Game Arena Studio''' is a platform to build online board game adaptation using the Board Game Arena platform.

It is open to any gamer with development skills :)

See announcement here:
http://forum.boardgamearena.com/viewtopic.php?f=10&t=1973

== How can I develop a board game on BGA Studio? ==

Check these presentations first:

* [http://www.slideshare.net/boardgamearena/5-reasons-why-you-should-use-bga-studio-for-your-online-board-game 5 reasons why you should use BGA Studio for your online board game]
* [http://www.slideshare.net/boardgamearena/the-8-steps-to-create-a-board-game-on-board-game-arena The 8 steps to create a board game on Board Game Arena]
* [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance]
* [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine]
* [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines]

== How do I register? ==

Registering is done by e-mail at '''studio(at)boardgamearena.com'''.

Please provide the following information:
* your developer user name to be used on “BGA Studio” (for technical reasons, no space, number or special character);
* your real name;
* your e-mail address;
* your postal address.

We also drafted a quick [http://en.doc.boardgamearena.com/images/0/02/BGA_TC_Dev_en.pdf 'terms & conditions' document]. It's very light, so as to get to the fun part faster.

To be valid, the registration e-mail must contain this document as an attachment, with the following sentence in the mail body: 'I agree with the terms & conditions for developers on BGA Studio joined as an attachment'.

And of course, we also encourage you to tell us about which games you would love to develop on BGA!

== Ok, I registered, what do I get? ==

First, from time to time you will get by e-mail the names of some of the games we have an agreement to develop, so that you can tell us 'Hey, this game is great! I want to develop it!' (please keep these names confidential, or it would ruin our tradition to make players guess the name of the next game on the forum)

<pre>NB: during the BETA pĥase, to smooth things up and make sure that everything is working correctly,
we will work only with 3 fearless developers on 3 simple games.</pre>

Second, once we have discussed together and are fixed on a game you'll take charge of, we'll create your studio account and you will get:
* one login / password to access files through SFTP
* ten logins with numeric suffixes from 0 to 9 and a common simple password to test games on the studio website while developing.

Once logged in to your SFTP root folder, you will find:
* a 'resources.html' file with the URLs to use and some extra connection information
* three folders containing the three simple games provided as examples
* a folder for the game you will be developing initialized after our 'EmptyGame' template, providing the game structure (and comments! and examples!)

Then... that's all, you can start!

== Great, I'm in! ... How should I start? ==

If you didn't already, check the presentations at the top of this page to get the basics.

After that, we would advise you to take a peek at one or both of these two game creation tutorials:
* [[Tutorial reversi]]
* [[Tutorial gomoku]]

Then start editing files and see what happens! ;)

If you have any questions, please ask them on the [http://forum.boardgamearena.com/viewforum.php?f=12 development forum].

== Other resources ==

[[Studio FAQ]]

[[Studio file reference]]

[[Studio function reference]]

[[Studio back-office]]

[http://forum.boardgamearena.com/viewforum.php?f=12 Development forum]

[http://forum.boardgamearena.com/viewforum.php?f=4 Bugs forum]

Tutorial gomoku

2012-12-06T22:27:38Z

Een: /* Implement rules and end of game conditions */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created:

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML. For example:

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit .game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit .game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections.

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit .js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in .game.php->getAllDatas() is now available in your .js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your .js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your .game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In .game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In .js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* In .js->setup() assign the constants to this variable

this.gameConstants = gamedatas.constants;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states in addition of the predefined states 1 (gameSetup) and 99 (gameEnd). One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Implement the 'stNextPlayer()' function in .game.php to manage turn rotation. Except if there are special rules for the game turn depending on context, this is really easy:

<pre>
function stNextPlayer()
{
self::trace( "stNextPlayer" );

// Go to next player
$active_player = self::activeNextPlayer();
self::giveExtraTime( $active_player );

$this->gamestate->nextState();
}
</pre>

Add onclick events on intersections in .js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding .js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in .action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in .game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in .js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in .js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in .game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in .game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so:

* declare a global 'end_of_game' variable in .game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

* init that global variable to 0 in .game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

* add the appropriate code in .game.php before proceeding to the next state, using a checkForWin() function implemented separately for clarity. If the game has been won, we set the score, send a score update notification to the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, check for this variable and for other possible 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* Catch the score notification on the client side in .js->setupNotifications(). It is advised to set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* Implement the function declared to handle the notification.

<pre>
notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},
</pre>

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-06T22:26:48Z

Een: /* Implement rules and end of game conditions */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created:

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML. For example:

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit .game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit .game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections.

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit .js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in .game.php->getAllDatas() is now available in your .js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your .js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your .game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In .game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In .js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* In .js->setup() assign the constants to this variable

this.gameConstants = gamedatas.constants;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states in addition of the predefined states 1 (gameSetup) and 99 (gameEnd). One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Implement the 'stNextPlayer()' function in .game.php to manage turn rotation. Except if there are special rules for the game turn depending on context, this is really easy:

<pre>
function stNextPlayer()
{
self::trace( "stNextPlayer" );

// Go to next player
$active_player = self::activeNextPlayer();
self::giveExtraTime( $active_player );

$this->gamestate->nextState();
}
</pre>

Add onclick events on intersections in .js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding .js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in .action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in .game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in .js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in .js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in .game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in .game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so:

* declare a global 'end_of_game' variable in .game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

* init that global variable to 0 in .game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

* add the appropriate code in .game.php before proceeding to the next state, using a checkForWin() function implemented separately for clarity. If the game has been won, we set the score, notify it to update the score on the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, check for this variable and for other possible 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* Catch the score notification on the client side in .js->setupNotifications(). It is advised to set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* Implement the function declared to handle the notification.

<pre>
notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},
</pre>

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-06T22:24:28Z

Een: /* Manage states and events */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created:

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML. For example:

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit .game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit .game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections.

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit .js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in .game.php->getAllDatas() is now available in your .js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your .js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your .game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In .game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In .js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* In .js->setup() assign the constants to this variable

this.gameConstants = gamedatas.constants;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states in addition of the predefined states 1 (gameSetup) and 99 (gameEnd). One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Implement the 'stNextPlayer()' function in .game.php to manage turn rotation. Except if there are special rules for the game turn depending on context, this is really easy:

<pre>
function stNextPlayer()
{
self::trace( "stNextPlayer" );

// Go to next player
$active_player = self::activeNextPlayer();
self::giveExtraTime( $active_player );

$this->gamestate->nextState();
}
</pre>

Add onclick events on intersections in .js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding .js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in .action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in .game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in .js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in .js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in .game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in .game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so:

* declare a global 'end_of_game' variable in .game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

* we init that global variable to 0 in .game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

* add the appropriate code in .game.php before proceeding to the next state, using a checkForWin() function implemented separately for clarity. If the game has been won, we set the score, notify it to update the score on the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, check for this variable and for other possible 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* Catch the score notification on the client side in .js->setupNotifications(). It is advised to set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* Implement the function declared to handle the notification.

<pre>
notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},
</pre>

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-06T22:23:06Z

Een: /* Setup the backbone of your game */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created:

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML. For example:

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit .game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit .game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections.

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit .js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in .game.php->getAllDatas() is now available in your .js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your .js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your .game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In .game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In .js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* In .js->setup() assign the constants to this variable

this.gameConstants = gamedatas.constants;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Implement the 'stNextPlayer()' function in .game.php to manage turn rotation. Except if there are special rules for the game turn depending on context, this is really easy:

<pre>
function stNextPlayer()
{
self::trace( "stNextPlayer" );

// Go to next player
$active_player = self::activeNextPlayer();
self::giveExtraTime( $active_player );

$this->gamestate->nextState();
}
</pre>

Add onclick events on intersections in .js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding .js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in .action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in .game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in .js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in .js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in .game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in .game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so:

* declare a global 'end_of_game' variable in .game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

* we init that global variable to 0 in .game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

* add the appropriate code in .game.php before proceeding to the next state, using a checkForWin() function implemented separately for clarity. If the game has been won, we set the score, notify it to update the score on the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, check for this variable and for other possible 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* Catch the score notification on the client side in .js->setupNotifications(). It is advised to set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* Implement the function declared to handle the notification.

<pre>
notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},
</pre>

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-06T22:22:43Z

Een: /* Setup the backbone of your game */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created:

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML. For example:

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit .game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit .game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections.

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit .js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in .game.php->getAllDatas() is now available in your .js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your .js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your .game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In .game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In .js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* In .js->setup() assign the constants to this variable

this.gameConstants = gamedatas.constants;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get after some tweaks and refresh:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Implement the 'stNextPlayer()' function in .game.php to manage turn rotation. Except if there are special rules for the game turn depending on context, this is really easy:

<pre>
function stNextPlayer()
{
self::trace( "stNextPlayer" );

// Go to next player
$active_player = self::activeNextPlayer();
self::giveExtraTime( $active_player );

$this->gamestate->nextState();
}
</pre>

Add onclick events on intersections in .js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding .js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in .action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in .game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in .js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in .js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in .game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in .game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so:

* declare a global 'end_of_game' variable in .game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

* we init that global variable to 0 in .game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

* add the appropriate code in .game.php before proceeding to the next state, using a checkForWin() function implemented separately for clarity. If the game has been won, we set the score, notify it to update the score on the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, check for this variable and for other possible 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* Catch the score notification on the client side in .js->setupNotifications(). It is advised to set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* Implement the function declared to handle the notification.

<pre>
notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},
</pre>

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-06T22:21:47Z

Een: /* Setup the backbone of your game */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created:

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML. For example:

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit .game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit .game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections.

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit .js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in .game.php->getAllDatas() is now available in your .js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your .js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your .game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In .game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In .js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* In .js->setup() assign the constants to this variable

this.gameConstants = gamedatas.constants;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Implement the 'stNextPlayer()' function in .game.php to manage turn rotation. Except if there are special rules for the game turn depending on context, this is really easy:

<pre>
function stNextPlayer()
{
self::trace( "stNextPlayer" );

// Go to next player
$active_player = self::activeNextPlayer();
self::giveExtraTime( $active_player );

$this->gamestate->nextState();
}
</pre>

Add onclick events on intersections in .js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding .js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in .action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in .game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in .js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in .js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in .game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in .game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so:

* declare a global 'end_of_game' variable in .game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

* we init that global variable to 0 in .game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

* add the appropriate code in .game.php before proceeding to the next state, using a checkForWin() function implemented separately for clarity. If the game has been won, we set the score, notify it to update the score on the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, check for this variable and for other possible 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* Catch the score notification on the client side in .js->setupNotifications(). It is advised to set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* Implement the function declared to handle the notification.

<pre>
notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},
</pre>

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-06T22:19:41Z

Een: /* You will start from our 'emtpy game' template */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created:

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML. For example:

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit .game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit .game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections.

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit .js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in .game.php->getAllDatas() is now available in your .js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your .js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your .game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In .game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In .js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Implement the 'stNextPlayer()' function in .game.php to manage turn rotation. Except if there are special rules for the game turn depending on context, this is really easy:

<pre>
function stNextPlayer()
{
self::trace( "stNextPlayer" );

// Go to next player
$active_player = self::activeNextPlayer();
self::giveExtraTime( $active_player );

$this->gamestate->nextState();
}
</pre>

Add onclick events on intersections in .js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding .js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in .action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in .game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in .js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in .js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in .game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in .game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so:

* declare a global 'end_of_game' variable in .game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

* we init that global variable to 0 in .game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

* add the appropriate code in .game.php before proceeding to the next state, using a checkForWin() function implemented separately for clarity. If the game has been won, we set the score, notify it to update the score on the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, check for this variable and for other possible 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* Catch the score notification on the client side in .js->setupNotifications(). It is advised to set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* Implement the function declared to handle the notification.

<pre>
notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},
</pre>

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-06T22:19:30Z

Een:

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML. For example:

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit .game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit .game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections.

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit .js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in .game.php->getAllDatas() is now available in your .js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your .js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your .game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In .game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In .js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Implement the 'stNextPlayer()' function in .game.php to manage turn rotation. Except if there are special rules for the game turn depending on context, this is really easy:

<pre>
function stNextPlayer()
{
self::trace( "stNextPlayer" );

// Go to next player
$active_player = self::activeNextPlayer();
self::giveExtraTime( $active_player );

$this->gamestate->nextState();
}
</pre>

Add onclick events on intersections in .js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding .js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in .action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in .game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in .js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in .js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in .game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in .game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so:

* declare a global 'end_of_game' variable in .game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

* we init that global variable to 0 in .game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

* add the appropriate code in .game.php before proceeding to the next state, using a checkForWin() function implemented separately for clarity. If the game has been won, we set the score, notify it to update the score on the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, check for this variable and for other possible 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* Catch the score notification on the client side in .js->setupNotifications(). It is advised to set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* Implement the function declared to handle the notification.

<pre>
notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},
</pre>

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-06T22:17:16Z

Een: /* Setup the backbone of your game */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML. For example:

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit gomoku.game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit gomoku.game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections.

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit gomoku.js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in gomoku.game.php->getAllDatas() is now available in your gomoku.js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your gomoku.js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your gomoku.game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In gomoku.game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In gomoku.js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Implement the 'stNextPlayer()' function in gomoku.game.php to manage turn rotation. Except if there are special rules for the game turn depending on context, this is really easy:

<pre>
function stNextPlayer()
{
self::trace( "stNextPlayer" );

// Go to next player
$active_player = self::activeNextPlayer();
self::giveExtraTime( $active_player );

$this->gamestate->nextState();
}
</pre>

Add onclick events on intersections in gomoku.js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding gomoku.js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in gomoku.action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in gomoku.game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in gomoku.js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in gomoku.js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in gomoku.game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in gomoku.game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so:

* declare a global 'end_of_game' variable in gomoku.game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

* we init that global variable to 0 in gomoku.game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

* add the appropriate code in gomoku.game.php before proceeding to the next state, using a checkForWin() function implemented separately for clarity. If the game has been won, we set the score, notify it to update the score on the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, check for this variable and for other possible 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* Catch the score notification on the client side in gomoku.js->setupNotifications(). It is advised to set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* Implement the function declared to handle the notification.

<pre>
notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},
</pre>

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-06T22:16:01Z

Een: /* Setup the board */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML. For example:

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit gomoku.game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit gomoku.game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections (jstpl_intersection).

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit gomoku.js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in gomoku.game.php->getAllDatas() is now available in your gomoku.js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your gomoku.js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your gomoku.game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In gomoku.game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In gomoku.js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Implement the 'stNextPlayer()' function in gomoku.game.php to manage turn rotation. Except if there are special rules for the game turn depending on context, this is really easy:

<pre>
function stNextPlayer()
{
self::trace( "stNextPlayer" );

// Go to next player
$active_player = self::activeNextPlayer();
self::giveExtraTime( $active_player );

$this->gamestate->nextState();
}
</pre>

Add onclick events on intersections in gomoku.js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding gomoku.js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in gomoku.action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in gomoku.game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in gomoku.js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in gomoku.js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in gomoku.game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in gomoku.game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so:

* declare a global 'end_of_game' variable in gomoku.game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

* we init that global variable to 0 in gomoku.game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

* add the appropriate code in gomoku.game.php before proceeding to the next state, using a checkForWin() function implemented separately for clarity. If the game has been won, we set the score, notify it to update the score on the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, check for this variable and for other possible 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* Catch the score notification on the client side in gomoku.js->setupNotifications(). It is advised to set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* Implement the function declared to handle the notification.

<pre>
notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},
</pre>

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-06T22:15:10Z

Een: /* Manage states and events */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML.

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit gomoku.game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit gomoku.game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections (jstpl_intersection).

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit gomoku.js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in gomoku.game.php->getAllDatas() is now available in your gomoku.js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your gomoku.js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your gomoku.game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In gomoku.game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In gomoku.js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Implement the 'stNextPlayer()' function in gomoku.game.php to manage turn rotation. Except if there are special rules for the game turn depending on context, this is really easy:

<pre>
function stNextPlayer()
{
self::trace( "stNextPlayer" );

// Go to next player
$active_player = self::activeNextPlayer();
self::giveExtraTime( $active_player );

$this->gamestate->nextState();
}
</pre>

Add onclick events on intersections in gomoku.js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding gomoku.js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in gomoku.action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in gomoku.game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in gomoku.js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in gomoku.js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in gomoku.game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in gomoku.game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so:

* declare a global 'end_of_game' variable in gomoku.game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

* we init that global variable to 0 in gomoku.game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

* add the appropriate code in gomoku.game.php before proceeding to the next state, using a checkForWin() function implemented separately for clarity. If the game has been won, we set the score, notify it to update the score on the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, check for this variable and for other possible 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* Catch the score notification on the client side in gomoku.js->setupNotifications(). It is advised to set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* Implement the function declared to handle the notification.

<pre>
notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},
</pre>

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-06T22:12:25Z

Een: /* Implement rules and end of game conditions */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML.

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit gomoku.game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit gomoku.game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections (jstpl_intersection).

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit gomoku.js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in gomoku.game.php->getAllDatas() is now available in your gomoku.js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your gomoku.js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your gomoku.game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In gomoku.game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In gomoku.js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Add onclick events on intersections in gomoku.js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding gomoku.js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in gomoku.action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in gomoku.game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in gomoku.js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in gomoku.js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in gomoku.game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in gomoku.game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so:

* declare a global 'end_of_game' variable in gomoku.game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

* we init that global variable to 0 in gomoku.game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

* add the appropriate code in gomoku.game.php before proceeding to the next state, using a checkForWin() function implemented separately for clarity. If the game has been won, we set the score, notify it to update the score on the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, check for this variable and for other possible 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* Catch the score notification on the client side in gomoku.js->setupNotifications(). It is advised to set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* Implement the function declared to handle the notification.

<pre>
notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},
</pre>

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-06T22:10:32Z

Een: /* Implement rules and end of game conditions */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML.

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit gomoku.game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit gomoku.game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections (jstpl_intersection).

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit gomoku.js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in gomoku.game.php->getAllDatas() is now available in your gomoku.js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your gomoku.js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your gomoku.game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In gomoku.game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In gomoku.js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Add onclick events on intersections in gomoku.js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding gomoku.js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in gomoku.action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in gomoku.game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in gomoku.js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in gomoku.js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in gomoku.game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in gomoku.game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so:

* we declare a global 'end_of_game' variable in gomoku.game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

* we init that global variable to 0 in gomoku.game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

* we add the appropriate code in gomoku.game.php before proceeding to the next state, using a checkForWin() function that we implement separately for clarity. If the game has been won, we set the score, notify it to update the score on the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, you check for this variable and for other possible 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* We catch the score notification on the client side in gomoku.js->setupNotifications() and we set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* We implement the function declared to handle the notification.

notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-06T22:09:13Z

Een: /* Implement rules and end of game conditions */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML.

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit gomoku.game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit gomoku.game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections (jstpl_intersection).

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit gomoku.js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in gomoku.game.php->getAllDatas() is now available in your gomoku.js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your gomoku.js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your gomoku.game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In gomoku.game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In gomoku.js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Add onclick events on intersections in gomoku.js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding gomoku.js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in gomoku.action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in gomoku.game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in gomoku.js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in gomoku.js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in gomoku.game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in gomoku.game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so:

* we declare a global 'end_of_game' variable in gomoku.game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

* we init that global variable to 0 in gomoku.game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

* we add the appropriate code in gomoku.game.php before proceeding to the next state, using a checkForWin() function that we implement separately for clarity. If the game has been won, we set the score, notify it to update the score on the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() which is called when your state machine goes to the 'checkEndOfGame' state, you check for this variable and for other 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* We catch the score notification on the client side in gomoku.js->setupNotifications() and we set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* We implement the function declared to handle the notification.

notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-06T22:07:37Z

Een: /* Implement rules and end of game conditions */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML.

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit gomoku.game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit gomoku.game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections (jstpl_intersection).

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit gomoku.js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in gomoku.game.php->getAllDatas() is now available in your gomoku.js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your gomoku.js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your gomoku.game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In gomoku.game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In gomoku.js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Add onclick events on intersections in gomoku.js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding gomoku.js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in gomoku.action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in gomoku.game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in gomoku.js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in gomoku.js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in gomoku.game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in gomoku.game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner in gomoku.game.php->stCheckEndOfGame()

* It is easier to check for a win directly after setting the stone, so:
** we declare a global 'end_of_game' variable in gomoku.game.php->Gomoku()

self::initGameStateLabels( array(
"end_of_game" => 10,
) );

** we init that global variable to 0 in gomoku.game.php->setupNewGame()

self::setGameStateInitialValue( 'end_of_game', 0 );

** we add the appropriate code in gomoku.game.php before proceeding to the next state, using a checkForWin() function that we implement separately for clarity. If the game has been won, we set the score, notify it to update the score on the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.

<pre>
// Check if end of game has been met
if ($this->checkForWin( $coord_x, $coord_y, $color )) {

// Set active player score to 1 (he is the winner)
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";
self::DbQuery($sql);

// Notify final score
$this->notifyAllPlayers( "finalScore",
clienttranslate( '${player_name} wins the game!' ),
array(
"player_name" => self::getActivePlayerName(),
"player_id" => $player_id,
"score_delta" => 1,
)
);

// Set global variable flag to pass on the information that the game has ended
self::setGameStateValue('end_of_game', 1);

// End of game message
$this->notifyAllPlayers( "message",
clienttranslate('Thanks for playing!'),
array(
)
);

}
</pre>

* Then in the gomoku->stCheckEndOfGame() which is called when your state machine goes to the 'checkEndOfGame' state, you check for this variable and for other 'end of game' conditions (draw).

<pre>
function stCheckEndOfGame()
{
self::trace( "stCheckEndOfGame" );

$transition = "notEndedYet";

// If there is no more free intersections, the game ends
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";
$free = self::getCollectionFromDb( $sql );

if (count($free) == 0) {
$transition = "gameEnded";
}

// If the 'end of game' flag has been set, end the game
if (self::getGameStateValue('end_of_game') == 1) {
$transition = "gameEnded";
}

$this->gamestate->nextState( $transition );
}
</pre>

* We catch the score notification on the client side in gomoku.js->setupNotifications() and we set up a small delay after that so that end of game popup doesn't show too quickly.

<pre>
dojo.subscribe( 'finalScore', this, "notif_finalScore" );
this.notifqueue.setSynchronous( 'finalScore', 1500 );
</pre>

* We implement the function declared to handle the notification.

notif_finalScore: function( notif )
{
console.log( '**** Notification : finalScore' );
console.log( notif );

// Update score
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );
},

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Studio function reference

2012-12-06T22:06:45Z

Een: /* Client side (Javascript functions) */

This page references useful server side and client side functions (and some interesting class variables), so that nobody needs to reinvent the wheel (unless he wants to).

This list is not exhaustive, in particular functions already well described by comments in the 'EmptyGame' game template may not be described again below.

== Server side (PHP functions) ==

=== APP_GameAction class (<gamename>.action.php) ===

; function isArg( $argName )
: Is this argument filled ?
; function getArg( $argName, $argType, $mandatory=false, $default=NULL, $argTypeDetails=array(), $bCanFail=false )
: Get script argument with the correct type
: bCanFail means than a validation failure is possible (user input)
: The main argType values are as follows.
<pre>
define( 'AT_int', 0 ); // an integer
define( 'AT_posint', 1 ); // a positive integer
define( 'AT_float', 2 ); // a float
define( 'AT_email', 3 ); // an email
define( 'AT_url', 4 ); // a URL
define( 'AT_bool', 5 ); // 1/0/true/false
define( 'AT_enum', 6 ); // argTypeDetails list the possible values
define( 'AT_alphanum', 7 ); // only 0-9a-zA-Z_ and space
</pre>

=== Table class (<gamename>.game.php) ===

; function _( $text )
: Transparent function, used to mark strings to be translated on the server side (ex: error message)
; function clienttranslate( $string )
: Transparent function: used to mark string to be translated on client side (ex: notification message)
; function getPlayersNumber()
: Returns the number of players playing at the table
; function checkAction( $actionName, $bThrowException=true )
: Check if action is valid regarding current game state (exception if fails)
: if "bThrowException" is set to "false", the function return false in case of failure instead of throwing and exception
; function getActivePlayerId()
: Get the "active_player", whatever what is the current state type
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"
; function getActivePlayerName()
: Get the "active_player" name
; function getCurrentPlayerId()
: Get the "current_player". The current player is the one from which the action originated. It is not always the active player.
; function getCurrentPlayerName()
: Get the "current_player" name
; function getCurrentPlayerColor()
: Get the "current_player" color
; function isCurrentPlayerZombie()
: Check the "current_player" zombie status
; function activeNextPlayer()
: Make the next player active
; function activePrevPlayer()
: Make the previous player active
; function giveExtraTime( $player_id, $specific_time=null )
: Give standard extra time to this player (standard extra time is a game option)
; function initStat( $table_or_player, $name, $value, $player_id=null )
: Create a statistic entry for the specified statistics with a default value
: In case of a "player" entry, if player_id is not specified, all players are set to the same value
; function setStat( $value, $name, $player_id = null )
: Set statistic value
; function incStat( $delta, $name, $player_id = null )
: Increment (or decrement) specified value
; function DbQuery( $sql )
: Executes sql query on the database
; function getCollectionFromDB( $sql, $bSingleValue=false )
: Returns an associative array of rows for the sql query. First column must be a primary or alternate key. The resulting collection can be empty.
; protected function getNonEmptyCollectionFromDB( $sql )
: Idem, but raise an exception if the collection is empty
; function getUniqueValueFromDB( $sql )
: Returns a unique value from DB or null if no value is found
: Raise an exception if more than 1 row is returned
; function getObjectFromDB( $sql )
: Returns one row for the sql query as an associative array or null if there is no result
: Raise an exception if the query return more than one row
; function getNonEmptyObjectFromDB( $sql )
: Idem, but raise an exception if the query doesn't return exactly one row

=== Exceptions you can throw ===

; throw new BgaUserException ( $error_message)
: Base class to notify a user error
; throw new BgaSystemException ( $error_message)
: Base class to notify a system exception. The message will be hidden from the user, but show in the logs. Use this if the message contains technical information.
; throw new BgaSystemVisibleException ( $error_message)
: Same as previous, except that the message is visible by the user. You can use this if the message is understandable by the user.

== Client side (Javascript functions) ==

; this.player_id
: Id of the player on whose browser the code is running.

; this.isSpectator
: Flag set to true if the user at the table is a spectator (not a player).

; this.gamedatas
: Contains your initial set of datas to init the game, created at game start or game refresh (F5)
: You can update it as needed to keep an up to date reference of the game on the client side.

; slideToObject: function( mobile_obj, target_obj, duration, delay )
: Return an dojo.fx animation that is sliding a DOM object from its current position over another one
: Animate a slide of the DOM object referred to by domNodeToSlide from its current position to the xpos, ypos relative to the object referred to by domNodeToSlideTo.

; slideToObjectPos: function( mobile_obj, target_obj, target_x, target_y, duration, delay )
: Return an dojo.fx animation that is sliding a DOM object from its current position over another one at the given coordinates relative to the target object.

; updateCounters(counters)
: Useful for updating game counters in the player panel (such as resources).
: 'counters' arg is an associative array [counter_name_value => [ 'counter_name' => counter_name_value, 'counter_value' => counter_value_value], ... ]
: All counters must be referenced in this.gamedatas.counters and will be updated.
: DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

; addTooltip( node, _( helpString ), _( actionString ), delay );
: Add a simple text tooltip to the DOM node. Only one of 'helpString' or 'actionString' must be used. _() must be used for the text to be marked for translation.

; addTooltipHtml( node, html, delay );
: Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

; addTooltipToClass( cssClass, _( helpString ), _( actionString ), delay );
: Add a simple text tooltip to all the DOM nodes set with this cssClass. Only one of 'helpString' or 'actionString' must be used. _() must be used for the text to be marked for translation.
: NB: all concerned nodes must have IDs to get tooltips

; addTooltipHtmlToClass( cssClass, html, delay );
: Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).
: NB: all concerned nodes must have IDs to get tooltips

; addEventToClass: function( cssClassName, eventName, functionName )
: Same as dojo.connect(), but for all the nodes set with the specified cssClassName

; addStyleToClass: function( cssClassName, cssProperty, propertyValue )
: Same as dojo.style(), but for all the nodes set with the specified cssClassName

; isCurrentPlayerActive()
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play)

; checkAction: function( action, nomessage )
: Check if player can do the specified action by taking into account: _ current game state & _ interface locking
: return true if action is authorized
: return false and display an error message if not (display no message if nomessage is specified)

; showMessage: function( msg, type )
: Show an information message during a few seconds at the top of the page
: Type can be 'error' or 'info'

; this.scoreCtrl[ player_id ].incValue( score_delta );
: Adds score_delta (positive or negative integer) to the current score value for player

Studio back-office

2012-12-06T21:43:49Z

Een: /* Sources */

You will find the URL to the Studio back-office in the 'resources.html' file at the root of your SFTP access.

Here is a list and description of the links and functions in this back-office.

Click on a menu to display its content.

=== Documentation ===

Contains links to this wiki, the development forum and the bugs forum.

=== Database ===

Contains a link to the Studio database administration tool (PHPMyAdmin).

Your login / password for this tool is the same as for your SFTP access.

=== Sources ===

Contains a form for committing your sources to the BGA repository.
* Game name field should contain the name of your game (lower case, no space). Ex: puertorico
* Comment field should contain your commit comment describing changes to the code since your last commit.

You should commit from time to time when you hit some landmarks in your development. This is an extra assurance not to lose your code, and to have the possibility (by asking BGA administrators) to get a previous version of your code if you need to backtrack.

=== Logs ===

Gives you a web based access to the studio server logs.

; Current table error log
: main log of interest to you while developing, it contains the error happening at the table you are currently playing at.
; Current table request logs
: this log traces all the actions happening at the table you are currently playing at.
; Javascript error log
: this log traces all the Javascript errors happening on the client side. Errors are also briefly displayed in your browser, but in this log it's better formatted and you can look a it quietly.
; Gameserver error log
: this log traces all errors happening on the gameserver. It should mainly be useful if your game setup crashes (ie before your table is ready, so before errors are collected in the current table error log), for example if there is a syntax error in your 'dbmodel.sql' file.
; HTTP error log
: this log traces the web server errors. This is useful to look at PHP syntax errors and warnings.

Please note that the three last logs are common to all games being developed on the platform, so there may be some noise in the data you are interested in.

You can open the log links in a different tab and just hit F5 when you need to refresh. The URL you will get for the new tab has a "?n=100" parameter that gives the number of lines to display: you can modify it in the URL if you need more.

Studio FAQ

2012-12-06T21:43:08Z

Een:

Tutorial gomoku

2012-12-05T23:06:25Z

Een: /* Implement rules and end of game conditions */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML.

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit gomoku.game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit gomoku.game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections (jstpl_intersection).

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit gomoku.js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in gomoku.game.php->getAllDatas() is now available in your gomoku.js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your gomoku.js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your gomoku.game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In gomoku.game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In gomoku.js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Add onclick events on intersections in gomoku.js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding gomoku.js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in gomoku.action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in gomoku.game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in gomoku.js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in gomoku.js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game. For example in Gomoku, black plays first. So in gomoku.game.php->setupNewGame():

* modify the default colors for players to white and black

$default_colors = array( "000000", "ffffff", );

* and at the end of the setup make the black player active

<pre>
// Black plays first
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";
$black_player = self::getNonEmptyObjectFromDb( $sql );

$this->gamestate->changeActivePlayer( $black_player['player_id'] );
</pre>

Implement rule for computing game progression in gomoku.game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).

<pre>
function getGameProgression()
{
// Compute and return the game progression

// Number of stones laid down on the goban over the total number of intersections * 100
$sql = "
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null
";
$counter = self::getNonEmptyObjectFromDB( $sql );

return $counter['value'];
}
</pre>

Implement end of game detection and update the score according to who is the winner in .game.php->stCheckEndOfGame()

Notify the score and implement the corresponding interface update in .js

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-05T22:55:18Z

Een: /* Manage states and events */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML.

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit gomoku.game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit gomoku.game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections (jstpl_intersection).

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit gomoku.js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in gomoku.game.php->getAllDatas() is now available in your gomoku.js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your gomoku.js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your gomoku.game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In gomoku.game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In gomoku.js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Add onclick events on intersections in gomoku.js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding gomoku.js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in gomoku.action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in gomoku.game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in gomoku.js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:

[[File:Gomoku stones.png]]

The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:

* we define in the css file the 'clickable' css class

<pre>
.clickable {
cursor: pointer;
}
.clickable:hover { background-position: -90px 0px; }
</pre>

* in gomoku.js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{

case 'playerTurn':
if( this.isCurrentPlayerActive() )
{
var queueEntries = dojo.query( '.no_stone' );
for(var i=0; i<queueEntries.length; i++) {
dojo.addClass( queueEntries[i], 'clickable' );
}
}
}
},
</pre>

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game (if any)

Nothing special for Gomoku

Implement rule for computing game progression in .game.php->getGameProgression()

Implement end of game detection and update the score according to who is the winner in .game.php->stCheckEndOfGame()

Notify the score and implement the corresponding interface update in .js

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-05T22:48:00Z

Een: /* Manage states and events */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML.

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit gomoku.game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit gomoku.game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections (jstpl_intersection).

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit gomoku.js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in gomoku.game.php->getAllDatas() is now available in your gomoku.js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your gomoku.js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your gomoku.game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In gomoku.game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In gomoku.js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Add onclick events on intersections in gomoku.js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding gomoku.js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in gomoku.action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in gomoku.game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in gomoku.js->setupNotifications() and link it to a javascript function to execute when the notification is received.

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like (we will use the red circle later on):

[[File:Gomoku stones.png]]

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game (if any)

Nothing special for Gomoku

Implement rule for computing game progression in .game.php->getGameProgression()

Implement end of game detection and update the score according to who is the winner in .game.php->stCheckEndOfGame()

Notify the score and implement the corresponding interface update in .js

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-05T22:45:13Z

Een: /* Manage states and events */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML.

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit gomoku.game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit gomoku.game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections (jstpl_intersection).

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit gomoku.js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in gomoku.game.php->getAllDatas() is now available in your gomoku.js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your gomoku.js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your gomoku.game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In gomoku.game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In gomoku.js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Add onclick events on intersections in gomoku.js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding gomoku.js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in gomoku.action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in gomoku.game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in gomoku.js->setupNotifications() and link it to a javascript function to execute

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},
</pre>

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

<pre>
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';
</pre>

* to define the css styles for the stones

<pre>
.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }
</pre>

These styles rely on an image of both the white and black stones, and position the background appropriately to show only the part of the background image matching the appropriate stone or the white space if there is no stone. Here is what the image looks like (we will use the red circle later on):

[[File:Gomoku stones.png]]

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game (if any)

Nothing special for Gomoku

Implement rule for computing game progression in .game.php->getGameProgression()

Implement end of game detection and update the score according to who is the winner in .game.php->stCheckEndOfGame()

Notify the score and implement the corresponding interface update in .js

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Fájl:Gomoku stones.png

2012-12-05T22:45:06Z

Een:

Tutorial gomoku

2012-12-05T22:40:51Z

Een: /* Manage states and events */

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).

== You will start from our 'emtpy game' template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some divs for the board in the HTML.

<pre>
<div id="gmk_game_area">
<div id="gmk_background">
<div id="gmk_goban">
</div>
</div>
</div>
</pre>

Edit .css to set the div sizes and positions and show the image of the board as background.

<pre>
#gmk_game_area {
text-align: center;
position: relative;
}

#gmk_background {
width: 620px;
height: 620px;
position: relative;
display: inline-block;
}

#gmk_goban {
background-image: url( '../../img/gomoku/goban.jpg');
width: 620px;
height: 620px;
position: absolute;
}
</pre>

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).

<pre>
CREATE TABLE IF NOT EXISTS `intersection` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`coord_x` tinyint(2) unsigned NOT NULL,
`coord_y` tinyint(2) unsigned NOT NULL,
`stone_color` varchar(8) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Edit gomoku.game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.

<pre>
// Insert (empty) intersections into database
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";
$values = array();
for ($x = 0; $x < 19; $x++) {
for ($y = 0; $y < 19; $y++) {

$values[] = "($x, $y)";
}
}
$sql .= implode( $values, ',' );
self::DbQuery( $sql );
</pre>

Edit gomoku.game.php->getAllDatas() to retrieve the state of the intersections from the database.

<pre>
// Intersections
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";
$result['intersections'] = self::getCollectionFromDb( $sql );
</pre>

Edit .tpl to create a template for intersections (jstpl_intersection).

<pre>
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';
</pre>

Define the styles for the intersection divs

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
}
</pre>

Edit gomoku.js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in gomoku.game.php->getAllDatas() is now available in your gomoku.js->setup() in gamedatas.intersections.

<pre>
// Setup intersections
for( var id in gamedatas.intersections )
{
var intersection = gamedatas.intersections[id];

dojo.place( this.format_block('jstpl_intersection', {
x:intersection.coord_x,
y:intersection.coord_y,
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)
} ), $ ( 'gmk_background' ) );

var x_pix = this.getXPixelCoordinates(intersection.coord_x);
var y_pix = this.getYPixelCoordinates(intersection.coord_y);

this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();

if (intersection.stone_color != null) {
// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );
}
}
</pre>

Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right.

<pre>
.gmk_intersection {
width: 30px;
height: 30px;
position: relative;
background-color: blue;
opacity: 0.3;
}
</pre>

You can declare some constants in material.inc.php and pass them to your gomoku.js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.

* Declare your constants in material.inc.php (this will be automatically included in your gomoku.game.php)

<pre>
$this->gameConstants = array(
"INTERSECTION_WIDTH" => 30,
"INTERSECTION_HEIGHT" => 30,
"INTERSECTION_X_SPACER" => 2.8, // Float
"INTERSECTION_Y_SPACER" => 2.8, // Float
"X_ORIGIN" => 0,
"Y_ORIGIN" => 0,
);
</pre>

* In gomoku.game.php->getAllDatas(), add the constants to the result array

// Constants
$result['constants'] = $this->gameConstants;

* In gomoku.js constructor, define a class variable for constants

// Game constants
this.gameConstants = null;

* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions

getXPixelCoordinates: function( intersection_x )
{
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']);
},

getYPixelCoordinates: function( intersection_y )
{
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']);
},

Here is what you should get:

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php. For gomoku we will use 3 states. One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.

The first state requires an action from the player, so its type is 'activeplayer'.

The two others are automatic actions for the game, so their type is 'game'.

We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

<pre>
2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a stone'),
"descriptionmyturn" => clienttranslate('${you} must play a stone'),
"type" => "activeplayer",
"possibleactions" => array( "playStone" ),
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )
),

3 => array(
"name" => "checkEndOfGame",
"description" => '',
"type" => "game",
"action" => "stCheckEndOfGame",
"updateGameProgression" => true,
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )
),

4 => array(
"name" => "nextPlayer",
"description" => '',
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "" => 2 )
),
</pre>

Add onclick events on intersections in gomoku.js->setup()

// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");

Declare the corresponding gomoku.js->onClickIntersection() function, which calls an action function on the server with appropriate parameters

<pre>
onClickIntersection: function( evt )
{
console.log( '$$$$ Event : onClickIntersection' );
dojo.stopEvent( evt );

if( ! this.checkAction( 'playStone' ) )
{ return; }

var node = evt.currentTarget.id;
var coord_x = node.split('_')[1];
var coord_y = node.split('_')[2];

console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );

if ( this.isCurrentPlayerActive() ) {
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );
}
},
</pre>

Add this action function in gomoku.action.php, retrieving parameters and calling the appropriate game action

<pre>
public function playStone()
{
self::setAjaxMode();

// Retrieve arguments
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method
$coord_x = self::getArg( "coord_x", AT_posint, true );
$coord_y = self::getArg( "coord_y", AT_posint, true );

// Then, call the appropriate method in your game logic, like "playCard" or "myAction"
$this->game->playStone( $coord_x, $coord_y );

self::ajaxResponse( );
}
</pre>

Add game action in gomoku.game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.

<pre>
function playStone( $coord_x, $coord_y )
{
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)
self::checkAction( 'playStone' );

$player_id = self::getActivePlayerId();

// Check that this intersection is free
$sql = "SELECT
id, coord_x, coord_y, stone_color
FROM
intersection
WHERE
coord_x = $coord_x
AND coord_y = $coord_y
AND stone_color is null
";
$intersection = self::getObjectFromDb( $sql );

if ($intersection == null) {
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
}

// Get player color
$sql = "SELECT
player_id, player_color
FROM
player
WHERE
player_id = $player_id
";
$player = self::getNonEmptyObjectFromDb( $sql );
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');

// Update the intersection with a stone of the appropriate color
$intersection_id = $intersection['id'];
$sql = "UPDATE
intersection
SET
stone_color = '$color'
WHERE
id = $intersection_id
";
self::DbQuery($sql);

// Notify all players
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),
'coord_x' => $coord_x,
'coord_y' => $coord_y,
'color' => $color
) );

// Go to next game state
$this->gamestate->nextState( "stonePlayed" );
}
</pre>

Catch the notification in gomoku.js->setupNotifications() and link it to a javascript function to execute

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );
}
</pre>

Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

<pre>
notif_stonePlayed: function( notif )
{
console.log( '**** Notification : stonePlayed' );
console.log( notif );

// Create a stone
dojo.place( this.format_block('jstpl_stone', {
stone_type:'stone_' + notif.args.color,
x:notif.args.coord_x,
y:notif.args.coord_y
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );

// Place it on the player panel
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );

// Animate a slide from the player panel to the intersection
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1000 );
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 'auto' );
}));
slide.play();

// This intersection is taken, it shouldn't appear as clickable anymore
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );
},

For this function to work properly, you also need:

* to declare a stone javascript template in your .tpl file.

var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';

* to define the css styles for the stones

.gmk_stone {
width: 30px;
height: 30px;
position: absolute;
background-image: url( '../../img/gomoku/stones.png');
}

.no_stone { background-position: -60px 0px; }

.stone_black { background-position: 0px 0px; }
.stone_white { background-position: -30px 0px; }

These styles rely on an image of both the white and black stones, and position the background appropriately to show only the part of the background image matching the appropriate stone.

The basic game turn is implemented: you can now drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup your styles ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game conditions ==

Implement specific rules for the game (if any)

Nothing special for Gomoku

Implement rule for computing game progression in .game.php->getGameProgression()

Implement end of game detection and update the score according to who is the winner in .game.php->stCheckEndOfGame()

Notify the score and implement the corresponding interface update in .js

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-05T22:36:37Z

Een: /* Manage states and events */

Tutorial gomoku

2012-12-05T22:21:30Z

Een: /* Setup the backbone of your game */

Tutorial gomoku

2012-12-05T22:20:55Z

Een: /* Setup the backbone of your game */

Tutorial gomoku

2012-12-05T22:18:34Z

Een: /* Setup the backbone of your game */

Tutorial gomoku

2012-12-05T22:13:56Z

Een: /* Setup the backbone of your game */

Tutorial gomoku

2012-12-05T22:13:33Z

Een: /* Setup the backbone of your game */

Tutorial gomoku

2012-12-05T21:58:44Z

Een: /* Setup the board */

Studio FAQ

2012-12-05T21:45:22Z

Een:

Tutorial gomoku

2012-12-05T21:26:20Z

Een: /* Implement rules and end of game condition(s) */

Tutorial gomoku

2012-12-05T21:26:10Z

Een: /* Cleanup */

Tutorial gomoku

2012-12-05T21:25:33Z

Een: /* Start from the emtpy game template */

Tutorial gomoku

2012-12-05T21:24:48Z

Een:

Tutorial gomoku

2012-12-05T21:18:27Z

Een: /* Setup the board */

== Start from the emtpy game template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.

Edit .tpl to add some div for the board in the HTML.

Edit .css to show the image of the board as background.

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit .sql to create a table for intersections.

Edit .game.php->setupNewGame to insert the empty intersections (19x19) with coordinates into the database.

Edit .game.php->getAllDatas to retrieve the state of the intersections from the database.

Edit .tpl to create a template for intersections (jstpl_intersection).

Edit .js to setup the intersections layer that will be used to get click events and to display the stones. Use some temporary css colors on borders or background+opacity to make sure they are positioned right. You can declare some constants in
material.inc.php and pass them to your .js through .game.php->getAllDatas for easy repositioning.

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php

Add onclick events on intersections in .js, calling an action with appropriate parameters

Add action in .action.php, retrieving parameters and calling the appropriate game action

Add game action in .game.php to update the database, then notify the client using a method ‘stonePlayed’

Implement this method in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

The basic game turn is implemented: you can drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game condition(s) ==

Implement specific rules for the game (if any)

Nothing special for Gomoku

Implement rule for computing game progression in .game.php->getGameProgression()

Implement end of game detection and update the score according to who is the winner in .game.php->stCheckEndOfGame()

Notify the score and implement the corresponding interface update in .js

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-05T21:17:54Z

Een:

== Start from the emtpy game template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed.

Edit .tpl to add some div for the board in the HTML.

Edit .css to show the image of the board as background.

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit .sql to create a table for intersections.

Edit .game.php->setupNewGame to insert the empty intersections (19x19) with coordinates into the database.

Edit .game.php->getAllDatas to retrieve the state of the intersections from the database.

Edit .tpl to create a template for intersections (jstpl_intersection).

Edit .js to setup the intersections layer that will be used to get click events and to display the stones. Use some temporary css colors on borders or background+opacity to make sure they are positioned right. You can declare some constants in
material.inc.php and pass them to your .js through .game.php->getAllDatas for easy repositioning.

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php

Add onclick events on intersections in .js, calling an action with appropriate parameters

Add action in .action.php, retrieving parameters and calling the appropriate game action

Add game action in .game.php to update the database, then notify the client using a method ‘stonePlayed’

Implement this method in javascript to update the intersection to show the stone, and register it inside the setNotifications function.

The basic game turn is implemented: you can drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game condition(s) ==

Implement specific rules for the game (if any)

Nothing special for Gomoku

Implement rule for computing game progression in .game.php->getGameProgression()

Implement end of game detection and update the score according to who is the winner in .game.php->stCheckEndOfGame()

Notify the score and implement the corresponding interface update in .js

'''Test everything thoroughly... you are done!'''

[[File:Gomoku tuto6.png]]

Tutorial gomoku

2012-12-05T21:14:15Z

Een: /* Start from the emtpy game template */

== Start from the emtpy game template ==

Here is how your games looks by default when it has just been created :

[[File:Gomoku tuto1.png]]

== Setup the board ==

Gather useful images for the game and edit them as needed.
Edit .tpl & .css to add the board :

[[File:Gomoku tuto2.png]]

== Setup the backbone of your game ==

Edit .sql to create a table for intersections.
Edit .game.php->setupNewGame to insert the empty intersections (19x19) with coordinates into the database.
Edit .game.php->getAllDatas to retrieve the state of the intersections from the database.
Edit .tpl to create a template for intersections (jstpl_intersection).
Edit .js to setup the intersections layer that will be used to get click events and to display the stones. Use some temporary css colors on borders or background+opacity to make sure they are positioned right. You can declare some constants in material.inc.php and pass them to your .js through .game.php->getAllDatas for easy repositioning.

[[File:Gomoku tuto3.png]]

== Manage states and events ==

Define your game states in states.inc.php
Add onclick events on intersections in .js, calling an action with appropriate parameters
Add action in .action.php, retrieving parameters and calling the appropriate game action.
Add game action in .game.php to update the database, then notify the client using a method ‘stonePlayed’
Implement this method in javascript to update the intersection to show the stone, and register it inside the setNotifications function.
The basic game turn is implemented: you can drop some stones!

[[File:Gomoku tuto4.png]]

== Cleanup ==

Remove temporary css visualisation helpers : looks good!

[[File:Gomoku tuto5.png]]

== Implement rules and end of game condition(s) ==

Implement specific rules for the game (if any)
Implement rule for computing game progression in .game.php->getGameProgression()
Implement end of game detection and update the score according to who is the winner in .game.php->stCheckEndOfGame()
Notify the score and implement the corresponding interface update in .js

Test everything thoroughly... you are done!

[[File:Gomoku tuto6.png]]