Overlay UI

By default, players open Playtolia with the floating Playtolia button that the SDK draws over your game. You can also open Playtolia from your own UI. Two examples are a “Playtolia” row in your settings screen and a support entry in your pause menu. GameScaffold gives you these calls in C#.

The floating Playtolia button over a running game — The floating Playtolia button resting in the bottom-left corner of a game

LaunchMenu() opens the overlay menu. The result is the same as a player tap on the floating Playtolia button:

using PlaytoliaSDK.Runtime;

// Wire this to your own button's onClick
GameScaffold.LaunchMenu();

This is sufficient for the usual case: your button opens our menu.

Opening a specific screen

To open one screen directly and skip the menu, induce the matching event:

using PlaytoliaSDK.Runtime;
using Playtolia.Entity.Scaffold;

GameScaffold.Induce(InducedScaffoldEvent.UIShowSettings);

LaunchMenu() is a short form of Induce(InducedScaffoldEvent.UIShowMenu). If you prefer one call site, you can use Induce for all of the screens.

Event	Opens
`UIShowMenu`	The main overlay menu
`UIShowSettings`	The settings screen
`UIShowProfile`	The player’s profile screen
`UIShowFriends`	The friends list
`UIShowTickets`	The player’s support tickets
`UICreateTicket`	The new support ticket form

What happens when the player is signed out

Every screen in the table needs a player that is signed in. If the player is signed out, the SDK shows the login prompt instead of the screen that you asked for. You do not need to make sure that the player is signed in before these calls. After the player signs in, the prompt closes and the SDK returns the player to your game. Call the method again to open the screen.

The Playtolia login prompt shown as a bottom sheet over a game — The login prompt in the default bottom sheet presentation

The Playtolia login prompt shown as a left side panel over a game — The same prompt as a side panel

UIShowFriends also needs the social component. If enableSocial is off in your declarative settings, the SDK ignores the call and writes a warning to the log.

By default, the menu and every screen from the menu slide up from the bottom of the screen. A game can show them as a side panel instead. The panel is anchored to the leading screen edge and covers half of the screen width:

using Playtolia.Entity.Scaffold;

GameScaffold.SetOverlayMenuPresentation(OverlayMenuPresentation.LeftPanel);

// Optional: a wider or narrower panel, as a fraction of the screen. Clamped to 0.2..1
GameScaffold.SetOverlayMenuPanelWidthFraction(0.6f);

You can also set this value one time under Project Settings ▸ Playtolia ▸ Overlay with Menu Presentation. Both presentations use the same screens, the same back and close behavior, and the same scrim that closes the menu on a tap outside. Nothing else in your integration changes. If you change the presentation while the menu is open, the new presentation applies at the next time that the menu opens. The menu tile grid adapts to the available space: three columns on a wide screen, two columns on a phone, and one column in a narrow panel. The labels stay readable at half width.

The Playtolia overlay menu shown as a bottom sheet, tiles laid out in three columns — The overlay menu as a bottom sheet, with room for three columns of tiles

The Playtolia overlay menu shown as a left side panel, tiles laid out in two columns — The same menu as a side panel, where the grid drops to two columns

The SDK draws the panel edge to edge. The surface of the panel goes behind the status bar and the home indicator. Each screen applies the safe-area insets in its own scroll area. Thus the content starts clear of the system bars, but it scrolls behind them. The panel does not keep a fixed empty strip.

Showing and hiding the floating button

These methods control the floating Playtolia button only. They do not open or close the menu. If you want your own button to be the only entry point, use these methods together with LaunchMenu():

// Hide the floating button, e.g. during a cutscene, or permanently if
// your own UI is the only way into Playtolia
GameScaffold.HideOverlay();

GameScaffold.ShowOverlay();

A hidden floating button does not disable Playtolia. The screens that you open with LaunchMenu() or Induce() continue to work while the button is hidden.

Moving and minimizing the floating button

Players can drag the button to any position on the screen. The snap mode controls the position of the button after the player releases it:

Snap mode	On release	Edges it can use
`EdgeLeftRight` (default)	Keeps the height at release and moves to the nearest side	Left, right
`EdgeTopBottom`	Keeps the horizontal position at release and moves to the top or the bottom	Top, bottom
`EdgeAny`	Moves to the nearest of the four edges and keeps the position along that edge	All four
`Corner`	Moves to the nearest of the four corners	Left, right
`Free`	Stays at the position of release	Left, right

The name of each edge mode gives the edges that the mode allows, not the axis of the movement, because these two readings are opposites. The older name Edge still parses as EdgeLeftRight, and existing settings continue to work. When the player pushes the button past an edge that its mode allows, the button minimizes into a notch on that edge. The notch has a chevron that points inward. The notch is a pill along the edge, and it turns with the edge: upright on the left and the right, flat on the top and the bottom. The straight side of the notch sits on the device’s safe-area boundary. A tap on the notch expands the button and opens the menu. A swipe inward also expands the button. The SDK judges the swipe by its distance and its speed. Thus a quick flick works, even when the finger stops again over the edge. The slide and the shape change run as one movement, not as two separate animations.

The Playtolia button minimized into a notch on the left edge of the screen — Minimized against the left edge: an upright pill with its flat side on the screen bound and the chevron pointing inward

The Playtolia button minimized into a notch on the bottom edge of the screen — Minimized against the bottom edge: the same notch turned flat, chevron pointing up

The SDK stores a position that the player chose with the other user preferences. Thus the button returns to that position at the next app start, and not to the anchor from the settings. Dragging is enabled by default. To disable dragging for a game, clear Enable Overlay Button Dragging under Project Settings ▸ Playtolia ▸ Overlay. The same page also gives the snap mode. You can control all of these values at runtime:

GameScaffold.SetOverlayButtonDraggingEnabled(false);
GameScaffold.SetOverlayButtonSnapMode(OverlayButtonSnapMode.Free);
GameScaffold.SetOverlayButtonAnchor(OverlayButtonAnchor.TopRight);
GameScaffold.SetOverlayButtonMinimized(true);

// Fractions of the button's free travel area: x from 0 at the start margin to 1 at the
// end margin, y from 0 at the top margin to 1 at the bottom margin
GameScaffold.SetOverlayButtonPosition(1f, 0.35f);

The SDK clamps the position values to 0..1. If you change the anchor or the position while the button is minimized, the notch can also move to a different edge. The SDK selects that edge from the edges that the current snap mode allows. If you change to a mode that does not allow the current edge of the button, the SDK docks the button again. For example, a button that is minimized on the left moves to the top or to the bottom with EdgeTopBottom.

Appearance and idle glass effect

When the SDK first shows the button, the button and the Playtolia logo scale, rotate, and fade into place. After a short period without a tap or a drag, the background of the button changes to a lighter translucent glass appearance. Each interaction restores the active appearance and starts the idle timer again. While a finger is on the button (a press or a drag), the button keeps its active appearance, and the idle and auto-hide timers start when the finger lifts. Under Project Settings ▸ Playtolia ▸ Overlay, you can customize both states without changing SDK code:

Background Color themes the expanded button and collapsed drawer together.
Expanded Icon and Collapsed Icon accept PNG, JPEG, or SVG assets. Clear either Show Expanded Icon or Show Collapsed Icon to remove that state’s logo/arrow entirely.
Expanded Length Along Edge and Expanded Depth From Edge are literal dimensions. The same length/depth model is used for the collapsed state, so size control does not change meaning when the button moves between the top, side, and bottom edges.
Expanded Corner Radius controls the normal generated button. Set it to 0 for a sharp, classic MMO-style drawer.
Collapsed Length, Collapsed Thickness, and Collapsed Corner Radius control the edge drawer independently. Values larger than the expanded host are safely clamped.

For a completely custom design, assign Expanded Artwork and/or Collapsed Artwork under Complete Custom Artwork. Full artwork bypasses the SDK background, border, corners, and icon for that state. PNG, JPEG, and SVG are supported. Artwork is authored horizontally with its docked edge at the bottom; Follow Docked Edge rotates it for every dock position instead of stretching it. The visual container grows from the edge-facing side rather than its center. The docked edge therefore stays fixed during collapse/expansion, avoiding the apparent scale-up or sideways jump common with center-anchored drawer artwork. Imported assets are embedded in the generated native configuration at build time, so they do not require a network request at runtime. Native KMP callers may also supply a URL or data URI. You can set the appearance at runtime:

// #RRGGBB or #AARRGGBB
GameScaffold.SetOverlayButtonBackgroundColor("#CC111416");

GameScaffold.SetOverlayButtonOpacity(0.95f);
GameScaffold.SetOverlayButtonIdleOpacity(0.48f);
GameScaffold.SetOverlayButtonMinimizedOpacity(0.6f);
GameScaffold.SetOverlayButtonIdleDelay(2500);

The SDK clamps the opacity values to 0..1. A negative idle delay becomes zero. The minimized opacity applies while the button is in its notch. This value has priority over the active value and over the idle value. With auto-hide on, a button therefore fades to the idle opacity first and then changes to the minimized opacity when it docks. Set the minimized opacity at or below the idle opacity if the notch must not become more visible than the idle button. Each opacity value applies to the whole generated background: the fill, the highlight, the border, and the shadow. An opacity of 0 leaves only the icon visible. Custom artwork is not affected by these values.

Safe-area placement

Respect Device Safe Area is enabled by default. Android reads the system safe-drawing insets (including display cutouts and system bars), while iOS reads safeAreaInsets. The SDK uses all four sides and recalculates placement when the available geometry changes, including rotation. This keeps the expanded button and the reachable part of the collapsed drawer away from notches, the Dynamic Island, and the home indicator without maintaining a device list. Safe Area Padding adds extra space inside the OS-reported boundary. Disable safe-area handling only when the game deliberately owns its own inset strategy.

Auto-hide

With auto-hide on, the button minimizes itself against its current side after a period without a touch. Only the notch stays over your game. A tap or a swipe on the notch expands the button again, and each interaction starts the timer again. Auto-hide never operates while the overlay menu is open. Auto-hide is off by default. To enable auto-hide, set Auto-Hide Overlay Button under Project Settings ▸ Playtolia ▸ Overlay. You can also enable it at runtime:

GameScaffold.SetOverlayButtonAutoHideEnabled(true);

// Measured from the last interaction, so this fires 5 seconds after the player lets go
GameScaffold.SetOverlayButtonAutoHideDelay(5000);

The SDK measures the delay from the last interaction, not from the idle transition. Thus a delay that is less than the idle delay minimizes the button when the button becomes idle. Native KMP clients can set the same behavior with ScaffoldStateful. They can also set the initial values in DeclarativeSettings. These settings are overlayMenuPresentation, overlayMenuPanelWidthFraction, overlayButtonAnchor, overlayButtonPositionX, overlayButtonPositionY, overlayButtonSnapMode, overlayButtonMinimized, overlayButtonDraggingEnabled, overlayButtonBackgroundColor, overlayButtonOpacity, overlayButtonIdleOpacity, overlayButtonMinimizedOpacity, overlayButtonIdleDelayMillis, overlayButtonAutoHideEnabled, overlayButtonAutoHideDelayMillis, overlayButtonIcon, overlayButtonMinimizedIcon, overlayButtonShowIcon, overlayButtonShowMinimizedIcon, overlayButtonExpandedArtwork, overlayButtonMinimizedArtwork, overlayButtonArtworkFollowsEdge, overlayButtonSizeDp, overlayButtonExpandedLengthDp, overlayButtonExpandedThicknessDp, overlayButtonCornerRadiusDp, overlayButtonMinimizedLengthDp, overlayButtonMinimizedThicknessDp, overlayButtonMinimizedCornerRadiusDp, overlayButtonRespectSafeArea, and overlayButtonSafeAreaPaddingDp.

Get Started

Features

Billing

Advanced

Opening the menu

Opening a specific screen

What happens when the player is signed out

Where the menu opens

Showing and hiding the floating button

Moving and minimizing the floating button

Appearance and idle glass effect

Safe-area placement

Auto-hide

​Opening the menu

​Opening a specific screen

​What happens when the player is signed out

​Where the menu opens

​Showing and hiding the floating button

​Moving and minimizing the floating button

​Appearance and idle glass effect

​Safe-area placement

​Auto-hide

Opening the menu

Opening a specific screen

What happens when the player is signed out

Where the menu opens

Showing and hiding the floating button

Moving and minimizing the floating button

Appearance and idle glass effect

Safe-area placement

Auto-hide