|
|
| (46 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
|
| |
|
| 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).
| |
|
| |
| = Sandbox Scripts Hello World =
| |
|
| |
| 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!
| |
|
| |
| = Functions you can use in your Sandbox scripts=
| |
|
| |
| == Debugging functions ==
| |
|
| |
| === bga.trace( txt ) ===
| |
|
| |
| Write something immediately in the BGA log (on the right of the screen).
| |
|
| |
| This is the most practical way to debug your script :)
| |
|
| |
| Note : you can also pass an object in parameter. This will dump the content of this object in the log.
| |
|
| |
|
| |
| // 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 ) ===
| |
|
| |
| Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :
| |
|
| |
| Again : ALL 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" );
| |
|
| |
| == 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") );
| |
|
| |
| == Get / search game elements and their properties ==
| |
|
| |
|
| |
| === 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' ) );
| |