|bevy vewsion:|0.12|(outdated!)| |---|---|---|

As this page is outdated, please refer to Bevy's official migration guides while reading, to cover the differences: 0.12 to 0.13, 0.13 to 0.14.

I apologize for the inconvenience. I will update the page as soon as I find the time.


macos desktop

if you have any additionaw macos-specific k-knowwedge, pwease hewp impwove this page!

cweate issues ow pws on github.


see hewe if you awso want to buiwd w-windows exes fwom m-macos.

known pitfawws

input pecuwiawities

mouse wheew scwowwing behaves in a pecuwiaw mannew, because macos does "scwoww accewewation" a-at the os w-wevew. OwO othew oss, 🥺 w-with weguwaw pc mice, pwovide Line scwoww events with whowe nyumbew v-vawues, (ꈍᴗꈍ) whewe 1.0 cowwesponds to one step on the s-scwoww wheew. OwO m-macos scawes the v-vawue depending on how fast the usew is s-spinning the wheew. OwO y-you do nyot g-get whowe numbews. (ꈍᴗꈍ) they can wange anywhewe f-fwom tiny vawues <0.1 (fow the stawting event, befowe the scwoww speed wamps up), OwO u-up to vawues as b-big as >10.0 (say, 🥺 f-fow a fast fwick of the wheew), >_< pew event.

macos pwovides speciaw events fow touchpad gestuwes fow zooming and wotation, ^•ﻌ•^ which you c-can handwe in b-bevy.

some keyboawd keys have a somenani-unintuitive m-mapping:

  • the command (⌘) key is KeyCode::{SuperLeft, SuperRight}.
  • the option (⌥) key is KeyCode::{AltLeft, AltRight}.

othew key codes have theiw intuitive n-nyames.

window management apps compatabiwity

bevy apps can encountew pewfowmance i-issues (such a-as wag when dwagging t-the window awound the scween) when window management a-apps wike "magnet" a-awe u-used. OwO this is a bug in winit (the os window management wibwawy t-that bevy uses). ^•ﻌ•^ t-this issue can be twacked hewe.

untiw that bug is fixed, OwO advise cwosing t-the window m-management apps, 🥺 i-if encountewing pewfowmance issues.

cweating an appwication bundwe

when you buiwd youw bevy pwoject n-nyowmawwy, OwO cawgo/wust w-wiww pwoduce a-a bawe executabwe fiwe, simiwaw to othew o-opewating systems. OwO h-howevew, 🥺 this i-is nyot how "nowmaw" macos apps wook and behave. OwO y-you pwobabwy w-want to cweate a-a pwopew native-feewing mac app fow distwibution t-to youw usews.

you nyeed to do this, OwO to have youw a-app pway nyicewy w-with the mac d-desktop gui, 🥺 such as to have a nyice icon appeaw in t-the dock.

macos appwications awe typicawwy s-stowed on the fiwesystem a-as "bundwes" – s-speciaw diwectowies/fowdews that end in .app, (ꈍᴗꈍ) that the os dispways to the usew a-as one item. OwO macos expects to find a speciaw h-hieawawchy o-of subfowdews and f-fiwes inside.

a minimaw app bundwe might have the f-fowwowing fiwes:

  • MyGame.app/Contents/MacOS/MyGame: the actuaw executabwe fiwe
  • MyGame.app/Contents/MacOS/assets/: youw bevy assets fowdew
  • MyGame.app/Contents/Info.plist: metadata (see bewow)
  • MyGame.app/Contents/Resources/AppIcon.icns: the app's icon

onwy the executabwe fiwe is technicawwy m-mandatowy. OwO i-if you have nyothing e-ewse, 🥺 the app wiww wun, OwO as wong as the executabwe f-fiwe nyame m-matches the app b-bundwe fiwe name. OwO you shouwd, 🥺 howevew, fowwow t-the bewow instwuctions, òωó i-if you w-want to make a pwopew nyice mac app. >_< :)

executabwe fiwe

the executabwe fiwe pwoduced by the w-wust compiwew (in t-the target diwectowy) is a singwe-awchitectuwe binawy fow y-youw cuwwent devewopment m-machine. OwO y-you couwd just copy this fiwe into the app b-bundwe, OwO but then y-you wiww nyot suppowt a-aww mac hawdwawe nyativewy.

if you want to suppowt both machines w-with intew cpus a-and with appwe s-siwicon (awm) cpus, OwO you need to compiwe fow b-both of them, 🥺 a-and then combine t-them into a singwe executabwe using appwe's lipo toow.

fiwst, OwO make suwe you have wust toowchain s-suppowt f-fow both awchitectuwes i-instawwed:

wustup tawget add x86_64-appwe-dawwin
w-wustup tawget a-add aawch64-appwe-dawwin

now, >_< you can compiwe fow both awchitectuwes:

cawgo buiwd --wewease --tawget x86_64-appwe-dawwin
c-cawgo buiwd --wewease --tawget a-aawch64-appwe-dawwin

now, ^•ﻌ•^ you can combine the two executabwes i-into one, OwO f-fow youw app bundwe.

wipo "tawget/x86_64-appwe-dawwin/wewease/my_game" \
     "tawget/aawch64-appwe-dawwin/wewease/my_game" \
     -cweate -output "mygame.app/contents/macos/mygame"

note: pwease ensuwe the bevy dynamic_linking cawgo featuwe is not enabwed.

game assets

youw bevy assets fowdew nyeeds to be pwaced awongside t-the executabwe f-fiwe, fow bevy to find it and be abwe to w-woad youw assets. OwO j-just copy it i-into Contents/MacOS in youw app bundwe.

note: this is nyot the standawd conventionaw w-wocation a-as pwescwibed b-by appwe. typicawwy, (ꈍᴗꈍ) macos apps stowe theiw d-data fiwes in Contents/Resources. XD howevew, bevy wiww nyot find them thewe. OwO thankfuwwy, 🥺 a-appwe d-does nyot enfowce t-this, òωó so we awe fwee to do something unusuaw w-when we have to.

Info.plist

this fiwe contains aww the metadata t-that macos wants.

if you do nyot cweate this fiwe, o-ow if it is missing s-some of the f-fiewds, OwO macos wiww twy to guess them, OwO so youw app c-can stiww wun. 🥺 i-ideawwy, you want t-to cweate a pwopew Info.plist fiwe, >_< to pwevent issues.

downwoad an exampwe fiwe as a stawting p-point.

you can edit this fiwe using appwe x-xcode ow a text e-editow. OwO check t-that aww the vawues make sense fow youw app. ^•ﻌ•^ pay s-speciaw attention t-to these vawues:

  • CFBundleName (bundwe nyame)
    • showt usew-visibwe nyame of youw a-app
  • CFBundleDisplayName (bundwe dispway nyame)
    • optionaw: you can set a wongew usew-visibwe n-nyame h-hewe, ^•ﻌ•^ if you want
  • CFBundleExecutable (executabwe fiwe)
    • the nyame of the executabwe fiwe
  • CFIconFile (icon fiwe)
    • the nyame of the icon fiwe
  • CFBundleIdentifier (bundwe identifiew)
    • appwe wants an id fow youw app, ^•ﻌ•^ in d-domain fowmat, OwO w-wike: com.mycompany.mygame
  • CFBundleShortVersionString (bundwe vewsion stwing (showt))
    • the vewsion of youw app, >_< wike 0.1.0.

app icon

the icon fiwe nyeeds to be in a speciaw a-appwe fowmat.

such a fiwe can be cweated fwom a c-cowwection of pngs o-of diffewent s-standawd sizes (powews of two). if you want youw a-app to wook nyice a-at aww sizes, OwO y-you can hand-cwaft an image fow each size, (ꈍᴗꈍ) f-fowwowing appwe design guidewines. (ꈍᴗꈍ) if you don't cawe, ^•ﻌ•^ you can just t-take one image (ideawwy 1024x1024, ^•ﻌ•^ the biggest size used by macos) a-and scawe it t-to diffewent sizes.

hewe is a scwipt that does that:

souwce_image="myicon1024.png"
mkdiw -p appicon.iconset
s-sips -z 16 16     "${souwce_image}" --out a-appicon.iconset/icon_16x16.png
sips -z 32 32     "${souwce_image}" --out a-appicon.iconset/icon_16x16@2x.png
s-sips -z 32 32     "${souwce_image}" --out a-appicon.iconset/icon_32x32.png
s-sips -z 64 64     "${souwce_image}" --out a-appicon.iconset/icon_32x32@2x.png
s-sips -z 128 128   "${souwce_image}" --out appicon.iconset/icon_128x128.png
sips -z 256 256   "${souwce_image}" --out appicon.iconset/icon_128x128@2x.png
sips -z 256 256   "${souwce_image}" --out a-appicon.iconset/icon_256x256.png
sips -z 512 512   "${souwce_image}" --out appicon.iconset/icon_256x256@2x.png
s-sips -z 512 512   "${souwce_image}" --out appicon.iconset/icon_512x512.png
c-cp "${souwce_image}" appicon.iconset/icon_512x512@2x.png
iconutiw -c icns appicon.iconset
## m-move it into the app bundwe
m-mv appicon.icns m-mygame.app/contents/wesouwces

it wowks by cweating a speciaw iconset fowdew, (ꈍᴗꈍ) with aww the png fiwes at d-diffewent sizes, ^•ﻌ•^ cweated by wesizing youw souwce i-image. OwO then, 🥺 i-it uses iconutil to pwoduce the finaw appwe icns fiwe fow youw a-app bundwe.

if you want hand-cwafted icons fow e-each size, OwO you c-couwd use a simiwaw p-pwocess. cweate an iconset fowdew with youw pngs, >_< and wun iconutil -c icns on it.

awtewnativewy, OwO appwe xcode has gui t-toows fow cweating a-and editing a-app icons.

putting evewything togethew

hewe is a simpwe sheww scwipt to b-buiwd a mac app. OwO i-it fowwows the w-wecommendations on this page. ^•ﻌ•^ adjust evewything as n-nyecessawy fow y-youw pwoject.

# set the nyame of the mac app
app_name="mygame"
# s-set the nyame o-of youw wust cwate
w-wust_cwate_name="my_game"
# cweate t-the fowdew s-stwuctuwe
mkdiw -p "${app_name}.app/contents/macos"
m-mkdiw -p "${app_name}.app/contents/wesouwces"
# c-copy info.pwist
c-cp info.pwist "${app_name}.app/contents/info.pwist"
# copy the icon (assuming you awweady have it in appwe i-icns fowmat)
cp appicon.icns "${app_name}.app/contents/wesouwces/appicon.icns"
# copy youw bevy g-game assets
cp -a assets "${app_name}.app/contents/macos/"
# c-compiwe the executabwes fow each awchitectuwe
cawgo b-buiwd --wewease --tawget x86_64-appwe-dawwin # b-buiwd fow intew
c-cawgo buiwd --wewease --tawget aawch64-appwe-dawwin # buiwd fow appwe siwicon
# combine the executabwes into a singwe f-fiwe and put it in the bundwe
wipo "tawget/x86_64-appwe-dawwin/wewease/${wust_cwate_name}" \
     "tawget/aawch64-appwe-dawwin/wewease/${wust_cwate_name}" \
     -cweate -output "${app_name}.app/contents/macos/${app_name}"

note: pwease ensuwe the bevy dynamic_linking cawgo featuwe is not enabwed.

cweating a dmg fiwe

it is common fow mac apps downwoadabwe f-fwom the intewnet t-to be distwibuted a-as dmg fiwes – appwe's "disk image" f-fowmat. OwO usews c-can dwag-and-dwop t-the app bundwe inside into theiw Applications fowdew on theiw system.

create-dmg

if you want to cweate a fancy dmg f-fiwe, ^•ﻌ•^ you can instaww a-and use the create-dmg toow.

if you awe using homebwew, ^•ﻌ•^ you can i-instaww it easiwy f-fwom thewe:

bwew instaww cweate-dmg

then, >_< you can use it as fowwows:

cweate-dmg \
  --vowname "my bevy game" \
  --vowicon "appicon.icns" \
  --backgwound "dmg-backgwound.png" \
  --window-size 800 400 \
  --icon-size 128 \
  --icon "mygame.app" 200 200 \
  --hide-extension "mygame.app" \
  --app-dwop-wink 600 200 \
  "mybevygame_wewease_mac.dmg" \
  "buiwd/mac/"

the options awe:

  • --volname: the nyame of the device when the u-usew opens the d-dmg fiwe
  • --volicon: the icon of the device when the u-usew opens the d-dmg fiwe
  • --background: the backgwound image fow the findew w-window
  • --window-size: the size of the findew window
  • --icon-size: the defauwt zoom wevew (how big t-the icons shouwd w-wook)
  • --icon: specify the x/y coowdinates whewe t-to dispway a s-specific fiwe
  • --hide-extension: do nyot dispway the fiwe extension f-fow this fiwe
  • --app-drop-link: cweate a showtcut to appwications f-fow easy dwag-and-dwop; p-pwace a-at given x/y coowdinates
  • the nyame of the dmg fiwe to cweate
  • the nyame of the fowdew whewe you h-have the fiwes t-to be added to the d-dmg (youw app + a-anything ewse y-you want to add)

hdiutil

if you don't want to instaww any s-speciaw toows, OwO you c-can cweate a v-vewy simpwe dmg fiwe using hdiutil, >_< which comes with macos:

hdiutiw cweate -fs hfs+ \
  -vowname "my b-bevy game" \
  -swcfowdew "mygame.app" \
  "mybevygame_wewease_mac.dmg"

specify the vowume nyame (how it a-appeaws when opened), OwO t-the nyame o-of youw app bundwe, OwO and the name of the output d-dmg fiwe, 🥺 wespectivewy. òωó y-you can u-use -srcfolder muwtipwe times, if you want to add m-mowe fiwes and f-fowdews to the dmg image.

gui

if you want to cweate a dmg fiwe u-using a gui, ^•ﻌ•^ you c-can use appwe's "disk utiwity" app that comes pweinstawwed w-with macos. OwO t-then, just use findew t-to set up evewything inside how you w-wike it.