Section Index


1. OpenAL || 2. Debugging || 3. String Manipulation || 4. Networking || 5. Console || 6. Device I/O || 7. File I/O
8. Packages || 9. Objects || 10. Event Scheduling || 11. Datablocks || 12. Video / Texturing || 13. Special || 14. Resource Management
15. Scene || 16. Containers and Raycasts || 17. Editors || 18. Build || 19. Time || 20. GUIs || 21. Math


This quick reference guide was taken directly out of The Game Programmer's Guide to Torque by Edward Maurina. It's an outstanding resource - a must for anyone wanting to get serious about programming in Torque.

Contents

File I/O

TGE provides a file manager maintains a list of all files in the game directory and all sub-directories. The followings functions are used to access this list. In order manipulate (read/write) the contents of a file, see the console object 'fileObject', listed in the 'ConObjects Quick Reference' or refer to the 'TGE I/O' chapter of EGTGE.


When a Torque game starts up a call, or calls are made to setModPaths(). This function is passed a game directories, separated by semi-colons (;). The file manager will examine each of these game paths and their sub-directories, building up a list of known files. This information is used later for relative pathing and file searching.


Torque supports both direct pathing and relative pathing.
Direct paths start with a slash (/). For example, "/starter.fps/main.cs" points to the file "main.cs" under the game directory "starter.fps", where "starter.fps" is in the root directory (the directory where the executable is started from.
Relative pathing can be accomplished in three basic ways.
In the first method, if an unadorned name is used as the first part of a directory ("starter.fps/test.cs"), the engine will assume that this first name is the name game directory, but then if the unadorned name does not match the game directory, the file match/search will fail. In general, you should not use unadorned names.
In the second method, if a tilde (~) is used as the first part of a directory ("~/test.cs"), the engine will assume that the tilde should be replaced by the root-child this file lives in. For example, the root child of "starter.fps/client/doit.cs" is "starter.fps". Therefore, if we use this path "~/somefile.cs" in a command within the file "doit.cs", the path will be expanded to be "starter.fps/somefile.cs".
In the third and final relative pathing method, if a dot (.) is used as the first part of a directory ("./test.cs"), then the dot is expanded to be the root- path that the current file resides in. For example, the root-path of "starter.fps/client/doit.cs" is "starter.fps/client". Therefore, if we use this path "./somefile.cs" in a command within the file "doit.cs", the path will be expanded to be "starter.fps/client/somefile.cs".


Torque supports a single wildcard, the asterisk (*). This wild card can be interpreted to mean "zero or more instances of any chracter(s)".


expandFilename( filename )

Purpose
Use the expandFilename function to convert a relative path name to a full path name.

Syntax
filename
– A string containing the relative or full path and file name of an existing or new file.

Returns
Returns a string containing the expanded path to the specified file.

expandFilename("~/data/sound/testing.wav");



fileBase( filename )

Purpose
Use the fileBase function to get the name of a file from a relative or full path, not including the file extension.

Syntax
filename
– A string containing the relative or full path and file name of an existing or new file.

Returns
Returns an unadorned file name without a path or file extension.

See Also
fileExt, fileName, filePath

fileBase(“egt/main.cs”); // will return “main”



fileExt( filename )

Purpose
Use the fileExt function to get the extension of a file from a relative or full path, not including the file extension.

Syntax
filename
– A string containing the relative or full path and file name of an existing or new file.

Returns
Returns a file extension, including the dot (.).

Notes
If asterisks are present in an extension, as passed in filename, they will not be expanded in the return value.

See Also
fileBase, fileName, filePath
Returns the file extension (suffix) for the file specified by filename.

fileExt(“script.cs”); // will return “.cs” 



fileName( filename )

Purpose
Use the fileName function to get the filename and extension of a file from a relative or full path, not including the file extension.

Syntax
filename
– A string containing the relative or full path and file name of an existing or new file.

Returns
Returns a string containing the full name of a file less any path before the name.

Notes
If asterisks are present in an file name, as passed in filename, they will not be expanded in the return value.

See Also
fileBase, fileExt, filePath

fileName(“egt/main.cs”); // will return “main.cs”



filePath( filename )

Purpose
Use the fileBase function to get all parts of a path up to, but not including the last slash (/).

Syntax
filename
– A string containing the relative or full path and file name of an existing or new file.

Returns
Returns a string containing the relative or full path portion of filename.

Notes
If asterisks are present in any part of the path, as passed in filename, they will not be expanded in the return value.

See Also
fileBase, fileExt, fileName

filePath(“common/ui/defaultProfiles.cs”); // Will return “common/ui” 



findFirstFile ( pattern )

Purpose
Use the findFirstFile function to find the first file matching pattern.

Syntax
pattern
– A full or partial path, followed by a full or partial filename, or any combination of these two elements.

Returns
Returns a full path to the first file name matching pattern. Returns a NULL string, when no matches are found.

Notes
This function will search all directories in the modpath, as created by setModPaths. Each time this function is called it will reset an internal variable tracking the current position in the file list. So, multiple routines calling this in an overlapping fashion will clobber each other.

See Also
findNextFile, getFileCount, getModPaths, setModPaths

findFirstFile(“*.cs”);



findNextFile ( pattern )

Purpose
Use the findNextFile function to find the next file matching pattern.

Syntax
pattern
– A full or partial path, followed by a full or partial filename, or any combination of these two elements.

Returns
Returns a full path to the next file name matching pattern. Returns a NULL string, when no matches are found.

Notes
This function will search all directories in the modpath, as created by a call to setModPaths. Also, this function requires that findNextFile be called at least with the same pattern, some time prior to calling this function.

See Also
findFirstFile, getFileCount, getModPaths, setModPaths

findNextFile( “*.cs” );



getFileCount ( pattern )

Purpose
Use the getFileCount function to determine how many files exist in modpaths that match the specified pattern.

Syntax
pattern
– A full or partial path, followed by a full or partial filename, or any combination of these two elements.

Returns
Returns a zero if no matches are found, or a positive integer value specifying how many matches there were.

See Also
findFirstFile, findNextFile

getFileCount(“*.cs”);



getFileCRC( filename )

Purpose
Use the getFileCRC function to calculate the Cyclic-Redundancy-Check (CRC) value for a file as specified by the partial or full path in filename.

Syntax
filename
– A string containing the relative or full path and file name of an existing or new file.

Returns
Returns a non-zero positive integer value corresponding to this file's CRC.

Notes
CRC values are useful for checking to see if two same named files are actually the same. If a client file of the same path and name as a file on the server has a differnt CRC from the server version, then the files are NOT the same, otherwise they highly likely to be the same. Although it is theoretically possible for two non-matching files to have matching CRCs, the odds are very much against it.

getFileCRC(“/fps/client/scripts/script/cs”);



isFile( filename )

Purpose
Use the isFile function to determine whether the value in filename is in fact an existing file.

Syntax
filename
– A string containing the relative or full path and file name of an existing file.

Returns
Returns true if the file exists, false otherwise.

See Also
isWriteableFileName

isFile(“/fps/client/scripts/script.cs”);



isWriteableFileName( filename )

Purpose
Use the isWriteableFileName function to determine whether the value in filename is in fact an existing file and it can be written to.

Syntax
filename
– A string containing the relative or full path and file name of an existing file.

Returns
Returns true if the file exists and can be written to, false otherwise.

See Also
isFile

isWriteableFileName(“/fps/client/scripts/script.cs”);


Section Index


1. OpenAL || 2. Debugging || 3. String Manipulation || 4. Networking || 5. Console || 6. Device I/O || 7. File I/O
8. Packages || 9. Objects || 10. Event Scheduling || 11. Datablocks || 12. Video / Texturing || 13. Special || 14. Resource Management
15. Scene || 16. Containers and Raycasts || 17. Editors || 18. Build || 19. Time || 20. GUIs || 21. Math