File I/O

Functions allowing you to search for files, read them, write them, and access their properties.

Classes

• FileDialog
• FileObject
• FileStreamObject
• OpenFileDialog
• OpenFolderDialog
• SaveFileDialog
• SimXMLDocument
• StreamObject
• ZipObject

Functions

bool createPath(string path)

Create the given directory or the path leading to the given filename. If path ends in a trailing slash, then all components in the given path will be created as directories (if not already in place). If path , does not end in a trailing slash, then the last component of the path is taken to be a file name and only the directory components of the path will be created.

Parameters:path – The path to create.

string expandFilename(string filename)

Grabs the full path of a specified file.

Parameters:filename – Name of the local file to locate Returns:String containing the full filepath on disk

string expandOldFilename(string filename)

Retrofits a filepath that uses old Torque style.

Returns:String containing filepath with new formatting

String fileBase(string fileName)

Get the base of a file name (removes extension).

Parameters:fileName – Name and path of file to check Returns:String containing the file name, minus extension

String fileCreatedTime(string fileName)

Returns a platform specific formatted string with the creation time for the file.

Parameters:fileName – Name and path of file to check Returns:Formatted string (OS specific) containing created time, “9/3/2010 12:33:47 PM” for example

bool fileDelete(string path)

Delete a file from the hard drive.

Parameters:path – Name and path of the file to delete Returns:True if file was successfully deleted

String fileExt(string fileName)

Get the extension of a file.

Parameters:fileName – Name and path of file Returns:String containing the extension, such as “.exe” or “.cs”

String fileModifiedTime(string fileName)

Returns a platform specific formatted string with the last modified time for the file.

Parameters:fileName – Name and path of file to check Returns:Formatted string (OS specific) containing modified time, “9/3/2010 12:33:47 PM” for example

String fileName(string fileName)

Get the file name of a file (removes extension and path).

Parameters:fileName – Name and path of file to check Returns:String containing the file name, minus extension and path

String filePath(string fileName)

Get the path of a file (removes name and extension).

Parameters:fileName – Name and path of file to check Returns:String containing the path, minus name and extension

int fileSize(string fileName)

Determines the size of a file on disk.

Parameters:fileName – Name and path of the file to check Returns:Returns filesize in KB, or -1 if no file

String getCurrentDirectory()

Return the current working directory.

Returns:The absolute path of the current working directory.

String getDirectoryList(string path, int depth)

Gathers a list of directories starting at the given path.

Parameters:

• path – String containing the path of the directory
• depth – Depth of search, as in how many subdirectories to parse through

Returns:

Tab delimited string containing list of directories found during search, “” if no files were found

String getExecutableName()

Gets the name of the game’s executable.

Returns:String containing this game’s executable name

int getFileCRC(string fileName)

Provides the CRC checksum of the given file.

Parameters:fileName – The path to the file. Returns:The calculated CRC checksum of the file, or -1 if the file could not be found.

String getMainDotCsDir()

Get the absolute path to the directory that contains the main.cs script from which the engine was started. This directory will usually contain all the game assets and, in a user-side game installation, will usually be read-only.

Returns:The path to the main game assets.

String getWorkingDirectory()

Reports the current directory.

Returns:String containing full file path of working directory

bool IsDirectory(string directory)

Determines if a specified directory exists or not.

Parameters:directory – String containing path in the form of “foo/bar” Returns:Returns true if the directory was found.

bool isFile(string fileName)

Determines if the specified file exists or not.

Parameters:fileName – The path to the file. Returns:Returns true if the file was found.

bool isWriteableFileName(string fileName)

Determines if a file name can be written to using File I/O.

Parameters:fileName – Name and path of file to check Returns:Returns true if the file can be written to.

String makeFullPath(string path, string cwd)

Converts a relative file path to a full path. For example, “./console.log” becomes “C:/Torque/t3d/examples/FPS Example/game/console.log”

Parameters:

• path – Name of file or path to check
• cwd – Optional current working directory from which to build the full path.

Returns:

String containing non-relative directory of path

String makeRelativePath(string path, string to)

Turns a full or local path to a relative one. For example, “./game/art” becomes “game/art”

Parameters:

• path – Full path (may include a file) to convert
• to – Optional base path used for the conversion. If not supplied the current working directory is used.

Returns:

String containing relative path

void openFile(string file)

Open the given file through the system. This will usually open the file in its associated application.

Parameters:file – Path of the file to open.

void openFolder(string path)

Open the given folder in the system’s file manager.

Parameters:path – full path to a directory.

String pathConcat(string path, string file)

Combines two separate strings containing a file path and file name together into a single string.

Parameters:

• path – String containing file path
• file – String containing file name

Returns:

String containing concatenated file name and path

bool pathCopy(string fromFile, string toFile, bool noOverwrite)

Copy a file to a new location.

Parameters:

• fromFile – Path of the file to copy.
• toFile – Path where to copy fromFile to.
• noOverwrite – If true, then fromFile will not overwrite a file that may already exist at toFile.

Returns:

True if the file was successfully copied, false otherwise.

bool setCurrentDirectory(string path)

Set the current working directory.

Parameters:path – The absolute or relative (to the current working directory) path of the directory which should be made the new working directory. Returns:, false otherwise.

void startFileChangeNotifications()

Start watching resources for file changes. Typically this is called during initializeCore().

void stopFileChangeNotifications()

Stop watching resources for file changes. Typically this is called during shutdownCore().

Variables

string $Con::File

The currently executing script file.

string $Con::Root

The mod folder for the currently executing script file.

File Searching

Functions for searching files by name patterns.

Functions

String findFirstFile(string pattern, bool recurse)

Returns the first file in the directory system matching the given pattern. Use the corresponding findNextFile() to step through the results. If you’re only interested in the number of files returned by the pattern match, use getFileCount() . This function differs from findFirstFileMultiExpr() in that it supports a single search pattern being passed in.

Parameters:

• pattern – The path and file name pattern to match against.
• recurse – If true, the search will exhaustively recurse into subdirectories of the given path and match the given filename pattern.

Returns:

The path of the first file matched by the search or an empty string if no matching file could be found.

Example:

// Execute all .cs files in a subdirectory and its subdirectories.
for( %file = findFirstFile( "subdirectory/*.cs" ); %file !$= ""; %file = findNextFile() )
   exec( %file );

String findFirstFileMultiExpr(string pattern, bool recurse)

Returns the first file in the directory system matching the given patterns. Use the corresponding findNextFileMultiExpr() to step through the results. If you’re only interested in the number of files returned by the pattern match, use getFileCountMultiExpr() . This function differs from findFirstFile() in that it supports multiple search patterns to be passed in.

Parameters:

• pattern – The path and file name pattern to match against, such as .cs. Separate multiple patterns with TABs. For example: “.cs” TAB “.dso”
• recurse – If true, the search will exhaustively recurse into subdirectories of the given path and match the given filename patterns.

Returns:

String of the first matching file path, or an empty string if no matching files were found.

Example:

// Find all DTS or Collada models
%filePatterns = "*.dts" TAB "*.dae";
%fullPath = findFirstFileMultiExpr( %filePatterns );
while ( %fullPath !$= "" )
{
   echo( %fullPath );
   %fullPath = findNextFileMultiExpr( %filePatterns );
}

String findNextFile(string pattern)

Returns the next file matching a search begun in findFirstFile() .

Parameters:pattern – The path and file name pattern to match against. This is optional and may be left out as it is not used by the code. It is here for legacy reasons. Returns:The path of the next filename matched by the search or an empty string if no more files match.

Example:

// Execute all .cs files in a subdirectory and its subdirectories.
for( %file = findFirstFile( "subdirectory/*.cs" ); %file !$= ""; %file = findNextFile() )
   exec( %file );

String findNextFileMultiExpr(string pattern)

Returns the next file matching a search begun in findFirstFileMultiExpr() .

Parameters:pattern – The path and file name pattern to match against. This is optional and may be left out as it is not used by the code. It is here for legacy reasons. Returns:String of the next matching file path, or an empty string if no matching files were found.

Example:

// Find all DTS or Collada models
%filePatterns = "*.dts" TAB "*.dae";
%fullPath = findFirstFileMultiExpr( %filePatterns );
while ( %fullPath !$= "" )
{
   echo( %fullPath );
   %fullPath = findNextFileMultiExpr( %filePatterns );
}

int getFileCount(string pattern, bool recurse)

Returns the number of files in the directory tree that match the given patterns. This function differs from getFileCountMultiExpr() in that it supports a single search pattern being passed in. If you’re interested in a list of files that match the given pattern and not just the number of files, use findFirstFile() and findNextFile() .

Parameters:

• pattern – The path and file name pattern to match against.
• recurse – If true, the search will exhaustively recurse into subdirectories of the given path and match the given filename pattern counting files in subdirectories.

Returns:

Number of files located using the pattern

Example:

// Count the number of .cs files in a subdirectory and its subdirectories.
getFileCount( "subdirectory/*.cs" );

int getFileCountMultiExpr(string pattern, bool recurse)

Returns the number of files in the directory tree that match the given patterns. If you’re interested in a list of files that match the given patterns and not just the number of files, use findFirstFileMultiExpr() and findNextFileMultiExpr() .

Parameters:

• pattern – The path and file name pattern to match against, such as .cs. Separate multiple patterns with TABs. For example: “.cs” TAB “.dso”
• recurse – If true, the search will exhaustively recurse into subdirectories of the given path and match the given filename pattern.

Returns:

Number of files located using the patterns

Example:

// Count all DTS or Collada models
%filePatterns = "*.dts" TAB "*.dae";
echo( "Nunmer of shape files:" SPC getFileCountMultiExpr( %filePatterns ) );