One of the most important parts of every game, that exceeds the volume of a quick game jam, is the file access.
As you could see in other chapters, there's already some file action going on in raptor, like in LG Localization, Race File Specifications or the Savefile structure.

Aside of that, you will likely have your own data files, you want to access during the game.

raptor offers two groups of file access functions: Sync and Async. Both offer the same signatures, but of course, as the nature of async access is a little different and depends on callbacks, the usage differs a bit.

There are four macros, you should spend a little attention, when setting up your project. All of them can be found quite at the top of the Game_Configuration script of the _GAME_SETUP_ folder of the project template.

As mentioned at the top of this page, both systems, synchronous and asynchronous, offer the same signatures. The async functions have an _async postfix appended to their name, which is quite industry standard.

/// @func	file_read_text_file(filename, cryptkey = "", remove_utf8_bom = true, add_to_cache = false)
/// @desc	Reads an entire file and returns the contents as string
///		checks whether the file exists, and if not, undefined returned.
///		Returns undefined, if the file is not a text file
function file_read_text_file      (filename, cryptkey = "", remove_utf8_bom = true, add_to_cache = false) {
///		If the file does not exist or an exception occurs, the on_failed callback gets invoked
function file_read_text_file_async(filename, cryptkey = "", remove_utf8_bom = true, add_to_cache = false) {

/// @func	file_read_text_file_lines(filename, cryptkey = "", remove_empty_lines = true, 
///					  remove_utf8_bom = true, add_to_cache = false)
/// @desc	Reads an entire file and returns the contents as string array, line by line
///		Checks whether the file exists, and if not, undefined returned.
///		Returns undefined, if the file is not a text file
function file_read_text_file_lines      (filename, cryptkey = "", remove_empty_lines = true, 
					 remove_utf8_bom = true, add_to_cache = false) {
///		If the file does not exist or an exception occurs, the on_failed callback gets invoked
function file_read_text_file_lines_async(filename, cryptkey = "", remove_empty_lines = true, 
					 remove_utf8_bom = true, add_to_cache = false) {

/// @func	file_write_text_file(filename, text, cryptkey = "")
/// @desc	Saves a given text as a plain text file. Can write any string, not only json.
function file_write_text_file      (filename, text, cryptkey = "") {
///		If an exception occurs, the on_failed callback gets invoked
function file_write_text_file_async(filename, text, cryptkey = "") {

/// @func	file_write_text_file_lines(filename, lines_array, cryptkey = "", line_delimiter = "\n")
/// @desc	Saves a given string array as a plain text file.
function file_write_text_file_lines      (filename, lines_array, cryptkey = "", line_delimiter = "\n") {
///		If an exception occurs, the on_failed callback gets invoked
function file_write_text_file_lines_async(filename, lines_array, cryptkey = "", line_delimiter = "\n") {

/// @func	file_read_struct(filename, cryptkey = "", add_to_cache = false)
/// @desc	Reads a given struct from a file, optionally encrypted
function file_read_struct      (filename, cryptkey = "", add_to_cache = false) {
///		If the file does not exist or an exception occurs, the on_failed callback gets invoked
function file_read_struct_async(filename, cryptkey = "", add_to_cache = false) {

/// @func	file_write_struct(filename, struct, cryptkey = "")
/// @desc	Saves a given struct to a file, optionally encrypted
function file_write_struct      (filename, struct, cryptkey = "") {
///		If an exception occurs, the on_failed callback gets invoked
function file_write_struct_async(filename, struct, cryptkey = "") {

/// @func	file_list_directory(_folder = "", _wildcard = "*.*", _recursive = false, attributes = 0)
/// @desc	List all matching files from a directory in an array, optionally recursive
///		_attributes	is one of the attr constants according to yoyo manual
///		
function file_list_directory(_folder = "", _wildcard = "*.*", _recursive = false, _attributes = 0) {

The reason is, that behind the read/write_struct functions, a very powerful feature of raptor is hiding: Class reconstruction.

There is a command, construct(...) in raptor, which will set a marker on all struct classes, so they can be recreated when loaded from a file (i.e. their constructor gets invoked instead of just creating an anonymous struct instance.

To use this feature, just create your struct classes like this:

No reconstruction possible	Reconstruction possible

Just by putting this one line in your class, it gets serializable and will be reconstructed, when you load it from a file.
Keep this in mind, when you create your classes.
You can see many many applications of this throughout the raptor source code. Almost all script classes are reconstructible.

While invoking the Sync functions is a simple, straightforward function call and needs no explanation, the async mechanism depends on a callback to be invoked, when the async operation finished.

All async functions follow this scheme:\

file_some_function_async(<your arguments>)
.set_data("property", "value")   <-- Transport any data value from your current function to the callback
                                     Repeat as often as you like. In the callback, _data contains all the values
.on_finished(function(_result, _data) {
})
[optional!]
.on_failed(function(_data) {
})
.start()    <-- NEVER FORGET THIS!
;

All the async functions return an instance of a raptor-internal __FileAsyncWorker class, which offers these callbacks. They get invoked, when the async operation finishes.
In case, you want to look deeper into the source code: The Async Save/Load event of GameMaker is handled by the GAMECONTROLLER persistent object of raptor. This is the one, communicating with the AsyncWorkers.

As the async functions follow the builder pattern, every method (including .start()!) return self, so you can build chains of calls.

This is important to know, because both, the .on_finished and the .on_failed callback registrations functions allow multiple callbacks to be registered! They will be invoked in the order they are registered.

Let's take the Savegame System as an example. It works async, as any other submodule of raptor, which means, at the moment, where you invoke savegame_save_game(...), your game is not saved! It just started saving. And while there are callbacks/overrides available in each Saveable Object, you might want to have a specific callback to be invoked, when saving finished, and not one in each single saveable instance.

So, even when the savegame system internally already uses a .on_finished callback, you still can add your own!

savegame_save_game("game.sav", FILE_CRYPT_KEY)
.on_finished(function(result, data) {
    ilog($"Game saved. Success = {result}");
});

This callback will be invoked after the raptor-internal callback, where all the Saveable callbacks are invoked and the user events are launched. But still, you can have your own callback, when the operation finished. And this is a great async feature of raptor!

That totally depends on the function you called, but is considered to be intuitive (like you would expect a string[], when you read a file line-by-line and a string containing the whole file if you do not read it line-by-line).

Whatever you like! Use the .set_data("property", value) function to fill an internal struct of the async worker. This is the content of your _data parameter. Use it, to transport any local variables, that might exist only in your local function to the callback.