Running a game on macOS: signing and diagnosis

This page covers launching an exported Reckfell game on macOS and separating system-policy blocks from application failures. First create a macOS export; see Exporting for macOS.

First launch

Extract a ZIP before launching its .app, or copy the application from a mounted disk image to the intended installation directory. Keep the complete bundle and its accompanying files together. Moving an app to Applications does not repair its signature or notarize it.

For software distributed outside the Mac App Store, signing, notarization and launch approval are different steps. An ad-hoc signature supplies no Developer ID identity. A local build working on the developer's Mac does not prove that the downloaded release will pass Gatekeeper on another Mac. App Store distribution uses its own submission checks; it is not a separate manual notarization workflow. See Apple's notarization requirements.

If macOS blocks a trusted test build as unidentified or not notarized, first try to open it. Then use System Settings → Privacy & Security → Open Anyway, where available, and confirm the specific application. Labels and availability depend on macOS and device-management policy. This is an exception for that application, not a distribution fix. Follow Apple's current launch instructions.

An alert about malware, revoked authorization or a damaged/modified application requires a different investigation. Obtain a fresh trusted package and report the exact alert to its developer. Re-signing or removing quarantine does not establish that a damaged download is correct. This workflow does not require disabling system-wide protection.

Inspect a failing bundle

Run the following on the target Mac. Replace the first value with the actual absolute .app path. CFBundleExecutable supplies the executable name; it need not match the displayed game name.

APP="/absolute/path/My Game.app"
EXECUTABLE=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleExecutable' "$APP/Contents/Info.plist")
file "$APP/Contents/MacOS/$EXECUTABLE"
codesign --display --verbose=4 "$APP"
codesign --verify --deep --strict --verbose=2 "$APP"
spctl --assess --type execute --verbose=4 "$APP"
xattr -l "$APP"

These commands inspect metadata, architecture, signatures and local launch policy; they do not re-sign the application, change Gatekeeper rules or remove quarantine. If reading CFBundleExecutable fails, resolve the bundle/path problem before using the remaining executable checks.

• file identifies available architectures. An arm64 Mac, an Intel Mac and a universal build are different targets; native libraries must support the running architecture too.
• codesign --display reports the signature identity. codesign --verify checks signed-code integrity; inspect its diagnostic and exit status. A valid ad-hoc signature is not Developer ID or proof of notarization.
• spctl --assess evaluates the current machine's policy. Its result can depend on device management and local policy. It does not replace a clean-machine test of the delivered archive.
• xattr -l lists attributes. The presence or absence of com.apple.quarantine alone does not prove integrity, safety or successful notarization.

Apple documents the distinction between signature verification and policy assessment. Keep the full outputs with the tested archive's hash, macOS version and CPU architecture.

If the game starts and immediately exits

After establishing that this is the intended build, run its executable from Terminal to retain startup diagnostics:

"$APP/Contents/MacOS/$EXECUTABLE" --verbose

Use the same APP and EXECUTABLE values as above. This command launches the game. A Terminal launch may have a different environment and working directory from Finder; success here does not replace testing the normal Finder launch.

Check the last error rather than assuming Gatekeeper caused every exit. For a crash, retain the matching macOS crash report and symbols from that exact build; see Native debugging on macOS.

Use asset:// for packed project assets and user:// for writable saves. The current process directory is not the project directory or a stable location next to the .app. macOS may run a quarantined application from a translocated path. Moving the bundle is not a substitute for correcting relative-path assumptions; do not write generated data into the signed bundle.

What the exporter guarantees

In current sources, macOS-hosted exports default to the Xcode codesign tool; other hosts default to built-in ad-hoc signing. The Xcode identity is initially empty, which the exporter treats as ad-hoc. Notarization defaults to disabled. These defaults do not create a Developer ID release.

The signing helper reports external signing failures as warnings and returns no signing status to its caller. Therefore, an otherwise successful export is insufficient evidence of a valid signature: inspect the export log and final bundle.

The notarytool branch reports a request UUID after submission. That is not an accepted notarization result. Check the final status and log using Apple's workflow, then prepare the ticket and final archive for distribution. Changing bundle contents after signing can invalidate the signature. See Apple's notarization workflow.

For a C# export, preserve the managed payload, architecture-matched native dependencies and required entitlements. When the exporter generates entitlements itself, a build with CSharpScript enables JIT-related permissions; a custom entitlement file needs its own review. codesign/entitlements/debugging defaults to false; enabling it adds com.apple.security.get-task-allow to generated entitlements. Keep local debugging and release signing separate.

Diagnose by symptom

For this guide, exporter defaults, signing/submission control flow, generated entitlements and path mapping were reviewed in source, alongside Apple documentation. No macOS UI, signature, notarization, quarantine, exported application or device launch was exercised on this Windows review host.