File Functions

A quick overview of verge file i/o functions. The standard procedure is to pass a filename to FileOpen() and get a file handle to use with the data read/write functions, and the close the file with FileClose() at the end. A few important points first. Opening a file in write mode will create a new file if one doesn't exist, but will overwrite if one does exist - just opening the file wipes all the data. Also, all read and write operations go from the current position in the file, which starts at the beginning, and move the position onwards in the process. Finally, the base unit of all everything here is the byte, 8 binary 1/0 switches, which equates to a number from 0 to 255 or one character of ascii text. There are two main uses for file i/o in verge, there's a brief summary of both below.

Reading from plain text data files

Useful for: Managing in-game data in an easy to access and alter form. Load-once purposes.

FileReadLn() to get a sting of data from the file

GetToken() to extract the information from the string

val() to turn string data into numbers where needed.

As it's easy to make the odd mistake when creating or editing datafiles by hand, be sure to add some error checking in case of mistakes, and preferably allow for extra non-data lines, so the file can be commented/explained where needed.

Writing and reading binary data files

Useful for: Recording and recalling data mid game. Fast read and write times.

FileWriteQuad() for writing any integer variables to file.

FileWriteString() for writing any string variables to file.

FileReadQuad() for reading integer variables from file.

FileReadString() for reading string variables from file.

There are several functions that do similar things, but these are relatively safe and simple, just remember to match the read and write formats exactly, and be aware changing either will cause big problems. For this reason, writing a 'version number' at the top of the file, and checking it is up to date on read might be useful.

  • FileClose() Releases a file handle when it is no longer needed
  • FileCurrentPos() Returns the current byte position in an open file
  • FileEOF() Determines whether or not the current file has reached its end.
  • FileOpen() Opens a file in the directory system for reading or writing
  • FileReadByte() Reads a byte from file into an integer
  • FileReadLn() Returns data from a file as an ascii string, ending at a new line
  • FileReadQuad() Reads four bytes from file into an integer
  • FileReadString() Reads a string from file as ascii with a two byte length header
  • FileReadToken() Reads a string from file as ascii stopping at whitespace
  • FileReadWord() Reads two bytes from file into an integer
  • FileSeekLine() Sets the current position in the file based on newline markers
  • FileSeekPos() Sets the current position in the file based byte ofsets
  • FileWrite() Writes a string to file as ascii with no padding
  • FileWriteByte() Writes an integer to file as one byte
  • FileWriteCHR() Saves an entity's CHR to the specified filehandle
  • FileWriteLn() Writes a string to file as ascii with a newline at the end
  • FileWriteMap() Writes the current map into a file.
  • FileWriteQuad() Writes an integer to file as four bytes
  • FileWriteString() Writes a string to file as ascii with the length stored in a header
  • FileWriteVSP() Saves the current VSP to the specified filehandle
  • FileWriteWord() Writes an integer to file as two bytes
  • ListFilePattern() Searches for a specified file pattern and returns a list.
  • Talkback

    There are no talkbacks on this documentation page yet. Post the first?

    Post a new comment?

    Ben McGraw's lovingly crafted this website from scratch for years.
    It's a lot prettier this go around because of Jon Wofford. is a member of the lunarnet irc network, and would like to take this opportunity to remind you that regardless how babies taste, it is wrong to eat them.