We will be covering the FileObject and the associated functions, to give a basic understanding of what file operations you can do with Torque. We will also cover some creative examples of how to use this object within your own projects.

When you create a FileObject you will be able to perform 3 possible functions: Write, Append or Read. You will note that there is no way from within TorqueScript to delete a file. This is a security measure designed to help prevent malicious use of this Object.

Creating the FileObject

To begin we will look at how we can create a new FileObject

	%file = new FileObject();

Seems simple enough doesn't it. But let's go over each part of the line to ensure we know what is there.

First we have a local variable named %file. This will hold the object reference to the FileObject we create. By using a local variable we limit the scope of our interaction with the FileObject to the current function we are in. The FileObject itself could be accessed globally, if you know the object reference.

Next we have the "new" statement. This tells the game engine to create a new instance of the object type that follows this command; in our case this is the FileObject. The FileObject has parenthesis following the name, this doesn't mean this is a function, instead it allows you to give you specific instance of a FileObject a name that could be used in place of the object reference.

For example, we could use a global variable, as well as give our FileObject a name for easy reference.

	$file = new FileObject("myFile");

Using the FileObject

Now that we have our FileObject created. Let's write some information to the file.

	%file = new FileObject();
	%file.OpenForWrite("starter.fps/test.txt");
	%file.writeline("This is the test file.");

OK we've just seen two new methods the OpenForWrite method and the writeline method. OpenForWrite will open a file if it exists or it will create a new file if it doesn't. If the file you name already has content, it will be erased. The writeline method does what it says. It writes a single line of text to a file. OpenForWrite returns true if successful and false otherwise.

If we wish to open an existing file and add to it we will use the OpenForAppend method. This works the same as the OpenForWrite, but doesn't erase the existing content of a file.

	%file = new FileObject();
	%file.OpenForAppend("starter.fps/test.txt");
	%file.writeline("This is the test file.");

Next, we may wish to read data from a file. To do so we will use the OpenForRead method. Paired with the OpenForRead method we use the readline method.

	%file = new FileObject();
	%file.OpenForRead("starter.fps/test.txt");
	%line = %file.readline();
 

You will see that we added a new variable named %line, we use this to store the return value from the FileObject method readline, which is the current line of the file.

Input Control

Now that we are reading in the file, we want to make sure we don't try to read past the end of the file. So we use another method named isEOF, which returns a True value if we are at the end of the file.

	%file = new FileObject();
	%file.OpenForRead("starter.fps/test.txt");
	while( !%file.isEOF() )
	{
		%line = %file.readline();
		echo(%line);
	}
 

Keeping things neat

Now that we have seen how to open, write, append and read a file… we need to learn what to do when we are done with a file. There are two things you can do. The first is to use the close method.

	%file = new FileObject();
	%file.OpenForWrite(“starter.fps/test.txt”);
	%file.writeline(“This is the test file.”);
	%file.close();

Once you have closed the file, you could reuse the FileObject to open a new file with a new method. The other option is to destroy the FileObject using the delete method.

	%file = new FileObject();
	%file.OpenForWrite(“starter.fps/test.txt”);
	%file.writeline(“This is the test file.”);
	%file.close();
	%file.delete();