Installing the game on MacOS: Difference between revisions

From Vintage Story Wiki
Line 1: Line 1:
== Installation on MacOS with Intel silicon ==
== Installation on macOS with Intel silicon ==


Since game version 1.18.8, Vintage Story is generally compatible with most types of hardware running MacOS, subject to certain issues experienced on some setups.   See separate section below for MacOS with Apple silicon, such as recent (late 2023) M1 Mac.
Since game version 1.18.8, Vintage Story is generally compatible with most types of hardware running MacOS.  This section describes set up on macOS with Intel Pentium or Xeon CPUs - that's most pre-2022 Macs. See separate section below for macOS with Apple silicon, such as recent M1, M2 or M3 machines.


It is necessary first to install .NET 7 runtime, any recent version, for example 7.0.15.  Download this from https://dotnet.microsoft.com/en-us/download/dotnet/7.0  You do not need the SDK.  You need the runtime, for example '''.NET Runtime 7.0.15''', MacOS version, x64 version.  With you Mac password give it permission to install and it should automatically install.
It is necessary first to install .NET 7 runtime, any recent version, for example 7.0.15.  Download this from https://dotnet.microsoft.com/en-us/download/dotnet/7.0  You do not need the SDK.  You need the runtime, for example '''.NET Runtime 7.0.15''', MacOS version, x64 version. [https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-7.0.15-macos-x64-installer Direct download link] With your Mac password give it permission to install and it should automatically install.


Then to install Vintage Story, in the [https://account.vintagestory.at/ Client Area] select the '''Mac OS App'''.  Download that and make sure you can access its folder <code>~/Downloads/vintagestory.app/</code>, you may want to create a shortcut to the folder.  If you run into difficulty, ask for help on Discord or on a [https://www.vintagestory.at/forums/topic/11017-mac-users-does-the-net7-build-work-for-you/ suitable Forum thread].
Then to install Vintage Story, in the [https://account.vintagestory.at/ Client Area] select the '''Mac OS App'''.  Download that, then when it has finished, in your Downloads folder, double-click the file you downloaded (normally ending with .tar) to Unarchive it.  This creates <code>vintagestory.app</code> in your Downloads folder.  If you want, you can drag <code>vintagestory.app</code> to your Applications folder or anywhere else on your Mac, and you can now delete the .tar download file.


Which game version to download?  To see all versions click on [https://account.vintagestory.at/#otherversions (Show all available downloads and mirrors of Vintage Story)] and you can choose between Stable and Unstable tabs.  At the time of writing (January 2024) we recommend the latest 1.19 version (1.19.0-rc.6) under the Unstable tab.  Although that one is tagged Unstable meaning that it may have some minor new issues with newly added features, generally it fixes numerous things since 1.18.15, including the sky color issue mentioned below.  However, if you want to play multiplayer on a server which is still running game version 1.18.15 (for example) then you would need to install Vintage Story version 1.18.15 of course.
If you run into difficulty, ask for help on Discord or on a [https://www.vintagestory.at/forums/topic/11017-mac-users-does-the-net7-build-work-for-you/ suitable Forum thread].


To run the game the first time, you'll need to [https://www.howtogeek.com/205393/gatekeeper-101-why-your-mac-only-allows-apple-approved-software-by-default/ tell your Mac that it's OK] to run this app from an 'Unidentified developer'. Holding the Option key, click on the app, and select OpenA box will appear asking 'Are you sure you want to open it?' Click the Open button (coloured white), and this security check will be satisfied.
Which game version to download?  To see all versions click on [https://account.vintagestory.at/#otherversions (Show all available downloads and mirrors of Vintage Story)] and you can choose between Stable and Unstable tabs.  At the time of writing (January 2024) we '''highly recommend''' the latest 1.19 version (1.19.0-rc.8) under the Unstable tab, which has been specifically made for easier installation on macOS.  Although that one is tagged Unstable meaning that it may have some minor new issues with newly added features, generally it fixes numerous things since 1.18However, if you want to play multiplayer on a server which is still running game version 1.18.15 (for example) then you would need to install Vintage Story version 1.18.15 of course and follow the steps described below if required.


Known issues generally:
To run the game the first time, you'll need to [https://www.howtogeek.com/205393/gatekeeper-101-why-your-mac-only-allows-apple-approved-software-by-default/ tell your Mac that it's OK] to run this app from an 'Unidentified developer'. Holding the Option key, click on vintagestory.app, and select Open.  A box will appear asking 'Are you sure you want to open it?' Click the Open button (coloured white), and this security check will be satisfied. You only need to give this security approval once.
* rarely on some MacOS setups, the sky was colored red not its correct blue color, in 1.18 game versions. This has been fixed in all 1.19 releases \o/
 
* if an external monitor with high resolution is used with a MacBook, the game window resolution may not fill the full screen on the monitor; a solution is to manually edit both ''info.plist'' files found in the vintagestory.app folder, to add the following text: <code><key>NSHighResolutionCapable</key><false/></code>
Known issues generally on macOS:
* if an external trackpad or external mouse is used alongside the primary system mouse, there were past reports that the external controller was not effective; there have been no recent reports and it is possible this has been resolved by game version 1.18.8.
* prior to game version 1.19.0-rc.8, macOS versions required additional manual installation steps, see details in separate section below
* in 1.18 game versions, on certain Mac hardware, the sky was colored red not its correct blue color. This has been fixed in all 1.19 releases \o/
* prior to game version 1.19.0-rc.7, if an external monitor with high resolution is used with a MacBook, the game window resolution may not fill the full screen on the monitor; a solution was to manually edit both ''info.plist'' files found in the vintagestory.app folder, to add the following text: <code><key>NSHighResolutionCapable</key><false/></code>
* prior to game version 1.18.8, if an external trackpad or external mouse is used alongside the primary system mouse, there were past reports that the external controller was not effective; there have been no recent reports and it is possible this has been resolved from game version 1.18.8
* a small number of players find that the GUI disappears while knapping stone, clayforming clay, or smithing on the anvil, this issue is under investigation


== Installation on MacOS with Apple silicon ==
== Installation on MacOS with Apple silicon ==

Revision as of 20:32, 14 January 2024

Installation on macOS with Intel silicon

Since game version 1.18.8, Vintage Story is generally compatible with most types of hardware running MacOS. This section describes set up on macOS with Intel Pentium or Xeon CPUs - that's most pre-2022 Macs. See separate section below for macOS with Apple silicon, such as recent M1, M2 or M3 machines.

It is necessary first to install .NET 7 runtime, any recent version, for example 7.0.15. Download this from https://dotnet.microsoft.com/en-us/download/dotnet/7.0 You do not need the SDK. You need the runtime, for example .NET Runtime 7.0.15, MacOS version, x64 version. Direct download link With your Mac password give it permission to install and it should automatically install.

Then to install Vintage Story, in the Client Area select the Mac OS App. Download that, then when it has finished, in your Downloads folder, double-click the file you downloaded (normally ending with .tar) to Unarchive it. This creates vintagestory.app in your Downloads folder. If you want, you can drag vintagestory.app to your Applications folder or anywhere else on your Mac, and you can now delete the .tar download file.

If you run into difficulty, ask for help on Discord or on a suitable Forum thread.

Which game version to download? To see all versions click on (Show all available downloads and mirrors of Vintage Story) and you can choose between Stable and Unstable tabs. At the time of writing (January 2024) we highly recommend the latest 1.19 version (1.19.0-rc.8) under the Unstable tab, which has been specifically made for easier installation on macOS. Although that one is tagged Unstable meaning that it may have some minor new issues with newly added features, generally it fixes numerous things since 1.18. However, if you want to play multiplayer on a server which is still running game version 1.18.15 (for example) then you would need to install Vintage Story version 1.18.15 of course and follow the steps described below if required.

To run the game the first time, you'll need to tell your Mac that it's OK to run this app from an 'Unidentified developer'. Holding the Option key, click on vintagestory.app, and select Open. A box will appear asking 'Are you sure you want to open it?' Click the Open button (coloured white), and this security check will be satisfied. You only need to give this security approval once.

Known issues generally on macOS:

  • prior to game version 1.19.0-rc.8, macOS versions required additional manual installation steps, see details in separate section below
  • in 1.18 game versions, on certain Mac hardware, the sky was colored red not its correct blue color. This has been fixed in all 1.19 releases \o/
  • prior to game version 1.19.0-rc.7, if an external monitor with high resolution is used with a MacBook, the game window resolution may not fill the full screen on the monitor; a solution was to manually edit both info.plist files found in the vintagestory.app folder, to add the following text: <key>NSHighResolutionCapable</key><false/>
  • prior to game version 1.18.8, if an external trackpad or external mouse is used alongside the primary system mouse, there were past reports that the external controller was not effective; there have been no recent reports and it is possible this has been resolved from game version 1.18.8
  • a small number of players find that the GUI disappears while knapping stone, clayforming clay, or smithing on the anvil, this issue is under investigation

Installation on MacOS with Apple silicon

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 arch 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.

The following step-by-step guide is offered by user Finn on Discord, originally based on a 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 Homebrew by following the steps below.

  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 Cairo won't install correctly!
  2. As described above, download an installer for x64 .NET Runtime from Microsoft. As above, make sure to get the x64 Version - not the Arm64 version (for now)! .NET Runtime 7.0.15 is recommended. Direct Download Link
  3. Install .NET Runtime by typing the following in Terminal:
arch -x86_64 sudo installer -pkg dotnet-runtime-7.0.15-osx-x64.pkg -target /
(You might need to tweak the filename here based on the version you've downloaded at step 2.)
 4. (If you don't have Homebrew set up already:) Install Homebrew for x64 using these five commands in Terminal:
cd ~/Downloads
mkdir homebrew
curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew
sudo mv homebrew /usr/local/homebrew
export PATH=$HOME/bin:/usr/local/bin:$PATH
 5. Install Cairo by typing the following in Terminal:
arch -x86_64 /usr/local/homebrew/bin/brew install cairo
 6. Now download the game itself from Vintage Story Client Area as described above, choosing the Mac OS App.
 7. In Terminal, cd into the game folder
cd ~/Downloads/vintagestory.app/
 8. Copy (symlink) the Cairo library into the game folder, basically inside 'vintagestory.app'
ln -s /usr/local/homebrew/lib/libcairo.2.dylib libcairo.2.dylib
 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
Allow unidentified app
 10. Run the game (you'll need to do this every time you want to play)
arch -x86_64 ./Vintagestory

Optionally, you can also place the Game file into your applications folder and start it from there. HowToGeek made a great guide to this - follow the instructions for a RAR archive file.