Mobile API & Capacitor Plugins

GemShell Desktop API on Mobile

The GemShell JavaScript API (file system, Steam, window, dialog, etc.) is desktop-only — it's not available in mobile builds. Mobile apps run in a native WebView and don't have access to the desktop runtime.

For mobile-specific device features, use Capacitor plugins.

Capacitor Core APIs

Capacitor provides built-in APIs available in every GemShell mobile build:

import { App } from '@capacitor/app'
import { Device } from '@capacitor/device'
import { Haptics } from '@capacitor/haptics'
import { Preferences } from '@capacitor/preferences'
import { ScreenOrientation } from '@capacitor/screen-orientation'

Plugin	What it does
@capacitor/app	App state, back button, deep links
@capacitor/device	Device info, platform, OS version
@capacitor/preferences	Key-value storage (replaces localStorage for persistence)
@capacitor/haptics	Vibration / haptic feedback
@capacitor/screen-orientation	Lock/unlock screen orientation at runtime
@capacitor/keyboard	Keyboard visibility and behavior
@capacitor/status-bar	Show/hide/style the status bar
@capacitor/splash-screen	Control the splash screen

Full list: capacitorjs.com/docs/apis

Adding Capacitor Plugins

Add plugins via gemshell.config.json — GemShell installs them automatically during build:

{
  "mobile": {
    "capacitor_plugins": [
      "@capacitor/haptics",
      "@capacitor/screen-orientation"
    ]
  }
}

Then use them in your game:

import { Haptics, ImpactStyle } from '@capacitor/haptics'

// On touch/collision
async function onImpact() {
  await Haptics.impact({ style: ImpactStyle.Medium })
}

Platform Detection

import { Capacitor } from '@capacitor/core'

if (Capacitor.isNativePlatform()) {
  // Running on iOS or Android
  const platform = Capacitor.getPlatform() // 'ios' | 'android' | 'web'
}

Saving Game Data

On mobile, localStorage can be cleared by the OS. Use @capacitor/preferences for persistent save data:

import { Preferences } from '@capacitor/preferences'

// Save
await Preferences.set({ key: 'save_slot_1', value: JSON.stringify(saveData) })

// Load
const { value } = await Preferences.get({ key: 'save_slot_1' })
const saveData = value ? JSON.parse(value) : null

// Delete
await Preferences.remove({ key: 'save_slot_1' })

Screen Orientation

GemShell sets the orientation at build time based on your window size. To change it at runtime:

import { ScreenOrientation } from '@capacitor/screen-orientation'

// Lock to landscape
await ScreenOrientation.lock({ orientation: 'landscape' })

// Unlock (follow device orientation)
await ScreenOrientation.unlock()

Add @capacitor/screen-orientation to capacitor_plugins in your config first.

Community Plugins

Browse hundreds of community Capacitor plugins at capawesome.io and github.com/capacitor-community.

Popular ones for games:

Plugin	Purpose
@capacitor-community/admob	Google AdMob ads
@capacitor-community/in-app-purchases-2	iOS/Android in-app purchases
@capawesome/capacitor-firebase	Firebase (analytics, auth, Firestore)
@capacitor-community/sqlite	SQLite database

TypeScript Types

All official Capacitor plugins ship with TypeScript definitions. Install the plugin via capacitor_plugins and import directly — types are included.

For type-safe platform detection:

import { Capacitor } from '@capacitor/core'

const isIos = Capacitor.getPlatform() === 'ios'
const isAndroid = Capacitor.getPlatform() === 'android'
const isNative = Capacitor.isNativePlatform()