Guide 03

How save works

How the console "memory card" became a folder of folders, and how to keep saves out of a read-only app bundle.

GoalSaving and loading through the game's own menus, with saves you can see, copy and back up.

1Pick the console code path that fits a filesystem

The game runs its Xbox save code (Config::HARDWARE_XBOX): every save is a directory with a display name, holding the data and an icon. Display names may contain characters files can't, so each folder gets a sanitized name and keeps the real one in SaveMeta.txt, like the Xbox's SaveMeta.xbx.

excerptWn32/Code/Plat/Sys/MemCard/p_McMan.cpp

// The game runs the Xbox save code path (Config::HARDWARE_XBOX), where every save is a
// "save game" directory with a display name (e.g. "Tony-Story/Skater") holding the save
// file and an icon. Display names can contain characters that aren't valid in file names,
// so each save directory gets a sanitized name and stores its display name in
// SaveMeta.txt, much like the Xbox's SaveMeta.xbx.
//
//   save/
//     Tony-Story_Skater/
//       SaveMeta.txt          display name
//       Tony-Story_Skater     save data
//       saveimage.xbx         icon

// Bytes per Xbox hard drive block, which is the unit mcfuncs.cpp expects for free space
static const uint64_t s_block_size = 16384;

// Mc::File stores an int handle, which can't hold a FILE* on 64-bit, so keep a table
static std::vector<FILE*> s_open_files;

The game's own save screen, listing the folders in <code>save/</code> with their <code>SaveMeta.txt</code> names, sizes and dates. — The game's own save screen, listing the folders in `save/` with their `SaveMeta.txt` names, sizes and dates.

An int holding a FILE*: fine in 2003, a segfault with extra steps in 64-bit land. Hence the handle table.

2Move user files out of the bundle

From a disk image (read-only) or after Gatekeeper translocation, the app can't write next to itself, and an update would wipe it anyway. So user files get their own root: next to the executable for a plain build, ~/Library/Application Support/THUG for THUG.app.

diffWn32/Code/Plat/Sys/File/p_filesys.cpp · 97790b7

@@ -146,6 +165,37 @@ namespace File
+	// Return user path
+	static std::filesystem::path GetUserPath()
+	{
+#if defined(__APPLE__)
+		// The app bundle may be read-only (run from the disk image, or translocated by Gatekeeper)
+		// and is replaced on updates, so its saves and settings go in ~/Library/Application Support/THUG
+		if (!GetBundleContentsPath().empty())
+		{
+			const char *home = getenv("HOME");
+			if (home == nullptr || home[0] == '\0')
+			{
+				struct passwd *pw = getpwuid(getuid());
+				home = (pw != nullptr) ? pw->pw_dir : "/tmp";
+			}
+
+			std::filesystem::path user_path = std::filesystem::path(home) / "Library" / "Application Support" / "THUG";
+			std::error_code ec;
+			std::filesystem::create_directories(user_path, ec);
+			return user_path;
+		}
+#endif
+		// Next to the executable
+		return ModulePath();
+	}

diffWn32/Code/Plat/Sys/MemCard/p_McMan.cpp · 97790b7

@@ -75,7 +76,7 @@ static std::vector<FILE*> s_open_files;
 static std::filesystem::path s_save_root( void )
 {
-	std::filesystem::path root = ::File::ModulePath() / "save";
+	std::filesystem::path root = ::File::UserPath() / "save";

3Know where your saves are

Running	Saves	Settings
`./Game/THUG`	`Game/save/`	`Game/config.ini`
`THUG.app`	`~/Library/Application Support/THUG/save/`	`~/Library/Application Support/THUG/config.ini`

Back up a save by copying its folder; delete one in the game or by deleting the folder. The most recent story/skater save loads automatically at start.

FOR EDUCATION PURPOSES ONLY. Screenshots are captured from the port running the reader's own copy of the game. The diffs are trimmed to the interesting lines (unchanged context is cut, marked ⋯); the repository has the full changes. Paths are relative to the THUG/ folder.