Skip to content

macOS で BepInEx が起動しない(Doorstop の ci 版と Rosetta で動作を確認) #3

Closed

Description

@223n

注意

この Issue は控えでした。清書して、フォーク元に TomXV/dragnwash-modframework#85 として起票しました。最新の内容はそちらにあります。

現象

macOS では、BepInEx 5.4.23.5 の macOS 版を入れても BepInEx が起動しません(確かめたのは Apple Silicon です)。ゲームは Mod なしで起動し、BepInEx/LogOutput.log も BepInEx/config/ もできません。

原因

原因は 3 つあります。

  1. Doorstop が Unity 6.3 にフックできない。
  2. BepInEx 5.4.23.5 は、arm64 のネイティブ実行では Harmony のパッチを当てられない。
  3. 共通インストーラーが macOS に対応していない。
    • Install.exe は Windows 用の BepInEx を入れます。
    • install-steamdeck.sh は Linux 用の BepInEx を入れます。bash 4 の機能(declare -A と mapfile)を使うので、macOS 標準の bash 3.2 では最初の declare -A で止まります。GNU 版にしかない sed -i(拡張子なし)と cp -T にも頼っています。

回避策(動作を確認済み)

公式の BepInEx 5.4.23.5 の macOS 版を使い、Doorstop の 2 ファイルを ci 版に差し替えて、Rosetta で起動します。ゲームのファイル(DragNWash.app の中)は書き換えません。

  1. BepInEx_macos_universal_5.4.23.5.zip(zip の sha256 01c2ae782eb016dfd6c345a18dbd2dcafffb3d9d318449d6486689f426b4a323)を、DragNWash.app の隣に展開します。

  2. doorstop_macos_release_4.6.0.zip(ci 版)の universal/libdoorstop.dylib と universal/run.sh で、libdoorstop.dylib と run_bepinex.sh を置き換えます。

    • ci 版は、master に push されるたびに同じ URL のまま作り直されます。版が上がると、ファイル名も変わります。
    • 最新の確認は、2026-09-25 20:37 UTC に master 97293a28 から作られた 4.6.0 です(zip の sha256 fa3c9e4638f82873620b7e7e12ce1730ce01cdc23a7ba3bac2e6bfa31c0e929d)。
    • ci 版が作り直されても使えるように、この zip を中身を変えずに 223n/UnityDoorstop の ci-4.6.0-97293a28 にもプレリリースとして置きました(sha256 は同じ。タグは同じコミット 97293a28 を指します)。
    • それより前は、4.5.0 の ci 版(master d8973b22、zip の sha256 025296d7339c72cce3020d46efd91823802ad06feb18706dd738f90bc762d649)で確かめていました。このファイルは、もうダウンロードできません。
  3. run_bepinex.sh の 3 行を書き換えます。

    sed -i '' \
        -e 's|^executable_name=""$|executable_name="DragNWash.app"|' \
        -e 's|^archpreference="arm64,x86_64"$|archpreference="x86_64"|' \
        -e 's|^target_assembly="Doorstop.dll"$|target_assembly="BepInEx/core/BepInEx.Preloader.dll"|' \
        run_bepinex.sh
    • どの式も、既定の値が入った行にだけ一致させています。
    • ^target_assembly=.* のように書くと、291 行目の target_assembly="$(abs_path "$target_assembly")" まで書き換わります。そうなると target_assembly が相対パスのまま Doorstop に渡り、Doorstop はそれを今いるフォルダーから探します。ゲームのフォルダー以外から起動すると、何も知らせずに Mod なしで起動します。
    • 環境変数 ARCHPREFERENCE を設定しても効きません。スクリプトが 331 行目で archpreference の値を ARCHPREFERENCE に入れ直して export するためです。
    • arch -x86_64 /bin/bash run_bepinex.sh で起動しても、x86_64 にはなりません。スクリプトは最後に必ず arch を通してゲームを起動し、既定の arm64,x86_64 では arm64 が選ばれるためです。BepInEx 5.4.23.5 に入っている run_bepinex.sh も同じです。
  4. 実行できるようにして、ダウンロードしたファイルから com.apple.quarantine を外します。

    chmod u+x run_bepinex.sh
    xattr -dr com.apple.quarantine run_bepinex.sh libdoorstop.dylib BepInEx
  5. フレームワークのリリース zip から、BepInEx/ だけをゲームの BepInEx/ に重ねます。

  6. Steam のライブラリで Drag'n Wash のプロパティを開き、「起動オプション」に次のように入れて、ふだんどおり「プレイ」で起動します。

    "<ゲームのフォルダーの絶対パス>/run_bepinex.sh" %command%
    
    • パスにアポストロフィ(Drag'n Wash)が入っていても、そのまま動きました。
    • ゲームのフォルダーに移ってから、ターミナルで ./run_bepinex.sh を実行して起動することもできます。ただし、Steam API が使えず、セーブも見えません(下の「確認した結果」)。確かめるときだけにとどめます。
  7. 4.6.0 の ci 版では要りません(run.sh: keep the Steam overlay on macOS via STEAM_DYLD_INSERT_LIBRARIES NeighTools/UnityDoorstop#121 が入っているため)。4.5.0 の ci 版を使っていて、Steam オーバーレイ(Shift+Tab)も使うときは、run_bepinex.sh の中で DYLD_INSERT_LIBRARIES を組み立てる部分(if [ -z "$DYLD_INSERT_LIBRARIES" ]; then から始まる 5 行)を、次のように直します。

    inherited_libraries="${DYLD_INSERT_LIBRARIES:-${STEAM_DYLD_INSERT_LIBRARIES}}"
    if [ -z "$inherited_libraries" ]; then
        dyld_insert_libraries="${doorstop_name}"
    else
        dyld_insert_libraries="${doorstop_name}:${inherited_libraries}"
    fi
    • スクリプトを動かす /bin/sh は SIP で保護されているので、Steam が渡す DYLD_INSERT_LIBRARIES(オーバーレイ)は、スクリプトに届く前に消されます。Steam は同じ一覧(steamloader.dylib と gameoverlayrenderer.dylib)を STEAM_DYLD_INSERT_LIBRARIES でも渡すので、そちらを引き継ぎます。
    • 直さなくても Mod は動きますが、Shift+Tab を押してもオーバーレイは開きません。

元に戻すときは、Steam の起動オプションを空にして、BepInEx/、run_bepinex.sh、libdoorstop.dylib、.doorstop_version、changelog.txt をどけます。起動に失敗したときは DragNWash.app/Contents/MacOS/ に preloader_*.log ができるので、それも消します。

確認した結果

項目 内容
Mac Apple A18 Pro、macOS 27.2
ゲーム macOS 版 9/12/2026_a93aa21a(Unity 6000.3.14f1、Metal)。ビルド番号は Windows 版と同じです
実行 vmmap の Code Type: X86-64 (translated)(Rosetta)
BepInEx Chainloader startup complete
フレームワーク 1.5.0。プラグイン 10 個が警告なしで読み込まれ、タイトル画面に「10 mods loaded」と出る

タイトル画面の右下に、フレームワークのバージョン、読み込まれた Mod の数、ゲームのビルド番号が出ています。

macOS のタイトル画面。右下に Drag'n Wash ModFramework 1.5.0、10 mods loaded、9/12/2026_a93aa21a と出ている

Mods 画面も開けます。

macOS で開いた Mods 画面。Drag'n Wash ModFramework 1.5.0 と各ライブラリが並んでいる
  • osx: fix the chained-fixups reader so Unity 6.3 games hook NeighTools/UnityDoorstop#117 の作者は arm64 でしか試していません。今回は、x86_64(Rosetta)のスライスでもこのゲームにフックできました。
  • Harmony のパッチが当たりました([cursor] Patched 3 GameStateManager method(s))。
  • Mods 画面、更新の確認、セーブのスナップショットが動きました。
  • F1 のウィンドウには文字が出ませんでした。macOS で F1 のウィンドウに文字が表示されない(Hiragino Sans が TextCore で見つからない) #4 で扱います。
  • ターミナルには、cant resolve internal call to "UnityEngine.UnityLogWriter::WriteStringToUnityLogImpl" と …::WriteStringToUnityLog" が 2 回ずつ出ます。それぞれのあとに Your mono runtime and class libraries are out of sync. という説明が続きます。Unity 6 に、BepInEx が探す内部関数がないだけです。無害で、ログは正しく書かれます。
  • ゲームの macOS 版の Assembly-CSharp.dll は、Windows 版や Linux 版とハッシュが違います(ci/game-fingerprints.json にない)。ただし、フレームワークが使う型やメンバーはすべてありました。

Steam から起動したとき(2026-09-25)

Steam の起動オプションから起動したときと、ターミナルから起動したときの違いです。

項目 ターミナルから起動 Steam の「プレイ」から起動
Mod(BepInEx とフレームワーク) 動く 動く
実行 Rosetta(x86_64) Rosetta(x86_64)
環境変数 SteamAppId なし 4739660
Steam API SteamAPI_Init() failed. 初期化される
セーブ(Continue と Load Game) 出ない 出る
Steam オーバーレイ ― 手順 7 を入れると開く
  • ゲームは起動のたびに、steam_appid.txt を DragNWash.app/ の中に書きます(Player.log の Wrote steam_appid.txt at:)。ターミナルから起動すると Steam API が使えないのは、Steam API がこのファイルを今いるフォルダー(ゲームのフォルダー)から探すためだと見ています。Steam から起動したときは、Steam が SteamAppId を渡すので問題になりません。
  • この Mac には、Steam Cloud から来たセーブ(~/Library/Application Support/Gator Dragon Games/DragNWash/<Steam ID>/slot1/)があります。ターミナルから起動したときは、タイトル画面に Continue と Load Game が出ませんでした。Steam API が使えないので、<Steam ID> のフォルダーを探せないためだと見ています。
  • 手順 7 を入れる前は、gameoverlayrenderer.dylib はあとから読み込まれていましたが、Shift+Tab を押してもオーバーレイは開きませんでした。入れたあとは、起動の時点から読み込まれ、オーバーレイが開きました。
Mod を入れたゲームの上に開いた Steam オーバーレイ。右上に ゲームに戻る (Shift+Tab) と出ている

起動直後の固まり方を、フレームワークが記録する起動時間で比べました。「最初のフレームまで」は、最初のシーンを読み込んでから次のフレームまでの時間です。「100 ms を超えたフレーム」は、シーンを読み込んでから 10 秒間の数です。

起動 最初のフレームまで 100 ms を超えたフレーム
手順 7 の前(オーバーレイは開かない) 2.8 秒 193 フレーム中 5
手順 7 のあと、1 回目 17.8 秒 1 フレーム中 1
手順 7 のあと、2 回目 3.8 秒 166 フレーム中 5
  • 手順 7 を入れて初めて起動したときだけ、タイトル画面が出る前に 15 秒ほど固まりました。原因はまだ分かっていません。
  • Rosetta がオーバーレイのライブラリを変換して保存するキャッシュ(gameoverlayrenderer.dylib.aot)は、この起動の 2 秒後に作られていました。ただし、固まったのはシーンを読み込んだあと(起動から 28 秒ほどあと)です。シーンを読み込むまでの時間は 2 回目と同じだったので、この変換だけでは説明できません。固まり始めたのは、Steam のログでオーバーレイの画面(gameoverlayui)が起動した直後でした。
  • 2 回目も起動直後に少し固まりましたが、手順 7 の前と同じ程度でした。この Mac はメモリーが 8 GB で(ゲームの最低要件も 8 GB)、ゲームを Rosetta で動かしているので、その分の重さだと見ています。最初のフレームまでの時間は、手順 7 の前より 1 秒ほど長いだけでした(1 回ずつの比較です)。

Doorstop 4.6.0(ci 版)で確認(2026-09-26)

手順 7 を入れず、4.6.0 の run.sh に 3 つの設定だけを入れた状態で、Steam の「プレイ」から起動しました。

項目 結果
Doorstop 4.6.0(master 97293a28 の ci 版)
実行 vmmap の Code Type: X86-64 (translated)(Rosetta)
DYLD_INSERT_LIBRARIES libdoorstop.dylib に続けて、Steam の steamloader.dylib と gameoverlayrenderer.dylib
Steam オーバーレイ Steam のログに GameOverlay: started … gameoverlayui が出て、Shift+Tab で開いた
BepInEx とフレームワーク Chainloader startup complete。タイトル画面に「10 mods loaded」
F1 のウィンドウ 文字が出る(Window font: Arial Unicode MS + Apple Symbols)
最初のフレームまで 2.4 秒(100 ms を超えたフレームは 311 フレーム中 2)
Doorstop 4.6.0 で起動したタイトル画面。F1 のウィンドウの Console に Window font: Arial Unicode MS + Apple Symbols が出ていて、右下に 10 mods loaded と出ている Doorstop 4.6.0 で起動し、手順 7 なしで Shift+Tab を押して開いた Steam オーバーレイ

インストーラーで確認(2026-09-26)

223n/dragnwash-localization の feature/macos-installer の installer/experimental/install-macos.sh を、上の 4.6.0(ci 版)の環境の上から実行し、Steam の「プレイ」から起動しました。翻訳 Mod は v1.5.0 のリリースの zip を使いました。

項目 結果
ダウンロード なし。BepInEx、Doorstop、ModFramework 1.5.0 は、入っているものをそのまま使った(4.6.0 の ci 版の libdoorstop.dylib は、スクリプトが固定している 4.5.0 のものとバイト単位で同じ)
run_bepinex.sh executable_name をフルパスにするため書き直した(元のファイルは run_bepinex.sh.dragnwash-backup に残る)。オーバーレイの引き継ぎはすでにあるので、そのまま
起動オプション Steam を終了させてから設定し、Steam を起動し直した
翻訳 日本語で表示された(1773 項目。日本語の 868 字をゲームのフォントに追加)
Steam オーバーレイ Shift+Tab で開いた
F1 のウィンドウ 文字と Inspector のアイコンが出た
  • 起動するときにタイトル画面の前で止まったように見えるのは、ゲームのウィンドウが前面にない(アクティブでない)ときに起きるようです。ウィンドウをアクティブにしておくと、なめらかに起動しました。「手順 7 のあと、1 回目」の 15 秒ほどの固まりも、これだった可能性がありますが、確かめてはいません。
  • インストーラーが固定していた 4.5.0 の ci 版の zip は、もうダウンロードできません(HTTP 404)。そこで、インストーラーは試した 4.6.0 を、上のコピー(223n/UnityDoorstop の ci-4.6.0-97293a28)から取るようにしました。偽の HOME と Steam のフォルダーの中で、本物の BepInEx、Doorstop のコピー、ModFramework をダウンロードする新規インストールが、SHA-256 の確認をすべて通って終わることを確かめました。何も入っていない状態からのインストールは、実際のゲームではまだ試していません。

残っている課題

  • 手順 7 の直しは、NeighTools/UnityDoorstop#121 として 2026-09-25 に上流にマージされ、ci 版の 4.6.0 に入りました。4.6.0 以降の Doorstop を使えば、手順 7 は要りません。
  • 安定版の Doorstop 4.6.0 は、まだ出ていません(2026-09-26 時点。本家には v4.6.0 のタグが付いていて、同じコミット 97293a28 を指しています)。出たら、コピーをやめて、安定版の zip を固定します。
  • 起動時に止まったように見える件は、ゲームのウィンドウが前面にないときに起きるようです(上の「インストーラーで確認」)。インストーラーと README には「ウィンドウをクリックすると進む」と書きました。run_bepinex.sh がゲームを直接起動するので、macOS がウィンドウを前面に出していないのかもしれませんが、確かめていません。
  • メモリーに余裕のある Mac では試していません。起動直後に少し固まるのがこの Mac だけなのかは、分かっていません。
  • Rosetta が全面的に使えるのは macOS 27 までです。長く使うには、Doorstop(Apple Silicon - Add doorstop_jit_memcpy for MAP_JIT writes NeighTools/UnityDoorstop#114 と osx: fix the chained-fixups reader so Unity 6.3 games hook NeighTools/UnityDoorstop#117)と BepInEx(v5: Fix crash on macOS arm64: wrap XTermFix and ConsoleSetOutFix in Utility.TryDo BepInEx/BepInEx#1288 と v5: Fix plugin loading on native arm64 macOS BepInEx/BepInEx#1402)の修正が入った安定版が出たあと、ネイティブ arm64 で動かす必要があります。
  • ci 版は正式なリリースではなく、master に push されるたびに同じ URL のまま作り直されます。配布用のインストーラーでは、SHA-256 で中身を確かめる必要があります。作り直されるとハッシュが合わなくなるので、そのたびに更新が要ります。そのため、インストーラーは ci 版の URL ではなく、試したビルドのコピー(223n/UnityDoorstop のプレリリース)から取ります。
  • macOS 用のインストーラーは、223n/dragnwash-localization の feature/macos-installer で installer/experimental/install-macos.sh を直しました(実験的なまま、リリースの zip には入れません)。フォーク元(TomXV/dragnwash-localization)への PR は、まだ出していません。
  • ドキュメントなどを直す必要があります。
    • docs/ROADMAP.md の「Waiting on others」と docs/DESIGN.md の「Non-goals (for now)」は、macOS: Doorstop cannot hook Unity 6000.3 Mono games — chained-fixups header parses as all zeros NeighTools/UnityDoorstop#108 だけを理由にしています。日本語版の docs/ROADMAP.ja.md「ほかの動きを待っているもの」と docs/DESIGN.ja.md「今はやらないこと」も同じです。
    • docs/GAME_BUILDS.md に macOS 版の行がありません。
    • ci/game-fingerprints.json に macOS 版のビルドがありません。DragNWash.app の中の 274 ファイルのうち、Assembly-CSharp.dll を含む 187 ファイルのハッシュがありません。
    • tools/game-fingerprints.py は libdoorstop.dylib を除外していないので、macOS で使う前に直す必要があります。
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationenhancementNew feature or request

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions