File System Limits

Here you can find information on how the file
system works and its limits.

When using the file system functions included with GameMaker:
Studio it is vitally important to know exactly how everything
works and what things are going on behind the scenes. To that end,
this section is designed to explain and clarify exactly how things
are stored, where they are stored and what possible limits or
workarounds there may be to this system.

Sandboxing

The first (and most important) thing to note about the file
functions is that they are limited (in general) to the
sandbox. What this means is that GameMaker: Studio
cannot save or load files from anywhere that is not part of the
game bundle or the local storage for the device without
explicit input from the user, and even then this input is
limited to only Windows and Mac target platforms.

To understand the sandbox first of all you need to understand that
there are two distinct areas for files:

The File Bundle - this is where all the files that are
packaged with the executable game are stored, including the files
that you have added to the Included Files resource list from
the GameMaker: Studio IDE (which are the external files that
you want packaged with the game).

The Save Area - this is an area of device storage that
can be safely written to by the game and the game is guaranteed
that this is a writable area.

The following diagram may help you to visualise this better:

NOTE: You can never write to the File Bundle
directory.

Using the File Functions

The two target areas (Bundle directory and the local storage
area) are available on each target platform, but on each one they
work slightly differently. However GameMaker: Studio has
abstracted out the main essence of what can and can't be done,
making it easier to re-target games to multiple environments.

To start with, you should understand what is meant when we talk of
the working_directory. This is a
synonym for the two possible save locations (as illustrated by the
diagram above) and when you use that directory it will do one of
two things depending on whether you are reading or writing, and
whether the file you are reading from has been changed or not:

Reading Operations - working_directory will
first check the save area to see if the file being accessed is
there, and if it is uses that. However if the file does not exists
in the save area, it then checks the file bundle area and uses that
(if the file being looked for is an included file with your
game).

Writing Operations - This can only happen in the save
area.

Using these two simple rules we can now see how the following
functions work (these are examples to help you to visualise the
process for the different functions available):

directory_create
(and the other directory functions) will only work in the save
area.

the file system
functions will return information on files from both the
bundle and the save area, but will only write to the save
area.

the functions for writing text, binary or ini files will create
a new file in the save area if one does not already exist, copying
over any information from the original files included with
the game bundle should they exist.

Saving And Loading Outside The Sandbox

On the Windows platform there is one way to save and load files
from outside of the sandbox and that is using the functions
get_open_filename
and get_save_filename.
Both of these functions will require that the user select an area
for loading and saving and the return string can then be used in
the rest of the file functions to bypass the sandbox.

Platform Specific Saving/Loading

When working with GameMaker: Studio, you should know that
each target platform has its own save area where files and
directories can be written to and read from. Below is a list of
those areas for each target:

Windows - Windows has all files in the
%localappdata%\<Game Name> directory (on Windows 7
this is the /Users/<User Name>/AppData/Local/<Game
Name> directory).

Mac OS - Storage will depend on whether the application
is sandboxed or not (following Apples rules, with the path usually
being ~/Library/Application Support/<Game
Name>).

Ubuntu (Linux) - Files are stored in the
Home/.config/gamename where "Home" is the users home
directory - /home/<username>

HTML5 - Everything is done through the local
storage.

iOS - Storage is the standard location (as viewed
through iTunes).

Android - Files are in the standard location (which is
invisible unless the device is rooted) /data/data/<package
name>.

While on some platforms you can use the file name on its own to
access included files, it is worth noting that on devices (Android,
iOS) you must use the prefix of the
working_directory to access stored files as using just the
relative path will not work. It is also worth noting that the HTML5
target module has a limit on local storage (which can be between
1MB and 5MB depending on the browser) meaning that you will not be
permitted to save large sprites, screenshots etc....