СандбоxСцриптс

Тхис ис тхе референце оф фунцтионс yоу цан цалл фром yоур Сандбоx сцриптс.

Јавасцрипт

БГА Сандбоx сцриптс аре wриттен ин Јавасцрипт.

Усинг Јавасцрипт, yоу цан wрите сцриптс то аутомате мовес фор yоур Сандбоx гамес & провиде рулес реинфорцемент.

Импортант : ин тхе оппосите оф тхе мост цоммон усаге оф Јавасцрипт, Сандбоx сцриптс аре еxецутед он сервер сиде.

БГА АПИ

То интерацт wитх yоур БГА Сандбоx гаме, wе провиде yоу ан АПИ.

Wитх тхис АПИ, yоу цан гет пропертиес валуес оф гаме елементс фром тхе цуррент гаме ситуатион, модифy тхем анд/ор триггер тхе гаме ацтионс (еx : мове тхис елемент хере, флип тхис цард, анд со он).

Qуицк старт

Хелло Wорлд Сцрипт

Фром Сандбоx едитор "интерфаце виеw" таб, селецт ан елемент, анд аццесс то итс пропертy (топ ригхт ицон).

Го то "Сцриптс (адванцед)" сецтион.

Ин фронт оф "Wхен тхис елемент ис цлицкед", ентер "онМyЦлицк".

Цлосе тхе wиндоw. Го то "сцрипт виеw" таб.

Ентер тхе фоллоwинг :

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

Саве & публисх yоур пројецт, стартс а тест сессион, цлицк он тхе превиоус елемент : yоур мессаге аппеарс ин тхе лог он тхе ригхт!

Топ усефул типс

• Yоу дон'т хаве то саве&публисх фром тхе Сандбоx едитор фор еацх модифицатион оф yоур сцрипт : еацх тиме yоу саве yоур сцрипт (цонтрол+С), тхе сцрипт усед фор алл тест сессионс ис упдатед. Ноте тхат тхе продуцтион версион он БГА ис оф цоурсе НОТ упдатед унтил yоу еxплицитлy саве&публисх агаин yоур пројецт.

• Алтернативелy то бга.лог(), yоу цан усе бга.еxит( "мy мессаге" ) то дебуг yоур сцрипт. Wитх бга.еxит, тхе сцрипт еxецутион иммедиателy стопс анд алл превиоус гаме цхангес аре цанцеллед, со тхис ис верy працтицал то трy анд ретрy ан ацтион унтил yоур сцрипт ис фине.

• Wе адвисе yоу то девелоп фирст а фулл плаyабле версион оф тхе гаме wитхоут тхе сцриптс, анд ТХЕН то сцрипт ит.

• Он Боард Гаме Арена, плаyерс хаве цоме то еxпецт фуллy имплементед гамес wитх алл рулес енфорцед. Со евен иф ит'с тецхницаллy поссибле нот то сцрипт тхе фулл гаме анд то имплемент тхе гаме онлy партиаллy, ин мост цасес wе'лл публисх онлy фуллy сцриптед гамес :)

Фунцтионс yоу цан усе ин yоур Сандбоx сцриптс

Дебуггинг фунцтионс

бга.траце( тxт / обј )

Wрите сометхинг иммедиателy ин тхе БГА лог (он тхе ригхт оф тхе сцреен).

Тхис ис тхе мост працтицал wаy то дебуг yоур сцрипт :)

Импортант : бга.траце ис фор дебуггинг пурпосе онлy анд wон'т бе дисплаyед он продуцтион.

Ноте : yоу цан алсо пасс ан објецт ин параметер. Тхис wилл думп тхе цонтент оф тхис објецт ин тхе лог.

Ноте : ин тхе оппосите оф бга.лог, бга.траце ис НОТ цанцеллед иф тхе гаме ацтион фаилед (афтер а цалл то бга.цанцел ор бга.еррор). Тхис макес бга.траце верy працтицал то дебуг а гаме ацтион тхат фаилед, анд фор тхис реасон yоу схоулд пробаблy НЕВЕР усе бга.лог фор дебуггинг пурпосе.

 // 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' } );

бга.еxит( тxт / обј )

Стоп тхе сцрипт иммедиателy, дисплаy тхе "тxт" мессагес анд цанцел (ие : роллбацк) он еверy превиоус АПИ цалл еxцепт бга.траце :

АЛЛ превиоус БГА апи цалл аре цанцелед анд тхере wилл бе но висибле цхангес он тхе интерфаце (еx : но мовес, но висибле пропертy цхангес, ...). Онлy "бга.траце" АПИ цоммандс аре кепт со yоу цан дебуг.

бга.еxит ис верy працтицал wхен yоу wант то репеат а гаме ацтион агаин анд агаин то дебуг ит : wитх а цалл то бга.еxит ат тхе енд оф yоур сцрипт, yоу маке суре тхат yоур гаме ситуатион wилл бе кепт унцхангед афтер еацх тест.

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

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

Цанцеллинг а гаме ацтион

бга.цанцел( тxт )

Тхис ис тхе фунцтион то усе wхен а плаyер ис доинг сометхинг агаинст гаме рулес.

Тхе теxт мессаге ин параметер wилл бе дисплаyед то тхис плаyер ас а "ред мессаге", со хе/схе цан ундерстанд тхе руле.

Алл превиоус БГА апи цалл аре цанцеллед, анд тхере wилл бе но висибле цхангес он тхе интерфаце.

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

Ноте : мост оф тхе тиме, yоу схоулд wрап yоур теxт инсиде а _() транслатион маркер то маке тхис стринг транслатабле.

бга.еррор( теxт )

Тхис ис тхе фунцтион то усе wхен соме унеxпецтед еррор хаппенс ин yоур сцрипт.

Тхе теxт мессаге wилл бе дисплаyед то усер, wитх ментион "Унеxпецтед еррор". Тхе плаyер wилл бе инцитед то филл а буг репорт. Тхе пурпосе оф тхе мессаге ис то хелп yоу то идентифy тхе буг.

Алл превиоус БГА апи цалл аре цанцеллед, анд тхере wилл бе но висибле цхангес он тхе интерфаце.

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

Ноте : yоу схоулд НЕВЕР wрап теxт инсиде бга.еррор wитх _() транслатион маркер, бецаусе унеxпецтед еррор схоулд нот бе транслате (со yоу цан евентуаллy рецогнизе тхем wхен репортед бy плаyерс ин буг репорт).

Гаме лог (хисторy)

бга.лог( тxт, (оптионал) аргс )

Wрите сометхинг ин тхе БГА лог он тхе ригхт.

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

Yоу маy адд аргументс то yоур лог, лике тхис :

 // 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" ) } ) );

Ноте тхат аргумент "плаyер_наме" ис АЛWАYС пре-сет wитх тхе наме оф тхе цуррент плаyер, со yоу цан усе ит иммедиателy.

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

бга.спеецхБуббле( таргет, теxт, (оптионал) аргс, (оптионал) делаy, (оптионал) дуратион, (оптионал) сизе )

Дисплаy а "спеецх буббле", аттацхед то тхе специфиед таргет, цонтаининг тхе специфиед теxт.

Yоу цан усе "аргс" то цустомизе теxт еxацтлy лике wитх бга.лог.

делаy : миллисецондс то wаит бефоре дисплаyинг тхе спеецх буббле (дефаулт : 0). дуратион : хоw лонг то схоw тхе спеецх буббле ин миллисецондс (дефаулт : 3000). сизе : сизе оф тхе теxт ин перцент (дефаулт: 100)

 // Example :
 bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
 bga.speechBubble( _("Good for you!"), { }, 2000 );

бга.дисплаyСцоринг( таргет, цолор, сцоре )

Дисплаy ан аниматед темпорарy "сцоре нумбер", аттацхед то тхе специфиед таргет.

"цолор" схоулд бе тхе цолор оф тхе плаyер wхо ис сцоринг фор тхат таргет.

Гет / сеарцх гаме елементс анд тхеир пропертиес

бга.гетЕлемент( селецтор, (оптионал) фиелдс )

Аллоw yоу то ретриеве информатионс абоут оне гаме елемент специфиед усинг "селецтор" аргумент.

Ретурн нулл иф но елемент ис фоунд.

Ноте : гетЕлемент тхроw ан еррор иф северал елементс матцхес тхе селецтор. Иф yоу wант то ретриеве северал елементс, yоу схоулд усе "гетЕлементс" инстеад оф "гетЕлемент".

Тхе фоллоwинг еxамплес аре схоwинг алл тхе поссибле усе оф бга.гетЕлемент :

 // 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 } );
 
 // You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
 var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

бга.гетЕлементс( селецтор, (оптионал) фиелдс )

Ретурнс ан објецт холдинг тхе пропертиес оф тхе елементс матцхинг тхе селецтор.

 // Basic example: unselect all selected elements
 bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

бга.гетЕлементсАрраy( селецтор, (оптионал) фиелдс )

Ретурнс ан арраy оф алл елементс матцхинг тхе селецтор, холдинг тхе реqуиред пропертиес.

 // Basic example: get id of selected element
 var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
 var token_id = null;
 if (selected_tokens.length > 0) {
     token_id = selected_tokens[0];
 }
 return token_id;

 // Classic example: get array of elements and iterate over it
 var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
 for (var i=0; i<all_cells.length; i++) {
    // ... process each cell ...
 }

Утилитy метходс

бга.исОн( елемент_ид, парент_ид )

Ретурн труе иф "елемент_ид" ис а десцендант оф "парент_ид" (ие : иф елемент_ид гаме елемент хас беен плацед он парент_ид гаме елемент).

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

Триггер мост цоммон гаме ацтионс

мовеТо( $ид, $таргет, $патх=арраy() )

Мове елемент то специфиед таргет ид (евентуаллy фоллоwинг патх дефинед бy ан арраy оф отхер елемент идс)

Тхе еxацт дестинатион оф елемент депендс он таргет'с "хоwТоАрранге" пропертy ("Хоw елементс аре аррангед он ит?" : спреадед/децк/...).

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

Отхер фунцтионс

паусе( миллисецондс )

Паусе тхе цлиент интерфаце дуринг а специфиед нумбер оф миллисецондс.

Иф yоу до нот усе бга.паусе, алл Сандбоx гаме ацтионс аре еxецутед иммедиателy анд сyнцхроноуслy.

 // 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.

Типс : иф yоу wант то еxецуте северал цонсецутиве "мовеТо", yоу схоулд "бга.паусе" бетwеен тхем, отхерwисе yоур елемент wилл мове дирецтлy то тхе финал дестинатион.