This is a documentation for Board Game Arena: play board games online !

Гаме интерфаце логиц: yоургаменаме.јс

Извор: Board Game Arena
Пређи на навигацију Пређи на претрагу

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

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

Филе струцтуре

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

Басицаллy, хере'с тхис струцтуре:

  • цонструцтор: хере yоу цан дефине вариабле глобал то yоур wхоле интерфаце.
  • сетуп: тхис метход ис цаллед wхен тхе паге ис рефресхед, ин ордер yоу цан сетуп тхе гаме интерфаце.
  • онЕнтерингСтате: тхе метход ис цаллед wхен ентеринг ин а неw гаме стате. Тхис wаy yоу цан цустомизе тхе виеw фор тхис гаме стате.
  • онЛеавингСтате: тхе метход ис цаллед wхен леавинг а гаме стате.
  • онУпдатеАцтионБуттонс: цаллед wхен ентеринг ин а неw стате, ин ордер yоу цан адд ацтион буттонс ин статус бар.
  • (утилитy метходс): ат тхис плаце yоу цан дефине yоур утилитy метходс
  • (плаyер'с ацтионс): ат тхис плаце yоу цан wрите yоур хандлерс фор плаyер'с ацтион он тхе интерфаце (еx: цлицк он ан итем).
  • сетупНотифицатионс: ин тхис метход yоу ассоциате нотифицатионс wитх нотифицатион хандлерс. Тхис wаy, фор еацх гаме нотифицатион, yоу триггер а јавасцрипт метход то хандле ит анд упдате тхе гаме интерфаце.
  • (нотифицатион хандлерс): ат тхис плаце yоу цан дефине yоур нотифицатионс хандлерс.

Генерал типс

тхис.плаyер_ид
Ид оф тхе плаyер он wхосе броwсер тхе цоде ис руннинг.
тхис.исСпецтатор
Флаг сет то труе иф тхе усер ат тхе табле ис а спецтатор (нот а плаyер).
Ноте: тхис ис нот а фунцтион, итс а вариабле.
Ноте: иф yоу wант то хиде соме елемент фор спецтаторс, yоу'д беттер усе ЦСС 'спецтаторМоде' цласс.
тхис.гамедатас
Цонтаинс yоур инитиал сет оф датас то инит тхе гаме, цреатед ат гаме старт ор гаме рефресх (Ф5)
Yоу цан упдате ит ас неедед то кееп ан уп то дате референце оф тхе гаме он тхе цлиент сиде иф yоу неед ит (мост оф тхе тиме yоу дон'т).
тхис.исЦуррентПлаyерАцтиве()
Ретурнс труе иф тхе плаyер он wхосе броwсер тхе цоде ис руннинг ис цуррентлy ацтиве (ит'с хис турн то плаy)
тхис.гетАцтивеПлаyерИд()
Ретурн тхе ИД оф ацтиве плаyер, ор нулл иф wе аре нот ин а "ацтивеплаyер" тyпе стате.
тхис.гетАцтивеПлаyерс()
Ретурн ан арраy wитх тхе ИДс оф плаyерс тхат аре цуррентлy ацтиве (ор ан емптy арраy иф тхере ис нот).

Дојо фрамеwорк

БГА ис усинг тхе Дојо Јавасцрипт фрамеwорк.

Тхе Дојо фрамеwорк аллоwс ус то до цомплеx тхингс еасиер, анд тхе БГА фрамеwорк ис усинг Дојо фрамеwорк а лот.

То реализе гаме алтхоугх, yоу онлy неед то усе а феw парт оф тхе Дојо фрамеwорк. Алл тхе Дојо метходс yоу неед то усе аре десцрибе он тхис паге.

Фор перформанце реасонс, wхен деплоyинг а гаме тхе јс цоде ис минифиед усинг Схринксафе (басед он ЕЦМАСЦРИПТ версион 3). Соме адванцед сyнтаx маy нот бе цомпатибле wитх тхис процесс. Ин партицулар:

  • yоу схоулд нот усе ресервед кеywордс фром тхе јавасцрипт лангуаге ас вариаблес
  • yоу схоулд нот децларе дефаулт аргумент валуес ин фунцтион децларатион, тхе фоллоwинг сyнтаx ис инвалид фор Схриксафе: фунцтион мyФунц(реqуиредАрг, оптионалАрг = 'дефаултВалуе') {}

Аццесс анд манипулате тхе ДОМ

$('соме_хтмл_елемент_ид')

Тхе $() фунцтион ис усед то гет соме ХТМЛ елемент усинг итс "ид" аттрибуте.

Еxампле 1: модифy тхе цонтент оф а "спан" елемент: 

In your HTML code:
   <span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
   $('a_value_in_the_game_interface').innerHTML = "9999";

Ноте: $() ис тхе стандард метход то аццесс соме ХТМЛ елемент wитх БГА Фрамеwорк. Yоу муст нот усе "гетЕлементБyИд" фунцтион.


дојо.стyле

Wитх дојо.стyле yоу цан модифy а ЦСС пропертy оф анy ХТМЛ елемент оф yоур интерфаце.

Еxамплес: 

     // Make an element disappear
     dojo.style( 'my_element', 'display', 'none' );

     // Give an element a 2px border
     dojo.style( 'my_element', 'borderWidth', '2px' );

     // Change the background position of an element
     // (very practical when you are using CSS sprite to transform an element to another)
     dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );

Ноте: yоу муст алwаyс усе дојо.стyле то модифy ЦСС пропертиес оф ХТМЛ елементс.

Ноте²: иф yоу хаве то модифy северал ЦСС пропертиес оф ан елемент, ор иф yоу хаве соме цомплеx ЦСС трансформатион то до, yоу схоулд цонсидер усинг дојо.аддЦласс/дојо.ремовеЦласс (сее белоw).

дојо ЦСС цлассес манипулатион

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

Адвантагес аре:

  • Алл yоур ЦСС стуфф ремаинс ин yоур ЦСС филе.
  • Yоу цан адд/ремове а лист оф ЦСС модифицатионс wитх а симпле фунцтион анд wхитхоут еррор.
  • Yоу цан тест иф yоу апплиед тхе стуфф то ан елемент wитх "дојо.хасЦласс" метход.

Еxампле фром "Реверси": 

    // We add "possibleMove" to an element
    dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

    // In our CSS file, the class is defined as:
    .possibleMove {
      background-color: white;
      opacity: 0.2;
      filter:alpha(opacity=20); /* For IE8 and earlier */  
      cursor: pointer;  
     }

     // So we've applied 4 CSS property change in one line of code.

     // ... and when we need to check if a square is a possible move on client side:
     if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
     { ... }

     // ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
     dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

Цонцлусион: wе енцоураге yоу то усе дојо.аддЦласс, дојо.ремовеЦласс анд дојо.хасЦласс то маке yоур лифе еасиер :)

дојо.qуерy

Wитх дојо.qуерy, yоу цан qуерy а бунцх оф ХТМЛ елементс wитх а сингле фунцтион, wитх а "ЦСС селецтор" стyле.

Еxампле: 

     // All elements with class "possibleMove":
     var elements = dojo.query( '.possibleMove' );

     // Count number of tokens (ie: elements with class "token") on the board (ie: element with id "board"):
     dojo.query( '#board .token' ).length;

Бут wхат ис реаллy цоол wитх дојо.qуерy ис тхат yоу цан цомбине ит wитх алмост алл метходс абове.

Еxамплес: 

     // Trigger a method when the mouse enter in any element with class "meeple":
     dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

     // Hide all meeples who are on the board
     dojo.query( '#board .meeple' ).style( 'display', 'none' );

дојо.плаце

дојо.плаце ис тхе бест фунцтион то инсерт соме ХТМЛ цоде сомеwхере ин yоур гаме интерфаце wитхоут бреакинг сометхинг. Ит ис муцх беттер то усе тхат "иннерХТМЛ=" метход ас соон ас yоу муст инсерт ХТМЛ тагс анд нот онлy валуес. 

     // Insert your HTML code as a child of a container element
     dojo.place( "<your html code>", "your_container_element_id" );

     // Replace the container element with your new html
     dojo.place( "<your html code>", "your_container_element_id", "replace" );

Тхе тхирд параметер оф дојо.плаце цан таке вариоус интерестинг валуе.

валуес поссиблес :

"реплаце" : (сее десцриптион абове).

"фирст" : Плацес тхе ноде ас а цхилд оф тхе референце ноде. Тхе ноде ис плацед ас тхе фирст цхилд.

"ласт" : Плацес тхе ноде ас а цхилд оф тхе референце ноде. Тхе ноде ис плацед ас тхе ласт цхилд.

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

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

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

поситиф интегер : Тхис параметер цан бе а поситиф интегер. Ин тхис цасе, тхе ноде wилл бе плацед ас а цхилд оф тхе референце ноде wитх тхис нумбер (цоунтинг фром 0). Иф тхе нумбер ис море тхан нумбер оф цхилдрен, тхе ноде wилл бе аппендед то тхе референце ноде макинг ит тхе ласт цхилд.

Сее алсо фулл доц он дојо.плаце : [1]

Усуаллy, wхен yоу wант то инсерт соме пиеце оф ХТМЛ ин yоур гаме интерфаце, yоу схоулд усе "Јавасцрипт темплатес".

аддСтyлеТоЦласс: фунцтион( цссЦлассНаме, цссПропертy, пропертyВалуе )

Саме ас дојо.стyле(), бут фор алл тхе нодес сет wитх тхе специфиед цссЦлассНаме

Аниматионс

Дојо Аниматионс

БГА аниматионс ис басед он Дојо Аниматион (сее туториал хере).

Хоwевер, мост оф тхе тиме, yоу цан јуст усе метходс белоw, wхицх аре буилт он топ оф Дојо Аниматион.

Ноте: оне интерестинг метход фром Дојо тхат цоулд бе усефул фром тиме то тиме ис "Дојо.Аниматион". Ит аллоwс yоу то маке анy ЦСС пропертy "слиде" фром оне валуе то анотхер.

тхис.слидеТоОбјецт( мобиле_обј, таргет_обј, дуратион, делаy )

Yоу цан усе слидеТоОбјецт то "слиде" ан елемент то а таргет поситион.

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

Тхе параметерс аре:

  • мобиле_обј: тхе ИД оф тхе објецт то мове. Тхис објецт муст бе "релативе" ор "абсолуте" поситионед.
  • таргет_обј: тхе ИД оф тхе таргет објецт. Тхис објецт муст бе "релативе" ор "абсолуте" поситионед. Ноте тхат ит ис нот мандаторy тхат мобиле_обј анд таргет_обј хаве тхе саме сизе. Иф тхеир сизе аре дифферент, тхе сyстем слидес тхе центер оф мобиле_обј то тхе центер оф таргет_обј.
  • дуратион: (оптионал) дефинес тхе дуратион ин миллисецонд оф тхе слиде. Тхе дефаулт ис 500 миллисецондс.
  • делаy: (оптионал). Иф yоу дефинес а делаy, тхе слиде wилл старт онлy афтер тхис делаy. Тхис ис партицуларлy усефул wхен yоу wант то слиде северал објецт фром тхе саме поситион то тхе саме поситион: yоу цан гиве а 0мс делаy то тхе фирст објецт, а 100мс делаy то тхе сецонд оне, а 200мс делаy то тхе тхирд оне, ... тхис wаy тхеy wон'т бе суперпосед дуринг тхе слиде.

БЕ ЦАРЕФУЛ: Тхе метход ретурнс ан дојо.фx аниматион, со yоу цан цомбине ит wитх отхер аниматион иф yоу wант то. Ит меанс тхат yоу хаве то цалл тхе "плаy()" метход, отхерwисе тхе аниматион WОН'Т СТАРТ.

Еxампле: 

   this.slideToObject( "some_token", "some_place_on_board" ).play();


тхис.слидеТоОбјецтПос( мобиле_обј, таргет_обј, таргет_x, таргет_y, дуратион, делаy )

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

Еxампле: слиде а токен то соме плаце он тхе боард, 10 пиxелс то тхе боттом: 

   this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();

тхис.слидеТемпорарyОбјецт( мобиле_обј_хтмл, мобиле_обј_парент, фром, то, дуратион, делаy )

Тхис метход ис усефул wхен yоу wант то слиде а темпорарy ХТМЛ објецт фром оне плаце то анотхер. Ас тхис објецт доес нот еxистс бефоре тхе аниматион анд wон'т ремаин афтер, ит цоулд бе цомплеx то цреате тхис објецт (wитх дојо.плаце), то плаце ит ат итс оригин (wитх плацеОнОбјецт) то слиде ит (wитх слидеТоОбјецт) анд то маке ит дисаппеар ат тхе енд.

слидеТемпорарyОбјецт доес алл оф тхис фор yоу:

  • мобиле_обј_хтмл ис а пиеце оф ХТМЛ цоде тхат репресент тхе објецт то слиде.
  • мобиле_обј_парент ис тхе ИД оф ан ХТМЛ елемент оф yоур интерфаце тхат wилл бе тхе парент оф тхис темпорарy ХТМЛ објецт.
  • фром ис тхе ИД оф тхе оригин оф тхе слиде.
  • то ис тхе ИД оф тхе таргет оф тхе слиде.
  • дуратион/делаy wоркс еxацтлy лике ин "слидеТоОбјецт"

Еxампле: 

this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' );

тхис.слидеТоОбјецтАндДестроy: фунцтион( ноде, то, тиме, делаy )

Тхис метход ис а хандy схортцут то слиде ан еxистинг ХТМЛ објецт то соме плаце тхен дестроy ит упон арривал. Ит цан бе усед фор еxампле то мове а вицторy токен ор а цард фром тхе боард то тхе плаyер панел то схоw тхат тхе плаyер еарнс ит, тхен дестроy ит wхен wе дон'т неед то кееп ит висибле он тхе плаyер панел.

Ит wоркс тхе саме ас тхис.слидеТоОбјецт анд такес тхе саме аргументс.

Еxампле: 

this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );

тхис.фадеОутАндДестроy( ноде, дуратион, делаy )

Тхис фунцтион фаде оут тхе таргет ХТМЛ ноде, тхен дестроy ит.

Еxампле: 

   this.fadeOutAndDestroy( "a_card_that_must_disappear" );

ЦАРЕФУЛ: тхе ХТМЛ ноде стилл еxистс унтил дуринг феw миллисецондс, унтил тхе фадеОут хас беен цомплетед.

Ротатинг елементс

Yоу цан цхецк хере ан еxампле оф усе оф Дојо то маке ан елемент ротате.

Тхис еxампле цомбинес "Дојо.Аниматион" метход анд а ЦСС3 пропертy тхат аллоw yоу то ротате тхе елемент.

ИМПОРТАНТ: то ассес броwсер цомпатибилитy, yоу муст селецт тхе ЦСС пропертy то усе јуст лике ин тхе еxампле (сее соурцецоде белоw): 

        var transform;
        dojo.forEach(
            ['transform', 'WebkitTransform', 'msTransform',
             'MozTransform', 'OTransform'],
            function (name) {
                if (typeof dojo.body().style[name] != 'undefined') {
                    transform = name;
                }
            });
        // ... and then use "transform" as the name of your CSS property for rotation

Мовинг елементс

тхис.плацеОнОбјецт( мобиле_обј, таргет_обј )

плацеОнОбјецт wоркс еxацтлy лике "слидеТоОбјецт", еxцепт тхат тхе еффецт ис иммедиате.

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

Еxампле: 

  // (We just created an object "my_new_token")

  // Place the new token on current player board
  this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );
  
  // Then slide it to its position on the board
  this.slideToObject( "my_new_token", "a_place_on_board" ).play();

тхис.плацеОнОбјецтПос( мобиле_обј, таргет_обј, таргет_x, таргет_y )

Тхис метход wоркс еxацтлy лике плацеОнОбјецт, еxцепт тхан yоу цан специфy соме (x,y) цоординатес. Тхис wаy, "мобиле_обј" wилл бе плацед то тхе специфиед x,y поситион релативелy то "таргет_обј".

тхис.аттацхТоНеwПарент( мобиле_обј, таргет_обј )

Wитх тхис метход, yоу цханге тхе ХТМЛ парент оф "мобиле_обј" елемент. "таргет_обј" ис тхе неw парент оф тхис елемент. Тхе беаутy оф аттацхТоНеwПарент ис тхат тхе мобиле_обј елемент ДОЕС НОТ МОВЕ дуринг тхис процесс.

Ноте: wхат хаппенс ис тхат тхе метход цалцулате а релативе поситион оф мобиле_обј то маке суре ит доес нот мове афтер тхе ХТМЛ парент цхангес.

Wхy усинг тхис метход?

Цхангинг тхе ХТМЛ парент оф ан елемент цан бе усефул фор тхе фоллоwинг реасонс:

  • Wхен тхе ХТМЛ парент мовес, алл итс цхилд аре мовинг wитх тхем. Иф соме гаме елементс ис но море линкед wитх а парент ХТМЛ објецт, yоу маy wант то аттацх ит то анотхер плаце.
  • Тхе з_ордер (вертицал ордер оф дисплаy) депендс он тхе поситион ин тхе ДОМ, со yоу маy неед то цханге тхе парент оф соме гаме елементс wхен тхеy аре мовинг ин yоур гаме ареа.

ЦАРЕФУЛ: тхис фунцтион дестроyс оригинал објецт анд плацес а цлоне онто а неw парент, тхис wилл бреак алл референцес то тхис ХТМЛ елемент (еx: дојо.цоннецт).

Плаyерс инпут

дојо.цоннецт

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

Еxампле: ассоциате а цлицк он ан елемент ("мy_елемент") wитх оне оф оур метход ("онЦлицкОнМyЕлемент"): 

      dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );

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

тхис.цхецкАцтион( "мy_ацтион_наме" )

Усаге: цхецкАцтион: фунцтион( ацтион, номессаге )

Цхецк иф плаyер цан до тхе специфиед ацтион бy такинг инто аццоунт:

  • цуррент гаме стате
  • интерфаце лоцкинг (а плаyер цан'т до анy ацтион иф ан ацтион ис алреадy ин прогресс)

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

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

Еxампле: 

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

тхис.ајаxцалл( урл, параметерс, обј_цаллбацк, цаллбацк, цаллбацк_еррор )

Тхис метход муст бе усед то сенд а плаyер инпут то тхе гаме сервер.

  • урл: тхе урл оф тхе ацтион то перформ. Фор а гаме, ит муст бе: "/<мyгаме>/<мyгаме>/мyАцтион.хтмл"
  • параметерс: ан арраy оф параметер то сенд то тхе гаме сервер. Ноте тхат "лоцк:труе" муст алwаyс бе специфиед ин тхис лист оф параметер ин ордер тхе интерфаце цан бе лоцкед дуринг тхе сервер цалл.
  • обј_цаллбацк: муст бе сет то "тхис".
  • цаллбацк: а фунцтион то триггер wхен тхе сервер ретурнс анд еверyтхинг wент фине.
  • цаллбацк_еррор: (оптионал анд рарелy усед) а фунцтион то триггер wхен тхе сервер ретурнс ан еррор.

Усаге: 

this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true, 
   arg1: myarg1, 
   arg2: myarg2, 
   ...
}, this, function( result ) {
   // Do some stuff after a successful call
} );

Рестрицтед аргументс намес (плеасе дон'т усе тхем):

  • "ацтион"
  • "модуле"
  • "цласс"

тхис.цонфирматионДиалог()

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

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

Усаге: тхис.цонфирматионДиалог( "Qуестион то дисплаyед", цаллбацк_фунцтион_иф_цлицк_он_yес );

Еxампле: 

this.confirmationDialog( _('Are you sure to use this bonus (points penalty at the end of the game) ?'),
                         dojo.hitch( this, function() {
                           this.ajaxcall( '/seasons/seasons/useBonus.html',
                                { id:bonus_id, lock:true }, this, function( result ) {} );
                        } ) );


аддЕвентТоЦласс
фунцтион( цссЦлассНаме, евентНаме, фунцтионНаме )
Саме ас дојо.цоннецт(), бут фор алл тхе нодес сет wитх тхе специфиед цссЦлассНаме

тхис.аддАцтионБуттон( ид, лабел, метход, (опт)дестинатион, (опт)блинкинг, (опт)цолор )

Yоу цан усе тхис метход то адд ан ацтион буттон ин тхе маин ацтион статус бар.

Аргументс:

  • ид: ан елемент ИД тхат схоулд бе униqуе ин yоур ХТМЛ ДОМ доцумент.
  • лабел: тхе теxт оф тхе буттон. Схоулд бе транслатабле (усе _() фунцтион).
  • метход: тхе наме оф yоур метход тхат муст бе триггеред wхен тхе плаyер цлицкс он тхис буттон.
  • дестинатион (оптионал): депрецатед, до нот усе тхис. Усе нулл ас валуе иф yоу неед то специфy отхер аргументс.
  • блинкинг (оптионал): иф сет то труе, тхе буттон ис гоинг блинк то цатцх плаyер'с аттентион. Плеасе дон'т абусе оф блинкинг буттон.
  • цолор: цоулд бе блуе (дефаулт), ред ор граy.

Yоу схоулд онлy усе тхис метход ин yоур "онУпдатеАцтионБуттонс" метход. Усуаллy, yоу усе ит лике тхис (фром Хеарс еxампле): 

        onUpdateActionButtons: function( stateName, args ) {
                      
            if (this.isCurrentPlayerActive()) {            
                switch( stateName ) {
                case 'giveCards':
                    this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' ); 
                    break;
                }
            }
        },

Ин тхе еxампле абове, wе аре аддинг а "Гиве селецтед цардс" буттон ин тхе цасе wе аре он гаме стате "гивеЦардс". Wхен плаyер цлицкс он тхис буттон, ит триггерс оур "онГивеЦардс" метход.

Еxампле усинг блинкинг ред буттон: 

     this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red');

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

Транслатионс

Сее Транслатионс

Нотифицатионс

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

Хере'с хоw yоу цан хандле тхесе нотифицатионс он тхе цлиент сиде.

Субсцрибе то нотифицатионс

Yоур Јавасцрипт "сетупНотифицатионс" метход ис тхе плаце wхере yоу цан субсцрибе то нотифицатионс фром yоур ПХП цоде.

Хере'с хоw yоу ассоциате оне оф yоур Јавасцрипт метход то а нотифицатион "плаyДисц" (фром Реверси еxампле): 

   // In setupNotifications method:
   dojo.subscribe( 'playDisc', this, "notif_playDisc" );

Ноте: тхе "плаyДисц" цорреспондс то тхе наме оф тхе нотифицатион yоу дефине ит ин yоур ПХП цоде, ин yоур "нотифyАллПлаyерс" ор "нотифyПлаyер" метход.

Тхен, yоу хаве то дефине yоур "нотиф_плаyДисц" метход: 

        notif_playDisc: function( notif )
        {
            // Remove current possible moves (makes the board more clear)
            dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );        
        
            this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
        },

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

Еxампле: 

    // If you did this on PHP side:
    self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );

    // On Javascript side, you can access the "myArgument" like this:
    notif_myNotification: function( notif )
    {
       alert( "myArgument = " + notif.args.myArgument );
    }


Сyнцхроноус нотифицатионс

Wхен северал нотифицатионс аре рецеивед бy yоур гаме интерфаце, тхесе нотифицатионс аре процессед иммедиателy, оне афтер тхе отхер, ин тхе саме еxацт ордер тхеy хаве беен генератед ин yоур ПХП гаме логиц.

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

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

Хере'с хоw wе до тхис, ригхт афтер оур субсцриптион: 

       dojo.subscribe( 'playDisc', this, "notif_playDisc" );
       this.notifqueue.setSynchronous( 'playDisc', 500 );   // Wait 500 milliseconds after executing the playDisc handler


Пре-дефинед нотифицатион тyпес

таблеWиндоw - Тхис дефинес нотифицатион то дисплаy Сцоринг Диалогс, сее белоw.

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

  // You can call this on php side without doing anything on client side
   self::notifyAllPlayers( 'message', 'hello', array( ) );

Тоолтипс

тхис.аддТоолтип( нодеИд, _( хелпСтринг ), _( ацтионСтринг ), делаy )

Адд а симпле теxт тоолтип то тхе ДОМ ноде.

Специфy 'хелпСтринг' то дисплаy соме информатион абоут "wхат ис тхис гаме елемент?". Специфy 'ацтионСтринг' то дисплаy соме информатион абоут "wхат хаппенс wхен I цлицк он тхис елемент?".

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

Усуаллy, _() муст бе усед фор тхе теxт то бе маркед фор транслатион.

"Делаy" ис ан оптионал параметер. Усуаллy, ит ис примарилy усед то специфy а зеро делаy фор соме гаме елемент wхен тхе тоолтип гивес реаллy импортант информатион фор тхе гаме - бут ремембер: но ессентиал информатион муст бе плацед ин тоолтипс ас тхеy wон'т бе дисплаyед ин соме броwсер (сее Гуиделинес).

Еxампле: 

   this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );

тхис.аддТоолтипХтмл( нодеИд, хтмл, делаy )

Адд ан ХТМЛ тоолтип то тхе ДОМ ноде (фор море елаборате цонтент суцх ас пресентинг а биггер версион оф а цард).

тхис.аддТоолтипТоЦласс( цссЦласс, _( хелпСтринг ), _( ацтионСтринг ), делаy )

Адд а симпле теxт тоолтип то алл тхе ДОМ нодес сет wитх тхис цссЦласс.

ИМПОРТАНТ: алл цонцернед нодес муст хаве ИДс то гет тоолтипс.

тхис.аддТоолтипХтмлТоЦласс( цссЦласс, хтмл, делаy )

Адд ан ХТМЛ тоолтип то то алл тхе ДОМ нодес сет wитх тхис цссЦласс (фор море елаборате цонтент суцх ас пресентинг а биггер версион оф а цард).

ИМПОРТАНТ: алл цонцернед нодес муст хаве ИДс то гет тоолтипс

тхис.ремовеТоолтип( нодеИд )

Ремове а тоолтип фром тхе ДОМ ноде.

Диалогс, wарнинг мессагес, цонфирматион диалогс, ...

Wарнинг мессагес

Сометимес, тхере ис сометхинг импортант тхат ис хаппенинг он тхе гаме анд yоу хаве то маке суре алл плаyерс гет тхе мессаге. Мост оф тхе тиме, тхе еволутион оф тхе гаме ситуатион ор тхе гаме лог ис еноугх, бут сометимес yоу неед сометхинг море висибле.

Еx: сомеоне фулфилл оне оф тхе енд оф тхе гаме цондитион, со тхис ис тхе ласт турн.

тхис.схоwМессаге( мсг, тyпе )

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

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

Импортант: тхе нормал wаy то информ плаyерс абоут тхе прогрессион оф тхе гаме ис тхе гаме лог. "схоwМессаге" ис интрусиве анд схоулд нот бе усед офтен.

Цонфирматион диалог

цонфирматионДиалог( мессаге, yесХандлер, ноХандлер )


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

ЦАРЕФУЛ: тхе генерал гуиделинес оф БГА ис то АВОИД тхе усе оф цонфирматион диалог. Цонфирматион диалогс слоw доwн тхе гаме анд ботхер плаyерс. Тхе плаyерс кноwс тхат тхеy хаве то паy аттентион абоут еацх мове wхен тхеy аре плаyинг онлине.

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

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

Хоw то дисплаy а цонфирматион диалог: 

        this.confirmationDialog( _('Are you sure you want to bake the pie?'), dojo.hitch( this, function() {
            this.bakeThePie();
        } ) ); 
        return; // nothing should be called or done after calling this, all action must be done in the handler

Мултипле цхоице диалог

Yоу цан усе тхис диалог то гиве усер а цхоице wитх смалл амоунт оф оптионс: 

        var keys = [1,5,10];
        this.multipleChoiceDialog(
          _('How many bugs to fix?"), keys, 
            dojo.hitch(this, function(choice) {
                            var bugchoice = keys[choice];
                            console.log('dialog callback with '+bugchoice);
                            this.ajaxcall( '/mygame/mygame/fixBugs.html', { bugs: bugchoice}, this, function( result ) {} );                        }));

Диалогс

Ат фирст, yоу схоулдн'т усе диалогс wиндоwс.

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

Сометимес алтхоугх, yоу неед то дисплаy а диалог wиндоw. Хере ис хоw yоу до тхис: 


 // Create the new dialog. You should store the handler in a member variable to access it later
 this.myDlg = new dijit.Dialog({ title: _("my dialog title to translate") });
 
 // Create the HTML of my dialog. 
 // The best practice here is to use Javascript templates
 var html = this.format_block( 'jstpl_myDialogTemplate', { 
               arg1: myArg1,
               arg2: myArg2,
               ...
           } );  
 
 // Show the dialog
 this.myDlg.attr("content", html );
 this.myDlg.show(); 
 
 // Now that the dialog has been displayed, you can connect your method to some dialog elements
 // Example, a "close" button:
 dojo.connect( $('closeDlg'), 'onclick', this, function(evt){
               evt.preventDefault();
               this.myDlg.hide();
           } );


Тип: бе царефул wитх "хиде()" метход то цлосе yоур диалог: тхе диалог анд итс цонтент ис нот цомплетелy ремовед фром тхе ДОМ. Ит цан цаусе yоу проблемс иф yоу трy то дисплаy тхе саме диалог северал тимес. А гоод працтице ис то wрап алл тхе цонтент оф yоур диалог ин а <div id='myDlgContent'> див елемент, анд то цалл "дојо.дестроy('мyДлгЦонтент')" бефоре дисплаyинг yоур диалог.

Сцоринг диалогс

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

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

Сцоринг диалогс аре манагед ентирелy он ПХП сиде, бут тхеy аре десцрибед хере ас тхеир еффецтс аре висибле онлy он цлиент сиде.

Дисплаyинг а сцоринг диалог ис qуите симпле анд ис усинг а специал нотифицатион тyпе: "таблеWиндоw": 

  // on PHP side:
  $this->notifyAllPlayers( "tableWindow", '', array(
            "id" => 'finalScoring',
            "title" => clienttranslate("Title of the scoring dialog"),
            "table" => $table
        ) );

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

Еxампле: дисплаy ан 3x3 арраy оф стрингс 

   $table = array(
      array( "one", "two", "three" ),    // This is my first line
      array( "four", "five", "six" ),    // This is my second line
      array( "seven", "height", "nine" )    // This is my third line
   );

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

   $table = array(
      array( "one", "two", array( "str" => "a string with an ${argument}", "args" => array( 'argument' => 'argument_value' )  ) ),
      array( "four", "five", "six" ), 
      array( "seven", "height", "nine" )
   );

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

        $firstRow = array( '' );
        foreach( $players as $player_id => $player )
        {
            $firstRow[] = array( 'str' => '${player_name}',
                                 'args' => array( 'player_name' => $player['player_name'] ),
                                 'type' => 'header'
                               );
        }
        $table[] = $firstRow;

Yоу цан алсо усе тхрее еxтра аттрибутес ин тхе параметер арраy фор тхе нотифицатион: 

   $this->notifyAllPlayers( "tableWindow", '', array(
            "id" => 'finalScoring',
            "title" => clienttranslate("Title of the scoring dialog"),
            "table" => $table,
            "header" => array('str' => clienttranslate('Table header with parameter ${number}'),
                                 'args' => array( 'number' => 3 ),
                               ),
            "footer" => '<div>Some footer</div>',
            "closing" => clienttranslate( "Closing button label" )
        ) );
  • хеадер: тхе цонтент фор тхис параметер wилл дисплаy бефоре тхе табле (алсо, тхе хтмл wилл бе парсед анд плаyер намес wилл бе цолоред аццординг то тхе цуррент гаме цолорс).
  • фоотер: тхе цонтент фор тхис параметер wилл дисплаy афтер тхе табле (но парсинг фор цолоринг тхе плаyер намес)
  • цлосинг: иф тхис параметер ис усед, а буттон wилл бе дисплаyед wитх тхис лабел ат тхе боттом оф тхе попуп анд wилл аллоw плаyерс то цлосе ит (море еасилy тхан бy цлицкинг тхе топ ригхт 'цросс' ицон).


Сцоринг аниматед дисплаy

Сометимес (Терра Мyстица финал сцоринг фор еxампле), yоу маy wант то дисплаy а сцоре валуе овер ан елемент то маке тхе сцоринг еасиер то фоллоw фор тхе плаyерс. Yоу цан до ит wитх: 

   this.displayScoring( anchor_id, color, score );


Спеецх буббле

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

   this.showBubble( anchor_id, text, delay, duration, custom_class )

делаy ин миллисецондс ис оптионал (дефаулт 0)

дуратион ин миллисецондс ис оптионал (дефаулт 3000)

цустом_цласс ис оптионал, иф yоу неед то оверриде тхе дефаулт буббле стyле

Упдате плаyерс сцоре

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

  this.scoreCtrl[ player_id ].incValue( score_delta );

Сет а плаyер сцоре то а специфиц валуе: 

  this.scoreCtrl[ player_id ].setValue( new_score );

Плаyерс панелс

Аддинг стуфф то плаyер'с панел

Ат фирст, цреате а неw "ЈС темплате" стринг ин yоур темплате (тпл) филе:

(фром Гомоку еxампле) 

var jstpl_player_board = '\<div class="cp_board">\
    <div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';

Тхен, yоу адд тхис пиеце оф цоде ин yоур ЈС филе то адд тхис темплате то еацх плаyер панел: 

            // Setting up player boards
            for( var player_id in gamedatas.players )
            {
                var player = gamedatas.players[player_id];
                         
                // Setting up players boards if needed
                var player_board_div = $('player_board_'+player_id);
                dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
            }

(Ноте: тхе цоде абове ис оф цоурсе фром yоур "сетуп" фунцтион ин yоур Јавасцрипт).

Верy офтен, yоу хаве то дистингуисх цуррент плаyер анд отхерс плаyерс. Ин тхис цасе, yоу јуст хаве то цреате анотхер ЈС темплате (еx: јстпл_отхерплаyер_боард) анд усе ит wхен "плаyер_ид" ис дифферент тхан "тхис.плаyер_ид".

Плаyер'с панел дисаблинг/енаблинг

тхис.дисаблеПлаyерПанел( плаyер_ид )

Дисабле гивен плаyер панел (тхе панел бацкгроунд бецоме граy).

Усуаллy, тхис ис усед то сигнал тхат тхис плаyед пассес, ор wилл бе инацтиве дуринг а wхиле.

Ноте тхат тхе онлy еффецт оф тхис ис висуал. Тхере аре но цонсеqуенцес он тхе бехавиоур оф тхе панел итселф.

тхис.енаблеПлаyерПанел( плаyер_ид )

Енабле а плаyер панел тхат хас беен дисаблед бефоре.

тхис.енаблеАллПлаyерПанелс()

Енабле алл плаyер панелс тхат хас беен дисаблед бефоре.

Имаге лоадинг

Сее алсо Гаме_арт:_имг_дирецторy.

Бе царефул: бy дефаулт, АЛЛ имагес оф yоур имг дирецторy аре лоадед он а плаyер'с броwсер wхен хе лоадс тхе гаме. Фор тхис реасон, дон'т лет ин yоур имг дирецторy имагес тхат аре нот усефул, отхерwисе ит'с гоинг то слоwдоwн тхе гаме лоад.

донтПрелоадИмаге( имаге_филе_наме )

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

Еxампле оф усе: 

this.dontPreloadImage( 'cards.png' );

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

Анотхер еxампле оф усе: ин "Госу" гаме wитх Камакор еxтенсион, yоу плаy wитх 5 сетс оф цардс амонг 10 аваилабле. Цардс имагес аре организед бy сетс, анд wе онлy прелоад тхе имагес цорреспондинг то тхе 5 цуррент сетс wитх енсуреСпецифицГамеИмагеЛоадинг( имаге_филе_намес_арраy ). 

// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
	var clan_id = this.gamedatas.clans[i];
	to_preload.push( 'clan'+clan_id+'.png' );
}
if( to_preload.length == 5 )
{
	this.ensureSpecificGameImageLoading( to_preload );
}

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

Отхер усефул стуфф

дојо.хитцх

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

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

        this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
            this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );
        } ) );

Ин тхе еxампле абове, усинг дојо.хитцх, wе аре суре тхат тхе "тхис" објецт wилл бе сет wхен тхе цаллбацк ис цаллед.


упдатеЦоунтерс(цоунтерс)
Усефул фор упдатинг гаме цоунтерс ин тхе плаyер панел (суцх ас ресоурцес).
'цоунтерс' арг ис ан ассоциативе арраy [цоунтер_наме_валуе => [ 'цоунтер_наме' => цоунтер_наме_валуе, 'цоунтер_валуе' => цоунтер_валуе_валуе], ... ]
Алл цоунтерс муст бе референцед ин тхис.гамедатас.цоунтерс анд wилл бе упдатед.
ДОМ објецтс референцед бy 'цоунтер_наме' wилл хаве тхеир иннерХТМЛ упдатед wитх 'цоунтер_валуе'.

БГА ГУИ цомпонентс

БГА фрамеwорк провидес соме усефул реадy-то-усе цомпонентс фор тхе гаме интерфаце:

Студио#БГА_Студио_гаме_цомпонентс_референце

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

Еxампле иф yоу аре усинг "ебг.стоцк": 

define([
    "dojo","dojo/_base/declare",
    "ebg/core/gamegui",
    "ebg/counter",
    "ebg/stock"  /// <=== we are using ebg.stock module
],
Преузето из „http:///index.php?title=Game_interface_logic:_yourgamename.js&oldid=3082”