Confirmedusers, editor
348
edits
Installing the game on MacOS: Difference between revisions
From Vintage Story Wiki
no edit summary
No edit summary |
|||
| Line 1: | Line 1: | ||
== Introduction == | == 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 | Since game version 1.18.8, Vintage Story is generally compatible with most types of hardware running macOS. macOS was not "officially supported" but it was unofficially supported: the (official!) downloads page offered a macOS build and the game worked reasonably well on a Mac if some additional steps were taken as detailed in the [[#Versions_prior_to_1.19.0:_set_up_using_Homebrew|final section below]]. | ||
Since game version 1.19.0, installation on macOS has been greatly simplified and the additional steps are no longer necessary, and Vintage Story works very well | Since game version 1.19.0, installation on macOS has been greatly simplified and the additional steps are no longer necessary, and Vintage Story now works very well on a Mac, equally well as the Windows and Linux versions. From game version 1.19.2 the remaining known macOS issues are fixed, so the time is now close to being able to say that Vintage Story officially supports macOS once again. \o/ | ||
== Game data folder == | == Game data folder == | ||
| Line 9: | Line 9: | ||
On macOS the game data folder is at filepath: <code>/users/{your username}/.config/VintagestoryData</code>. 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 ever since. | On macOS the game data folder is at filepath: <code>/users/{your username}/.config/VintagestoryData</code>. 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 ever since. | ||
You can | You can find the data folder from inside the game: in the Main Menu, choose Singleplayer game, and then click Open Saves Folder instead of selecting a save. The Saves folder is a subfolder of the VintagestoryData folder. In Finder, View menu, you can click Show Path Bar and to see the full path of the VintagestoryData folder. | ||
If you prefer to find the game data folder at some other location, the simplest solution is to create an alias for <code>/users/{your username}/.config/VintagestoryData</code> and then drag that alias to the new location. | If you prefer to find the game data folder at some other location, the simplest solution is to create an alias for <code>/users/{your username}/.config/VintagestoryData</code> and then drag that alias to the new location. | ||
| Line 17: | Line 17: | ||
All or most modern Macs have very high resolution Retina displays, and the desktop resolution is downscaled so that text and graphics do not look too tiny. For example, a Macbook Air can have an actual hardware display resolution of 2560 x 1600, but the desktop resolution by default will be 1680 x 1050. | All or most modern Macs have very high resolution Retina displays, and the desktop resolution is downscaled so that text and graphics do not look too tiny. For example, a Macbook Air can have an actual hardware display resolution of 2560 x 1600, but the desktop resolution by default will be 1680 x 1050. | ||
On a fresh installation of the game on macOS, Vintage Story will make an initial guess at a reasonable scaling factor for the in-game GUI, including the main menu and the Settings menu. | On a fresh installation of the game on macOS, Vintage Story will make an initial guess at a reasonable scaling factor for the in-game GUI, including the main menu and the Settings menu. From game version 1.19.2 this guess is reasonably good, but if it seems wrong the normal solution is to go to the in-game Settings / Interface menu and change it; the Settings menu can be accessed either from the Main Menu or in-game from the Pause menu. | ||
Occasionally (especially with game versions 1.19.1 and earlier) the GUI scaling might initially be so large on some Mac Retina displays that it causes the Settings menu Interface tab to be off-screen, making it impossible to adjust the GUI scaling in-game. To fix this problem, exit the game, find the [[Installing_the_game_on_MacOS#Game_data_folder|data folder]], and edit the <code>clientsettings.json</code> file in a decent text editor. Search for the <code>"guiScale": </code> setting and set it to a lower value, like 1.0 or 0.75. (You need a text editor which can edit a plain text file, such as ''Notepad++'', ''Brackets'', or ''Sublime Text''. Do not use the macOS in-built TextEdit, that one writes in rtf format which can really mess things up!) | |||
== Installation on macOS with Intel silicon == | == Installation on macOS with Intel silicon == | ||
| Line 29: | Line 29: | ||
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. | 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? | Which game version to download? When it comes, we recommend 1.19.2-stable or later, which has been specifically made for easier installation on macOS. To see other 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. 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 additional installation steps described [[Installing_the_game_on_MacOS#Versions_prior_to_1.19.0:_set_up_using_Homebrew|below]] if required. Bear in mind that game versions prior to 1.19.0 may have other issues on some Macs for example the red sky issue. | ||
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]. | If you run into any difficulty, do ask for help on Discord (search for macOS to find existing Mac discussions) 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'. 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. | To run the game the first time after downloading it, 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'. If you simply double-click the app to run it, it will only give you two 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 issues generally on macOS:=== | ||
====Known current issues==== | ====Known current issues==== | ||
* | * (minor!) in the Settings / Graphics menu, for some players the brown menu background is too small in size so that some settings extend slightly beyond it | ||
====Issues in older game versions==== | ====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 | * prior to game version 1.19.0-rc.8, all macOS versions required additional manual installation steps, see details in separate section below | ||
* prior to game version 1.19.2, 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 | |||
* prior to game version 1.19.2, for some Retina displays, the GUI scaling originally chosen by the game on a clean installation was too large, potentially needing a manual edit to clientsettings.json to fix it | |||
* 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/ | * 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.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>; this has been fixed already in all stable 1.19 releases | ||
* 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 | * 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 | ||
| Line 51: | Line 52: | ||
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 | ''Currently'' as of game version 1.19, Vintage Story does not run "natively" on Arm64 hardware, but thanks to Rosetta 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. | ||
=== Normal installation === | === Normal installation === | ||
For installation, please follow exactly the same directions as for Intel Macs in the [[Installing_the_game_on_MacOS#Installation_on_macOS_with_Intel_silicon|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. | For installation, please follow exactly the same directions as for Intel Macs in the [[Installing_the_game_on_MacOS#Installation_on_macOS_with_Intel_silicon|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: note, it needs to be the x64 version not the arm64 version of the .NET7 Runtime. Then download the macOS version of Vintage Story, version 1.19.2 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. | ||
For most players, the x64 build should "just work" (TM) on Apple silicon as well, 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 manually as detailed in the next two sections below. | For most players, the x64 build should "just work" (TM) on Apple silicon as well, 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 manually as detailed in the next two sections below. | ||
| Line 72: | Line 73: | ||
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: | 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) | : 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 to a different folder) | ||
::: <code>cd ~/Downloads/vintagestory.app/</code> | ::: <code>cd ~/Downloads/vintagestory.app/</code> | ||
::: <code>arch -x86_64 ./Vintagestory</code> | ::: <code>arch -x86_64 ./Vintagestory</code> | ||
| Line 78: | Line 79: | ||
[[File:Allowunidentified.png|frameless|center|Allow unidentified app]] | [[File:Allowunidentified.png|frameless|center|Allow unidentified app]] | ||
== Versions prior to 1.19.0 | == Versions prior to 1.19.0: set up using Homebrew == | ||
Prior to game version 1.19.0 | Prior to game version 1.19.0, at least from version 1.18.8 onwards, 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 | 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, 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. | 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. | ||
| Line 109: | Line 110: | ||
::: <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> | ||
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 | 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 onwards \o/ | ||
