---
id: "0072h"
title: "gamedev — iOS build (Xcode + Metal via sokol + safe area + WalletConnect)"
status: pendiente
type: feature
domain:
  - gamedev
scope: multi-app
priority: media
depends:
  - "0072b"
  - "0072c"
blocks: []
related: []
created: 2026-05-10
updated: 2026-05-17
tags:
  - gamedev
  - ios
  - mobile
---

## Objetivo

Compilar el runtime gamedev a IPA iOS, ejecutarlo en device (iPhone/iPad) usando Metal como backend grafico via sokol_gfx, gestionar touch input + virtual gamepad (compartido con Android), integrar WalletConnect para wallets crypto, y cumplir presupuesto IPA ≤ 25 MB.

## Requisitos duros

- **Mac fisico** o GitHub/Gitea Actions con runner `macos-latest`. NO se puede compilar iOS desde Linux/Windows.
- **Apple Developer Program**: 99 USD/año para distribucion en App Store. Para test en device propio: cuenta gratuita basta (signing limited).
- **Xcode 15+** instalado en el mac.
- iPhone/iPad de prueba con iOS 15+.

## Toolchain

Si tenemos mac local: instalar Xcode + command line tools.

Si NO: GitHub Actions workflow (`gamedev-ios-build.yml`):
```yaml
runs-on: macos-latest
steps:
  - uses: actions/checkout@v4
  - run: brew install cmake ninja
  - run: cmake -B build -S cpp/apps/<app> -GXcode -DCMAKE_SYSTEM_NAME=iOS
  - run: cmake --build build --config Release -- -sdk iphoneos
  - run: xcodebuild -project build/<app>.xcodeproj -scheme <app> archive
  # Upload artifact
```

Coste: GitHub free tier no incluye macos minutes. Gitea Actions self-hosted en mac local es opcion si tenemos uno.

## CMake con Metal backend

```cmake
if(IOS)
    target_compile_definitions(<target> PRIVATE SOKOL_METAL)
    target_link_libraries(<target> PRIVATE
        "-framework Metal"
        "-framework MetalKit"
        "-framework Foundation"
        "-framework UIKit"
        "-framework AVFoundation"  # miniaudio
        "-framework AudioToolbox"
    )
endif()
```

sokol_gfx tiene backend Metal nativo. Mismo codigo C++ del juego, sokol traduce las llamadas. Shaders: SPIRV-Cross convierte GLSL → MSL en build (sub-issue 0072c).

## Touch input

SDL3 ya tiene `SDL_FINGERDOWN/UP/MOTION` en iOS. `input_unified_cpp_gamedev` (de 0072b) los recibe igual que Android. Mismo `virtual_gamepad_cpp_gamedev` (de 0072g) sin cambios.

## Safe area

iOS notch + home indicator. SDL3: `SDL_GetWindowSafeArea`. Mismo helper `safe_area_cpp_gamedev` que Android.

## Info.plist

```xml
<key>UILaunchScreen</key>
<dict><key>UIColorName</key><string>LaunchScreenColor</string></dict>
<key>UISupportedInterfaceOrientations</key>
<array>
    <string>UIInterfaceOrientationLandscapeLeft</string>
    <string>UIInterfaceOrientationLandscapeRight</string>
</array>
<!-- WalletConnect deep link: -->
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array><string><app_name></string></array>
    </dict>
</array>
<!-- Universal links opcional: -->
<key>com.apple.developer.associated-domains</key>
<array><string>applinks:<app>.example.com</string></array>
```

## Crypto wallet en iOS

Mismo plan que Android (sub-issue 0072g): WalletConnect deep links via Universal Links o custom URL schemes. Wallets compatibles: MetaMask iOS, Trust iOS, Rainbow, Coinbase Wallet.

Apple es estricto con apps que tocan crypto:
- App Store Review Guideline **3.1.5 (b)** permite NFTs y blockchain features.
- NO se puede usar IAP (in-app purchase) para comprar crypto/NFTs — debe ser tx on-chain directa.
- NO ofrecer "rewards" en crypto sin disclaimers (3.1.1 anti-bypass).

Documentar en `cpp/GAMEDEV.md` seccion "iOS App Store compliance".

## Pipeline de build

`bash/functions/pipelines/build_ios_cpp_pipelines.sh` (corre solo en mac):

```bash
#!/usr/bin/env bash
set -euo pipefail
APP="$1"
SRC="cpp/apps/$APP"
BUILD="build/ios/$APP"

cmake -B "$BUILD" -S "$SRC" -GXcode \
    -DCMAKE_SYSTEM_NAME=iOS \
    -DCMAKE_OSX_DEPLOYMENT_TARGET=15.0 \
    -DCMAKE_OSX_ARCHITECTURES=arm64

cmake --build "$BUILD" --config Release -- -sdk iphoneos
# Archive + export
xcodebuild -project "$BUILD/$APP.xcodeproj" \
    -scheme "$APP" -configuration Release \
    -archivePath "$BUILD/$APP.xcarchive" archive
xcodebuild -exportArchive \
    -archivePath "$BUILD/$APP.xcarchive" \
    -exportPath "$BUILD/ipa" \
    -exportOptionsPlist exportOptions.plist
```

## Signing

`exportOptions.plist`:
```xml
<dict>
    <key>method</key><string>development</string>  <!-- o app-store -->
    <key>teamID</key><string>XXXXXXXXXX</string>
    <key>signingStyle</key><string>automatic</string>
</dict>
```

Para CI: usar **fastlane match** o secrets de Apple Developer. Out of scope inicial — primer paso es hacer build local en mac.

## TestFlight / App Store distribucion

- TestFlight: subir IPA via `xcrun altool --upload-app` o `Transporter.app`. Beta tester invitations.
- App Store: revision Apple ~24-72h tipica. Rejections crypto-related: documentar bien las features.

## Tamaño

iOS IPA es zip de `.app/`. Componentes:
- Binario universal (solo arm64): 5-7 MB.
- SDL3 framework: 2-3 MB.
- Assets bundle: depende del juego.
- App icon + launch screen: 100 KB.

IPA base objetivo: **≤ 25 MB**.

App Thinning en App Store reduce el download del usuario final (solo arm64, recursos por device).

## e2e_checks

```yaml
e2e_checks:
  - id: build_ios
    cmd: "bash bash/functions/pipelines/build_ios_cpp_pipelines.sh <app>"
    timeout_s: 900
    severity: warning  # Solo corre en mac
  - id: ipa_size
    cmd: "test $(stat -c%s build/ios/<app>/ipa/<app>.ipa) -lt 26214400"
    severity: warning
```

## Tests

Manual primero (es lo que toca con iOS). Automatizar con XCUITest mas adelante si hay volumen de juegos.

## Criterio de exito

- [x] `engine_demo` corre en iPhone fisico (test device).
- [x] Metal backend activo (no rasterizer software).
- [x] Touch + virtual gamepad funcionan.
- [x] Audio sin glitches (CoreAudio via miniaudio).
- [x] Safe area respetada en iPhone con notch.
- [x] IPA ≤ 25 MB.
- [x] WalletConnect deep link basico funciona con MetaMask iOS.
- [x] Pipeline documentado para mac local + CI macos-latest.

## Riesgos

1. **Sin mac** — bloqueante. Resolver antes de empezar.
2. **Apple Developer Program** — 99 USD/año fijo. Sin esto solo "personal device sideloading" (limitado).
3. **App Store review crypto** — rechazos posibles. Tener un build "vanilla" sin crypto features para fallback.
4. **MoltenVK alternativa** — si sokol_gfx Metal da problemas, MoltenVK (Vulkan→Metal) es opcion. +complejidad +tamaño. Plan B.
5. **iOS 15+ minimum** — corta dispositivos pre-2015 (iPhone 6S y anteriores).

## No-objetivos

- TestFlight automatizado (mas tarde).
- Apple Pay para fiat → crypto.
- Wallet propio custodial (no, mismo motivo que 0072e).
- iPad-specific UI (escala automatica desde iPhone basta para empezar).