macOS: Multiple games crash or have other errors if the user doesn't allow ScummVM to access the Documents folder

[Thunderforge]

Overview

macOS 10.15 Catalina introduced new iOS-style protections requiring users to explicitly allow apps to access their webcam, Documents folder, and other potentially sensitive information.

Unfortunately, the default path for ScummVM savegames is ~/Documents/ScummVM Savegames. If the user does not allow ScummVM to access the Documents folder, then multiple games will crash or fail for unexplained reasons.

Set up

If ScummVM is being run on macOS 10.15 Catalina for the first time, simply start up the app. A dialog box will appear saying that ScummVM would like permission to access Documents. Click "Deny". If the dialog does not appear, then ScummVM has already been run on macOS 10.15. To deny access:

1. Open System Preferences
2. Go to "Security & Privacy"
3. Select "Files and Folders"
4. Find ScummVM and uncheck "Documents Folder"

Bugs

The user will not see any immediate issues within the ScummVM app. However, multiple games fail or crash for unexplained reasons. Here are a few I've tested.

General

Manual saves by pressing F5 to bring up the ScummVM menu and clicking the "Save" button do not crash the game, and the game continues without actually saving the game. In ~/Library/Logs/scummvm.log, there will be multiple instances of this:

[2020-04-14 20:51:16] WARNING: DefaultSaveFileManager: failed to open 'timestamps' file to load timestamps!
[2020-04-14 20:51:16] WARNING: DefaultSaveFileManager: failed to open '/Users/TestUser/Documents/ScummVM Savegames/timestamps' file to save timestamps!

Pajama Sam's Sock Works

After creating a new user and starting level 1, you'll get an error saying "This Level cannot be read from the CD" and Sam will say the CD may be dirty and you should clean it.

Spy Fox 2: Some Assembly Required

When you try to save a game, nothing will happen. When you leave the save screen, you'll get this error dialog:

Failed to load saved game from file:

spyfox2-win-temp.sgL

Followed by:

Error reading savegame 861114394 - terminating game (Disk full?)

And then ScummVM exits.

Sam & Max Hit the Road (Demo)

After trying to save a game, I get the following error:

Failed to save game to file:

samnmax.s00

AGI/SCI Games

I tried several King's Quest games for both AGI and SCI and tried saving in the in-game menu. All of them showed no indication that a save was unsuccessful, but there were no saves when I loaded the game.

Suggested Solution

Notify the User

Since the user may be unaware that denying access to the Documents folder is related to saves not actually being saved (as with manual saves and AGI/SCI) or games crashing, the immediate solution would be to provide some sort of notification that this is happening.

Perhaps when the ScummVM launcher starts up, check that the savegame path is writable and prompt the user to change it if it's not (this would address other edge cases as well, such as the savegame path pointing to a folder on removable media that is not inserted).

Change the Default Save Location

A long-term solution for the macOS port would be to change the default location of the savegames files from ~/Documents to ~/Library/Application Support/ScummVM, which is the recommended location according to ​Apple's developer guidelines:

Contains all app-specific data and support files. These are the files that your app creates and manages on behalf of the user and can include files that contain user data.

This will prevent new users from experiencing the issue since ScummVM will not need access to Documents, meaning users will not be prompted. (No special permissions are needed to access Application Support).