This is a documentation for Board Game Arena: play board games online !

„Players actions: yourgamename.action.php” változatai közötti eltérés

Innen: Board Game Arena
Ugrás a navigációhoz Ugrás a kereséshez
(Created page with "=== APP_GameAction class (<gamename>.action.php) === ; function isArg( $argName ) : Is this argument filled ? ; function getArg( $argName, $argType, $mandatory=false, $defaul...")
 
 
(3 közbenső módosítás ugyanattól a szerkesztőtől nincs mutatva)
1. sor: 1. sor:
=== APP_GameAction class (<gamename>.action.php) ===
 
  
; function isArg( $argName )
+
== Purpose of this file ==
: Is this argument filled ?
+
 
; function getArg( $argName, $argType, $mandatory=false, $default=NULL, $argTypeDetails=array(), $bCanFail=false  )
+
With this file, you define all the players entry points (ie: possible game actions) of your game.
: Get script argument with the correct type
+
 
: bCanFail means than a validation failure is possible (user input)
+
This file is a sort of "bridge" between the AJAX calls you are doing from your Javascript client side, and your main PHP code in "yourgame.game.php".
: The main argType values are as follows.
+
 
 +
The role of the methods defined in this file is to filter the arguments, eventually to format them a little bit, and then to call a corresponding PHP method from your main game logic ("yourgame.game.php" file).
 +
 
 +
Methods in this file must be short: no game logic must be introduced here.
 +
 
 +
== Example of typical action method ==
 +
 
 +
(from Reversi example)
 +
 
 +
<pre>
 +
    public function playDisc()
 +
    {
 +
        self::setAjaxMode();   
 +
        $x = self::getArg( "x", AT_posint, true );
 +
        $y = self::getArg( "y", AT_posint, true );
 +
        $result = $this->game->playDisc( $x, $y );
 +
        self::ajaxResponse( );
 +
    }
 +
</pre>
 +
 
 +
== Methods to use in action methods ==
 +
 
 +
'''function setAjaxMode'''
 +
 
 +
Must be use at the beginning of each action method.
 +
 
 +
'''function ajaxResponse'''
 +
 
 +
Must be use at the end of each action method.
 +
 
 +
'''function getArg( $argName, $argType, $mandatory=false, $default=NULL, $argTypeDetails=array(), $bCanFail=false  )'''
 +
 
 +
This method must be used to retrieve the arguments sent with your AJAX query.
 +
You must NOT use "_GET", "_POST" or equivalent PHP variables to do this, as it is unsafe.
 +
This method use the following arguments:
 +
* argName: the name of the argument to retrieve.
 +
* argType: the type of the argument. You should use one of the following:
 +
  'AT_int' for an integer
 +
  'AT_posint' for a positive integer
 +
  'AT_float' for a float
 +
  'AT_bool' for 1/0/true/false
 +
  'AT_enum' for an enumeration (argTypeDetails list the possible values as an array)
 +
  'AT_alphanum' for a string with 0-9a-zA-Z_ and space
 +
  'AT_numberlist' for a list of several numbers separated with "," or ";" (ex: exemple: 1,4;2,3;-1,2).
 +
* mandatory: specify "true" if the argument is mandatory.
 +
* default: if mandatory=false, you can specify here a default value in case the argument is not present.
 +
* argTypeDetails: see AT_enum above.
 +
* bCanFail: if true, specify that it may be possible that the argument won't be of the type specified by argType (and then do not log this as a fatal error in the system, and return a standard exception to the player).
 +
 
 +
 
 +
'''function isArg( $argName )'''
 +
 
 +
This is a useful method when you only want to check if an argument is present or not present in your AJAX request (and don't care of the value.
 +
 
 +
It returns "true" or "false" whether "argName" has been specified as an argument of the AJAX request or not.
 +
 
 +
== Useful tip: retrieve a list of number ==
 +
 
 +
If your Javascript send a list of integer separated by ";" (ex: "1;2;3;4") as an argument, you can transform them in a PHP array with the following:
 +
 
 
<pre>
 
<pre>
define( 'AT_int', 0 );        //  an integer
+
    public function playCards()
define( 'AT_posint', 1 );    //  a positive integer
+
    {
define( 'AT_float', 2 );     // a float
+
        self::setAjaxMode();     
define( 'AT_email', 3 );     //  an email 
+
 
define( 'AT_url', 4 );       //  a URL
+
        $card_ids_raw = self::getArg( "card_ids", AT_numberlist, true );
define( 'AT_bool', 5 );       //  1/0/true/false
+
       
define( 'AT_enum', 6 );       //  argTypeDetails list the possible values
+
        // Removing last ';' if exists
define( 'AT_alphanum', 7 );   //  only 0-9a-zA-Z_ and space
+
        if( substr( $card_ids_raw, -1 ) == ';' )
 +
            $card_ids_raw = substr( $card_ids_raw, 0, -1 );
 +
        if( $card_ids_raw == '' )
 +
            $card_ids = array();
 +
        else
 +
            $card_ids = explode( ';', $card_ids_raw );
 +
 
 +
        $this->game->playCards( $card_ids );
 +
        self::ajaxResponse( );
 +
    }
 
</pre>
 
</pre>

A lap jelenlegi, 2013. január 11., 16:07-kori változata

Purpose of this file

With this file, you define all the players entry points (ie: possible game actions) of your game.

This file is a sort of "bridge" between the AJAX calls you are doing from your Javascript client side, and your main PHP code in "yourgame.game.php".

The role of the methods defined in this file is to filter the arguments, eventually to format them a little bit, and then to call a corresponding PHP method from your main game logic ("yourgame.game.php" file).

Methods in this file must be short: no game logic must be introduced here.

Example of typical action method

(from Reversi example)

    public function playDisc()
    {
        self::setAjaxMode();     
        $x = self::getArg( "x", AT_posint, true );
        $y = self::getArg( "y", AT_posint, true );
        $result = $this->game->playDisc( $x, $y );
        self::ajaxResponse( );
    }

Methods to use in action methods

function setAjaxMode

Must be use at the beginning of each action method.

function ajaxResponse

Must be use at the end of each action method.

function getArg( $argName, $argType, $mandatory=false, $default=NULL, $argTypeDetails=array(), $bCanFail=false )

This method must be used to retrieve the arguments sent with your AJAX query. You must NOT use "_GET", "_POST" or equivalent PHP variables to do this, as it is unsafe. This method use the following arguments:

  • argName: the name of the argument to retrieve.
  • argType: the type of the argument. You should use one of the following:
 'AT_int' for an integer
 'AT_posint' for a positive integer 
 'AT_float' for a float
 'AT_bool' for 1/0/true/false
 'AT_enum' for an enumeration (argTypeDetails list the possible values as an array)
 'AT_alphanum' for a string with 0-9a-zA-Z_ and space
 'AT_numberlist' for a list of several numbers separated with "," or ";" (ex: exemple: 1,4;2,3;-1,2).
  • mandatory: specify "true" if the argument is mandatory.
  • default: if mandatory=false, you can specify here a default value in case the argument is not present.
  • argTypeDetails: see AT_enum above.
  • bCanFail: if true, specify that it may be possible that the argument won't be of the type specified by argType (and then do not log this as a fatal error in the system, and return a standard exception to the player).


function isArg( $argName )

This is a useful method when you only want to check if an argument is present or not present in your AJAX request (and don't care of the value.

It returns "true" or "false" whether "argName" has been specified as an argument of the AJAX request or not.

Useful tip: retrieve a list of number

If your Javascript send a list of integer separated by ";" (ex: "1;2;3;4") as an argument, you can transform them in a PHP array with the following:

    public function playCards()
    {
        self::setAjaxMode();     

        $card_ids_raw = self::getArg( "card_ids", AT_numberlist, true );
        
        // Removing last ';' if exists
        if( substr( $card_ids_raw, -1 ) == ';' )
            $card_ids_raw = substr( $card_ids_raw, 0, -1 );
        if( $card_ids_raw == '' )
            $card_ids = array();
        else
            $card_ids = explode( ';', $card_ids_raw );

        $this->game->playCards( $card_ids );
        self::ajaxResponse( );
    }