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
 
(26 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Studio_Framework_Navigation}}


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


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.
Board Game Arena supports mobile phones and tablets. Most games are already playable on touch devices, but their layout and interactions still need to work on narrow screens.


However, to provide your players the best experience, you should follow the two piece of advice below.
== Declare your interface minimum width ==
 
<code>game_interface_width.min</code> is the smallest logical width at which your game remains usable. The default is 740 pixels.
 
When the available game area is at least this wide, the game is displayed at its normal scale. When it is narrower, <code>game_interface_width.autoscale</code> determines how BGA handles the difference. With the default <code>autoscale: true</code>, BGA scales the game content down to fit. For example, a minimum width of 740 pixels displayed in 390 pixels of available space is scaled to approximately 53%.
 
Declare it in '''gameinfos.jsonc''':


== Declare your interface minimum width ==
  "game_interface_width": {
      // Smallest usable width. Default: 740
      "min": 540,
 
      // Default: true
      "autoscale": true
  }


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.
The declared width must actually work. If you declare 540 pixels, the complete interface must remain usable at 540 pixels.


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.
{{Info|1=
'''Autoscaling is not a substitute for adapting your interface to narrow screens.''' Keep <code>game_interface_width.min</code> no larger than the interface genuinely needs. Scaling a large fixed layout down can make text and controls too small and increases rendering work. On iOS, heavily scaled interfaces can contribute to WebKit crashes. Use responsive CSS or narrower layout variants where practical.
}}


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.
Below 490 pixels, player panels may no longer use a two-column mobile layout.


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''' :
Examples:  


* In '''Can't Stop''', the dice are moved below the board on narrow screens:


   // Game interface width range (pixels)
   @media only screen and (max-width: 990px) {
  // Note: game interface = space on the left side, without the column on the right
      #dicechoices {
  'game_interface_width' => array(
          left: 180px;
          top: 530px;
      }
    
    
    // Minimum width
      #cantstop_wrap {
    //  default: 740
          height: 900px;
    //  maximum possible value: 740 (i.e. your game interface should fit with a 740px width, corresponding to a 1024px screen)
          width: 550px;
    //  minimum possible value: 320 (the lower the value you specify, the better the display is on mobile)
      }
    'min' => 540,
  }
 
*In '''Seasons''', panels normally displayed to the right of the board are moved below it:
 
  @media only screen and (max-width: 970px) {
      #board {
          float: none;
          margin: auto;
      }
    
    
    // Maximum width
      .seasons_rightpanel {
    //  default: null (i.e. no limit, the game interface is as big as the player's screen allows).
          margin-left: 0;
    // maximum possible value: unlimited
      }
    // minimum possible value: 740
  }
    'max' => null
 
  ),
On mobile, BGA moves player panels above the game and adds <code>mobile_version</code> to <code>#ebd-body</code>. The desktop layout uses <code>desktop_version</code>. Use these classes for layout-specific CSS.
 
===Autoscale===
 
<code>game_interface_width.autoscale</code> controls what happens when the available width is smaller than <code>game_interface_width.min</code>. It accepts <code>true</code>, <code>false</code>, or <code>"viewport"</code>. The default is <code>true</code>.


====<code>autoscale: true</code>====


And that's it! Now, BGA can choose the better display for your game interface, whatever the device.
BGA applies CSS <code>[https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/zoom zoom]</code> to the game content.


'''Important'''
The game content scales independently from the surrounding BGA interface:


If you declare that your interface can run with a 540 pixels width, it must effectively run on an interface with 540 pixels width.
*the top bar and tableview chat keep their normal size;
* the action bar and player panels use separate framework scaling on very narrow screens;
*standard BGA dialogs and tooltips generally keep their normal size;
*overlays inside the game area inherit the game zoom.


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.
This is the default mode and should suit most fixed-width games.


Examples :
=====Coordinates and animations=====


* 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 :
Browsers do not return consistent geometry for elements using CSS zoom. For custom positioning inside the zoomed game area, use:


   @media only screen and (max-width: 990px) {
   const rect = this.getBoundingClientRectIgnoreZoom("my-element");
 
 
    #dicechoices {
It returns logical, unscaled coordinates. BGA animation and positioning helpers already account for framework zoom.
        left: 180px;
 
        top: 530px;
Use the native <code>getBoundingClientRect()</code> when you need the visual position in the browser viewport, such as for an overlay outside the zoomed game area.
    }
 
    #cantstop_wrap {
====<code>autoscale: false</code> ====
        height: 900px;
 
        width: 550px;
BGA does not scale the game area.
    }
 
  }
{{Warn|1=
'''This mode is not recommended.''' Disable framework autoscaling only if the game already handles narrow screens itself, either through a fully responsive layout or a scaling system such as [[BgaZoom]].
}}
 
A fixed 740-pixel layout displayed in 390 pixels of available space will overflow horizontally and may require scrolling.
 
====<code>autoscale: "viewport"</code>====
 
This mode presents the whole game through a wider logical viewport. The game area and the BGA interface around it are scaled together, preserving their relative sizes and layout.
 
This option exists as a compatibility fallback. CSS <code>zoom</code> has behaved differently across browsers and has broken coordinate calculations or animations in some older games. Viewport scaling can keep those games working without rewriting their layout.
 
It also has important drawbacks:
 
*action bars, player panels, dialogs, and other game-page controls are scaled down with the game;
*text and controls can become very small;
*the layout does not adapt to the available space;
*scaling the entire game document is more expensive to render.
 
{{Warn|1=
'''This mode is not recommended.''' Use it only as a compatibility fallback when CSS <code>zoom</code> causes a confirmed problem. Do not use viewport scaling as a shortcut for building a responsive interface.
}}
 
{{Warn|1=
'''Legacy <code>default_viewport</code>'''
 
Some older games set the internal field <code>default_viewport</code> directly:
 
  this.default_viewport = "width=740";
 
This undocumented workaround predates the <code>autoscale</code> option. It is still supported to avoid breaking published games, but now has the same effect as <code>autoscale: "viewport"</code> and takes precedence over the configured mode.
 
'''Do not use it in new code.''' Existing games should test removing it and configure scaling through <code>game_interface_width</code> instead.
}}
 
==Touchscreen compatibility ==
 
BGA adds <code>touch-device</code> to <code>#ebd-body</code> when it detects a touchscreen, and <code>notouch-device</code> otherwise.
 
'''CSS <code>:hover</code>'''
 
Touch devices have no persistent mouse cursor. Some emulate <code>:hover</code> after a short touch, which can block the intended interaction. Prefix hover-only rules with <code>.notouch-device</code> when they should not apply to touchscreens.
 
'''Tooltips'''


* On Seasons, we have some panels on the right of the board. On small screens, we display these panels below the board:
Do not make required information available only through hover. Provide a touch-accessible alternative.


'''Mouse events'''


  @media only screen and (max-width: 970px) {
Do not rely only on mouse-specific events such as <code>mouseover</code>. Prefer the [https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events Pointer Events API], which supports mouse, touch, and pen input.
 
    #board {
        float: none;
        margin: auto;
    }
    .seasons_rightpanel {
        margin-left: 0px;
    }
 
  }


'''Drag and drop'''


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".
Common approaches:


== Touchscreen compatibility ==
*[https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events Pointer Events API]
**Example: https://codepen.io/VictoriaLa/pen/MWOgYYZ
**Game example: Century


Most of your games should work with touchscreen devices without needing any changes.
*[https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API Native HTML drag and drop]
**Example: https://codepen.io/VictoriaLa/pen/rNGXKxj
**Game example: Patchwork


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).
Add <code>touch-action: none</code> only to elements where you handle touch or pointer gestures and need to suppress native scrolling or zooming.


What may not work :
[[Category:Studio]]
* ":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.

Latest revision as of 19:23, 24 July 2026


Game File Reference


Useful Components

Official

  • ItemManager: a PHP component to manage cards or other game items.
  • PlayerCounter and TableCounter: PHP components to manage counters.
  • 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).
  • 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).
  • bga-zoom : a JS component for zoom controls.
  • bga-animations : a JS component for animations.
  • bga-cards : a JS component for cards.
  • bga-dice : a JS component for dice.
  • bga-autofit : a JS component to make text fit on a fixed size div.
  • bga-score-sheet : a JS component to help you display an animated score sheet at the end of the game.
  • bga-jump-to : a JS component to add board shortcuts

Deprecated

  • Deck: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
  • Stock: a JS component to manage and display a set of game elements displayed at a position.

Unofficial


Game Development Process


Guides for Common Topics


Miscellaneous Resources

Board Game Arena supports mobile phones and tablets. Most games are already playable on touch devices, but their layout and interactions still need to work on narrow screens.

Declare your interface minimum width

game_interface_width.min is the smallest logical width at which your game remains usable. The default is 740 pixels.

When the available game area is at least this wide, the game is displayed at its normal scale. When it is narrower, game_interface_width.autoscale determines how BGA handles the difference. With the default autoscale: true, BGA scales the game content down to fit. For example, a minimum width of 740 pixels displayed in 390 pixels of available space is scaled to approximately 53%.

Declare it in gameinfos.jsonc: 

 "game_interface_width": {
     // Smallest usable width. Default: 740
     "min": 540,
 
     // Default: true
     "autoscale": true
 }

The declared width must actually work. If you declare 540 pixels, the complete interface must remain usable at 540 pixels.

MediaWiki-note-icons.png​Autoscaling is not a substitute for adapting your interface to narrow screens. Keep game_interface_width.min no larger than the interface genuinely needs. Scaling a large fixed layout down can make text and controls too small and increases rendering work. On iOS, heavily scaled interfaces can contribute to WebKit crashes. Use responsive CSS or narrower layout variants where practical.

Below 490 pixels, player panels may no longer use a two-column mobile layout.

Examples:

  • In Can't Stop, the dice are moved below the board on narrow screens:
 @media only screen and (max-width: 990px) {
     #dicechoices {
         left: 180px;
         top: 530px;
     }
 
     #cantstop_wrap {
         height: 900px;
         width: 550px;
     }
 }
  • In Seasons, panels normally displayed to the right of the board are moved below it:
 @media only screen and (max-width: 970px) {
     #board {
         float: none;
         margin: auto;
     }
 
     .seasons_rightpanel {
         margin-left: 0;
     }
 }

On mobile, BGA moves player panels above the game and adds mobile_version to #ebd-body. The desktop layout uses desktop_version. Use these classes for layout-specific CSS.

Autoscale

game_interface_width.autoscale controls what happens when the available width is smaller than game_interface_width.min. It accepts true, false, or "viewport". The default is true.

autoscale: true

BGA applies CSS zoom to the game content.

The game content scales independently from the surrounding BGA interface:

  • the top bar and tableview chat keep their normal size;
  • the action bar and player panels use separate framework scaling on very narrow screens;
  • standard BGA dialogs and tooltips generally keep their normal size;
  • overlays inside the game area inherit the game zoom.

This is the default mode and should suit most fixed-width games.

Coordinates and animations

Browsers do not return consistent geometry for elements using CSS zoom. For custom positioning inside the zoomed game area, use: 

 const rect = this.getBoundingClientRectIgnoreZoom("my-element");

It returns logical, unscaled coordinates. BGA animation and positioning helpers already account for framework zoom.

Use the native getBoundingClientRect() when you need the visual position in the browser viewport, such as for an overlay outside the zoomed game area.

autoscale: false

BGA does not scale the game area.

MediaWiki-note-icons.png​This mode is not recommended. Disable framework autoscaling only if the game already handles narrow screens itself, either through a fully responsive layout or a scaling system such as BgaZoom.

A fixed 740-pixel layout displayed in 390 pixels of available space will overflow horizontally and may require scrolling.

autoscale: "viewport"

This mode presents the whole game through a wider logical viewport. The game area and the BGA interface around it are scaled together, preserving their relative sizes and layout.

This option exists as a compatibility fallback. CSS zoom has behaved differently across browsers and has broken coordinate calculations or animations in some older games. Viewport scaling can keep those games working without rewriting their layout.

It also has important drawbacks:

  • action bars, player panels, dialogs, and other game-page controls are scaled down with the game;
  • text and controls can become very small;
  • the layout does not adapt to the available space;
  • scaling the entire game document is more expensive to render.
MediaWiki-note-icons.png​This mode is not recommended. Use it only as a compatibility fallback when CSS zoom causes a confirmed problem. Do not use viewport scaling as a shortcut for building a responsive interface.
MediaWiki-note-icons.png​Legacy default_viewport

Some older games set the internal field default_viewport directly: 

 this.default_viewport = "width=740";

This undocumented workaround predates the autoscale option. It is still supported to avoid breaking published games, but now has the same effect as autoscale: "viewport" and takes precedence over the configured mode.

Do not use it in new code. Existing games should test removing it and configure scaling through game_interface_width instead.

Touchscreen compatibility

BGA adds touch-device to #ebd-body when it detects a touchscreen, and notouch-device otherwise.

CSS :hover

Touch devices have no persistent mouse cursor. Some emulate :hover after a short touch, which can block the intended interaction. Prefix hover-only rules with .notouch-device when they should not apply to touchscreens.

Tooltips

Do not make required information available only through hover. Provide a touch-accessible alternative.

Mouse events

Do not rely only on mouse-specific events such as mouseover. Prefer the Pointer Events API, which supports mouse, touch, and pen input.

Drag and drop

Common approaches:

Add touch-action: none only to elements where you handle touch or pointer gestures and need to suppress native scrolling or zooming.

Retrieved from "http:///index.php?title=Your_game_mobile_version&oldid=30861"