Skip to content

macOS で BepInEx が起動しない(Doorstop 4.6.0 の ci 版と Rosetta で動くことを確認) #85

Closed

Description

@223n

何が起きたか / What happened

macOS では、BepInEx 5.4.23.5 の macOS 版を入れても BepInEx が起動しません。BepInEx が起動してフレームワークが読み込まれるはずが、ゲームは Mod なしで起動します。BepInEx/LogOutput.log も BepInEx/config/ もできません。確かめたのは Apple Silicon の Mac です。

Doorstop を 4.6.0 の ci 版に替えて、ゲームを Rosetta(x86_64)で起動すると、BepInEx とフレームワークが動きます。翻訳 Mod と Steam オーバーレイ(Shift+Tab)も動きました。手順は下の「回避策」に、確かめた結果は「確認したこと」にまとめました。

再現の手順 / Steps to reproduce

  1. BepInEx_macos_universal_5.4.23.5.zip を、DragNWash.app の隣(ゲームのフォルダー)に展開します。
  2. BepInEx の手順どおりに、run_bepinex.sh の executable_name を "DragNWash.app" にして、chmod u+x run_bepinex.sh で実行できるようにします。
  3. ゲームのフォルダーで ./run_bepinex.sh を実行して、ゲームを起動します。
  4. ゲームは Mod なしで起動します。BepInEx/LogOutput.log も BepInEx/config/ もできません。

TomXV/dragnwash-localization の README(macOS の注意書き)にも、Apple M3 Pro / macOS 26.6 で、ネイティブでも Rosetta でも同じ結果になったと書かれています。

バージョン / Versions

ModFramework 1.5.0 / ゲームの macOS 版 9/12/2026_a93aa21a(Unity 6000.3.14f1)/ BepInEx 5.4.23.5 の macOS 版(中の Doorstop は 4.5.0)

環境 / Platform

macOS(macOS 27.2、Apple A18 Pro、メモリー 8 GB、Metal)

ほかに入れている Mod / Other mods installed

BepInEx そのものが起動しないので、ほかの Mod には関係しません。回避策を確かめたときは、フレームワーク 1.5.0(プラグイン 10 個)を入れていました。インストーラーを確かめたときは、翻訳 Mod(TomXV/dragnwash-localization)1.5.0 も日本語で入れていました。2026-09-26 の確認では、フレームワークのうち Tool window だけを、#86 を直したビルドに替えています。

ログ / Log

BepInEx が起動しないので、BepInEx/LogOutput.log はできません。回避策を入れると、LogOutput.log は Chainloader startup complete まで進みます。そのときターミナルに出る無害なメッセージは、下の「確認したこと」に書きました。

原因

原因は 3 つあります。

  1. BepInEx 5.4.23.5 に入っている Doorstop 4.5.0 が、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 にも頼っています。

Steam オーバーレイ(Doorstop 4.6.0 の ci 版で解決済み)

Doorstop 4.5.0 の ci 版の run.sh では、Steam の起動オプションから起動しても、Shift+Tab で Steam オーバーレイが開きませんでした。

  • スクリプトを動かす /bin/sh は SIP で保護されています。そのため、Steam が渡す DYLD_INSERT_LIBRARIES(オーバーレイ)は、スクリプトに届く前に消されます。
  • Steam は、同じ一覧(steamloader.dylib と gameoverlayrenderer.dylib)を STEAM_DYLD_INSERT_LIBRARIES でも渡します。
  • これを引き継ぐ変更が、run.sh: keep the Steam overlay on macOS via STEAM_DYLD_INSERT_LIBRARIES NeighTools/UnityDoorstop#121 として 2026-09-25 にマージされ、4.6.0 の ci 版に入りました。

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

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

TomXV/dragnwash-localization#53 で出している実験的なインストーラー(installer/experimental/install-macos.sh)は、この手順を自動で行います。TomXV/dragnwash-localization#53 は、まだマージされていません。このスクリプトは、リリースの zip には入れません。

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

  2. Doorstop 4.6.0 の ci 版の doorstop_macos_release_4.6.0.zip から universal/libdoorstop.dylib と universal/run.sh を取り出して、libdoorstop.dylib と run_bepinex.sh を置き換えます。

    • 試したのは、2026-09-25 20:37 UTC に UnityDoorstop の master 97293a28 から作られたビルドです。zip の SHA-256 は fa3c9e4638f82873620b7e7e12ce1730ce01cdc23a7ba3bac2e6bfa31c0e929d、universal/libdoorstop.dylib の SHA-256 は 5f31b9fca678536ed1636206f47b77431ac5b972ff92a0a2badf84bc065f9562 です。
    • 本家の ci プレリリースは、master に push されるたびに同じ URL のまま作り直されます。版が上がるとファイル名も変わり、前の zip はダウンロードできなくなります。前に試した 4.5.0 の ci 版の zip は、4.6.0 に替わったときに HTTP 404 になりました。
    • そのため、試した zip を中身を変えずに、223n/UnityDoorstop の ci-4.6.0-97293a28 にプレリリースとして置きました。上のリンクはこちらを指しています。SHA-256 は本家の zip と同じで、タグは同じコミット 97293a28 を指します。
    • インストーラーは、SHA-256 で中身を確かめます。本家の ci 版は作り直されるとハッシュが合わなくなるので、インストーラーもこのコピーから取ります。
  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
    • どの式も、既定の値が入った行にだけ一致させています。
    • 行番号は、4.6.0 の run.sh のものです。
    • ^target_assembly=.* のように書くと、291 行目の target_assembly="$(abs_path "$target_assembly")" まで書き換わります。そうなると、target_assembly が相対パスのまま Doorstop に渡り、Doorstop はそれを今いるフォルダーから探します。ゲームのフォルダー以外から起動すると、何も知らせずに Mod なしで起動します。
    • 環境変数 ARCHPREFERENCE を設定しても効きません。スクリプトが 338 行目で 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 も同じです。
    • インストーラーは、executable_name に DragNWash.app のフルパスを入れます。ゲームのフォルダー以外から起動しても動くようにするためです。
  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 が使えず、セーブも見えません(下の「Steam から起動したとき」)。確かめるときだけにとどめます。

4.5.0 の ci 版(master d8973b22)の run.sh を使っている場合は、Steam オーバーレイが開きません。その run_bepinex.sh の中で DYLD_INSERT_LIBRARIES を組み立てる部分(if [ -z "$DYLD_INSERT_LIBRARIES" ]; then から始まる 5 行)を、次のように直すと開きます。NeighTools/UnityDoorstop#121 と同じ中身です。直さなくても Mod は動きます。

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

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

確認したこと

試した環境です。

項目 内容
Mac Apple A18 Pro、メモリー 8 GB、macOS 27.2
ゲーム macOS 版 9/12/2026_a93aa21a(Unity 6000.3.14f1、Metal)。ビルド番号は Windows 版と同じです
BepInEx 5.4.23.5 の macOS 版
Doorstop 2026-09-25 までは 4.5.0 の ci 版(master d8973b22、zip の SHA-256 025296d7339c72cce3020d46efd91823802ad06feb18706dd738f90bc762d649。もうダウンロードできません)。2026-09-26 からは 4.6.0 の ci 版(master 97293a28)
フレームワーク 1.5.0

Doorstop 4.5.0 の ci 版で確認

項目 結果
実行 vmmap の Code Type: X86-64 (translated)(Rosetta)
BepInEx Chainloader startup complete
フレームワーク プラグイン 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 と各ライブラリが並んでいる

Steam から起動したとき(2026-09-25、Doorstop 4.5.0 の ci 版)

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

項目 ターミナルから起動 Steam の「プレイ」から起動
Mod(BepInEx とフレームワーク) 動く 動く
実行 Rosetta(x86_64) Rosetta(x86_64)
環境変数 SteamAppId なし 4739660
Steam API SteamAPI_Init() failed. 初期化される
セーブ(Continue と Load Game) 出ない 出る
Steam オーバーレイ ― run.sh を直すと開く(「回避策」の最後)
  • ゲームは起動のたびに、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> のフォルダーを探せないためだと見ています。
  • run.sh を直す前は、gameoverlayrenderer.dylib はあとから読み込まれていましたが、Shift+Tab を押してもオーバーレイは開きませんでした。直したあとは、起動の時点から読み込まれ、オーバーレイが開きました。
Mod を入れたゲームの上に開いた Steam オーバーレイ。右上に ゲームに戻る (Shift+Tab) と出ている

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

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

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

run.sh のオーバーレイの部分には手を加えず、4.6.0 の run.sh に「回避策」の手順 3 の 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 のウィンドウ Tool window を直したビルドで、文字が出る(Window font: Arial Unicode MS + Apple Symbols。#86)
最初のフレームまで 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 で起動し、run.sh のオーバーレイの部分を直さずに Shift+Tab を押して開いた Steam オーバーレイ

インストーラーで確認(2026-09-26、TomXV/dragnwash-localization#53)

TomXV/dragnwash-localization#53 の installer/experimental/install-macos.sh を、コミットする前の版で 1 回実行しました。実行したのは、上の 4.6.0 の ci 版の環境(手作業で入れたもの)の上からです。コミットしたのはそのあとです。Doorstop の取得元は、さらにあとのコミットで替えています。

翻訳 Mod は、1.5.0 のリリースの zip を使いました。フレームワークは 1.5.0 で、Tool window だけを #84 のビルドに替えています。インストールのあと、Steam の「プレイ」から起動しました。

項目 結果
ダウンロード なし。BepInEx、Doorstop、ModFramework 1.5.0 は、入っているものをそのまま使った(libdoorstop.dylib は、スクリプトが固定しているものとバイト単位で同じ。4.5.0 と 4.6.0 の ci 版の libdoorstop.dylib は同じバイト列)
run_bepinex.sh executable_name をフルパスにするため書き直した(元のファイルは run_bepinex.sh.dragnwash-backup に残る)。オーバーレイの引き継ぎはすでにあるので、そのまま
起動オプション Steam を終了させてから設定し、Steam を起動し直した
翻訳 日本語で表示された(1773 項目。日本語の 868 字をゲームのフォントに追加)
Steam オーバーレイ Shift+Tab で開いた
F1 のウィンドウ 文字と Inspector のツールバーのアイコンが出た。ウィンドウのフォントは、Hiragino Sans を飛ばして Arial Unicode MS + Apple Symbols になった(詳しくは #86)
  • コミットした版は、サンドボックス(偽の HOME と Steam のフォルダー、偽の curl、/bin/bash 3.2)で 235 件のテストを通りました。
  • 同じサンドボックスで、本物の BepInEx、Doorstop のコピー、ModFramework の zip をダウンロードする新規インストールも行いました。どれも SHA-256 の確認を通って、最後まで終わりました。
  • 試していないこと: 実際のゲームへの、何も入っていない状態からのインストール。コミットした版の実機での実行。実機でのアンインストールと「動作確認」(--check)。Apple Silicon 以外の Mac。

残っている課題

関連

クレジット表記 / Credit

希望します。表記は @223n でお願いします。

Activity

  1. added
    area: framework-coreGame start-up, BepInEx loading, window or alt-tab, crashes not tied to one feature
    bugSomething isn't working
    triage: checkThe automatic triage was unsure; a person should look
    on Sep 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area: framework-coreGame start-up, BepInEx loading, window or alt-tab, crashes not tied to one featurebugSomething isn't workingtriage: checkThe automatic triage was unsure; a person should look

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions