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

Your game mobile version: Difference between revisions

From Board Game Arena
Jump to navigation Jump to search
No edit summary
(14 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Studio_Framework_Navigation}}


Board Game Arena is now adaptated for Mobiles and Tablets too.
Board Game Arena is now adaptated for Mobiles and Tablets too.


This is very easy to have a mobile version of the game you developed with BGA Studio. In fact, your game is probably already 100% playable on mobile.
It is very easy to have a mobile version of the game you developed with BGA Studio. In fact, your game is probably already 100% playable on mobile.
 
However, to provide your players the best experience, you should follow the 2 advices below.


However, to provide your players the best experience, you should follow the two piece of advice below.


== Declare your interface minimum width ==
== Declare your interface minimum width ==


By default, your game can run in an window up to 740 pixels width. Considering the informations of the right column (player's panel), it fits on a 1024px wide screen.
By default, your game can run in a window of up to 740 pixels wide. Including the information in the right column (player's panel), it fits on a 1024px wide screen.


However, you can choose to declare that your game is able to run with a smaller width. This way, the game will appear much better on mobile and tablets.
However, you can choose to declare that your game is able to run with a smaller width. This way, the game will appear much better on mobile screens and tablets.


For example, Reversi board is only 540px wide. If we stay with the default width (740px), the game interface displayed on mobile will be too large and some space will be lost on the left and on the right. Consequently the Reversi board is going to appear very small on the mobile screen, and players will have to "pinch & zoom" to display it correctly.
For example, the Reversi board is only 540px wide. If we stay with the default width (740px), the game interface displayed on mobile will be too large and some space will be lost on the left and on the right. Consequently the Reversi board will appear very small on the mobile screen, and players will have to "pinch & zoom" to display it correctly.


To avoid that, we can specify that the game can be played with an interface with a minimum width of 540 pixels, by adding the following to gameinfos.inc.php :
To avoid that, we can specify that the game can be played with an interface with a minimum width of 540 pixels, by adding the following to '''gameinfos.inc.php''' :




Line 23: Line 23:
    
    
     // Minimum width
     // Minimum width
     //  default: 760
     //  default: 740
     //  maximum possible value: 760 (ie: your game interface should fit with a 760px width (correspond to a 1024px screen)
     //  maximum possible value: 740 (i.e. your game interface should fit with a 740px width, corresponding to a 1024px screen)
     //  minimum possible value: 320 (the lowest value you specify, the better the display is on mobile)
     //  minimum possible value: 320 (the lower the value you specify, the better the display is on mobile)
     'min' => 540,
     'min' => 540,
    
    
     // Maximum width
     // Maximum width
     //  default: null (ie: no limit, the game interface is as big as the player's screen allows it).
     //  default: null (i.e. no limit, the game interface is as big as the player's screen allows).
     //  maximum possible value: unlimited
     //  maximum possible value: unlimited
     //  minimum possible value: 760
     //  minimum possible value: 740
     'max' => null
     'max' => null
   ),
   ),
Line 42: Line 42:
If you declare that your interface can run with a 540 pixels width, it must effectively run on an interface with 540 pixels width.
If you declare that your interface can run with a 540 pixels width, it must effectively run on an interface with 540 pixels width.


Note that it doesn't mean that your interface must ALWAYS be 540 pixels width : you just have to make your interface fluid and/or to use CSS media query to fit in any width.
Note that this doesn't mean that your interface must ''always'' be 540 pixels width; you just have to make your interface fluid and/or use CSS media queries to fit any width.


Examples :
Examples :


* On Can't Stop, when the screen is too wide, we move the dices on another position (below the main board) to fit in the width :
* On '''Can't Stop''', when the screen is too narrow, we move the dice on another position (below the main board) to fit within the width :


   @media only screen and (max-width: 990px) {
   @media only screen and (max-width: 990px) {
Line 60: Line 60:
   }
   }


* On Seasons, we have some panels on the right of the boards. On small screen, we display these panels below :
* On Seasons, we have some panels on the right of the board. On small screens, we display these panels below the board:




Line 76: Line 76:




Tips : on mobile, BGA displays players' panels at the top of the page (instead of displaying them on the right). When doing this, BGA applies the CSS class "mobile_version" to the root HTML element. If you want you can use this CSS "mobile_version" class to synchronize some of your game adaptations to this change.
Tip: on mobile, BGA displays player panels at the top of the page (instead of displaying them on the right). When doing this, BGA applies the CSS class "mobile_version" to the root HTML element with id "ebd-body". If you want you can use this CSS "mobile_version" class to optimize some of your game adaptations to this change. In the opposite, when the "normal" version is active, the CSS class "desktop_version" BGA applies the CSS class "desktop_version" to the root HTML element with id "ebd-body".


== Touchscreen compatibility ==
== Touchscreen compatibility ==


Most of your game should work with touchscreen device.
Most of your games should work with touchscreen devices without needing any changes.


Note : When your game is running on a touchscreen device, the global CSS class "touch-device" is added to the root HTML element (and "notouch-device" is added in the contrary).
Note: when your game is running on a touchscreen device, the global CSS class "touch-device" is added to the to the root HTML element with id "ebd-body" (and "notouch-device" is added for the opposite).


What may not work :
What may not work :
* ":hover" CSS switch. Because there is no mouse, ":hover" won't be triggered. This is not an issue unless it is needed to play the game. In addition, some touch device considers that a short touch must trigger a ":hover" (and should apply corresponding CSS), which can block an interaction in your game. We advise you to explicitely disable ":hover" effects when your game is running on a touchscreen device.
* ":hover" CSS switch. Because there is no mouse, ":hover" won't be triggered. This is not an issue unless it is needed to play the game. In addition, some touch devices consider that a short touch must trigger a ":hover" (and should apply corresponding CSS), which can block an interaction in your game. We advise you to explicitely disable ":hover" effects when your game is running on a touchscreen device (for ex. by adding ".notouch-device" as a prefix to all your CSS :hover rules).
* Mouseover events : like the previous one : if you associated Javascript events to "onmouseover" event, it won't work on tablets.
* Mouseover events : like the previous one : if you associated Javascript events to "onmouseover" event, it won't work on tablets.
* Drag'n'drop : it won't work. To make it work, you should listen to "ontouchstart", "ontouchmove" and "ontouchend" event and trigger the same logic you already have for "onmousedown", "onmousemove" and "onmouseup". You should also make sure to stop the Javascript "ontouchmove" event (ex: dojo.stopEvent( evt ) ) during the drag n drop, otherwise the interface is going to scroll while drag'n'droping.
* Drag'n'drop : it won't work. To make it work, you should listen to "ontouchstart", "ontouchmove" and "ontouchend" event and trigger the same logic you already have for "onmousedown", "onmousemove" and "onmouseup". You should also make sure to stop the Javascript "ontouchmove" event (ex: dojo.stopEvent( evt ) ) during the drag n drop, otherwise the interface is going to scroll while drag'n'dropping.
 
Note that you may need to add the CSS property <code>touch-action: none</code> on elements where you listen for touch events, in order to prevent the browser from interpreting the touch as a request to scroll/zoom the page.
 
Instead of handling both "mouse" and "touch" events separately, consider using the newer [https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events Pointer Events API], which consolidates all pointer input (from mouse/touch/stylus/other) into a single set of events. Most browsers started supporting this in 2016, but Apple's support for this began relatively late in [https://developer.apple.com/documentation/safari-release-notes/safari-13-release-notes Safari 13 (September 2019)].
 
== Viewport <meta> tag ==
 
Mobile is an area where the BGA framework is very much showing its age. The built-in handling for mobile is incredibly unsatisfying because the framework was designed for a previous era, before mobile became the predominant form of web browsing (mobile has outpaced desktop browsing since 2016).
 
The most obvious problem is that the BGA framework uses [https://developer.mozilla.org/en-US/docs/Web/CSS/zoom the non-standard "zoom" CSS property] to resize your game for the mobile screen. The proper method is [https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag the viewport <meta> tag], which is supported by all mobile browsers and offers more control. You can disable BGA's broken "zoom" feature with the following code:
 
; In gameinfos.inc.php
<pre>
    'game_interface_width' => [
        'min' => 550,
        'max' => null
    ],
</pre>
 
; In yourgame.js:
<pre>
  return declare("bgagame.yourgame", ebg.core.gamegui, {
    setup: function (gamedatas) {
      // Set mobile viewport for portrait orientation based on gameinfos.inc.php
      this.default_viewport = "width=" + this.interface_min_width;
      this.onScreenWidthChange();
     
      ...
    },
   
    onScreenWidthChange: function () {
      // Remove broken "zoom" property added by BGA framework
      this.gameinterface_zoomFactor = 1;
      dojo.style("page-content", "zoom", "");
      dojo.style("page-title", "zoom", "");
      dojo.style("right-side-first-part", "zoom", "");
    },
</pre>
 
Note that in landscape orientation, the BGA framework always sets the viewport to "width=980". Overriding the viewport for landscape orientation is much more complicated (requires overriding undocumented framework functions), so it is not recommended.

Revision as of 16:29, 28 February 2021


Game File Reference



Useful Components

Official

  • Deck: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
  • Draggable: a JS component to manage drag'n'drop actions.
  • Counter: a JS component to manage a counter that can increase/decrease (ex: player's score).
  • ExpandableSection: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
  • 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)

  • Wrapper: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.

Unofficial



Game Development Process



Guides for Common Topics



Miscellaneous Resources

Board Game Arena is now adaptated for Mobiles and Tablets too.

It is very easy to have a mobile version of the game you developed with BGA Studio. In fact, your game is probably already 100% playable on mobile.

However, to provide your players the best experience, you should follow the two piece of advice below.

Declare your interface minimum width

By default, your game can run in a window of up to 740 pixels wide. Including the information in the right column (player's panel), it fits on a 1024px wide screen.

However, you can choose to declare that your game is able to run with a smaller width. This way, the game will appear much better on mobile screens and tablets.

For example, the Reversi board is only 540px wide. If we stay with the default width (740px), the game interface displayed on mobile will be too large and some space will be lost on the left and on the right. Consequently the Reversi board will appear very small on the mobile screen, and players will have to "pinch & zoom" to display it correctly.

To avoid that, we can specify that the game can be played with an interface with a minimum width of 540 pixels, by adding the following to gameinfos.inc.php :


 // Game interface width range (pixels)
 // Note: game interface = space on the left side, without the column on the right
 'game_interface_width' => array(
 
   // Minimum width
   //  default: 740
   //  maximum possible value: 740 (i.e. your game interface should fit with a 740px width, corresponding to a 1024px screen)
   //  minimum possible value: 320 (the lower the value you specify, the better the display is on mobile)
   'min' => 540,
 
   // Maximum width
   //  default: null (i.e. no limit, the game interface is as big as the player's screen allows).
   //  maximum possible value: unlimited
   //  minimum possible value: 740
   'max' => null
 ),


And that's it! Now, BGA can choose the better display for your game interface, whatever the device.

Important

If you declare that your interface can run with a 540 pixels width, it must effectively run on an interface with 540 pixels width.

Note that this doesn't mean that your interface must always be 540 pixels width; you just have to make your interface fluid and/or use CSS media queries to fit any width.

Examples :

  • On Can't Stop, when the screen is too narrow, we move the dice on another position (below the main board) to fit within the width :
 @media only screen and (max-width: 990px) {
 
   #dicechoices {
       left: 180px;
       top: 530px;
   }
   #cantstop_wrap {
       height: 900px;
       width: 550px;
   }
 }
  • On Seasons, we have some panels on the right of the board. On small screens, we display these panels below the board:


 @media only screen and (max-width: 970px) {
 
   #board {
       float: none;
       margin: auto;
   }
   .seasons_rightpanel {
       margin-left: 0px;
   }
 
 }


Tip: on mobile, BGA displays player panels at the top of the page (instead of displaying them on the right). When doing this, BGA applies the CSS class "mobile_version" to the root HTML element with id "ebd-body". If you want you can use this CSS "mobile_version" class to optimize some of your game adaptations to this change. In the opposite, when the "normal" version is active, the CSS class "desktop_version" BGA applies the CSS class "desktop_version" to the root HTML element with id "ebd-body".

Touchscreen compatibility

Most of your games should work with touchscreen devices without needing any changes.

Note: when your game is running on a touchscreen device, the global CSS class "touch-device" is added to the to the root HTML element with id "ebd-body" (and "notouch-device" is added for the opposite).

What may not work :

  • ":hover" CSS switch. Because there is no mouse, ":hover" won't be triggered. This is not an issue unless it is needed to play the game. In addition, some touch devices consider that a short touch must trigger a ":hover" (and should apply corresponding CSS), which can block an interaction in your game. We advise you to explicitely disable ":hover" effects when your game is running on a touchscreen device (for ex. by adding ".notouch-device" as a prefix to all your CSS :hover rules).
  • Mouseover events : like the previous one : if you associated Javascript events to "onmouseover" event, it won't work on tablets.
  • Drag'n'drop : it won't work. To make it work, you should listen to "ontouchstart", "ontouchmove" and "ontouchend" event and trigger the same logic you already have for "onmousedown", "onmousemove" and "onmouseup". You should also make sure to stop the Javascript "ontouchmove" event (ex: dojo.stopEvent( evt ) ) during the drag n drop, otherwise the interface is going to scroll while drag'n'dropping.

Note that you may need to add the CSS property touch-action: none on elements where you listen for touch events, in order to prevent the browser from interpreting the touch as a request to scroll/zoom the page.

Instead of handling both "mouse" and "touch" events separately, consider using the newer Pointer Events API, which consolidates all pointer input (from mouse/touch/stylus/other) into a single set of events. Most browsers started supporting this in 2016, but Apple's support for this began relatively late in Safari 13 (September 2019).

Viewport <meta> tag

Mobile is an area where the BGA framework is very much showing its age. The built-in handling for mobile is incredibly unsatisfying because the framework was designed for a previous era, before mobile became the predominant form of web browsing (mobile has outpaced desktop browsing since 2016).

The most obvious problem is that the BGA framework uses the non-standard "zoom" CSS property to resize your game for the mobile screen. The proper method is the viewport <meta> tag, which is supported by all mobile browsers and offers more control. You can disable BGA's broken "zoom" feature with the following code:

In gameinfos.inc.php
    'game_interface_width' => [
        'min' => 550,
        'max' => null
    ],
In yourgame.js
  return declare("bgagame.yourgame", ebg.core.gamegui, {
    setup: function (gamedatas) {
      // Set mobile viewport for portrait orientation based on gameinfos.inc.php
      this.default_viewport = "width=" + this.interface_min_width;
      this.onScreenWidthChange();
      
      ...
    },
    
    onScreenWidthChange: function () {
      // Remove broken "zoom" property added by BGA framework
      this.gameinterface_zoomFactor = 1;
      dojo.style("page-content", "zoom", "");
      dojo.style("page-title", "zoom", "");
      dojo.style("right-side-first-part", "zoom", "");
    },

Note that in landscape orientation, the BGA framework always sets the viewport to "width=980". Overriding the viewport for landscape orientation is much more complicated (requires overriding undocumented framework functions), so it is not recommended.