Opened 12 years ago

Closed 12 years ago

Last modified 12 years ago

#1145 closed enhancement (fixed)

[PATCH] Improve game data paths in OS X and Windows

Reported by: historic_bruno Owned by: historic_bruno
Priority: Nice to Have Milestone: Alpha 10
Component: Core engine Keywords: osx, build
Cc: Patch:

Description (last modified by historic_bruno)

Paths could be greatly improved for usability and to follow OS conventions on Windows and OS X. The current vision is something like this table with a few tweaks as I go along. To summarize discussions to this point:

  • On Windows, %appdata% or %localappdata% are used for behind-the-scenes data the game creates, and are considered more obscure locations than, say, My Documents. Most users don't even know they exist. So we should use %localappdata% for cache for the reasons given here, and My Documents for most other things like saved games, screenshots, and the proposed user mod. Config and log locations are still up in the air, because at this stage people are often wanting to access the config and log files directly (for troubleshooting things), hopefully less often as we get closer to beta.
    • Implementation is straightforward, just copying and pasting code in wutil.
  • On OS X, ~/Library/Application Support is what we're supposed to use for our run-time game data, with the exception of preferences and cache. Since we're unlikely to switch to using NSPreferences, we can ignore than suggestion, but cache should probably go in ~/Library/Caches (the main distinction is that Application Support is included in backups but Caches is not). However, Application Support is hidden on Lion, so it doesn't seem the best place for saved games, screenshots, and other friendly data. We can use ~/Documents instead.
    • Implementation should use NSSearchPathForDirectoriesInDomains implemented in Objective-C with a plain C wrapper. I hope this will work with Premake and gcc with little extra work, I don't know because we don't have any Objective-C code yet :)
    • There may be some weird cases to test, like what happens if the app bundle is run in "sandbox" mode or if the directory doesn't exist.

Attachments (3)

windows_osx_path_fixes-02042012.patch (17.2 KB ) - added by historic_bruno 12 years ago.
windows_osx_path+bundle_fixes-03062012.patch (25.7 KB ) - added by historic_bruno 12 years ago.
windows_osx_path+bundle_fixes-03212012.patch (25.6 KB ) - added by historic_bruno 12 years ago.

Download all attachments as: .zip

Change History (17)

by historic_bruno, 12 years ago

comment:1 by historic_bruno, 12 years ago

Patch attached. Notes:

  • I went with Philip's suggestion of using %appdata% for config files on Windows, the reason is it's a pain to move configs back and forth, even if we later add an in-game config editor. So I've set the path to where it should be, not where it's more convenient in the short-term. But I did move logs/crash dumps to My Documents for convenience as I don't see any long term alternative to reading logs (they also represent a tiny amount of data and get overwritten).
  • For OS X, I put the config files in Application Support, which is roughly equivalent to app data on Windows. OS X paths basically mirror Windows, except cache goes in ~/Library/Caches.
  • I split Paths::Data into two distinct concepts: user data and game data. UserData is for things the user chose to create explicitly like screenshots and saved games, GameData is for data created internally by the game or mods that were downloaded/installed. We don't currently mount anything in GameData, but we might later, also it's the same as UserData on Linux, unless there are better suggestions.
  • I didn't update the NSIS installer script yet.

comment:2 by historic_bruno, 12 years ago

Need someone to test on OS X, Lion and Snow Leopard if possible, maybe some testing on XP, and if anyone has experience with Objective-C++ and Cocoa - even better :)

Last edited 12 years ago by historic_bruno (previous) (diff)

comment:3 by historic_bruno, 12 years ago

Keywords: review added
Summary: Improve game data paths in OS X and Windows[PATCH] Improve game data paths in OS X and Windows

comment:4 by historic_bruno, 12 years ago

Version 2 of this patch coming soon with various corrections.

in reply to:  1 ; comment:5 by Philip Taylor, 12 years ago

Replying to historic_bruno:

I did move logs/crash dumps to My Documents for convenience as I don't see any long term alternative to reading logs (they also represent a tiny amount of data and get overwritten).

I think the long (or medium) term alternative would be to provide a standalone "Report a problem" program (in the start menu on Windows, and/or automatically run if the game detects it crashed when last run), which uploads the log files and crashdumps and the user-report data (full hardware details etc), and gives the user a report ID number which they can post on IRC/forums/Trac etc so we can easily look up their data. That should be much easier for users than forcing them to register on Trac and find and upload the multiple relevant log files.

in reply to:  5 comment:6 by historic_bruno, 12 years ago

Well actually, looking in %localappdata% on my system reveals a number of log files, but there aren't many in My Documents, so that's something to go by :) I guess we should place files where they logically belong, not where it's temporarily convenient. That does raise the question of what to do with saved games, especially since we can delete them from the main menu now.

Last edited 12 years ago by historic_bruno (previous) (diff)

by historic_bruno, 12 years ago

comment:7 by historic_bruno, 12 years ago

Attached patch with combined path + OS X bundle fixes, which does the following:

  • Windows
    • %localappdata%\0ad - logs, cache
    • %appdata%\0ad - config, game data
    • My Documents\My Games\0ad - user data (screenshots + saved games)
  • OS X
    • ~/Library/Application Support/0ad - logs, config, data
    • ~/Library/Caches/0ad - cache
    • No other directories are written to per Apple's requirements.
    • Checks if valid bundle is used, if so:
      • Load dylibs from bundle's private Frameworks directory (AtlasUI, Collada)
      • Load game data from bundle's Resources directory
  • Other OSes are unchanged

We may not even need the game data vs user data distinction, it seems the only difference is on Windows, where screenshots and saved games are user data and everything else(?) is game data.

Sticking with "0ad" as the subdirectory name unless someone has a better alternative.

Last edited 12 years ago by historic_bruno (previous) (diff)

comment:8 by Kieran P, 12 years ago

Milestone: Alpha 9Alpha 10

comment:9 by Kieran P, 12 years ago

Priority: Should HaveNice to Have

comment:10 by historic_bruno, 12 years ago

Description: modified (diff)

comment:11 by Philip Taylor, 12 years ago

Haven't tried actually running the code, and I haven't attempted to understand Obj-C++, but the rest mostly looks good to me now :-)

Code duplication in wutil.cpp is ugly - should split out the blocks that call SHGetFolderPathW into a new OsPath GetFolderPath(int csidl) function.

The m_rdata setup in Paths.cpp is confusing, and looks like it'll break silently (leaving m_rdata empty) if resourcesPath.empty() is true. Probably best to split that out into a separate function and make it return once it's found a valid path, to avoid needing all the #elses and elses.

Paths.h: "Only things created in reponse" - typo.

osx_GetLibraryPath and osx_GetPicturesPath are defined but never used.

tools/dist/0ad.nsi needs updating to delete $LOCALAPPDATA\0ad\cache and $LOCALAPPDATA\0ad\logs on uninstall.

by historic_bruno, 12 years ago

comment:12 by historic_bruno, 12 years ago

Thanks Philip, I've made those corrections.

The Obj-C++ is fairly straightforward (Apple's documentation is quite helpful), I'm going to replace the hack in osx.cpp where it searches for .app in the path to identify a bundle, instead we should use the NSBundle interface (like the current patch does). After testing I'll commit it.

I included this patch in the Alpha 9 app bundle and haven't seen reports of problems related to paths, so it seems to work :)

comment:13 by ben, 12 years ago

Resolution: fixed
Status: newclosed

In 11389:

Updates data paths on OS X and Windows. On OS X only write to locations inside ~/Library. On Windows make the distinction between local and roaming appdata, and use folder inside My Documents for user-created data. Fixes #1145.
Adds proper OS X app bundle support.
Updates Windows installer script.

comment:14 by historic_bruno, 12 years ago

Keywords: review removed
Note: See TracTickets for help on using tickets.