this.bga.actions

Actions

this.bga.actions.performAction(action: string, args?: object, options: { lock: boolean, checkAction: boolean, checkPossibleActions?: boolean, ignoreDefaultErrorHandler?: boolean }): Promise\<void>

Triggers an asynchronous action call in the PHP backend. See which actions and arguments are available in the Main_game_logic:_Game.php#Actions_(autowired) documentation.

This method must be used to send a player's input to the game server. It should not be triggered programmatically, especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break game replay and tutorial features. It should be used only in reaction to a user action in the interface.

Parameters:

• action: name of the action, as it is written in "possibleactions" of the current state.
• args: an object containing the call parameters to send to the action, which can be undefined or omitted if the action has no parameters. Note: the following argument names are forbidden: $args / $activePlayerId / $active_player_id / $currentPlayerId / $current_player_id / $activePlayerNo/ $active_player_no / $currentPlayerNo / $current_player_no to avoid interfering with magic params.
• options: options to tweak the call with some defaults. The default is { lock: true, checkAction: true }.
• lock: (true by default) locks the user interface before any other action can be executed, which prevents the user from clicking on more buttons while this action is in progress. Set to false if you want to handle locking yourself.
• checkAction: (true by default) checks that the action specified by the "action" parameter is in the list of possible actions and that the user is active. Only set this to false in rare cases when special out-of-turn actions are allowed.
• checkPossibleActions: (false by default) checks that the action specified by the "action" parameter is in the list of possible actions.

Important: this is an asynchronous action, so you should not do anything after this line of code except return. If you want to do something after the call is resolved, use the promise handlers catch and then. See the examples below.

Example of a standard call without args:

 this.bga.actions.performAction('pass');

Example of a standard call with action args:

 this.bga.actions.performAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking the action (because the player is inactive in a multiactive state):

 this.bga.actions.performAction('actChangeMind', {}, { checkAction: false, checkPossibleActions: true });

Example of a call without locking (because of a special action not directly related to the game flow):

 this.bga.actions.performAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of a call with an array of IDs (to be used with #[IntArrayParam]):

 this.bga.actions.performAction('actPlayCards', { ids: this.selectedCardIds });

Example of a call with a JSON object (to be used with #[JsonParam], note the "stringify"):

 this.bga.actions.performAction('actPlanComplexStuff', { answer: JSON.stringify(this.theJsonObject) });

Example of a call that handles an exception:

 this.bga.actions.performAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of a call that handles success:

 this.bga.actions.performAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

this.bga.actions.checkAction(action: string, nomessage?: boolean): boolean

Check whether the player can do the specified action by taking the following into account:

• if the interface is locked, it will return false and show the message "An action is already in progress", unless nomessage is set to true.
• if the player is not active, it will return false and show the message "This is not your turn", unless nomessage is set to true.
• if the action is not in the list of possible actions (defined by "possibleaction" in the current game state), it will return false and show the "This move is not authorized now" error (unconditionally).
• otherwise, it returns true.

Example:

  function onClickOnGameElement( evt )  {
     if( this.bga.actions.checkAction( "actMyAction" ) ) {
        // Do the action
     }
  }

this.bga.actions.checkPossibleActions(action: string): boolean

• this is independent of the player being active, so it can be used instead of this.bga.actions.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.bga.actions.checkAction, this function does NOT take interface locking into account.

• if the action is not in the list of possible actions (defined by "possibleaction" in the current game state), it will return false and show the "This move is not authorized now" error (unconditionally).

• otherwise, it returns true.

 function onChangeMyMind( evt )  {
    if( this.bga.actions.checkPossibleActions( "actMyAction" ) ) {
       // Do the action
    }
 }