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
(Remove the part suggesting to hack the framework)
(clarify game_interface_width.autoscale and overall polish)
Line 3: Line 3:
__TOC__
__TOC__


Board Game Arena is now adaptated for Mobiles and Tablets too.
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.


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.
== Declare your interface minimum width ==


However, to provide your players the best experience, you should follow the two piece of advice below.
<code>game_interface_width.min</code> is the smallest logical width at which your game remains usable. The default is 740 pixels.


== Declare your interface minimum width ==
Declare it in '''gameinfos.jsonc''':
 
  "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.
Keep the minimum as low as reasonably possible. Large values require stronger scaling on phones, make content smaller, and increase rendering work. Use fluid layouts and CSS media queries instead of declaring a large fixed width.


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.jsonc''' :
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" => {
          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:


And that's it! Now, BGA can choose the better display for your game interface, whatever the device.
  @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 <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>min</code>. It accepts <code>true</code>, <code>false</code>, or <code>"viewport"</code>. The default is <code>true</code>.
 
The examples below use a 740-pixel game displayed in 390 pixels of available space.
 
==== <code>autoscale: true</code> ====


'''Important'''
BGA applies CSS <code>zoom</code> to the game content. In the example, the scale is approximately 53%.


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 game content scales independently from the surrounding BGA interface:


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.
* 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.


Under 490, player panels aren't on 2 columns on mobile, so you probably shouldn't go under 490.
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.
    }
 
  }
Use this for responsive games or games with their own scaling system, such as [[BgaZoom]]. A fixed 740-pixel layout displayed in 390 pixels will otherwise overflow horizontally and may require scrolling.
 
==== <code>autoscale: "viewport"</code> ====
 
This mode scales the whole game document through a wider logical viewport.


* On Seasons, we have some panels on the right of the board. On small screens, we display these panels below the board:
Previously, when game pages were opened directly, BGA set the document viewport width and let the mobile browser fit it to the screen.


Games are now normally opened through <code>/tableview</code>. The game runs in an iframe, and its viewport cannot resize that iframe. Tableview emulates the same result by laying out the iframe at the requested width and applying <code>transform: scale(...)</code> to it.


  @media only screen and (max-width: 970px) {
In the example, the iframe is laid out at 740 pixels and displayed at approximately 53% scale. The game area and the BGA controls inside the iframe are scaled together.
 
    #board {
        float: none;
        margin: auto;
    }
    .seasons_rightpanel {
        margin-left: 0px;
    }
 
  }


CSS <code>zoom</code> participates in layout. <code>transform: scale(...)</code> scales after layout and usually creates a composited layer. Transforming a large iframe can be expensive on mobile devices.


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".
Prefer <code>autoscale: true</code> or a responsive layout unless viewport scaling is required for compatibility.


=== Autoscale ===
==== Legacy <code>default_viewport</code> ====


Some older games contain code such as:


There is an option in `game_interface_width`, called `autoscale`, than can be `true`, `false` or `viewport`
  this.default_viewport = "width=740";


* autoscale: true -> it sets CSS zoom property on player panels, title bar, and game area
<code>default_viewport</code> started as internal framework state. Games later used it as an undocumented viewport override before <code>game_interface_width.autoscale</code> existed.
* autoscale: false -> it sets CSS zoom property on player panels, title bar, but NOT and game area. Some devs disabled it with `zoom: 1 !important`, now they can remove the hack and use this framework flag instead 🙂


* autoscale: 'viewport' -> use native viewport (it makes chat button and bar very small)
It remains supported to avoid breaking published games. In tableview, it enables the same iframe scaling as <code>autoscale: "viewport"</code> and takes precedence over the configured autoscaling mode.


currently, the default autoscale value is 'true'
Do not use it in new code. Existing games should test removing it and use <code>game_interface_width</code> instead.


  'game_interface_width' => [
==== Mobile rendering performance ====
    "autoscale" => true
  ...


Discussion about this option in https://discord.com/channels/753304735615811584/1276225578797633536
Large transformed interfaces can crash iOS browsers during pinch zoom. See [https://boardgamearena.com/bug?id=229359 BGA bug #229359] and [https://bugs.webkit.org/show_bug.cgi?id=172206 WebKit bug #172206].


== Touchscreen compatibility ==
Reduce the risk:


Most of your games should work with touchscreen devices without needing any changes.
* keep interface dimensions reasonable;
* reduce image pixel dimensions and file sizes;
* avoid unnecessarily large sprite sheets;
* limit large fixed or transformed elements;
* avoid unnecessary animation, canvas, and WebGL rendering;
* test through <code>/tableview</code>, including pinch zoom on iOS.


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).
== Touchscreen compatibility ==


Special cases:
BGA adds <code>touch-device</code> to <code>#ebd-body</code> when it detects a touchscreen, and <code>notouch-device</code> otherwise.


'''CSS :hover'''
'''CSS <code>:hover</code>'''


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).
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'''
'''Tooltips'''


Tooltips generally do not work properly on mobile, if important consider alternative implementation
Do not make required information available only through hover. Provide a touch-accessible alternative.


'''Mouse events'''
'''Mouse events'''


If you use "onmouseover" or other mouse events, it won't work on mobile devices. Use pointer events.
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.


'''Drag'n'drop'''
'''Drag and drop'''


Not considering some old ways here is basically two ways of doing it:
Common approaches:


* Use pointer events [https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events Pointer Events API]  
* [https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events Pointer Events API]
** code pen https://codepen.io/VictoriaLa/pen/MWOgYYZ
** Example: https://codepen.io/VictoriaLa/pen/MWOgYYZ
** game: Century
** Game example: Century


* Use native drag and drop [https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API HTML Drag and Drop]
* [https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API Native HTML drag and drop]
** code pen https://codepen.io/VictoriaLa/pen/rNGXKxj
** Example: https://codepen.io/VictoriaLa/pen/rNGXKxj
** game: Patchwork  
** Game example: Patchwork


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


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.
[[Category:Studio]]
[[Category:Studio]]

Revision as of 16:20, 23 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.

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.

Keep the minimum as low as reasonably possible. Large values require stronger scaling on phones, make content smaller, and increase rendering work. Use fluid layouts and CSS media queries instead of declaring a large fixed width.

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 min. It accepts true, false, or "viewport". The default is true.

The examples below use a 740-pixel game displayed in 390 pixels of available space.

autoscale: true

BGA applies CSS zoom to the game content. In the example, the scale is approximately 53%.

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.

Use this for responsive games or games with their own scaling system, such as BgaZoom. A fixed 740-pixel layout displayed in 390 pixels will otherwise overflow horizontally and may require scrolling.

autoscale: "viewport"

This mode scales the whole game document through a wider logical viewport.

Previously, when game pages were opened directly, BGA set the document viewport width and let the mobile browser fit it to the screen.

Games are now normally opened through /tableview. The game runs in an iframe, and its viewport cannot resize that iframe. Tableview emulates the same result by laying out the iframe at the requested width and applying transform: scale(...) to it.

In the example, the iframe is laid out at 740 pixels and displayed at approximately 53% scale. The game area and the BGA controls inside the iframe are scaled together.

CSS zoom participates in layout. transform: scale(...) scales after layout and usually creates a composited layer. Transforming a large iframe can be expensive on mobile devices.

Prefer autoscale: true or a responsive layout unless viewport scaling is required for compatibility.

Legacy default_viewport

Some older games contain code such as: 

 this.default_viewport = "width=740";

default_viewport started as internal framework state. Games later used it as an undocumented viewport override before game_interface_width.autoscale existed.

It remains supported to avoid breaking published games. In tableview, it enables the same iframe scaling as autoscale: "viewport" and takes precedence over the configured autoscaling mode.

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

Mobile rendering performance

Large transformed interfaces can crash iOS browsers during pinch zoom. See BGA bug #229359 and WebKit bug #172206.

Reduce the risk:

  • keep interface dimensions reasonable;
  • reduce image pixel dimensions and file sizes;
  • avoid unnecessarily large sprite sheets;
  • limit large fixed or transformed elements;
  • avoid unnecessary animation, canvas, and WebGL rendering;
  • test through /tableview, including pinch zoom on iOS.

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=30797"