> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playtolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overlay UI
> Open the Playtolia menu and its screens from your own buttons with GameScaffold
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#.
### Opening the menu
`LaunchMenu()` opens the overlay menu. The result is the same as a player tap on the floating Playtolia button:
```c# theme={null}
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:
```c# theme={null}
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.
`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.
### Where the menu opens
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:
```c# theme={null}
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 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()`:
```c# theme={null}
// 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 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:
```c# theme={null}
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:
```c# theme={null}
// #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:
```c# theme={null}
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`.