Your game mobile version - Revision history

BROT42 at 17:23, 24 July 2026

2026-07-24T17:23:13Z

← Older revision		Revision as of 19:23, 24 July 2026
Line 63:		Line 63:

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

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

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

	BGA applies CSS <code>[https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/zoom zoom]</code> to the game content~~. In the example, the scale is approximately 53%~~.		BGA applies CSS <code>[https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/zoom zoom]</code> to the game content.

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

BROT42 at 17:22, 24 July 2026

2026-07-24T17:22:03Z

← Older revision		Revision as of 19:22, 24 July 2026
Line 8:		Line 8:

	<code>game_interface_width.min</code> is the smallest logical width at which your game remains usable. The default is 740 pixels.		<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 it in '''gameinfos.jsonc''':

BROT42 at 17:12, 24 July 2026

2026-07-24T17:12:43Z

← Older revision		Revision as of 19:12, 24 July 2026
Line 21:		Line 21:
	The declared width must actually work. If you declare 540 pixels, the complete interface must remain usable at 540 pixels.		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~~.		{{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.
			}}

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

	Examples:		Examples:

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

	* In '''Seasons''', panels normally displayed to the right of the board are moved below it:		*In '''Seasons''', panels normally displayed to the right of the board are moved below it:

	@media only screen and (max-width: 970px) {		@media only screen and (max-width: 970px) {
Line 56:		Line 58:
	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.		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 ===		===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>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>.
Line 62:		Line 64:
	The examples below use a 740-pixel game displayed in 390 pixels of available space.		The examples below use a 740-pixel game displayed in 390 pixels of available space.

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

	BGA applies CSS <code>zoom</code> to the game content. In the example, the scale is approximately 53%.		BGA applies CSS <code>[https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/zoom zoom]</code> to the game content. In the example, the scale is approximately 53%.

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

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

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

	===== Coordinates and animations =====		=====Coordinates and animations=====

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

	==== <code>autoscale: false</code> ====		====<code>autoscale: false</code> ====

	BGA does not scale the game area.		BGA does not scale the game area.
Line 95:		Line 97:
	A fixed 740-pixel layout displayed in 390 pixels of available space will overflow horizontally and may require scrolling.		A fixed 740-pixel layout displayed in 390 pixels of available space will overflow horizontally and may require scrolling.

	==== <code>autoscale: "viewport"</code> ====		====<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 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.
Line 103:		Line 105:
	It also has important drawbacks:		It also has important drawbacks:

	* action bars, player panels, dialogs, and other game-page controls are scaled down with the game;		*action bars, player panels, dialogs, and other game-page controls are scaled down with the game;
	* text and controls can become very small;		*text and controls can become very small;
	* the layout does not adapt to the available space;		*the layout does not adapt to the available space;
	* scaling the entire game document is more expensive to render.		*scaling the entire game document is more expensive to render.

	{{Warn\|1=		{{Warn\|1=
Line 124:		Line 126:
	}}		}}

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

	BGA adds <code>touch-device</code> to <code>#ebd-body</code> when it detects a touchscreen, and <code>notouch-device</code> otherwise.		BGA adds <code>touch-device</code> to <code>#ebd-body</code> when it detects a touchscreen, and <code>notouch-device</code> otherwise.
Line 144:		Line 146:
	Common approaches:		Common approaches:

	* [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]
	** Example: https://codepen.io/VictoriaLa/pen/MWOgYYZ		**Example: https://codepen.io/VictoriaLa/pen/MWOgYYZ
	** Game example: Century		**Game example: Century

	* [https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API Native HTML drag and drop]		*[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		**Example: https://codepen.io/VictoriaLa/pen/rNGXKxj
	** Game example: 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.		Add <code>touch-action: none</code> only to elements where you handle touch or pointer gestures and need to suppress native scrolling or zooming.

	[[Category:Studio]]		[[Category:Studio]]

BROT42 at 16:38, 24 July 2026

2026-07-24T16:38:40Z

← Older revision		Revision as of 18:38, 24 July 2026
Line 89:		Line 89:
	BGA does not scale the game area.		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.		{{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> ====		==== <code>autoscale: "viewport"</code> ====
Line 104:		Line 108:
	* scaling the entire game document is more expensive to render.		* scaling the entire game document is more expensive to render.

	Do not use viewport scaling as a shortcut for building a responsive interface. ~~Prefer <code>autoscale: true</code> or responsive CSS unless the game has a confirmed compatibility problem with CSS zoom.~~		{{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=		{{Warn\|1=

BROT42 at 14:54, 23 July 2026

2026-07-23T14:54:34Z

← Older revision		Revision as of 16:54, 23 July 2026
Line 58:		Line 58:
	=== Autoscale ===		=== 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>.		<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>.

	The examples below use a 740-pixel game displayed in 390 pixels of available space.		The examples below use a 740-pixel game displayed in 390 pixels of available space.
Line 93:		Line 93:
	==== <code>autoscale: "viewport"</code> ====		==== <code>autoscale: "viewport"</code> ====

	This mode ~~scales~~ the whole game ~~document~~ through a wider logical 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.

	~~Previously, when game pages were opened directly, BGA set the document viewport width~~ and ~~let the mobile browser fit it to the screen~~.		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.

	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.~~		It also has important drawbacks:

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

	~~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~~.		Do not use viewport scaling as a shortcut for building a responsive interface. Prefer <code>autoscale: true</code> or responsive CSS unless the game has a confirmed compatibility problem with CSS zoom.

	Prefer <code>autoscale: true</code> or a responsive ~~layout~~ unless ~~viewport scaling is required for~~ compatibility.

	{{Warn\|1=		{{Warn\|1=
	'''Legacy <code>default_viewport</code>'''		'''Legacy <code>default_viewport</code>'''

	Some older games ~~contain~~ code ~~such as~~:		Some older games set the internal field <code>default_viewport</code> directly:

	this.default_viewport = "width=740";		this.default_viewport = "width=740";

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

	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.

	~~'''Do not use it in new code.''' Existing games should test removing it and use <code>game_interface_width</code> instead.~~
	}}

	~~{{Warn\|1=~~
	~~'''Mobile rendering performance'''~~

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

	~~Reduce the risk:~~

	* keep interface dimensions reasonable;		'''Do not use it in new code.''' Existing games should test removing it and configure scaling through <code>game_interface_width</code> instead.
	* 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.
	}}		}}

BROT42 at 14:49, 23 July 2026

2026-07-23T14:49:14Z

← Older revision		Revision as of 16:49, 23 July 2026
Line 105:		Line 105:
	Prefer <code>autoscale: true</code> or a responsive layout unless viewport scaling is required for compatibility.		Prefer <code>autoscale: true</code> or a responsive layout unless viewport scaling is required for compatibility.

	=~~===~~ Legacy <code>default_viewport</code> ~~====~~		{{Warn\|1=
			'''Legacy <code>default_viewport</code>'''

	Some older games contain code such as:		Some older games contain code such as:
Line 115:		Line 116:
	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.		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.

	Do not use it in new code. Existing games should test removing it and use <code>game_interface_width</code> instead.		'''Do not use it in new code.''' Existing games should test removing it and use <code>game_interface_width</code> instead.
			}}

	=~~===~~ Mobile rendering performance ~~====~~		{{Warn\|1=
			'''Mobile rendering performance'''

	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].		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].
Line 127:		Line 130:
	* avoid unnecessarily large sprite sheets;		* avoid unnecessarily large sprite sheets;
	* limit large fixed or transformed elements;		* limit large fixed or transformed elements;
	* avoid unnecessary animation, canvas, and WebGL rendering;		* avoid unnecessary animation, canvas, and WebGL rendering.
			}}

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

BROT42 at 14:24, 23 July 2026

2026-07-23T14:24:13Z

← Older revision		Revision as of 16:24, 23 July 2026
Line 128:		Line 128:
	* limit large fixed or transformed elements;		* limit large fixed or transformed elements;
	* avoid unnecessary animation, canvas, and WebGL rendering;		* avoid unnecessary animation, canvas, and WebGL rendering;
	* test through <code>/tableview</code>, including pinch zoom on iOS.

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

BROT42: clarify game_interface_width.autoscale and overall polish

2026-07-23T14:20:50Z

clarify game_interface_width.autoscale and overall polish

Show changes

Thoun: Remove the part suggesting to hack the framework

2026-07-07T12:36:11Z

Remove the part suggesting to hack the framework

← Older revision		Revision as of 14:36, 7 July 2026
Line 128:		Line 128:

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

	~~== Viewport <meta> tag ==~~

	~~Disclaimer: the infamouse chrome update 128 changed zoom implementation (properly below), as a result framework code was changed (Sep 2024) and text below may not be applicable.~~
	~~Please follow discussion on dev discord for now and update wiki if you have more information. There is autoscale option in 'game_interface_width' to mitigate some of the zoom issues.~~

	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~~
	~~(that is probably already there, just make sure min is set to minimum value)~~
	~~<pre>~~
	~~'game_interface_width' => [~~
	~~'min' => 550,~~
	],
	~~</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();~~

	~~...~~
	},

	~~// To be overrided by games~~
	~~onScreenWidthChange: function () {~~
	~~// Remove broken "zoom" property added by BGA framework~~
	~~this.gameinterface_zoomFactor = 1;~~
	~~$("page-content").style.removeProperty("zoom");~~
	~~$("page-title").style.removeProperty("zoom");~~
	~~$("right-side-first-part").style.removeProperty("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.

	This code you cannot really test in desktop browser because bga framework with check window.orientation field which is likely not set on desktop, if you want to test on desktop (and override landscape viewport) you can add this code and the end of onScreenWidthChange. I suggest to remove it after testing

	~~<pre>~~
	~~var viewport = document.querySelector('meta[name="viewport"]');~~
	~~if (viewport) {~~
	~~viewport.content = this.default_viewport;~~
	}
	~~</pre>~~


	[[Category:Studio]]		[[Category:Studio]]

Thoun at 10:06, 20 April 2026

2026-04-20T10:06:29Z

← Older revision		Revision as of 12:06, 20 April 2026
Line 17:		Line 17:
	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.		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.jsonc''' :


	// Game interface width range (pixels)		// Game interface width range (pixels)
	// Note: game interface = space on the left side, without the column on the right		// Note: game interface = space on the left side, without the column on the right
	'game_interface_width' => ~~array(~~		"game_interface_width" => {

	// Minimum width		// Minimum width
Line 28:		Line 28:
	// maximum possible value: 740 (i.e. your game interface should fit with a 740px width, corresponding 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 lower the 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,
	),		},