Hey — listen, I spent most of last evening poking at Mercury Game Framework 2 (app) on my Mac, and I figured I’d write this down while it’s still fresh. Not a guide, not a review. Just “here’s what broke, here’s what actually fixed it”.

So the context first. I wanted to spin up a small prototype using Mercury as a lightweight framework layer — nothing fancy, just validating that the build runs locally on macOS before committing to it. This was on macOS Sonoma 14.3, M1 Pro, clean-ish dev environment, Xcode up to date, usual command-line tools already in place. I downloaded the framework bundle, unpacked it, glanced at the README, and did what you’d expect: tried to run the launcher binary to see if everything initialized correctly.

Nothing happened.
No crash dialog. No error popup. No logs in the UI. Just a brief bounce in the Dock and then… gone.

My first instinct (wrong one, as usual) was to assume I messed up a dependency. I checked the obvious stuff: verified the executable bit was set, ran otool -L to see if anything was missing, confirmed it wasn’t trying to link against some ancient library. Everything looked boringly normal. I even rebuilt a small sample project to see if I’d get any output at all. Same behavior — instant exit, zero feedback.

Next attempt was the classic “maybe it hates my shell environment” move. I launched it directly from Terminal to catch stderr. That at least gave me something, but not much: a one-line exit with no descriptive error. No stack trace. No helpful message. Just enough to make me suspicious that macOS itself was involved.

At this point, Gatekeeper crossed my mind, but here’s the thing: there was no warning dialog. No “developer cannot be verified” message. Nothing in System Settings → Privacy & Security asking me to allow the app. That’s what made it confusing. Usually macOS is loud when it blocks something.

I burned another 20 minutes toggling quarantine attributes on the main bundle (which didn’t help), reinstalling the framework, and briefly blaming OrchardKit for shipping a weird build. That was unfair. The framework itself wasn’t broken.

The “oh, come on” moment happened when I checked the Console app and filtered for security-related messages. That’s where I finally saw it: one of the helper binaries inside the framework was being blocked silently. Not the main launcher — a nested executable that Mercury spins up during initialization. Gatekeeper flagged it as unnotarized and killed it before it could do anything visible.

Apple actually documents this behavior, but it’s easy to forget: Gatekeeper doesn’t always surface UI warnings for background helpers or binaries launched programmatically. This is especially common with dev tools and frameworks. The relevant docs live on developer.apple.com under notarization and code signing, and they explain why some launches fail quietly instead of prompting the user.

Once I knew what I was looking for, the fix was almost boring.

I manually removed the quarantine attribute from the entire framework directory (not just the top-level app), then re-ran the launcher from Terminal. This time, macOS immediately threw the familiar “developer cannot be verified” dialog — which was actually a relief, because at least it was honest. I allowed it, relaunched, and suddenly the framework initialized exactly as expected. Logs appeared. Sample project ran. No more disappearing act.

To sanity-check it, I reapplied the quarantine flag to the helper binary only. The problem came back. Removed it again, and everything worked. Consistent, reproducible, and definitely not a Mercury-specific bug.

I ended up bookmarking this page because it helped me confirm how macOS treats nested executables and background helpers in developer tools, especially when notarization is missing or incomplete:
https://rvfcb.com/developer/41368-mercury-game-framework-2.html

What I should have done from the start was run the launcher once from Terminal and then immediately check Console for security logs. That would’ve saved me a chunk of time and a lot of second-guessing. Apple’s own support docs on Gatekeeper behavior and notarization (support.apple.com and developer.apple.com) line up exactly with what I saw in practice — the OS was doing its job, just very quietly.

For future me, and maybe for you if you ever hit this with a framework or toolchain on macOS, here’s the short mental checklist I’m keeping:

• If an app or framework exits instantly with no UI error, assume Gatekeeper before assuming broken code.

• Check for nested executables, not just the main bundle.

• Look in Console for security and codesigning messages — Finder won’t always tell you.

• Don’t blame the framework until you’ve ruled out macOS protections.

Once unblocked, Mercury behaved perfectly. Builds were stable, performance was fine, nothing else needed tweaking. It wasn’t a bad framework or a bad release — just a modern macOS being protective in a way that’s a little too subtle for its own good.

Anyway, that was my evening. Hope this saves you a bit of head-scratching if you run into the same “it launches but actually doesn’t” situation.