Stock

"Stock" is a javascript component that you can use on your game interface to display a set of elements of the same size that need to be arranged in one or several lines.

Stock is very flexible and is the most used component in BGA games.

Stock is used for example:

• To display set of cards, typically hands (ex: in Hearts, Seasons, The Boss, Race for the Galaxy, ...).
• To display items in player panels (ex: Takenoko, Amyitis, ...)
• ... in many other situations. For example, black dice and cubes on cards in Troyes are displayed with stock components.

Using stock:

• Your items are arranged nicely and sorted by type.
• When adding (or removing) items to the set. All items slide smoothly to their new position in the set to host the new one.
• Select/unselect items is a built-in functionnality.
• You don't have to care about inserting/removing HTML piece of code: the entire life of the stock is managed by the component.

Using stock: a simple example

Let's have a look on how the stock is used in game "Hearts" to display a hand of standard cards.

The stock is initialized in Javascript "setup" method like this:

    // Player hand
    this.playerHand = new ebg.stock();
    this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );

Explanations:

• We create a new stock object for the player hand.
• As parameters of the "create" method, we provide the width/height of an item (=a card), and the container div "myhand" - which is a simple void "div" element defines in our HTML template (.tpl).

Then, we must tell the stock what are the items it is going to display during its life: the 52 cards of a standard card game. Of course, we did not create 52 different images, but create a "CSS sprite" image named "cards.jpg" with all the cards arranged in 4 rows and 13 columns.

Here's how we tell stock what are the items type to display:

    // 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_themeurl+'img/hearts/cards.jpg', card_type_id );
        }
    }

Explanations:

• At first, we tell the stock component that our CSS sprite contains 13 items per row. This way, it can find the correct image for each card type id.
• Then for the 4x13 cards, we call "addItemType" method that create the type. The arguments are the type id, the weight of the card (for sorting purpose), the URL of our CSS sprite, and the position of our card image in the CSS sprite.

Note: in this specific example we need to generate a unique ID for each type of card based on its color and value. This is the only purpose of "getCardUniqueId".

From now, if we need to add - for example - the 5 of Heart to player's hand, we can do this. this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ) );

In reality, cards have some IDs, which are useful to manipulate them. This is the reason we are using "addToStockWithId" instead: this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ), my_card_id );

If afterwards we want to remove this card from the stock: this.playerHand.removeFromStockById( my_card_id );

Complete stock component reference

create( page, container_div, item_width, item_height ):

With create, you create a new stock component. Parameters:

• page: the container page. Usually: "this".
• container_div: the container "
  " element (a void

  element in your template).
• a stock item width and height, in pixels.

(See "Hearts" example above).

count():

Return the total number of items in the stock right now.

addItemType( type, weight, image, image_position ):

Define a new type of item to the stock.