Skip to main content

​
Overview

Hyperscape uses Capacitor to build native mobile apps from the web client.

​
Prerequisites

​
iOS

  • macOS with Xcode installed
  • Apple Developer account (for device testing)

​
Android

  • Android Studio installed
  • Android SDK configured

​
Build Commands

​
iOS

npm run ios          # Build, sync, and open Xcode
npm run ios:dev      # Sync and open without rebuild
npm run ios:build    # Production build

​
Android

npm run android      # Build, sync, and open Android Studio
npm run android:dev  # Sync and open without rebuild
npm run android:build # Production build

​
Sync Commands

npm run cap:sync          # Sync both platforms
npm run cap:sync:ios      # iOS only
npm run cap:sync:android  # Android only

​
Development Workflow

1

Build the web client

cd packages/client
bun run build
2

Sync to native project

npm run cap:sync
3

Open in IDE

npm run ios:dev      # Opens Xcode
# or
npm run android:dev  # Opens Android Studio
4

Run on device/simulator

Use the native IDE to build and run on your target device.

​
Configuration

​
Capacitor Config

The Capacitor configuration is in packages/client/capacitor.config.ts: 
{
  appId: 'game.hyperscape.app',
  appName: 'Hyperscape',
  webDir: 'dist',
  server: {
    // Production API URLs
    url: 'https://hyperscape.club'
  }
}

​
Environment Variables

For mobile builds, ensure these are set: 
PUBLIC_API_URL=https://api.hyperscape.club
PUBLIC_WS_URL=wss://api.hyperscape.club
PUBLIC_CDN_URL=https://cdn.hyperscape.club

​
Platform-Specific Notes

​
iOS

  • Minimum iOS version: 14.0
  • Requires provisioning profile for device testing
  • Use TestFlight for beta distribution

​
Android

  • Minimum SDK: 24 (Android 7.0)
  • Generate signed APK for distribution
  • Use Play Console for beta testing

​
Debugging

​
iOS

  1. Open Xcode from npm run ios:dev
  2. Select simulator or connected device
  3. Use Safari Web Inspector for debugging

​
Android

  1. Open Android Studio from npm run android:dev
  2. Select emulator or connected device
  3. Use Chrome DevTools for debugging
Enable USB debugging on Android devices and trust your computer on iOS devices.