Installing the game on MacOS

Introduction

Since game version 1.18.8, Vintage Story is generally compatible with most types of hardware running macOS. macOS was not "officially supported" but in fact the game worked on a Mac, at least if some additional steps were taken as detailed in section 4 below.

Since game version 1.19.0-rc.8, installation on macOS has been greatly simplified and the additional steps are no longer necessary, and Vintage Story works very well and is close to being able to say again that it officially supports macOS. \o/

Game data folder

On macOS the game data folder is at filepath: /users/{your username}/.config/VintagestoryData. This is a different location from Windows/Linux, the reason is that historically that was where .NET applications were advised to place their data on macOS, and it has been kept that way for backwards compatibility reasons.

If you prefer to find the game data folder at some other location, the simplest solution is to create an alias for /users/{your username}/.config/VintagestoryData and then drag that alias to the new location.

Installation on macOS with Intel silicon

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

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), until there is a stable 1.19 version, we highly recommend the latest 1.19 version (1.19.0-rc.8 or later) 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.

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

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'. If you simply double-click the app to run it, it will only give you options to move it to Bin or to Cancel, so press Cancel. Instead, to tell your Mac it's OK, hold the Command 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:

Known current issues

• on Apple silicon (M1/M2/M3) only, the hotbar and other HUD elements may become (temporarily) invisible while knapping stone, clayforming clay, or smithing on the anvil, this issue is under investigation; look away at some other block (with a black block outline around it) to restore the HUD
• in the Settings / Graphics menu, the brown menu background is too small in size so that some settings extend beyond it

Issues in older game versions

• 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

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, 120fps has been reported. 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 arch 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.

For installation, please follow exactly 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 vintagestory.app as soon as you have Unarchived it and given it permission to Open.

Manual installation of .NET 7 Runtime

For most people, the .NET Runtime will automatically install simply by double-clicking on it in the Downloads folder. But if necessary it can be manually installed using the following steps:

1. First download the installer for x64 .NET Runtime from 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. Direct Download Link
2. Then start Terminal
3. If necessary, use cd ~/Downloads to change to the Downloads folder if Terminal is not already there
4. Manually 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 precise version of .NET Runtime you've downloaded.)

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:

 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)

cd ~/Downloads/vintagestory.app/

arch -x86_64 ./Vintagestory

 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

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 client-main.txt referring to libcairo.2.dylib.

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 Homebrew by following the steps below.

The following step-by-step guide is adapted from the one offered by user Finn on Discord, originally based on a forum post by Bohdan Vasylyshyn, reproduced here with thanks.

 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 start Terminal and then type git 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.

 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:

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

 3. Now install Cairo by typing the following in Terminal:

On a Mac M1 / M2 / M3:

arch -x86_64 /usr/local/homebrew/bin/brew install cairo

Or on an Intel Mac:

/usr/local/homebrew/bin/brew install cairo

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.

 4. Now download Vintage Story (if you didn't already) and double-click it to Unarchive it to vintagestory.app.

 5. In Terminal, cd into the vintagestory.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:

cd ~/Downloads/vintagestory.app/

 6. In Terminal, from the vintagestory.app folder, type the following command:

ln -s /usr/local/homebrew/lib/libcairo.2.dylib libcairo.2.dylib

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/