Mobile Development

Build Hyperscape for iOS and Android with Capacitor

Overview

Hyperscape uses Tauri to build native desktop and mobile apps from the web client. The build system supports Windows, macOS, Linux, iOS, and Android with automated CI/CD via GitHub Actions.

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.lol'
  }
}

Environment Variables

For mobile builds, ensure these are set:

PUBLIC_API_URL=https://api.hyperscape.lol
PUBLIC_WS_URL=wss://api.hyperscape.lol
PUBLIC_CDN_URL=https://cdn.hyperscape.lol

Automated Release Builds

Hyperscape uses GitHub Actions to automatically build native apps for all platforms when you create a tagged release.

Creating a Release

# Tag a new version
git tag v1.0.0
git push origin v1.0.0

This triggers the .github/workflows/build-app.yml workflow which builds:

• Windows: .msi installer
• macOS: .dmg installer (Intel + Apple Silicon universal binary)
• Linux: .AppImage and .deb packages
• iOS: .ipa bundle (requires Apple Developer account)
• Android: .apk bundle

Download Portal

Built apps are automatically published to:

• GitHub Releases: https://github.com/HyperscapeAI/hyperscape/releases
• Public Portal: https://hyperscapeai.github.io/hyperscape/

Required Secrets

For the build workflow to succeed, configure these GitHub repository secrets:

Secret	Purpose	Required For
APPLE_CERTIFICATE	Code signing certificate (base64)	macOS, iOS
APPLE_CERTIFICATE_PASSWORD	Certificate password	macOS, iOS
APPLE_SIGNING_IDENTITY	Developer ID	macOS, iOS
APPLE_ID	Apple ID email	macOS, iOS
APPLE_PASSWORD	App-specific password	macOS, iOS
APPLE_TEAM_ID	Developer team ID	macOS, iOS
TAURI_PRIVATE_KEY	Updater signing key	All platforms
TAURI_KEY_PASSWORD	Key password	All platforms

See docs/native-release.md in the repository for complete setup instructions.

Platform-Specific Notes

iOS

• Minimum iOS version: 13.0
• Requires provisioning profile for device testing
• Automated builds via GitHub Actions on tagged releases
• Manual builds: cd packages/app && bun run tauri ios build

Android

• Minimum SDK: 24 (Android 7.0)
• Automated builds via GitHub Actions on tagged releases
• Manual builds: cd packages/app && bun run tauri android build

Desktop

• Windows: Requires Windows 10+ (x64)
• macOS: Universal binary (Intel + Apple Silicon)
• Linux: AppImage (portable) and .deb (Debian/Ubuntu)

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.