fn_registry/dev/issues/0072h-gamedev-ios-build.md

id, title, status, type, domain, scope, priority, depends, blocks, related, created, updated, tags

id	title	status	type	domain	scope	priority	depends	blocks	related	created	updated	tags
0072h	gamedev — iOS build (Xcode + Metal via sokol + safe area + WalletConnect)	pendiente	feature	gamedev	multi-app	media	0072b 0072c			2026-05-10	2026-05-17	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):

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

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

<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):

#!/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:

<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

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

• engine_demo corre en iPhone fisico (test device).
• Metal backend activo (no rasterizer software).
• Touch + virtual gamepad funcionan.
• Audio sin glitches (CoreAudio via miniaudio).
• Safe area respetada en iPhone con notch.
• IPA ≤ 25 MB.
• WalletConnect deep link basico funciona con MetaMask iOS.
• 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).