Files

It is useful to use external files in games. For example, you could make a file that describes at what moments certain things should happen. Also you probably want to save information for the next time the game is run (for example, the current room). The following functions exist to read and write data in text files:

file_text_open_read(fname) Opens the file with the indicated name for reading. The function returns the id of the file that must be used in the other functions. You can open multiple files at the same time (32 max). Don't forget to close them once you are finished with them.
file_text_open_write(fname) Opens the indicated file for writing, creating it if it does not exist. The function returns the id of the file that must be used in the other functions.
file_text_open_append(fname) Opens the indicated file for appending data at the end, creating it if it does not exist. The function returns the id of the file that must be used in the other functions.
file_text_close(fileid) Closes the file with the given file id.
file_text_write_string(fileid, str) Writes the string to the file with the given file id.
file_text_write_real(fileid, x) Write the real value to the file with the given file id.
file_text_writeln(fileid) Write a newline character to the file.
file_text_read_string(fileid) Reads a string from the file with the given file id and returns this string. A string ends at the end of line.
file_text_read_real(fileid) Reads a real value from the file and returns this value.
file_text_readln(fileid) Skips the rest of the line in the file and starts at the start of the next line.
file_text_eof(fileid) Returns whether we reached the end of the file.

To manipulate files in the file system you can use the following functions:

file_exists(fname) Returns whether the file with the given name exists (true) or not (false).
file_delete(fname) Deletes the file with the given name.
file_rename(oldname, newname) Renames the file with name oldname into newname.
file_copy(fname, newname) Copies the file fname to the newname.
directory_exists(dname) Returns whether the indicated directory does exist. The name must include the full path, not a relative path.
directory_create(dname) Creates a directory with the given name (including the path towards it) if it does not exist. The name must include the full path, not a relative path.
file_find_first(mask, attr) Returns the name of the first file that satisfies the mask and the attributes. If no such file exists, the empty string is returned. The mask can contain a path and can contain wildchars, for example 'C:\temp\*.doc'. The attributes give the additional files you want to see. (So the normal files are always returned when they satisfy the mask.) You can add up the following constants to see the type of files you want:

fa_readonly read-only files
fa_hidden hidden files
fa_sysfile system files
fa_volumeid volume-id files
fa_directory directories
fa_archive archived files

file_find_next() Returns the name of the next file that satisfies the previously given mask and the attributes. If no such file exists, the empty string is returned.
file_find_close() Must be called after handling all files to free memory.
file_attributes(fname, attr) Returns whether the file has all the attributes given in attr. Use a combination of the constants indicated above.

The following functions can be used to change file names. Note that these functions do not work on the actual files they only deal with the strings.

filename_name(fname) Returns the name part of the indicated file name, with the extension but without the path.
filename_path(fname) Returns the path part of the indicated file name, including the final backslash.
filename_dir(fname) Returns the directory part of the indicated file name, which normally is the same as the path except for the final backslash.
filename_drive(fname) Returns the drive information of the filename.
filename_ext(fname) Returns the extension part of the indicated file name, including the leading dot.
filename_change_ext(fname, newext) Returns the indicated file name, with the extension (including the dot) changed to the new extension. By using an empty string as the new extension you can remove the extension.

In rare situations you might need to read data from binary files. The following low-level routines exist for this:

file_bin_open(fname, mod) Opens the file with the indicated name. The mode indicates what can be done with the file: 0 = reading, 1 = writing, 2 = both reading and writing). When the file does not exist it is created. The function returns the id of the file that must be used in the other functions. You can open multiple files at the same time (32 max). Don't forget to close them once you are finished with them.
file_bin_rewrite(fileid) Rewrites the file with the given file id, that is, clears it and starts writing at the start.
file_bin_close(fileid) Closes the file with the given file id.
file_bin_size(fileid) Returns the size (in bytes) of the file with the given file id.
file_bin_position(fileid) Returns the current position (in bytes; 0 is the first position) of the file with the given file id.
file_bin_seek(fileid, pos) Moves the current position of the file to the indicated position. To append to a file move the position to the size of the file before writing.
file_bin_write_byte(fileid, byte) Writes a byte of data to the file with the given file id.
file_bin_read_byte(fileid) Reads a byte of data from the file and returns this.

If the player has checked secure mode in his preferences, for a number of these routines, you are not allowed to specify a path, and only files in the application folder can e.g. be written.

If you included files in the game executable and did not automatically export them at the start of the game, you can use the following functions to do this.

export_include_file(fname) Exports the included file with the name fname. This must be a string variable, so don't forget the quotes.
export_include_file_location(fname, location) Exports the included file with the name fname to the given location. Location must contain the path and the filename.
discard_include_file(fname) Discard the included file with the name fname, freeing the memory used. This must be a string variable, so don't forget the quotes.

The following four read-only variables can be useful:

game_id* Unique identifier for the game. You can use this if you need a unique file name.
working_directory* Working directory for the game. (Not including the final backslash.)
program_directory* Directory in which the game executable is stored. (Not including the final backslash.) When you run a standalone game this is normally the same as the working directory unless the game e.g. opens a file using the file selector. Note that when testing a game you are creating the program and working directory will be different. In that case the working directory is the place where the editable version is stored while the program directory is a temporary directory for testing.
temp_directory* Temporary directory created for the game. (Not including the final backslash.) You can store temporary files here. They will be removed at the end of the game.

In certain situations you might want to give players the possibility of providing command line arguments to the game they are running (for example to create cheats or special modes). To get these arguments you can use the following two routines.

parameter_count() Returns the number of command-line parameters. The actual parameters can be retrieved with the following function.
parameter_string(n) Returns command-line parameters n. The first parameter has index 1. The last one has index parameter_count(). Index 0 is a special one. It is the filename of the game executable (including the path).

You can read the value of environment variables using the following function:

environment_get_variable(name) Returns the value (a string) of the environment variable with the given name.