[!IMPORTANT]
この記事は AI（Antigravity / Gemini）によって執筆され、Qiita API を通じて自動投稿されたものです。
10年前の Cocos2d-x 2.x プロジェクトを現代の Axmol Engine に移植する過程での、リアルタイムなデバッグログと解決策をまとめています。
10年前の Cocos2d-x プロジェクトを最新の Axmol Engine へ移植して Xcode で起動するまで
10年前に作成した Cocos2d-x 2.x のミニゲーム「Rush Freak」を、現代のビルド環境（macOS 15.3, Xcode 26.3, Axmol Engine 2.11.3）で蘇らせるまでの全記録です。
はじめに
古い Cocos2d-x プロジェクトを最新環境で動かすのは、APIの非推奨化やビルドシステムの変更により一筋縄ではいきません。今回は、Cocos2d-x の現代的フォークである Axmol Engine を採用し、環境構築からビルド成功までたどり着いた手順をまとめます。
今回の「気づき」と「発見」 (Tips for Qiita)
単なる手順以上に、デバッグ中に得られた重要な技術的知見をまとめます。
💡 PowerShell on Mac の落とし穴
setup.ps1 が失敗する原因は、PowerShell の Add-Type コマンドが macOS 版 (Homebrew) では参照アセンブリを正しく解決できないことにありました。
- 発見: エラーメッセージから「C# の動的コンパイル」が鬼門であると特定。
-
知見: PowerShell 5.0 以降はネイティブで
class構文をサポートしているため、C# (Add-Type) を介さずとも複雑な型定義が可能です。これを native class に書き換えることで、環境依存を大幅に減らせることに気づきました。
🔍 リンカーエラーの「真犯人」の見つけ方
Simulator 向けビルドで Device 用 SDK が混入する問題は、Xcode の詳細なビルドログがヒントになりました。
-
発見:
clang++の引数の中に、意図しない-F/Applications/Xcode.app/.../iPhoneOS.platform/...というパスが含まれているのを見逃しませんでした。 -
知見: このパスをキーワードにエンジン内の CMake ファイルを
grepした結果、AXConfigDepend.cmakeにハードコードされた/System/Library/Frameworksが「真犯人」であると確信。現代のマルチプラットフォーム開発において、絶対パスのハードコードがいかに危険かを再認識しました。
📂 axmol new のディレクトリ挙動
-
気づき:
-dオプションでディレクトリを指定しても、その下にさらにプロジェクト名のフォルダが掘られます。二重階層になりやすいため、出力先とプロジェクト名の関係には注意が必要です。
1. 環境構築：Axmol の導入
必須ツールのインストール
まずは Homebrew を使って必要なツールを揃えます。
brew install cmake ninja powershell
Axmol Engine 本体のセットアップ
GitHub からリポジトリをクローンし、セットアップスクリプトを実行します。
git clone https://github.com/axmolengine/axmol.git ~/ext/axmol --depth 1
cd ~/ext/axmol
./setup.ps1
[!IMPORTANT]
macOS (Homebrew 版 PowerShell) での注意点
現在の Axmol のsetup.ps1は C# コードの動的コンパイル（Add-Type）を利用していますが、macOS の Homebrew 版 PowerShell では参照アセンブリのパス問題で失敗することがあります。
今回は、1k/extensions.ps1内の C# クラス定義を PowerShell ネイティブのclass定義に書き換えるパッチを当てることで回避しました。
2. プロジェクトの新規作成と移行
新規プロジェクト生成
Axmol の axmol new コマンドで現代的なディレクトリ構造を持つプロジェクトを作成します。
axmol new -p com.example.rendapower -d ./new_project -l cpp --portrait rendaPower
ソースとリソースの配置
- 旧
Classes/→ 新Source/ - 旧
Resources/→ 新Content/
CMakeLists.txt の設定
Axmol は Source/ 以下のファイルを自動的に検知するため、特別なファイル追加指定は不要です。
3. コードの修正 (移行のハマりポイント)
API の変更対応
-
cocos2d名前空間からax名前空間への変更。 -
AudioEngineの利用方法：audio::AudioEngineではなくax::AudioEngine(またはusing namespace ax;下でのAudioEngine) を使用。 -
Directorメソッドの現代化：-
getOpenGLView()→getGLView() -
setDisplayStats()→setStatsDisplay()
-
-
インクルードの変更:
AudioEngineを使用する場合、明示的に#include "audio/AudioEngine.h"が必要。 -
コールバックマクロの変更: 引数なしの関数には
AX_CALLBACK_0を、引数1つ（送信者）にはAX_CALLBACK_1を使い分ける。
4. Xcode でのビルドと実行
Xcode プロジェクトの生成
axmol build -p osx -c
これで build/ ディレクトリ内に .xcodeproj が生成されます。
ビルドの実行
Xcode で開くか、コマンドラインから実行します。
xcodebuild -project build/rendaPower_axmol.xcodeproj -configuration RelWithDebInfo -target rendaPower_axmol
無事に ** BUILD SUCCESSFUL ** となれば完了です！
5. トラブルシューティング：ビルドエラーとの戦い
移植の最終段階で遭遇した、非常に教育的な（Qiita 向きの）エラーとその解決策です。
① Multiple commands produce 'Info.plist'
現象: Xcode ビルド時に Info.plist が重複しているというエラーで停止する。
原因: 旧プロジェクトからコピーした Content/Info.plist と、Axmol (CMake) が自動生成しようとする Info.plist が衝突していました。
解決策: Content/Info.plist を削除。Axmol はエンジンの仕様に合わせた最適な Info.plist を自動生成してくれるため、古いものは不要です。
② iOS シミュレーターでの Linker Error (AudioToolbox)
現象: building for 'iOS-simulator', but linking in dylib ... built for 'iOS' というエラー。
原因: AudioToolbox フレームワークを「実機用 SDK」から探してしまい、シミュレーター向けビルドに混入していました。
根本理由: Axmol の cmake/Modules/AXConfigDepend.cmake に /System/Library/Frameworks というホストマシンのパスがハードコードされていたことと、ツールchainでの検索制限が不十分だったこと。
解決策:
-
AXConfigDepend.cmakeからハードコードされたパスを削除。 -
1k/ios.cmakeにてCMAKE_FIND_ROOT_PATH_MODE_LIBRARY等をONLYに設定し、ターゲット SDK 以外を探さないよう強制。 -
buildフォルダを削除して CMake キャッシュをクリアし、-DSIMULATOR=TRUEで再生成。
③ コールバックの型不一致 (MenuItemLabel)
現象: no matching function for call to 'create' というエラーでビルドが止まる。
原因: MenuItemLabel::create が期待する ccMenuCallback (引数1つ) に対し、引数なしのメンバ関数を AX_CALLBACK_1 で渡そうとしていた。
解決策: AX_CALLBACK_0 に修正。Cocos2d-x 2.x 時代よりもマクロの厳密性が増している印象です。
まとめ
10年前のコードでも、適切なエンジン（Axmol）と環境設定のパッチを組み合わせることで、最新の Apple Silicon Mac や Xcode 環境で再び動かすことができます。今回の PowerShell パッチや CMake の修正などの知見が、同じようにレトロゲームを復旧させたい方の助けになれば幸いです。
ハッピー・コーディング！
人による追記：
起動した記念のスクリーンショット
移行の途中経過で撮った動作確認のスクリーンショット
完全移行した後のゲーム画面のスクリーンショット
職場での風の噂でcocos2d-xから派生したAxmolEngineなるものが出来の良いエンジンがあると
聞いたのでcocos2d-x初心者の時に作ったアプリをバイブコーディングで移植してみました。
動かなかったアプリも結構良い感じに移行できました。
職場では使えるかどうかの判断は、サードパーティSDKが組み込めるかどうかにかかってくるので
このまま行けるかわからないですが、cocos2d-xプロジェクトの延命だったり
再利用はもしかしたらAIのおかげでスムーズに行けるかもしれないですね。