SandboxScripts

This is the reference of functions you can call from your Sandbox scripts.

Javascript

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed on server side.

BGA API

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

Quick start

Hello World Script

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
   bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

Top useful tips

• You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

• Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

• We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

• This is not mandatory to script the full game! You can start by automate most painful game actions first, publish the game, and then continue later :)

Functions you can use in your Sandbox scripts

Debugging functions

bga.trace( txt / obj )

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

 // Example : write "Hello world" in the log
 bga.trace( "Hello world" );

 // Example : dump an associative array in the log
 bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

bga.exit( txt / obj )

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

 // Example :
 bga.exit( "My script is stopped by this call" );

 // Example with dumping a javascript variable
 bga.exit( my_variable_to_dump );

Cancelling a game action

bga.cancel( txt )

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

  // Example :
  bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

bga.error( text )

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

  // Example :
  if( card_picked === null )
  {
      bga.error( "Cannot find a card to pick !" );
  }

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

Game log (history)

bga.log( txt, (optional) args )

Write something in the BGA log on the right.

 // Example : simple log
 bga.log( _("A new round starts") );

You may add arguments to your log, like this :

 // Example: log with argument to display a card name.
 //          In this example, variable "event_name" is specified afterwards.
 //          Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
 bga.log( _("Event ${event_name} is triggered"), {  event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

 // Example :
 bga.log( _("${player_name} draw a card from the deck") );

bga.getElement( selector, (optionnal) fields )

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

 // Basic example :
 
 // Retrieve the ID of a game element using its name ("Deck")
 var deck_id = bga.getElement( { name: "Deck" } );
 // Return : 1234  

 // Examples using "field" parameter :
 
 // Retrieve a specific property from a game element using its name ("Deck")
 var deck_id = bga.getElement( { name: "Deck" }, 'x' );
 // Return : 20
 
 // Retrieve several properties from the previous element
 var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
 // Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }
 
 // Note : as you can see, getElement returns:
 //        _ the element ID by default, or
 //        _ a single value if you request a single field, or
 //        _ an object if you request several fields

 // Examples using different "selector" paramter
 
 // Retrieve an element name from its id
 var deck_name = bga.getElement( { id: 1234 }, ['name'] );
 // Return : "Deck"

 // Retrieve the last child element of another element
 // Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
 // Note the use of "limit:1" which allows us to retrieve only 1 element.
 var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );
 //

bga.getElementById( id )

Get an object with all the properties of the element with specified ID.

Throw an exception if the element does not exists.

bga.getElementsByIds( ids )

Get all specified elements with an array of ids.

Return an associative array (element_id => element).

bga.getElementsByParent( parent_id )

Get all children (ie : all elements contained) of the specified element_id.

Ex : if you call getElementsByParent on a deck of cards, you'll get all cards.

 // Example : Get all cards of a deck with name "mydeck"
 var cards = bga.getElementsByParent( bga.getElementByName( 'mydeck' ) );

bga.getElementIdByName( name )

Get the ID of a Sandbox element from its name.

Return null if there are no element with this name. Throw an exception if there are more than 1 element with this name.

 // Example :
 var chess_square = bga.getElementIdByName( 'h3' );

bga.getElementsIdsByName( name )

Get the IDs of all Sandbox elements with this name.

 // Example :
 var pawn_pieces_ids = bga.getElementsIdByName( 'pawn' );
 
 // Result : [ 41, 42, 43, ... ]

Utility methods

bga.isOn( element_id, parent_id )

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

 // Example :
 if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
 {
    // Trigger game end
 }

Trigger most common game actions

moveElement( element_id, target_id )

Move element to specified target id.

The exact destination of element depends on target "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

 // Example :
 bga.moveElement( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

Other functions

pause( milliseconds )

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

 // Example :
 bga.log( "1" );    // Will be displayed immediately on the log
 bga.pause( 3000 ); // pause during 3 seconds
 bga.log( "2" );    // Will be displayed after the 3 second on the log
 bga.log( "3" );    // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.