This is a documentation for Board Game Arena: play board games online !
Players actions: yourgamename.action.php: Розніца паміж версіямі
Victoria La (размовы | уклад) |
|||
(Не паказана 6 прамежкавых версій 5 удзельнікаў) | |||
Радок 1: | Радок 1: | ||
{{Studio_Framework_Navigation}} | |||
== Purpose of this file == | == Purpose of this file == | ||
Радок 27: | Радок 28: | ||
== Methods to use in action methods == | == Methods to use in action methods == | ||
'''function setAjaxMode''' | '''function setAjaxMode()''' | ||
Must be | Must be used at the beginning of each action method. | ||
'''function ajaxResponse''' | '''function ajaxResponse()''' | ||
Must be | Must be used at the end of each action method. | ||
'''function getArg( $argName, $argType, $mandatory=false, $default=NULL, $argTypeDetails=array(), $bCanFail=false )''' | '''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. | This method must be used to retrieve the arguments sent with your AJAX query. | ||
You must | |||
This method | You must ''not'' use "_GET", "_POST" or equivalent PHP variables to do this, as it is unsafe. | ||
This method uses the following arguments: | |||
* argName: the name of the argument to retrieve. | * argName: the name of the argument to retrieve. | ||
* argType: the type of the argument. You should use one of the following: | * argType: the type of the argument. You should use one of the following: | ||
Радок 46: | Радок 50: | ||
'AT_float' for a float | 'AT_float' for a float | ||
'AT_bool' for 1/0/true/false | 'AT_bool' for 1/0/true/false | ||
'AT_enum' for an enumeration (argTypeDetails | 'AT_enum' for an enumeration (argTypeDetails lists the possible values as an array) | ||
'AT_alphanum' for a string with 0-9a-zA-Z_ and space | 'AT_alphanum' for a string with 0-9a-zA-Z_ and space | ||
'AT_numberlist' for a list of | 'AT_numberlist' for a list of numbers separated with "," or ";" (example: 1,4;2,3;-1,2). | ||
'AT_base64' for a base64-encoded string. | |||
* mandatory: specify "true" if the argument is mandatory. | * 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. | * default: if mandatory=false, you can specify here a default value in case the argument is not present. | ||
Радок 57: | Радок 62: | ||
'''function isArg( $argName )''' | '''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 | 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 about the value). | ||
It returns "true" or "false" whether "argName" has been specified as an argument of the AJAX request or not. | It returns "true" or "false" according to whether "argName" has been specified as an argument of the AJAX request or not. | ||
== Useful tip: retrieve a list of numbers == | == Useful tip: retrieve a list of numbers == | ||
If your Javascript sends a list of integers separated by ";" ( | If your Javascript sends a list of integers separated by ";" (example: "1;2;3;4") as an argument, you can transform them into a PHP array with the following: | ||
<pre> | <pre> | ||
Радок 84: | Радок 89: | ||
} | } | ||
</pre> | </pre> | ||
== Example pass array of Id's == | |||
If your Javascript sends a list of object denomated by alphanumerical tokenId, you can use AT_alphanum type and space as array separator: | |||
<pre> | |||
// sending 'card_ids' => "card_1 card_23 card_12" | |||
public function playCards() { | |||
self::setAjaxMode(); | |||
$card_ids_raw = self::getArg( "card_ids", AT_alphanum, true ); | |||
$card_ids_raw = trim($card_ids_raw); | |||
if( $card_ids_raw == '' ) | |||
$card_ids = array(); | |||
else | |||
$card_ids = explode( ' ', $card_ids_raw ); | |||
$this->game->playCards( $card_ids ); | |||
self::ajaxResponse( ); | |||
} | |||
</pre> | |||
== Retrieving data from ajax call == | |||
Note that this is not possible to return any result from a player action: it should return nothing (action went fine) or an exception (action unsuccessful). | |||
The typical way to implement this is using games states with game state arguments. Eventually, use player notifications. |
Актуальная версія на 01:17, 17 жніўня 2020
- Main game logic: yourgamename.game.php
- Your game state machine: states.inc.php
- Game database model: dbmodel.sql
- Players actions: yourgamename.action.php
- Game material description: material.inc.php
- Game statistics: stats.inc.php
- Game interface logic: yourgamename.js
- Game art: img directory
- Game interface stylesheet: yourgamename.css
- Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl
- Your game mobile version
- Translations (how to make your game translatable)
- Game options and preferences: gameoptions.inc.php
- Game meta-information: gameinfos.inc.php
- Game replay
- 3D
- Some usual board game elements image ressources
- Deck: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
- Counter: a JS component to manage a counter that can increase/decrease (ex: player's score).
- Scrollmap: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
- Stock: a JS component to manage and display a set of game elements displayed at a position.
- Zone: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).
Undocumented component (if somebody knows please help with docs)
- Draggable: a JS component to manage drag'n'drop actions.
- ExpandableSection: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
- Wrapper: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.
- BGA game Lifecycle
- First steps with BGA Studio
- Tutorial reversi
- Tutorial gomoku
- Tutorial hearts
- Create a game in BGA Studio: Complete Walkthrough
- Tools and tips of BGA Studio - Tips and instructions on setting up development environment
- Practical debugging - Tips focused on debugging
- Studio logs - Instructions for log access
- BGA Studio Cookbook - Tips and instructions on using API's, libraries and frameworks
- BGA Studio Guidelines
- Troubleshooting - Most common "I am really stuck" situations
- Studio FAQ
- Pre-release checklist - Go throught this list if you think you done development
- Post-release phase
- BGA Code Sharing - Shared resources, projects on git hub, common code, other links
Purpose of this file
With this file, you define all the player entry points (i.e., possible game actions) for your game.
This file is a sort of "bridge" between the AJAX calls you perform from the 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, format them a bit, and then call a corresponding PHP method from your main game logic ("yourgame.game.php" file).
Methods in this file should 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 used at the beginning of each action method.
function ajaxResponse()
Must be used 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 uses 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 lists the possible values as an array) 'AT_alphanum' for a string with 0-9a-zA-Z_ and space 'AT_numberlist' for a list of numbers separated with "," or ";" (example: 1,4;2,3;-1,2). 'AT_base64' for a base64-encoded string.
- 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 about the value).
It returns "true" or "false" according to whether "argName" has been specified as an argument of the AJAX request or not.
Useful tip: retrieve a list of numbers
If your Javascript sends a list of integers separated by ";" (example: "1;2;3;4") as an argument, you can transform them into 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( ); }
Example pass array of Id's
If your Javascript sends a list of object denomated by alphanumerical tokenId, you can use AT_alphanum type and space as array separator:
// sending 'card_ids' => "card_1 card_23 card_12" public function playCards() { self::setAjaxMode(); $card_ids_raw = self::getArg( "card_ids", AT_alphanum, true ); $card_ids_raw = trim($card_ids_raw); if( $card_ids_raw == '' ) $card_ids = array(); else $card_ids = explode( ' ', $card_ids_raw ); $this->game->playCards( $card_ids ); self::ajaxResponse( ); }
Retrieving data from ajax call
Note that this is not possible to return any result from a player action: it should return nothing (action went fine) or an exception (action unsuccessful).
The typical way to implement this is using games states with game state arguments. Eventually, use player notifications.