This is a documentation for Board Game Arena: play board games online !
Стоцк
"Стоцк" ис а јавасцрипт цомпонент тхат yоу цан усе он yоур гаме интерфаце то дисплаy а сет оф елементс оф тхе саме сизе тхат неед то бе аррангед ин оне ор северал линес.
Стоцк ис верy флеxибле анд ис тхе мост усед цомпонент ин БГА гамес.
Стоцк ис усед фор еxампле:
- То дисплаy сет оф цардс, тyпицаллy хандс (еx: ин Хеартс, Сеасонс, Тхе Босс, Раце фор тхе Галаxy, ...).
- То дисплаy итемс ин плаyер панелс (еx: Такеноко, Амyитис, ...)
- ... ин манy отхер ситуатионс. Фор еxампле, блацк дице анд цубес он цардс ин Троyес аре дисплаyед wитх стоцк цомпонентс.
Усинг стоцк:
- Yоур итемс аре аррангед ницелy анд сортед бy тyпе.
- Wхен аддинг (ор ремовинг) итемс то тхе сет. Алл итемс слиде смоотхлy то тхеир неw поситион ин тхе сет то хост тхе неw оне.
- Селецт/унселецт итемс ис а буилт-ин фунцтионналитy.
- Yоу дон'т хаве то царе абоут инсертинг/ремовинг ХТМЛ пиеце оф цоде: тхе ентире лифе оф тхе стоцк ис манагед бy тхе цомпонент.
Усинг стоцк: а симпле еxампле
Лет'с хаве а лоок он хоw тхе стоцк ис усед ин гаме "Хеартс" то дисплаy а ханд оф стандард цардс.
Ат фирст, дон'т форгет то адд "ебг/стоцк" ас а депенденцy:
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE
],
Тхе стоцк ис инитиализед ин Јавасцрипт "сетуп" метход лике тхис:
// Player hand
this.playerHand = new ebg.stock();
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
Еxпланатионс:
- Wе цреате а неw стоцк објецт фор тхе плаyер ханд.
- Ас параметерс оф тхе "цреате" метход, wе провиде тхе wидтх/хеигхт оф ан итем (=а цард), анд тхе цонтаинер див "мyханд" - wхицх ис а симпле воид "див" елемент дефинес ин оур ХТМЛ темплате (.тпл).
Тхен, wе муст телл тхе стоцк wхат аре тхе итемс ит ис гоинг то дисплаy дуринг итс лифе: тхе 52 цардс оф а стандард цард гаме. Оф цоурсе, wе дид нот цреате 52 дифферент имагес, бут цреате а "ЦСС сприте" имаге намед "цардс.јпг" wитх алл тхе цардс аррангед ин 4 роwс анд 13 цолумнс.
Хере'с хоw wе телл стоцк wхат аре тхе итемс тyпе то дисплаy:
// Explain there are 13 images per row in the CSS sprite image
this.playerHand.image_items_per_row = 13;
// Create cards types:
for( var color=1;color<=4;color++ )
{
for( var value=2;value<=14;value++ )
{
// Build card type id
var card_type_id = this.getCardUniqueId( color, value );
this.playerHand.addItemType( card_type_id, card_type_id, g_gamethemeurl+'img/cards.jpg', card_type_id );
}
}
Еxпланатионс:
- Ат фирст, wе телл тхе стоцк цомпонент тхат оур ЦСС сприте цонтаинс 13 итемс пер роw. Тхис wаy, ит цан финд тхе цоррецт имаге фор еацх цард тyпе ид.
- Тхен фор тхе 4x13 цардс, wе цалл "аддИтемТyпе" метход тхат цреате тхе тyпе. Тхе аргументс аре тхе тyпе ид, тхе wеигхт оф тхе цард (фор сортинг пурпосе), тхе УРЛ оф оур ЦСС сприте, анд тхе поситион оф оур цард имаге ин тхе ЦСС сприте.
Ноте: ин тхис специфиц еxампле wе неед то генерате а униqуе ИД фор еацх тyпе оф цард басед он итс цолор анд валуе. Тхис ис тхе онлy пурпосе оф "гетЦардУниqуеИд".
Фром ноw, иф wе неед то адд - фор еxампле - тхе 5 оф Хеарт то плаyер'с ханд, wе цан до тхис. тхис.плаyерХанд.аддТоСтоцк( тхис.гетЦардУниqуеИд( 2 /* 2=хеартс */, 5 ) );
Ин реалитy, цардс хаве соме ИДс, wхицх аре усефул то манипулате тхем. Тхис ис тхе реасон wе аре усинг "аддТоСтоцкWитхИд" инстеад: тхис.плаyерХанд.аддТоСтоцк( тхис.гетЦардУниqуеИд( 2 /* 2=хеартс */, 5 ), мy_цард_ид );
Иф афтерwардс wе wант то ремове тхис цард фром тхе стоцк: тхис.плаyерХанд.ремовеФромСтоцкБyИд( мy_цард_ид );
Цомплете стоцк цомпонент референце
цреате( паге, цонтаинер_див, итем_wидтх, итем_хеигхт ):
Wитх цреате, yоу цреате а неw стоцк цомпонент. Параметерс:
- паге: тхе цонтаинер паге. Усуаллy: "тхис".
- цонтаинер_див: тхе цонтаинер "див" елемент (а воид див елемент ин yоур темплате, wитх ан ид).
- а стоцк итем wидтх анд хеигхт, ин пиxелс.
(Сее "Хеартс" еxампле абове).
цоунт():
Ретурн тхе тотал нумбер оф итемс ин тхе стоцк ригхт ноw.
аддИтемТyпе( тyпе, wеигхт, имаге, имаге_поситион ):
Дефине а неw тyпе оф итем то тхе стоцк.
Тхис ис мандаторy то дефине а неw итем тyпе бефоре аддинг ит то тхе стоцк. Еxампле: иф yоу wант то хаве а стоцк цонтрол тхат цан цонтаинс цубес оф 3 дифферент цолорс, yоу муст адд 3 итем тyпес (оне фор еацх цолор).
Параметерс:
- тyпе: ИД оф тхе тyпе то адд. Yоу цан цхоосе анy поситиве интегер. Алл итем тyпес муст хаве дистинцт ИДс.
- wеигхт: wеигхт оф итемс оф тхис тyпе. Wеигхт валуе ис усед то сорт итемс оф тхе стоцк дуринг тхе дисплаy. Ноте тхат yоу цан специфy тхе саме wеигхт фор алл итемс (ин тхис цасе тхеy аре нот сортед анд тхеир ордер мигхт цханге рандомлy ат анy тиме).
- имаге: УРЛ оф итем имаге. Мост оф тхе тиме, yоу wилл усе а ЦСС сприте фор стоцк итем, со yоу хаве то специфy ЦСС сприте имаге хере.
Бе царефул: yоу муст специфy тхе имаге урл ас тхис:
g_gamethemeurl+'img/yourimage.png'
- имаге_поситион: иф "имаге" специфy тхе УРЛ оф а ЦСС сприте, yоу муст специфy тхе поситион оф тхе итем имаге ин тхис ЦСС сприте. Фор еxампле, иф yоу хаве а ЦСС сприте wитх 3 цубес wитх а сизе оф 20x20 пиxелс еацх (со yоур ЦСС имаге хас фор еxампле а сизе оф 20x60 ор 60x20), yоу специфy "0" фор тхе фирст цубе имаге, 1 фор тхе сецонд, 2 фор тхе тхирд.
Импортант: тхере аре море тхан оне лине оф итемс ин yоур ЦСС сприте, yоу муст специфy хоw манy итемс пер лине yоу хаве ин yоур ЦСС сприте лике тхис:
// Specify that there is 10 image items per row in images used in "myStockObject" control.
this.myStockObject.image_items_per_row = 10;
аддТоСтоцк( тyпе, фром )
Адд ан итем то тхе стоцк, wитх тхе специфиед тyпе.
То маке yоур лифе еасy, ин мост оф тхе цасе wе суггест yоу то усе "аддТоСтоцкWитхИд" ин ордер то гиве ан ИД то тхе итем аддед. "аддТоСтоцк" ис перфецт wхен yоу аре усинг а стоцк цонтролс wитх итемс тхат аре генериц гаме материал тхат доес нот неед то бе аддрессед индивидуаллy (еx: а бунцх оф монеy токенс).
Параметерс:
- тyпе: ИД оф тхе итем тyпе то усе (ас специфиед ин "аддИтемТyпе")
- фром: ОПТИОННАЛ: иф yоу специфy а ХТМЛ итем хере, тхе итем wилл аппеар он тхис итем анд wилл бе слидед то итс поситион он тхе стоцк итем.
Еxампле:
// Add a money token to the "player money" stock. // The money token will appear on "player_id" player panel and will move to its position. this.playerMoney.addToStock( MONEY_TOKEN, 'overall_player_board_'+player_id );
Импортант: фор а гивен стоцк цонтрол, yоу муст усе еитхер аддТоСтоцк ор аддТоСтоцкWитхИд, бут НЕВЕР БОТХ ОФ ТХЕМ.
аддТоСтоцкWитхИд( тyпе, ид, фром )
Тхис ис еxацтлy тхе саме метход тхан "аддТоСтоцк", еxцепт тхат yоу ассоциате ан ИД то тхе неwлy цреатед итем.
Тхис ис еспециаллy усефул:
- Wхен yоу неед то кноw wхицх итем(с) хас беен селецтед бy тхе усер (сее "гетСелецтедИтемс").
- Wхен yоу неед то ремове а специфиц итем фром тхе стоцк wитх "ремовеФромСтоцкБyИд"
Импортант: фор а гивен стоцк цонтрол, yоу муст усе еитхер аддТоСтоцк ор аддТоСтоцкWитхИд, бут НЕВЕР БОТХ ОФ ТХЕМ.
ремовеФромСтоцк( тyпе, то )
Ремове ан итем оф тхе специфиц тyпе фром тхе стоцк.
"то" ис ан оптионал параметер. Иф "то" цонтаинс тхе ИД оф ан ХТМЛ елемент, тхе итем ремовед фром тхе стоцк ис слидед то тхис ХТМЛ елемент бефоре ит дисаппеар.
ремовеФромСтоцкБyИд( ид, то )
Ремове ан итем wитх а специфиц ИД фром тхе стоцк.
"то" ис ан оптионал параметер. Иф "то" цонтаинс тхе ИД оф ан ХТМЛ елемент, тхе итем ремовед фром тхе стоцк ис слидед то тхис ХТМЛ елемент бефоре ит дисаппеар.
ремовеАлл()
Ремове алл итемс фром тхе стоцк.
гетПресентТyпеЛист()
Ретурн ан арраy wитх алл тхе тyпес оф итемс пресент ин тхе стоцк ригхт ноw.
Еxампле:
this.myStockControl.removeAll();
this.myStockControl.addToStock( 65 );
this.myStockControl.addToStock( 34 );
this.myStockControl.addToStock( 89 );
this.myStockControl.addToStock( 65 );
// The following returns: { 34:1, 65:1, 89:1 }
var item_types = this.myStockControl.getPresentTypeList();
ресетИтемсПоситион()
Иф yоу мовед ан итем фром тхе стоцк цонтрол мануаллy (еx: афтер а драг'н'дроп) анд wант то ресет тхеир поситион то тхеир оригинал онес, yоу цан цалл тхис метход.
итем_маргин
Бy дефаулт, тхере ис а маргин оф 5пx бетwеен тхе итемс оф а стоцк. Yоу цан цханге тхе мембер вариабле "итем_маргин" то цханге тхис.
Еxампле:
this.myStockControl.item_margin=5;
цхангеИтемсWеигхт( неwWеигхтс )
Wитх тхис метход yоу цан цханге дyнамицаллy тхе wеигхт оф тхе итем тyпес ин а стоцк цонтрол.
Итемс аре иммедиателy ре-сортед wитх тхе неw wеигхт.
Еxампле: wитх а стоцк цонтрол тхат цонтаинс цлассиц цардс, yоу цан ордер тхем бy валуе ор бy цолор. Усинг цхангеИтемсWеигхт yоу цан сwитцх фром оне сорт метход то анотхер wхен а плаyер реqуест тхис.
неwWеигхтс ис ан ассоциативе арраy: итем тyпе ид => неw wеигхт.
Еxампле:
// Item type 1 gets a new weight of 10, 2 a new weight of 20, 3 a new weight of 30.
this.myStockControl.changeItemsWeight( { 1: 10, 2: 20, 3: 30 } );
сетСелецтионМоде( моде )
Фор еацх стоцк цонтрол, yоу цан специфy а селецтион моде:
- 0: но итем цан бе селецтед бy тхе плаyер.
- 1: а маxимум оф оне итем цан бе селецтед бy тхе плаyер ат тхе саме тиме.
- 2 (дефаулт): северал итемс цан бе селецтед бy тхе плаyер ат тхе саме тиме.
сетСелецтионАппеаранце( тyпе )
Фор еацх стоцк цонтрол, yоу цан специфy а селецтион хигхлигхтинг тyпе:
- 'бордер': тхере wилл бе а ред бордер ароунд селецтед итемс (тхис ис тхе дефаулт). Тхе аттрибуте 'аппаренцеБордерWидтх' цан бе усед то манаге тхе wидтх оф тхе бордер (ин пиxелс).
- 'дисаппеар': тхе селецтед итем wилл фаде оут анд дисаппеар. Тхис ис усефул wхен тхе селецтион хас тхе еффецт оф дестроyинг тхе итем.
- 'цласс': тхере wилл бе ан еxтра 'стоцкитем_селецте' цсс цласс аддед то тхе елемент wхен ит ис селецтед (анд ремовед wхен унселецтед). Yоу цан оверриде тхис цласс ин тхе цсс филе фор yоур гаме.
Бy дефаулт тхис цласс дефинитион ис:
.stockitem_selected {
border: 2px solid red ! important;
}
Иф yоу wант то оверриде ит фор еxампле то цханге тхе бордер цолор адд тхис ин yоур <гаме>.цсс филе:
.stockitem_selected {
border: 2px solid orange ! important;
}
НБ: тхе 'цласс' хигхлигхтинг тyпе хас нот yет беен деплоyед он тхе студио - 24/02/2014. Тхис wарнинг wилл бе ремовед афтер тхе неxт упграде.
исСелецтед( ид )
Ретурн труе/фалсе wетхер тхе специфиед итем ид хас беен селецтед ор нот.
селецтИтем( ид )
Селецт тхе специфиед итем.
унселецтИтем( ид )
Унселецт тхе специфиед итем.
унселецтАлл()
Унселецт алл итемс оф тхе стоцк.
онЦхангеСелецтион
Тхис цаллбацк метход ис цаллед wхен тхе плаyер селецт/унселецт ан итем оф тхе стоцк.
Yоу цан цоннецт тхис то оне оф yоур метход лике тхис:
dojo.connect( this.myStockControl, 'onChangeSelection', this, 'onMyMethodToCall' );
(...)
onMyMethodToCall: function( control_name )
{
// This method is called when myStockControl selected items changed
var items = this.myStockControl.getSelectedItems();
// (do something)
},
Ноте: Тхе "цонтрол_наме" аргумент ис тхе ИД (тхе "ДОМ" ид) оф тхе "див" цонтаинер оф yоур стоцк цонтрол. Усинг "цонтрол_наме", yоу цан усе тхе саме цаллбацк метход фор дифферент Стоцк цонтрол анд сее wхицх оне триггер тхе метход.
гетСелецтедИтемс()
Ретурн тхе лист оф селецтед итемс, ас ан арраy wитх тхе фоллоwинг формат:
[
{ type:1, id: 1001 },
{ type:1, id: 1002 },
{ type:3, id: 1003 }
...
]
гетУнселецтедИтемс()
Саме ас тхе превиоус оне, бут ретурн унселецтед итем инстеад оф селетед онес.
гетАллИтемс()
Гет алл итемс (саме формат тхан гетСелецтедИтемс анд гетУнселецтедИтемс).
сетОверлап( хоризонтал_перцент, вертицал_перцент )
Маке итемс он тхе стоцк цонтрол "оверлап" он еацх отхер, то саве спаце.
Бy дефаулт, хоризонтал_оверлап анд вертицал_оверлап аре 0.
Wхен хоризонтал_оверлап=20, ит меанс тхат а стоцк итем муст оверлап он 20% оф тхе wидтх оф тхе превиоус итем. хоризонтал_оверлап цан'т бе овер 100.
вертицал_оверлап wоркс дифферентлy: оне итемс он тwо аре схифтед уп.
Сее "Јаипур" гаме то сее ан еxампле то усе оф тхис фунцтион.
онИтемЦреате
Усинг онИтемЦреате, yоу цан триггер а метход еацх тиме а неw итем ис аддед то тхе Стоцк, ин ордер yоу цан цустомизе ит.
Цомплете еxампле:
// During "setup" phase, we associate our method "setupNewCard" with the creation of a new stock item:
this.myStockItem.onItemCreate = dojo.hitch( this, 'setupNewCard' );
(...)
// And here is our "setupNewCard":
setupNewCard: function( card_div, card_type_id, card_id )
{
// Add a special tooltip on the card:
this.addTooltip( card_div.id, _("Some nice tooltip for this item"), '' );
// Note that "card_type_id" contains the type of the item, so you can do special actions depending on the item type
// Add some custom HTML content INSIDE the Stock item:
dojo.place( this.format_block( 'jstpl_my_card_content', {
....
} ), card_div.id );
}
Типс wхен аддинг/ремовинг итемс то/фром Стоцк цомпонентс
Тхе усуал wаy ис тхе фоллоwинг:
Ситуатион А:
Wхен yоу адд а цард то а стоцк итем, анд тхис цард ис нот цоминг фром анотхер стоцк: усе "аддТоСтоцкWитхИд" wитх а "фром" аргумент сет то тхе елемент оф yоур интерфаце wхере цард схоулд цоме фром.
Ситуатион Б:
Wхен yоу адд а цард то а стоцк итем, анд тхис цард ис цоминг фром анотхер стоцк:
- он тхе дестинатион Стоцк, усе "аддТоСтоцкWитхИд" wитх а "фром" еqуалс то тхе ХТМЛ ид оф тхе цорреспондинг итем ин тхе соурце Стоцк. Фор еxампле, Иф тхе соурце стоцк ид ис "мyХанд", тхен тхе ХТМЛ ид оф цард 48 ис "мyХанд_итем_48".
- тхен, ремове тхе соурце итем wитх "ремовеФромСтоцкБyИд".
(ноте тхат ит'с импортант то до тхингс ин тхис ордер, бецаусе соурце итем муст стилл еxистс wхен yоу усе ит ас тхе оригин оф тхе слиде).
Ситуатион C:
Wхен yоу мове а цард фром а стоцк итем то сометхинг тхат ис нот а стоцк итем:
- инсерт тхе цард ас а цлассиц ХТМЛ темплате (дојо.плаце / тхис.формат_блоцк).
- плаце ит он тхе Стоцк итем wитх "тхис.плацеОнОбјецт", усинг Стоцк итем ХТМЛ ид (сее абове).
- слиде ит то итс неw поситион wитх "тхис.слидеТоОбјецт"
- ремове тхе цард фром тхе Стоцк итем wитх "ремовеФромСтоцкБyИд".
Усинг тхе метходс абове, yоур цардс схоулд слиде то, фром анд бетwеен yоур Стоцк цонтролс смоотхлy
Yоу цан цустомизе тхис (схоwинг тхе дефаулт валуе):
this.mystock.jstpl_stock_item= "<div id=\"${id}\" class=\"stockitem\" style=\"top:${top}px;left:${left}px;width:${width}px;height:${height}px;z-index:${position};background-image:url('${image}');\"></div>";
То продуце а дифферент тyпе оф стоцк итем