iOS ビルドガイド

作成日: 2026-03-08 ／ 更新日: 2026-06-10

概要

macOS 上でネイティブエンジンを iOS 向けにクロスビルドし、シミュレーターで動作確認する手順。SDL2 をソースからビルドし、CMake + Xcode 経由でコンパイルする。macOS / Android とエンジンコードは共通で、プラットフォーム差異は main.cpp の #ifdef ガードのみ。

共通手順（リポジトリ clone / SDL2 ソース取得 / CMake の基本 / 共通ハマり）は ビルドガイド共通 を参照。本書は iOS 固有の差分（Xcode ジェネレータ / シミュレーター / LaunchScreen / sandbox データ配置）を記載する。

前提条件

Simulator Runtime と Deployment Target は別の概念。上表の「iOS Simulator Runtime: iOS 26+」は動作確認に使うシミュレーターの OS バージョン（実機テスト用ランタイム）。一方、アプリがサポートする最小 OS バージョン（Deployment Target）は iOS 15.0（ios/build-ios.sh の -DCMAKE_OSX_DEPLOYMENT_TARGET=15.0 と ios/CMakeLists.txt の XCODE_ATTRIBUTE_IPHONEOS_DEPLOYMENT_TARGET "15.0"）。新しいシミュレーターで確認しても、ビルド成果物は iOS 15.0 以降で動作する。

Step 1: SDL2 ソースのダウンロード

共通ガイド Step 2 のとおり。macOS ビルドで既に取得済みなら不要。

# リポジトリルートから実行（配置先: packages/native-engine/external/）
bash scripts/build/download-sdl2-sources.sh

Step 2: CMake プロジェクト生成

cd packages/native-engine/ios
mkdir -p build-sim && cd build-sim

cmake .. -G Xcode \
  -DCMAKE_SYSTEM_NAME=iOS \
  -DCMAKE_OSX_SYSROOT=iphonesimulator \
  -DCMAKE_OSX_ARCHITECTURES=arm64

実機向けの場合は -DCMAKE_OSX_SYSROOT=iphoneos を使用する（署名が必要）。

Step 3: ビルド

cmake --build . --target kaedevn_ios

# または Xcode で直接開く
open kaedevn_ios.xcodeproj

出力: Debug-iphonesimulator/kaedevn_ios.app

初回ビルドは SDL2 + satellite ライブラリの全コンパイルが走るため数分かかる。2回目以降は差分ビルドで高速。

Step 4: シミュレーターの準備

# 利用可能なデバイスタイプを確認
xcrun simctl list devicetypes | grep iPhone

# シミュレーターを起動（既に起動中なら不要）
open -a Simulator

# 起動中のデバイスを確認
xcrun simctl list devices booted

Step 5: インストールとデータ配置

iOS アプリは sandbox 内にデータを持つため、プロジェクトデータを手動でコピーする必要がある。

# アプリをインストール
xcrun simctl install booted Debug-iphonesimulator/kaedevn_ios.app

# データコンテナのパスを取得
CONTAINER=$(xcrun simctl get_app_container booted com.kaedevn.native-engine data)

# プロジェクトデータをコピー
mkdir -p "$CONTAINER/Documents/project"
cp -r ../../data/YOUR_PROJECT_ID/* "$CONTAINER/Documents/project/"

重要: simctl install するたびにコンテナ UUID が変わるため、インストール後に毎回データコピーが必要。

Step 6: 起動と確認

# 起動
xcrun simctl launch booted com.kaedevn.native-engine

# コンソールログ付きで起動（デバッグ用）
xcrun simctl launch --console-pty booted com.kaedevn.native-engine

# シミュレーターを横向きにする
# Device > Rotate Left (Cmd+←)

正常に動作すると、背景・立ち絵・日本語テキストがシミュレーター上に表示される。

ハマりポイント

1. 左右に黒帯が出る（最もよくハマる）

症状: アプリは表示されるが、画面の左右に黒帯が出て全画面にならない。

原因: LaunchScreen.storyboard がバンドルに含まれていない。iOS は LaunchScreen がないアプリをレガシー互換モード（iPhone 4 相当の 320×480 points）で起動する。

解決: ios/LaunchScreen.storyboard と Info.plist.in の UILaunchStoryboardName が正しく設定されていることを確認。CMakeLists.txt でバンドルリソースとして追加されていること。

set(LAUNCHSCREEN "${CMAKE_CURRENT_SOURCE_DIR}/LaunchScreen.storyboard")
target_sources(kaedevn_ios PRIVATE ${LAUNCHSCREEN})
set_source_files_properties(${LAUNCHSCREEN} PROPERTIES
    MACOSX_PACKAGE_LOCATION Resources
)

検証: ログに以下が表示されれば正常（iPhone 17 Pro の場合）:

Window: 874x402, Renderer: 2622x1206

Window: 480x320 が表示されたら LaunchScreen が認識されていない。

2. シミュレーターが縦画面のまま

症状: landscape-only の Info.plist を設定しているのに、シミュレーターが縦画面で表示される。

原因: SDL2 2.30.12 の SDLLaunchScreenController.shouldAutorotate が NO を返すため、シミュレーターでは自動回転しない。実機では正しく横画面になる。

解決: シミュレーターの Device > Rotate Left (Cmd+←) で手動回転する。

3. simctl install 後にデータが消える

症状: 再インストール後にアプリが起動するが背景やキャラクタが表示されない。

原因: simctl install でコンテナ UUID が変わり、以前コピーしたデータが別の場所になる。

解決: インストール後に毎回データをコピーする。ワンライナー:

xcrun simctl install booted Debug-iphonesimulator/kaedevn_ios.app && \
CONTAINER=$(xcrun simctl get_app_container booted com.kaedevn.native-engine data) && \
mkdir -p "$CONTAINER/Documents/project" && \
cp -r ../../data/YOUR_PROJECT_ID/* "$CONTAINER/Documents/project/"

4. 'SDL2/SDL_image.h' file not found

症状: CMake ビルド中にヘッダが見つからない。

原因: Android と同じ問題。macOS Homebrew のヘッダ配置と SDL2 ソースビルドのヘッダ配置が異なる。

解決: CMakeLists.txt に互換 include ディレクトリの仕組みが入っている。SDL2 コア + satellite ライブラリのヘッダを sdl2-compat-include/SDL2/ にコピーし、include パスに追加する。

5. storyboard のコンパイルエラー

症状: ビルド中に Unknown target runtime "AppleSDK" エラー。

原因: storyboard XML の targetRuntime 属性が間違っている。

解決: targetRuntime="iOS.CocoaTouch" に設定する（AppleSDK ではない）。

6. 日本語テキストが表示されない

症状: テキストウィンドウは表示されるが文字が空。

原因: フォントのロードに失敗している。iOS シミュレーターはホスト macOS のフォントを共有するが、パスが異なる場合がある。

解決: main.cpp のフォント候補リストを確認。ログに Font loaded: が表示されていれば OK。表示されていなければフォントパスの追加が必要。

7. Mix/Audio 関連のリンクエラー

症状: SDL2_mixer のビルドで undefined symbol エラー。

原因: SDL2_mixer の vendored 依存（ogg, vorbis, opus, wavpack 等）が静的ライブラリとしてビルドされていない。

解決: CMakeLists.txt で以下が設定されていることを確認:

set(BUILD_SHARED_LIBS OFF CACHE BOOL "" FORCE)
set(SDL2MIXER_VENDORED ON CACHE BOOL "Use vendored libs")

アーキテクチャ補足

実行アーキテクチャ（コンパイル済み Op[] → KscVM (C++) + OpRunner → IOpHandler 実装（SDL2Engine + HostBinding 群）→ SDL2 + GLRenderer）は ビルドガイド共通 の全体像と 22-ksc-pipeline-overview.md を参照。SDL2Engine のコードは全プラットフォーム共通で、差異は main.cpp の #ifdef（iOS は TARGET_OS_IPHONE）に閉じている。iOS も描画は GLRenderer（OpenGL ES3）が既定。

iOS 固有の対応箇所

論理解像度

高さ 720 固定、幅はスクリーンのアスペクト比から動的計算:

iPhone 17 Pro (874x402 points): logicalW = 720 * (874/402) = 1564
iPhone SE    (667x375 points): logicalW = 720 * (667/375) = 1281
iPad         (1024x768 points): logicalW = 720 * (1024/768) = 960

UI は 1280 幅基準で設計し、ox = (logicalW - 1280) / 2 でセンタリングする。背景は logicalW × logicalH のフルサイズで描画。

クイックリファレンス

# === SDL2 ソース取得 ===
bash scripts/build/download-sdl2-sources.sh

# === CMake 生成（初回のみ） ===
cd packages/native-engine/ios
mkdir -p build-sim && cd build-sim
cmake .. -G Xcode \
  -DCMAKE_SYSTEM_NAME=iOS \
  -DCMAKE_OSX_SYSROOT=iphonesimulator \
  -DCMAKE_OSX_ARCHITECTURES=arm64

# === ビルド ===
cmake --build . --target kaedevn_ios

# === インストール + データコピー + 起動 ===
xcrun simctl install booted Debug-iphonesimulator/kaedevn_ios.app && \
CONTAINER=$(xcrun simctl get_app_container booted com.kaedevn.native-engine data) && \
mkdir -p "$CONTAINER/Documents/project" && \
cp -r ../../data/YOUR_PROJECT_ID/* "$CONTAINER/Documents/project/" && \
xcrun simctl launch booted com.kaedevn.native-engine

# === ログ確認 ===
xcrun simctl launch --console-pty booted com.kaedevn.native-engine

# === シミュレーター横回転 ===
# Device > Rotate Left (Cmd+←)

# === クリーンビルド ===
rm -rf build-sim && mkdir build-sim && cd build-sim
cmake .. -G Xcode -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_ARCHITECTURES=arm64
cmake --build . --target kaedevn_ios