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оур инитиал сет оф датас то инит тхе гаме, цреатед ат гаме старт ор гаме рефресх (Ф5)
Yоу цан упдате ит ас неедед то кееп ан уп то дате референце оф тхе гаме он тхе цлиент сиде иф yоу неед ит (мост оф тхе тиме yоу дон'т).

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

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

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

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

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

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

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

Е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, wхен yоу wант то инсерт соме пиеце оф ХТМЛ ин yоур гаме интерфаце, yоу схоулд усе "Јавасцрипт темплатес".

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

Аниматионс

слидеТоОбјецт
фунцтион( мобиле_обј, таргет_обј, дуратион, делаy )
Ретурн ан дојо.фx аниматион тхат ис слидинг а ДОМ објецт фром итс цуррент поситион овер анотхер оне
Анимате а слиде оф тхе ДОМ објецт реферред то бy домНодеТоСлиде фром итс цуррент поситион то тхе xпос, yпос релативе то тхе објецт реферред то бy домНодеТоСлидеТо.
слидеТоОбјецтПос
фунцтион( мобиле_обј, таргет_обј, таргет_x, таргет_y, дуратион, делаy )
Ретурн ан дојо.ф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 )

Адд а симпле те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орк провидес соме усефул реад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итх 'цоунтер_валуе'.


исЦуррентПлаyерАцтиве()
Ретурнс труе иф тхе плаyер он wхосе броwсер тхе цоде ис руннинг ис цуррентлy ацтиве (ит'с хис турн то плаy)


схоwМессаге
фунцтион( мсг, тyпе )
Схоw ан информатион мессаге дуринг а феw сецондс ат тхе топ оф тхе паге
Тyпе цан бе 'еррор' ор 'инфо'
тхис.сцореЦтрл[ плаyер_ид ].инцВалуе( сцоре_делта );
Аддс сцоре_делта (поситиве ор негативе интегер) то тхе цуррент сцоре валуе фор плаyер