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
Automatic CSS Custom Properties: The SDK automatically updates CSS variables on
:rootas the container changes or rotates.Synchronous Imperative Access:
RundotGameAPI.system.getSafeArea()returns an immediate, cached snapshot of{ top, right, bottom, left }updated in real time.Reactive Lifecycles:
RundotGameAPI.lifecycles.onSafeAreaChangedandRundotGameAPI.lifecycles.onDeviceChangednotify game engines whenever the container geometry or orientation changes.
Integration Methods
1. Automatic CSS Custom Properties (Recommended for DOM/UI)
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 withpxsuffix (e.g.44px).--rundot-safe-area-right: Right inset withpxsuffix (e.g.0px).--rundot-safe-area-bottom: Bottom inset withpxsuffix (e.g.34px).--rundot-safe-area-left: Left inset withpxsuffix (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
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()andvar(--rundot-safe-area-*)as the source of truth (they include both device safe areas and host chrome).For games declared with
--orientation bothor games supporting rotation, use CSS variables orlifecycles.onSafeAreaChangedrather than caching insets once on load.
Deprecated paths
RundotGameAPI.context.safeArea
RundotGameAPI.system.getSafeArea() or lifecycles.onSafeAreaChanged
RundotGameAPI.context.device
RundotGameAPI.system.getDevice() or lifecycles.onDeviceChanged
HudInsets type
SafeArea type
Last updated