Players actions: yourgamename.action.php - Revision history

Thoun at 11:15, 5 November 2026

2026-11-05T11:15:11Z

← Older revision		Revision as of 11:15, 5 November 2026
Line 1:		Line 1:
	~~<span style~~=~~"color:red; font-size:20px;">~~'''IMPORTANT NOTE:''' This file is deprecated, you shouldn't need to use it if you use [https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Actions_(autowired) Autowired action]~~</span>~~{{Studio_Framework_Navigation}}		{{InfoBox\|title=Deprecated\|body='''IMPORTANT NOTE:''' This file is deprecated, you shouldn't need to use it if you use [https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Actions_(autowired) Autowired action]}}

			{{Studio_Framework_Navigation}}

	== Purpose of this file ==		== Purpose of this file ==

ShaharHarshuv at 20:13, 5 October 2025

2025-10-05T20:13:34Z

← Older revision		Revision as of 20:13, 5 October 2025
Line 1:		Line 1:
	{{Studio_Framework_Navigation}}		<span style="color:red; font-size:20px;">'''IMPORTANT NOTE:''' This file is deprecated, you shouldn't need to use it if you use [https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Actions_(autowired) Autowired action]</span>{{Studio_Framework_Navigation}}

	== Purpose of this file ==		== Purpose of this file ==
	~~'''IMPORTANT NOTE:''' This file is deprecated, you shouldn't need to use it if you use~~
	~~[https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Actions_(autowired) Autowired action]~~

Thoun at 09:45, 3 April 2025

2025-04-03T09:45:04Z

← Older revision		Revision as of 09:45, 3 April 2025
Line 94:		Line 94:
	$bValid = preg_match("/^[_0-9a-zA-Z- ]*$/", $value) === 1;		$bValid = preg_match("/^[_0-9a-zA-Z- ]*$/", $value) === 1;
	if (!$bValid) {		if (!$bValid) {
	throw new BgaSystemException("Bad value for: $argName", true, true, FEX_bad_input_argument);		throw new \BgaSystemException("Bad value for: $argName", true, true, FEX_bad_input_argument);
	}		}
	return true;		return true;

Thoun: /* Purpose of this file */

2024-09-03T13:42:08Z

Purpose of this file

← Older revision		Revision as of 13:42, 3 September 2024
Line 2:		Line 2:

	== Purpose of this file ==		== Purpose of this file ==
			'''IMPORTANT NOTE:''' This file is deprecated, you shouldn't need to use it if you use
			[https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Actions_(autowired) Autowired action]


	With this file, you define all the player entry points (i.e., possible game actions) for your game.		With this file, you define all the player entry points (i.e., possible game actions) for your game.
Line 11:		Line 14:
	Methods in this file should be short: no game logic must be introduced here.		Methods in this file should be short: no game logic must be introduced here.

	== Example of typical action method ==
			==Example of typical action method==

	(from Reversi example)		(from Reversi example)
Line 26:		Line 30:
	</pre>		</pre>

	== Methods to use in action methods ==		== Methods to use in action methods==

	'''function setAjaxMode()'''		'''function setAjaxMode()'''
Line 44:		Line 48:
	This method uses the following arguments:		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:
	'AT_int' for an integer		'AT_int' for an integer
	'AT_posint' for a positive integer		'AT_posint' for a positive integer
Line 57:		Line 61:
	'AT_json' for a JSON stringified string (SECURITY WARNING**)		'AT_json' for a JSON stringified string (SECURITY WARNING**)

	* 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.
	* argTypeDetails: used with the 'AT_enum'. Validates that the value passed in is in this list.		*argTypeDetails: used with the 'AT_enum'. Validates that the value passed in is in this list.
	* 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).		*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).


Line 66:		Line 70:

	Here is an example of a sanity check for JSON :		Here is an example of a sanity check for JSON :
	~~'''~~
	public function actMyAction()		public function actMyAction()
	{		{
Line 94:		Line 98:
	return true;		return true;
	}		}
	~~'''~~

	'''AT_enum and argTypeDetails Example'''		'''AT_enum and argTypeDetails Example'''
Line 108:		Line 111:
	It returns "true" or "false" according to 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 ";" (example: "1;2;3;4") as an argument, you can transform them into a PHP array with the following:		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:
Line 132:		Line 135:
	</pre>		</pre>

	== Example pass array of Id's ==		==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:		If your Javascript sends a list of object denomated by alphanumerical tokenId, you can use AT_alphanum type and space as array separator:
Line 154:		Line 157:
	</pre>		</pre>

	== Retrieving data from ajax call ==		==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).		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).
Line 160:		Line 163:
	The typical way to implement this is using games states with game state arguments. Eventually, use player notifications.		The typical way to implement this is using games states with game state arguments. Eventually, use player notifications.

	== Game action handler ==		==Game action handler==
	This is a note on what you should be doing and not doing in ggg.game.php action handler vs in action.php action handler		This is a note on what you should be doing and not doing in ggg.game.php action handler vs in action.php action handler

	action.php		action.php
	* action handler in action.php should very simple and it should ONLY extract arguments from ajax call, pass them down to game handler		*action handler in action.php should very simple and it should ONLY extract arguments from ajax call, pass them down to game handler
	* it should not implement any game logic or check for validity beyong the syntax. I.e. DO NOT put checkAction this action.php		*it should not implement any game logic or check for validity beyong the syntax. I.e. DO NOT put checkAction this action.php

	game.php		game.php
	* call checkAction('actMyAction') first		*call checkAction('actMyAction') first
	* check arguments for game validity (i.e. player is not cheating), throw system exceptions if it is (usually this cases where JS side won't be sending it but you still have to check for it)		* check arguments for game validity (i.e. player is not cheating), throw system exceptions if it is (usually this cases where JS side won't be sending it but you still have to check for it)
	* perfom action and update database, can do more check if throw user exception if this is not valid move by the rules		*perfom action and update database, can do more check if throw user exception if this is not valid move by the rules
	* send notifications (must send notification even if empty if not transitioning in new state on some paths)		*send notifications (must send notification even if empty if not transitioning in new state on some paths)
	* transition to new state		*transition to new state

	[[Category:Studio]]		[[Category:Studio]]

Thoun at 12:05, 11 July 2024

2024-07-11T12:05:02Z

← Older revision		Revision as of 12:05, 11 July 2024
Line 16:		Line 16:

	<pre>		<pre>
	public function ~~playDisc~~()		public function actPlayDisc()
	{		{
	$this->setAjaxMode();		$this->setAjaxMode();
	$x = $this->getArg( "x", AT_posint, true );		$x = $this->getArg( "x", AT_posint, true );
	$y = $this->getArg( "y", AT_posint, true );		$y = $this->getArg( "y", AT_posint, true );
	$result = $this->game->~~playDisc~~( $x, $y );		$result = $this->game->actPlayDisc( $x, $y );
	$this->ajaxResponse( );		$this->ajaxResponse( );
	}		}
Line 113:		Line 113:

	<pre>		<pre>
	public function ~~playCards~~()		public function actPlayCards()
	{		{
	$this->setAjaxMode();		$this->setAjaxMode();
Line 127:		Line 127:
	$card_ids = explode( ';', $card_ids_raw );		$card_ids = explode( ';', $card_ids_raw );

	$this->game->~~playCards~~( $card_ids );		$this->game->actPlayCards( $card_ids );
	$this->ajaxResponse( );		$this->ajaxResponse( );
	}		}
Line 138:		Line 138:
	<pre>		<pre>
	// sending 'card_ids' => "card_1 card_23 card_12"		// sending 'card_ids' => "card_1 card_23 card_12"
	public function ~~playCards~~() {		public function actPlayCards() {
	$this->setAjaxMode();		$this->setAjaxMode();

Line 149:		Line 149:
	$card_ids = explode( ' ', $card_ids_raw );		$card_ids = explode( ' ', $card_ids_raw );

	$this->game->~~playCards~~( $card_ids );		$this->game->actPlayCards( $card_ids );
	$this->ajaxResponse( );		$this->ajaxResponse( );
	}		}
Line 168:		Line 168:

	game.php		game.php
	* call checkAction('~~myAction~~') first		* call checkAction('actMyAction') first
	* check arguments for game validity (i.e. player is not cheating), throw system exceptions if it is (usually this cases where JS side won't be sending it but you still have to check for it)		* check arguments for game validity (i.e. player is not cheating), throw system exceptions if it is (usually this cases where JS side won't be sending it but you still have to check for it)
	* perfom action and update database, can do more check if throw user exception if this is not valid move by the rules		* perfom action and update database, can do more check if throw user exception if this is not valid move by the rules

Thoun: remplace self:: by $this->

2024-04-10T12:42:36Z

remplace self:: by $this->

← Older revision		Revision as of 12:42, 10 April 2024
Line 18:		Line 18:
	public function playDisc()		public function playDisc()
	{		{
	~~self::~~setAjaxMode();		$this->setAjaxMode();
	$x = ~~self::~~getArg( "x", AT_posint, true );		$x = $this->getArg( "x", AT_posint, true );
	$y = ~~self::~~getArg( "y", AT_posint, true );		$y = $this->getArg( "y", AT_posint, true );
	$result = $this->game->playDisc( $x, $y );		$result = $this->game->playDisc( $x, $y );
	~~self::~~ajaxResponse( );		$this->ajaxResponse( );
	}		}
	</pre>		</pre>
Line 69:		Line 69:
	public function actMyAction()		public function actMyAction()
	{		{
	~~self::~~setAjaxMode();		$this->setAjaxMode();
	$args = ~~self::~~getArg('actionArgs', AT_json, true);		$args = $this->getArg('actionArgs', AT_json, true);
	$this->validateJSonAlphaNum($args, 'actionArgs');		$this->validateJSonAlphaNum($args, 'actionArgs');
	$this->game->actMyAction($args);		$this->game->actMyAction($args);
	~~self::~~ajaxResponse();		$this->ajaxResponse();
	}		}

Line 100:		Line 100:
	Validates that the value of 'myarg' is either 'apple', 'orange', or 'banana'		Validates that the value of 'myarg' is either 'apple', 'orange', or 'banana'

	$myarg = ~~self::~~getArg( 'myarg', AT_enum, false, null, [ 'apple', 'orange', 'banana' ] ); // optional enum		$myarg = $this->getArg( 'myarg', AT_enum, false, null, [ 'apple', 'orange', 'banana' ] ); // optional enum

	'''function isArg( $argName )'''		'''function isArg( $argName )'''
Line 115:		Line 115:
	public function playCards()		public function playCards()
	{		{
	~~self::~~setAjaxMode();		$this->setAjaxMode();

	$card_ids_raw = ~~self::~~getArg( "card_ids", AT_numberlist, true );		$card_ids_raw = $this->getArg( "card_ids", AT_numberlist, true );

	// Removing last ';' if exists		// Removing last ';' if exists
Line 128:		Line 128:

	$this->game->playCards( $card_ids );		$this->game->playCards( $card_ids );
	~~self::~~ajaxResponse( );		$this->ajaxResponse( );
	}		}
	</pre>		</pre>
Line 139:		Line 139:
	// sending 'card_ids' => "card_1 card_23 card_12"		// sending 'card_ids' => "card_1 card_23 card_12"
	public function playCards() {		public function playCards() {
	~~self::~~setAjaxMode();		$this->setAjaxMode();

	$card_ids_raw = ~~self::~~getArg( "card_ids", AT_alphanum, true );		$card_ids_raw = $this->getArg( "card_ids", AT_alphanum, true );
	$card_ids_raw = trim($card_ids_raw);		$card_ids_raw = trim($card_ids_raw);

Line 150:		Line 150:

	$this->game->playCards( $card_ids );		$this->game->playCards( $card_ids );
	~~self::~~ajaxResponse( );		$this->ajaxResponse( );
	}		}
	</pre>		</pre>

Victoria La: /* Game action handler */

2023-05-31T21:56:35Z

Game action handler

← Older revision		Revision as of 21:56, 31 May 2023
Line 161:		Line 161:

	== Game action handler ==		== Game action handler ==
	This is note on what you should be doing and not doing ggg.game.php action handler vs action.php handler		This is a note on what you should be doing and not doing in ggg.game.php action handler vs in action.php action handler

	action.php		action.php
Line 171:		Line 171:
	* check arguments for game validity (i.e. player is not cheating), throw system exceptions if it is (usually this cases where JS side won't be sending it but you still have to check for it)		* check arguments for game validity (i.e. player is not cheating), throw system exceptions if it is (usually this cases where JS side won't be sending it but you still have to check for it)
	* perfom action and update database, can do more check if throw user exception if this is not valid move by the rules		* perfom action and update database, can do more check if throw user exception if this is not valid move by the rules
	* send notifications		* send notifications (must send notification even if empty if not transitioning in new state on some paths)
	* transition to new state		* transition to new state

	[[Category:Studio]]		[[Category:Studio]]

Victoria La at 23:12, 16 May 2022

2022-05-16T23:12:40Z

← Older revision		Revision as of 23:12, 16 May 2022
Line 173:		Line 173:
	* send notifications		* send notifications
	* transition to new state		* transition to new state

			[[Category:Studio]]

Bennygui at 20:10, 8 April 2022

2022-04-08T20:10:27Z

← Older revision		Revision as of 20:10, 8 April 2022
Line 90:		Line 90:
	$bValid = preg_match("/^[_0-9a-zA-Z- ]*$/", $value) === 1;		$bValid = preg_match("/^[_0-9a-zA-Z- ]*$/", $value) === 1;
	if (!$bValid) {		if (!$bValid) {
	throw new ~~feException~~("Bad value for: $argName", true, true, FEX_bad_input_argument);		throw new BgaSystemException("Bad value for: $argName", true, true, FEX_bad_input_argument);
	}		}
	return true;		return true;

JoeProgram: there were now two examples of AT_enum - reduced it to 1

2022-02-05T16:17:13Z

there were now two examples of AT_enum - reduced it to 1

← Older revision		Revision as of 16:17, 5 February 2022
Line 61:		Line 61:
	* argTypeDetails: used with the 'AT_enum'. Validates that the value passed in is in this list.		* argTypeDetails: used with the 'AT_enum'. Validates that the value passed in is in this list.
	* 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).		* 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).

	~~'''AT_enum and argTypeDetails Example'''~~

	~~Validates that the value of 'myarg' is either 'apple', 'orange', or 'banana'~~
	~~'''~~
	~~self::getArg( 'myarg', AT_enum, false, null, array( 'apple', 'orange', 'banana' ) );~~
	~~'''~~


Line 103:		Line 96:
	'''		'''

	Example:		'''AT_enum and argTypeDetails Example'''

			Validates that the value of 'myarg' is either 'apple', 'orange', or 'banana'

	$myarg = self::getArg( 'myarg', AT_enum, false, null, [ 'apple', 'orange', 'banana' ] ); // optional enum		$myarg = self::getArg( 'myarg', AT_enum, false, null, [ 'apple', 'orange', 'banana' ] ); // optional enum