Installing the game on MacOS: Difference between revisions

From Vintage Story Wiki
Line 24: Line 24:
Apple's recently released Mac M1, M2 or M3 computers - all new Macs since June 2023 - use "Apple silicon" (based on ARM) for better performance, better graphics and lower power consumption.
Apple's recently released Mac M1, M2 or M3 computers - all new Macs since June 2023 - use "Apple silicon" (based on ARM) for better performance, better graphics and lower power consumption.


''Currently'' as of game version 1.19.0, Vintage Story does not run "natively" on ARM64 hardware, but the x64 build of the game (the same as for MacOS with Intel silicon) can be run successfully and with decent performance, using <code>arch</code> in Terminal to run some commands as detailed below.  The Vintage Story developers intend in future to release a native ARM64 version of the game, but this is dependent on some third-party libraries releasing ARM64 versions, which are not yet available.
''Currently'' as of game version 1.19.0, Vintage Story does not run "natively" on Arm64 hardware, but the x64 build of the game (the same as for MacOS with Intel silicon) can be run successfully and with decent performance. For most players, the x64 build should "just work" (TM), this is the magic of Rosetta.  If for some reason Rosetta does not work you can use <code>arch</code> in Terminal to run the game as detailed below.  The Vintage Story developers intend in future to release a native Arm64 version of the game, but no release date for this has been announced.


The following step-by-step guide is offered by user Finn on [https://discord.com/channels/302152934249070593/1180622192027914310/1182672688527966400 Discord], originally based on a [https://www.vintagestory.at/forums/topic/11017-mac-users-does-the-net7-build-work-for-you/#comment-47058 forum post by Bohdan Vasylyshyn], reproduced here with thanks.  Essentially, some of the steps described are necessary to install the .NET7 Runtime and to make Cairo work with Apple silicon, and you should only need to do this once. Cairo is a third-party code library which is used by Vintage Story for displaying all the in-game text and fonts, and it has to be present for the game to work. We are unable to create Cairo but each player can create it themselves using [https://formulae.brew.sh/formula/cairo Homebrew] by following the steps below.
Please follow the same directions as for Intel Macs in the section above.  You first need to download and install .NET 7 Runtime (macOS x64 version), see link above, if you do not already have that on your computer. Then download the macOS version of Vintage Story, version 1.19.0-rc.8 or later, and it should simply run from <code>vintagestory.app</code> as soon as you have Unarchived it and given it permission to Open.


# First of all: Make sure you have the latest Command Line Tools for Xcode installed (they come with the OS but you may not have used them before now), otherwise Cairo won't install correctly!
=== Manual installation .NET 7 Runtime ===
# As described above, download an installer for x64 .NET Runtime from [https://dotnet.microsoft.com/en-us/download/dotnet/7.0 Microsoft]. As above, make sure to get the x64 Version - not the Arm64 version (for now)!  .NET Runtime 7.0.15 is recommended. [https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-7.0.15-macos-x64-installer Direct Download Link]
 
# Install .NET Runtime by typing the following in Terminal:
For most people, the .NET Runtime will automatically install just by double-clicking on it in the Downloads folder.  But if necessary it can be manually installed using the following steps:
# First download the installer for x64 .NET Runtime from [https://dotnet.microsoft.com/en-us/download/dotnet/7.0 Microsoft]. Currently, while Vintage Story has no native Arm64 build, it is important to get the x64 Version of .NET Runtime - not the Arm64 version!  .NET Runtime 7.0.15 is recommended. [https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-7.0.15-macos-x64-installer Direct Download Link]
# Then [https://support.apple.com/en-gb/guide/terminal/apd5265185d-f365-44cb-8b09-71a064a42125/mac start Terminal]
# If necessary, use <code>cd ~/Downloads</code> to change to the Downloads folder if Terminal is not already there
# Manually install .NET Runtime by typing the following in Terminal:
::: <code>arch -x86_64 sudo installer -pkg dotnet-runtime-7.0.15-osx-x64.pkg -target /</code>
::: <code>arch -x86_64 sudo installer -pkg dotnet-runtime-7.0.15-osx-x64.pkg -target /</code>
:: (You might need to tweak the filename here based on the version you've downloaded at step 2.)
:: (You might need to tweak the filename here based on the precise version you've downloaded.)
:  &nbsp;4. (If you don't have Homebrew set up already:) Install Homebrew for x64 using these five commands in Terminal:
 
=== Manually starting Vintage Story ===
For most people, the vintagestory.app can simply be double-clicked to run the game, or (on first run) Command+click and select Open, then tell macOS it's OK to Open this application by an unidentified developer.  Rosetta should automatically detect that it's a x64 application.  But if for some reason Rosetta is not working or you want to start the game manually, use the following steps:
 
:  &nbsp;1. In Terminal, use these commands to run the game (you'll need to do this every time you want to play; adjust /Downloads/ folder to /Applications/ or anywhere else if you moved vintagestory.app)
::: <code>cd ~/Downloads/vintagestory.app/</code>
::: <code>arch -x86_64 ./Vintagestory</code>
:  &nbsp;2. On first run, you'll need to tell System Preferences / Security & Privacy that it's OK to allow this app by an unidentified developer
[[File:Allowunidentified.png|frameless|center|Allow unidentified app]]
 
 
== Versions prior to 1.19.0-rc.8: set up using Homebrew ==
 
Prior to game version 1.19.0-rc.8, it was necessary to set up Cairo using Homebrew, one time, before Vintage Story could run successfully.  Failure to do this would produce a crash as soon as the game app starts, with  error messages in <code>client-main.txt</code> referring to <code>libcairo.2.dylib</code>.
 
Cairo is a third-party code library which is used by Vintage Story for displaying all the in-game text and fonts, and it has to be present for the game to work. Prior to 1.19.0-rc.8, Cairo was not fully included in the Vintage Story download, some players might have had a working copy of it thanks to other software installed on their computer, but for most players the player had to create a working version of Cairo themselves using [https://formulae.brew.sh/formula/cairo Homebrew] by following the steps below.
 
The following step-by-step guide is adapted from the one offered by user Finn on [https://discord.com/channels/302152934249070593/1180622192027914310/1182672688527966400 Discord], originally based on a [https://www.vintagestory.at/forums/topic/11017-mac-users-does-the-net7-build-work-for-you/#comment-47058 forum post by Bohdan Vasylyshyn], reproduced here with thanks.
 
:  &nbsp;1. First of all: Make sure you have the latest Command Line Tools for Xcode installed (they come with the OS but you may not have used them before now), otherwise the commands below cannot be used.  The easiest way to do this is to [https://support.apple.com/en-gb/guide/terminal/apd5265185d-f365-44cb-8b09-71a064a42125/mac start Terminal] and then type <code>git</code> and press Enter. This will trigger an automatic process which installs the Command Line Tools, it may take a few minutes; or if it does nothing much, you probably have the Tools installed already.
:  &nbsp;2. ''If you don't have Homebrew set up already:'' Install Homebrew for x64 using these five commands in Terminal, type them exactly as written here:
::: <code>cd ~/Downloads</code>
::: <code>cd ~/Downloads</code>


Line 43: Line 67:


::: <code>export PATH=$HOME/bin:/usr/local/bin:$PATH</code>
::: <code>export PATH=$HOME/bin:/usr/local/bin:$PATH</code>
:  &nbsp;5. Install Cairo by typing the following in Terminal:
:  &nbsp;3. Now install Cairo by typing the following in Terminal:
::: <code>arch -x86_64 /usr/local/homebrew/bin/brew install cairo</code>
::: <code>arch -x86_64 /usr/local/homebrew/bin/brew install cairo</code>
:  &nbsp;6. Now download the game itself from [https://account.vintagestory.at/ Vintage Story Client Area] as described above, choosing the Mac OS App.
:: This will take many minutes to complete, with hundreds of lines of log messages in Terminal. It can take half an hour or more on some machines.
 
:  &nbsp;4. Now download Vintage Story and double-click it to Unarchive it to <code>vintagestory.app</code>. In Terminal, cd into the vintagetory.app folder: here we assume it is still located in Downloads, but if you moved it to Applications or somewhere else, then change Downloads to Applications as appropriate:
:  &nbsp;7. In Terminal, cd into the game folder
::: <code>cd ~/Downloads/vintagestory.app/</code>
::: <code>cd ~/Downloads/vintagestory.app/</code>
:  &nbsp;8. Copy (symlink) the Cairo library into the game folder, basically inside 'vintagestory.app'
:  &nbsp;5. In Terminal, from the vintagestory.app folder, type the following command:
::: <code>ln -s /usr/local/homebrew/lib/libcairo.2.dylib libcairo.2.dylib</code>
::: <code>ln -s /usr/local/homebrew/lib/libcairo.2.dylib libcairo.2.dylib</code>
:  &nbsp;9. On first run, you'll need to tell System Preferences / Security & Privacy that it's OK to allow this app by an unidentified developer
[[File:Allowunidentified.png|frameless|center|Allow unidentified app]]
:  &nbsp;10. Run the game (you'll need to do this every time you want to play)
::: <code>arch -x86_64 ./Vintagestory</code>


Optionally, you can also place the Game file into your applications folder and start it from there. [https://www.howtogeek.com/177619/how-to-install-applications-on-a-mac-everything-you-need-to-know/#other-archive-files-and-loose-application-icons HowToGeek] made a great guide to this - follow the instructions for a RAR archive file.
That's it. Hopefully it all worked, and as written above, you should only need to do this once - or not at all from game version 1.19.0-rc.8 onwards \o/
Retrieved from "https://wiki.vintagestory.at/index.php/Installing_the_game_on_MacOS"