> ## Documentation Index
> Fetch the complete documentation index at: https://hyperscape-ai-mintlify-docs-update.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile Development

> Build Hyperscape for iOS and Android with Capacitor

## Overview

Hyperscape uses [Tauri](https://tauri.app) 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

```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
npm run ios          # Build, sync, and open Xcode
npm run ios:dev      # Sync and open without rebuild
npm run ios:build    # Production build
```

### Android

```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
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

```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
npm run cap:sync          # Sync both platforms
npm run cap:sync:ios      # iOS only
npm run cap:sync:android  # Android only
```

## Development Workflow

<Steps>
  <Step title="Build the web client">
    ```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
    cd packages/client
    bun run build
    ```
  </Step>

  <Step title="Sync to native project">
    ```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
    npm run cap:sync
    ```
  </Step>

  <Step title="Open in IDE">
    ```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
    npm run ios:dev      # Opens Xcode
    # or
    npm run android:dev  # Opens Android Studio
    ```
  </Step>

  <Step title="Run on device/simulator">
    Use the native IDE to build and run on your target device.
  </Step>
</Steps>

## Configuration

### Capacitor Config

The Capacitor configuration is in `packages/client/capacitor.config.ts`:

```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
{
  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:

```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
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

```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
# 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](https://github.com/HyperscapeAI/hyperscape/releases)
* **Public Portal**: [https://hyperscapeai.github.io/hyperscape/](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 |

<Info>
  See `docs/native-release.md` in the repository for complete setup instructions.
</Info>

## 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

<Info>
  Enable USB debugging on Android devices and trust your computer on iOS devices.
</Info>