Best Practices When Programming
© Copyright YoYo Games Ltd. 2023 All Rights Reserved
diff --git a/Manual/contents/Additional_Information/The_File_System.htm b/Manual/contents/Additional_Information/The_File_System.htm index 7fcc3ec6b..f04ba4852 100644 --- a/Manual/contents/Additional_Information/The_File_System.htm +++ b/Manual/contents/Additional_Information/The_File_System.htm @@ -15,34 +15,41 @@The File System
-When using the file system functions or included files with GameMaker it is vitally important to know exactly how the file system 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.
-The first and most important thing to note about the file functions is that they are limited - in general and by default - to the sandbox. What this means is that GameMaker 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, macOS and Ubuntu (Linux) target platforms.
+When using the file system functions or included files with GameMaker, it's important to know how the file system works and what things are going on behind the scenes. 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.
+The first thing to note about the file functions is that they are limited - in general and by default - to the sandbox. What this means is that GameMaker 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, macOS and Ubuntu (Linux) target platforms.
It is possible to turn off sandboxing on the Desktop targets (Windows, macOS, and Ubuntu) by checking the Disable file system sandbox option in the Game Options for the target platform. You do this at your own risk, and while this will open up file saving and loading and permit you to access files anywhere on the given system, it may still be limited by the OS permissions.
+File Areas
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 asset list from the GameMaker 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 File Bundle - This is where all the files that are packaged with the executable are stored, including the files that you have added to the Included Files asset list from the GameMaker IDE (which are the external files that you want packaged with the game). This area can be accessed through the working_directory variable, however, files will be read from this location automatically when reading, without explicitly needing a path - this is explained more in the next section. +
- 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. This can be accessed through the game_save_id variable, however files will be read from this location too automatically when reading, and any saves are done here by default.
The following diagram may help you to visualise this better:
When your game is sandboxed, the two target areas - the bundle directory and the local storage area - are available on each target platform, but on each one they will work slightly differently. However GameMaker 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:
+Accessing File Areas
+When your game is sandboxed, only the two target areas - the file bundle and the save area - are available on each target platform, but on each one they will work slightly differently. However GameMaker 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, let's look at how files are looked up in GameMaker, say if you do a read:
+buf = buffer_load("my_file.dat");
+or a write:
+buffer_save(buf, "my_file.dat");
+This will do one of two things depending on whether you are reading or writing:
-
-
- 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 exist 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. +
- Reading Operations - This will first check the save area to see if the file being accessed is there, and if it is, it uses that. However if the file does not exist 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, unless the sandbox is disabled and a path outside the save area is explicitly specified.
In general GameMaker will handle all this for you and you rarely need to use the working_directory built-in variable.
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. Note that the original files will still remain in the read-only part of the save directory, but they won't be referenced as long as a version exists in the read/write section of 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. Note that the original files will still remain in the read-only part of the save directory, but they won't be referenced as long as a version exists in the read/write section of the save area.
On the Windows, macOS and Ubuntu (Linux) platforms there are two ways to save and load files from outside of the sandbox and that is either 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 - see the function descriptions for more details). The other way is to disable the sandbox altogether from the Game Options for the target platform (only available for Desktop targets, as discussed further up this page).
+Outside The Sandbox
+On the Windows, macOS and Ubuntu (Linux) platforms there are two ways to save and load files from outside of the sandbox and that is either 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 returned string can then be used in the rest of the file functions to bypass the sandbox - see the function descriptions for more details). The other way is to disable the sandbox altogether from the Game Options for the target platform (only available for Desktop targets, as discussed further up this page).
On HTML5 it is also possible to load files from outside the sandbox from a server, however this should only be done using the function buffer_load_async as loading synchronously has been deprecated on most browsers and will eventually be obsoleted. This means that files being loaded in this way should be saved as binary files - for example, you can save an *.ini as a string (see ini_close for details) and then write that into a buffer which can then be saved and loaded using the async functions. Note that if you are loading images using sprite_add then these are already dealt with asynchronously.
-You should also 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 when sandboxed:
+Save Area Locations
+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 when sandboxed:
-
-
- 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). +
- Windows: Windows has all files in the %localappdata%\<Game Name> directory (on Windows this is the /Users/<User Name>/AppData/Local/<Game Name> directory).
- HTML5, GX.games: Everything is done through the local storage.
- macOS: Storage will depend on whether the application is sandboxed or not (following Apple's 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> @@ -55,8 +62,8 @@