Scripts can access files. File access works almost identical between PCC 1.x and PCC2, but many limits have been raised in PCC2.

Files must be opened using the Open command before you can work with them. When opening, you associate a file number with the file. The file number is an integer between 1 and 100 (1 and 20 in PCC 1.x). You can assign your own file number, or use the FreeFile() function to get an unused one (recommended!). When you're done with the file, you close it using the Close command. This makes the file number available for future re-use.

In all commands, the file number is, by convention, written with a leading #. This is optional for all file-related commands except for Print (which needs the # sign to know that this is a file number, not a value to print).

Text files can be accessed using the Input and Print commands. PCC2 will automatically convert them from the game character set. As an exception, if they start with a UTF-8 byte order mark, they will be read as UTF-8. PCC 1.x will access all files with the game character set.

Binary files can be accessed using the Get and Put commands. Those transfer data to and from a special data block object stored in a variable. You can dissect this data block using the GetWord() function and its relatives, and modify it using SetWord and relatives.

For example, a xyplan.dat file consists of records of 6 byte each. You could read those using a script like this:

 % Open the file
 Dim fd = FreeFile()
 Open "xyplan.dat" For Input As #fd

 % Read coordinates
 Dim i, block, x, y
 For i:=1 To 500 Do
   Get #fd, block, 6
   x := GetWord(block, 0)
   y := GetWord(block, 2)
   Print "Planet ", i, " is at ", x, ",", y
 Next

See Data Type Blob for details.

On File Names

PCC2 runs on operating systems that have different conventions how a file name looks like. If you wish to build a file name, you should therefore use the MakeFileName function; to split a file name into components, use GetFileName and GetDirectoryName.

In PCC 1.x, you could just concatenate a directory name such as System.GameDirectory and a file name. This does no longer work in PCC2!

Pitfalls

In PCC 1.x, a data block was just a string. In PCC2, it is a whole new data type which cannot be used with string manipulation functions (which was possible but deprecated in PCC 1.x).

File I/O is buffered. When you write something to a file, the change may not immediately show up on the disk. If you open the same file on another file number, that other file number will also not immediately see the changes. Changes will be written out when you call Close.