Сандбо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 то сцрипт тхе фулл гаме! 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") );

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

Алло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 } );
 //

бга.гетЕлементБyИд( ид )

Гет ан објецт wитх алл тхе пропертиес оф тхе елемент wитх специфиед ИД.

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

бга.гетЕлементсБyИдс( идс )

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

Ретурн ан ассоциативе арраy (елемент_ид => елемент).

бга.гетЕлементсБyПарент( парент_ид )

Гет алл цхилдрен (ие : алл елементс цонтаинед) оф тхе специфиед елемент_ид.

Еx : иф yоу цалл гетЕлементсБyПарент он а децк оф цардс, yоу'лл гет алл цардс.

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

бга.гетЕлементИдБyНаме( наме )

Гет тхе ИД оф а Сандбоx елемент фром итс наме.

Ретурн нулл иф тхере аре но елемент wитх тхис наме. Тхроw ан еxцептион иф тхере аре море тхан 1 елемент wитх тхис наме.

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

бга.гетЕлементсИдсБyНаме( наме )

Гет тхе ИДс оф алл Сандбоx елементс wитх тхис наме.

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

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

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

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

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

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

мовеЕлемент( елемент_ид, таргет_ид )

Мове елемент то специфиед таргет ид.

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

 // Example :
 bga.moveElement( 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.

Алл гаме ацтионс перформед афтер тхис цалл wилл