File search

From YoYoGames Wiki

File Search functions in Game Maker have a multitude of uses, and are crucial to several types of games. Compared to other functions, it is hard to make up creative uses for file search functions, since what they do is pretty straight forward – find files.

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()!="".

Applications

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
f1=string(argument0);
f2=string(argument1);
file=file_find_first(f1+"\*",0);
while(file!="")
{
  file_copy(f1+"\"+string(file),
f2+"\"+string(filename_name(file)));
  file_delete(f1+"\"+string(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
F0=string(argument0);
 i=0;
file=file_find_first(F0+"\*",0);
while(file!="")
{
    i+=1;
    file=file_find_next();
}
file_find_close();

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 which’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!

See Also

• file_find_first