Scrollmap

Studio Framework Navigation

File structure of a BGA game

Game logic (Server side)

• Main game logic: yourgamename.game.php
• Your game state machine: states.inc.php
• Game database model: dbmodel.sql
• Players actions: yourgamename.action.php
• Game material description: material.inc.php
• Game statistics: stats.inc.php

Game interface (Client side)

• Game interface logic: yourgamename.js
• Game art: img directory
• Game interface stylesheet: yourgamename.css
• Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl
• Your game mobile version

Other components

• Translations (how to make your game translatable)
• Game options and preferences: gameoptions.inc.php
• Game meta-information: gameinfos.inc.php
• Game replay
• 3D
• Some usual board game elements image ressources

BGA Studio game components reference

• Deck: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
• Counter: a JS component to manage a counter that can increase/decrease (ex: player's score).
• Scrollmap: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
• Stock: a JS component to manage and display a set of game elements displayed at a position.
• Zone: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).

Undocumented component (if somebody knows please help with docs)

• Draggable: a JS component to manage drag'n'drop actions.
• ExpandableSection: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
• Wrapper: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.

BGA Studio user guide

• BGA game Lifecycle
• First steps with BGA Studio
• Tutorial reversi
• Tutorial gomoku
• Tutorial hearts
• Create a game in BGA Studio: Complete Walkthrough
• Tools and tips of BGA Studio - Tips and instructions on setting up development environment
• Practical debugging - Tips focused on debugging
• Studio logs - Instructions for log access
• BGA Studio Cookbook - Tips and instructions on using API's, libraries and frameworks
• BGA Studio Guidelines
• Troubleshooting - Most common "I am really stuck" situations
• Studio FAQ
• Pre-release checklist - Go throught this list if you think you done development
• Post-release phase
• BGA Code Sharing - Shared resources, projects on git hub, common code, other links

Scrollmap is a BGA client side component to display an infinite game area.

In some games, players are building the main game area with tiles or cards. Examples:

• Carcassonne
• Saboteur
• Takenoko
• Taluva
• ...

Of course this cause an additional difficulty for the adaptation, because we have to display an infinite game area into a finite space on the screen. This is where Scrollmap component can help you.

Scrollmap in action

If you want to see how Scrollmap looks like, please try "Saboteur" or "Takenoko" games on BGA, or watch a game in progress.

In both games, you can see that there are arrow controls around the main game area, so that players can use them to scroll the view. You can also drag'n'drop the game area to scroll.

How to use Scrollmap

At first, in the Javascript file, don't forget to add "ebg/scrollmap" as a dependency:

define([
    "dojo","dojo/_base/declare",
    "ebg/core/gamegui",
    "ebg/counter",
    "ebg/scrollmap"     /// <==== HERE
],

Then, declare a new variable in your class for the Scrollmap object:

        constructor: function(){
        console.log('yourgame constructor');
              
        // Scrollable area        	
        this.scrollmap = new ebg.scrollmap();

Now, open your template (TPL) file and add this HTML code:

    <div id="map_container">
    	<div id="map_scrollable"></div>
        <div id="map_surface"></div>
        <div id="map_scrollable_oversurface"></div>
        <a id="movetop" href="#"></a>
        <a id="moveleft" href="#"></a>
        <a id="moveright" href="#"></a>
        <a id="movedown" href="#"></a>
    </div>

There are also some lines to add to your CSS stylesheet. Please note that you can adapt it to your needs, especially the default width of the scrollable area:

/** Scrollable area **/

#map_container {
    position: relative;
    width: 100%;
    height: 400px;
    overflow: hidden;
}
#map_scrollable, #map_scrollable_oversurface {
    position: absolute;
    top: 205px;
    left:  315px;
}
#map_surface {
    position: absolute;
    top: 0px;
    left: 0px;
    width: 100%;
    height: 100%;
    cursor: move;
}
#map_footer {
    text-align: center;
}

Finally, to link your HTML code with your Javascript, place this in your Javascript "Setup" method:

   	// Make map scrollable        	
        this.scrollmap.create( $('map_container'),$('map_scrollable'),$('map_surface'),$('map_scrollable_oversurface') );
        this.scrollmap.setupOnScreenArrows( 150 );

This is it! Now, you should see on your game interface a scrollable game area. This is not really impressive though, because you didn't add anything on the game area yet. This is the next step.

Scrollable area layers

There are 2 - and only 2 - places where you should place your HTML stuff in your scrollable area:

• inside "map_scrollable" div
• inside "map_scrollable_oversurface" div

The difference is very important: "map_scrollable" is beneath the surface that is used to drag'n'drop the game area, and "map_scrollable_oversurface" is above this surface. In practice:

• If some element on the game area need to be clicked (or any kind of user interaction), you should place it in map_scrollable_oversurface, otherwise no click can reach it.
• If some element on the game area don't need to be clicked, you'd better place it in "map_scrollable", so it is possible to drag'n'drop the game area from a point on this element.

Of course, all layers are scrolled synchronously.

Tips: in some situation, it's also useful to place a game element on map_scrollable and a corresponding invisible element over the surface to manage the interactions. Example: when an interactive element must be placed beneath a non interactive element for display reason.

Positioning elements on game area

All elements on the game are must be absolute positioned (with "top" and "left" attributes).

By default, the game area is centered on 0,0 coordinates.

Enable move arrows

To show move arrows icons around the scrollmap in order to enable click based navigation in addition to drag and drop, add these lines to your CSS:

/** Move arrows **/

#movetop,#moveleft,#moveright,#movedown {
    display: block;
    position: absolute;
    background-image: url('../../../img/common/arrows.png');
    width: 32px;
    height: 32px;
}

#movetop {
    top: 0px;
    left: 50%;
    background-position: 0px 32px;
}
#moveleft {
    top: 50%;
    left: 0px;
    background-position: 32px 0px;
}
#moveright {
    top: 50%;
    right: 0px;
    background-position: 0px 0px;
}
#movedown {
    bottom: 0px;
    left: 50%;
    background-position: 32px 32px;
}

In your javascript, define the following functions:

        onMoveTop : function( evt )
        {
            console.log( "onMoveTop" );        
            evt.preventDefault();
            this.scrollmap.scroll( 0, 300 );
        },
        onMoveLeft : function( evt )
        {
            console.log( "onMoveLeft" );        
            evt.preventDefault();
            this.scrollmap.scroll( 300, 0 );
        },
        onMoveRight : function( evt )
        {
            console.log( "onMoveRight" );        
            evt.preventDefault();
            this.scrollmap.scroll( -300, 0 );
        },
        onMoveDown : function( evt )
        {
            console.log( "onMoveDown" );        
            evt.preventDefault();
            this.scrollmap.scroll( 0, -300 );
        },

And connect onclick events on the arrows to these functions in your javascript setup

        dojo.connect( $('movetop'), 'onclick', this, 'onMoveTop' );
        dojo.connect( $('moveleft'), 'onclick', this, 'onMoveLeft' );
        dojo.connect( $('moveright'), 'onclick', this, 'onMoveRight' );
        dojo.connect( $('movedown'), 'onclick', this, 'onMoveDown' );

Enable scrollmap zone extension

This is optional, when there can be unused screen space under the scrollmap that a player might want to use. Add this in your .tpl after the scrollmap div (the matching css rules has already been defined):

<div id="map_footer" class="whiteblock">
    <a href="#" id="enlargedisplay">↓  {LABEL_ENLARGE_DISPLAY}  ↓</a>
</div>

In your javascript, define the following function:

        onIncreaseDisplayHeight: function( evt )
        {
        	console.log( '$$$$ Event : onIncreaseDisplayHeight' );
        	evt.preventDefault();
        	
            var cur_h = toint( dojo.style( $('map_container'), 'height' ) );
            dojo.style( $('map_container'), 'height', ( cur_h+300 ) + 'px' );
        },

and connect them to the 'enlargedisplay' link in your setup:

dojo.connect( $('enlargedisplay'), 'onclick', this, 'onIncreaseDisplayHeight' );

In your view.php file, define the template variable LABEL_ENLARGE_DISPLAY so that it gets substituted with appropriate translatable text:

$this->tpl['LABEL_ENLARGE_DISPLAY'] = self::_("Enlarge display");