For the complete documentation index, see llms.txt. This page is also available as Markdown.

Safe Areas API

Games on RUN.game run inside responsive web and native host containers (iOS, Android, Web, and Desktop). Because devices have notches, dynamic islands, home indicator bars, and host navigation chrome, RUN provides automatic CSS variables, a synchronous imperative reader, and reactive lifecycle subscriptions to ensure games can position their HUD elements cleanly without overlapping system chrome.

Core Concepts

  1. Automatic CSS Custom Properties: The SDK automatically updates CSS variables on :root as the container changes or rotates.

  2. Synchronous Imperative Access: RundotGameAPI.system.getSafeArea() returns an immediate, cached snapshot of { top, right, bottom, left } updated in real time.

  3. Reactive Lifecycles: RundotGameAPI.lifecycles.onSafeAreaChanged and RundotGameAPI.lifecycles.onDeviceChanged notify game engines whenever the container geometry or orientation changes.


Integration Methods

The SDK automatically injects and maintains the following CSS custom properties on document.documentElement:

.hud-header {
  padding-top: var(--rundot-safe-area-top, 0px);
  padding-right: var(--rundot-safe-area-right, 0px);
  padding-left: var(--rundot-safe-area-left, 0px);
}

.hud-footer {
  padding-bottom: var(--rundot-safe-area-bottom, 0px);
}
  • --rundot-safe-area-top: Top inset with px suffix (e.g. 44px).

  • --rundot-safe-area-right: Right inset with px suffix (e.g. 0px).

  • --rundot-safe-area-bottom: Bottom inset with px suffix (e.g. 34px).

  • --rundot-safe-area-left: Left inset with px suffix (e.g. 0px).

2. Reactive Subscriptions (Engine / Canvas Layouts)

If your game logic positions HUD items or canvas viewports procedurally (e.g. Three.js, Phaser, Pixi):

3. Synchronous Imperative Read

Safe area insets are available synchronously after successful import initialization. If initialization fails, getSafeArea() throws: [RUN] Safe area not available. SDK initialization has not completed. Check the SDK initialization error in the console before calling getSafeArea().


API Reference

Method
Namespace
Returns
Description

getSafeArea()

RundotGameAPI.system

SafeArea

Returns the current safe area insets in pixels { top, right, bottom, left }. Primary source of truth.

getDevice()

RundotGameAPI.system

DeviceInfo

Returns device information including screen and viewport dimensions, DPR, and orientation.

onSafeAreaChanged(callback)

RundotGameAPI.lifecycles

Subscription

Subscribes to host safe area updates. Returns an object with .unsubscribe().

onDeviceChanged(callback)

RundotGameAPI.lifecycles

Subscription

Subscribes to host device & viewport dimension updates. Returns an object with .unsubscribe().

RundotGameAPI.system.getSafeArea(): SafeArea

Returns the safe-area insets the host computed for this game. The value includes device safe areas (notches, home indicator) plus host navigation chrome, so you can treat it as the single source of truth for usable layout bounds. Safe area insets are available synchronously after successful import initialization. If initialization fails, this method throws '[RUN] Safe area not available. SDK initialization has not completed. Check the SDK initialization error in the console before calling getSafeArea().'.

All four fields are numbers in pixels:

Example:

RundotGameAPI.lifecycles.onSafeAreaChanged(callback: (safeArea: SafeArea) => void): Subscription

Registers a listener called whenever safe area insets change (e.g. screen orientation change, foldable unfolding, system chrome toggle).

RundotGameAPI.lifecycles.onDeviceChanged(callback: (device: DeviceInfo) => void): Subscription

Registers a listener called whenever device orientation or viewport dimensions change.


Layout Tips

  • Combine safe-area padding with your own gameplay gutters. getSafeArea() guarantees you won't overlap system chrome.

  • Treat RundotGameAPI.system.getSafeArea() and var(--rundot-safe-area-*) as the source of truth (they include both device safe areas and host chrome).

  • For games declared with --orientation both or games supporting rotation, use CSS variables or lifecycles.onSafeAreaChanged rather than caching insets once on load.

Deprecated paths

Deprecated
Replacement

RundotGameAPI.context.safeArea

RundotGameAPI.system.getSafeArea() or lifecycles.onSafeAreaChanged

RundotGameAPI.context.device

RundotGameAPI.system.getDevice() or lifecycles.onDeviceChanged

HudInsets type

SafeArea type

Last updated