File search

File Search functions in Game Maker have a multitude of uses, and are crucial to several types of games. Uses for these functions can include loading a save game, loading an image or file, etc.

The Basics
Though many people think of file search as a limited mechanism to find a single file, it actually is capable of finding multiple files under the same conditions. To start finding files, the file_find_first function is used. After that function, file_find_next functions could be used to find the next file under the same conditions as those outlined in the first command.

To close the thread of file-finding, a simple file_find_close function is used. After such functions, find next functions cannot be used anymore.

Order of File Finding
Obviously, if multiple file possibilities existed for a search conditions, multiple files need to be returned. Also a well known fact is that Game Maker doesn't return multiple values so only a single value will be returned for the first file finding function. Other files will be returned in the find next function.

The order of how the values are returned is ascending, so a file called armor.csv will be returned before bike.ogg.

Arguments
The file_find_first function requires two arguments: the mask and the attributions. While the find next function has no arguments, as it relies on the find first command.

The Mask
The mask for a file is a string that should match with both the name and location of the file to be found. The mask could include wildchars (*) which basically means any character or a group of characters.

So, using * as the mask would result in having all files being returned. Using a *.txt would return all text files in that given directory. Using hello_*.gmk would result in returning all folders that have the .gmk extension and begin with hello_.

The Attributes
The attributes argument is a (collection) of real-valued variables that could be added up together using regular addition (+) in Game Maker. For no attributes, the real value 0 is used. Here is a set of variables to be used with the attributes in the table below.

To return files that are read-only, hidden, and system files, (fa_readonly + fa_hidden + fa_systemfile) is used.

Returned Values
If such a file exists, only the name of the file will be returned. This means that the path (location) of the file will not be returned, however, the file extension will be part of the name returned.

If the file being searched for does not exist, an empty string (ââ) will be returned. This could be used to count the number of files satisfying a certain set of conditions by using a simple while loop that adds 1 to a counter each time  file_find_next != "" .

Copying All Folder Content
//Script: move_folder //move_folder(string folder1, string folder 2); //Folders must not include final backslash! //Courtesy of Eyas Sharaiha, //Featured on MarkUp var f1, f2, file; f1 = argument0; f2 = argument1; file = file_find_first(f1+"\*",0); while (file != "") {  file_copy(f1+"\"+file,f2+"\"+file); file_delete(f1+"\"+file); file = file_find_next; } file_find_close;

Counting files in a folder
//Script: count_folder //count_folder(string folder); //Folder must not include final backslash! var i, file; i = 0; file = file_find_first(argument0+"\*",0); while (file != "") {    i += 1; file = file_find_next; } file_find_close; return i;

Conclusion
While finding folders might not have that many different uses. These uses still find their ways to multiple games, both with Game Maker on the GMC and other commercial games as well.

Finding files could be useful in multiple ways. Either when searching for a particular file in multiple destinations, or even searching for a file when it's exact name is not known. File finding functions could be used to create folder operations, or just as a method of storing settings, counting files, etc.

One good example I can now think of is counting the number of .sav files in a directory so that a game could display the names of all saved games in a certain directory.

All in all, the possibilities are endless!