325 lines
12 KiB
HTML
325 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
<html>
|
|
<head>
|
|
<title>Files</title>
|
|
<link href="style.css" rel="stylesheet" type="text/css">
|
|
</head>
|
|
<body background="images/back.gif">
|
|
<!--START-->
|
|
|
|
<h3>Files</h3>
|
|
|
|
It is useful to use external files in games.
|
|
For example, you could make a file that
|
|
describes at what moments certain things should happen. Also you probably
|
|
want to save information for the next time the game is run (for example,
|
|
the current room). The following functions exist to read and write data
|
|
in text files:
|
|
|
|
<p>
|
|
<blockquote>
|
|
<tt><b>file_text_open_read(fname)</b></tt>
|
|
Opens the file with the indicated name for reading. The function
|
|
returns the id of the file that must be used in the other functions.
|
|
You can open multiple files at the same time (32 max). Don't forget
|
|
to close them once you are finished with them.<br>
|
|
<tt><b>file_text_open_write(fname)</b></tt>
|
|
Opens the indicated file for writing, creating it if it does not
|
|
exist. The function returns the id of the file that must be
|
|
used in the other functions.<br>
|
|
<tt><b>file_text_open_append(fname)</b></tt>
|
|
Opens the indicated file for appending data at the end, creating
|
|
it if it does not exist. The function returns the id of the file
|
|
that must be used in the other functions.<br>
|
|
<tt><b>file_text_close(fileid)</b></tt>
|
|
Closes the file with the given file id.<br>
|
|
<tt><b>file_text_write_string(fileid,str)</b></tt>
|
|
Writes the string to the file with the given file id.<br>
|
|
<tt><b>file_text_write_real(fileid,x)</b></tt>
|
|
Write the real value to the file with the given file id. (As separator between the integer and decimal
|
|
part always a dot is used.<br>
|
|
<tt><b>file_text_writeln(fileid)</b></tt>
|
|
Write a newline character to the file.<br>
|
|
<tt><b>file_text_read_string(fileid)</b></tt>
|
|
Reads a string from the file with the given file id and returns this
|
|
string. A string ends at the end of line.<br>
|
|
<tt><b>file_text_read_real(fileid)</b></tt>
|
|
Reads a real value from the file and returns this value.<br>
|
|
<tt><b>file_text_readln(fileid)</b></tt>
|
|
Skips the rest of the line in the file and starts at the start of the next line.<br>
|
|
<tt><b>file_text_eof(fileid)</b></tt>
|
|
Returns whether we reached the end of the file.<br>
|
|
<tt><b>file_text_eoln(fileid)</b></tt>
|
|
Returns whether we reached the end of a line in the file.<br>
|
|
</blockquote>
|
|
|
|
<p>
|
|
To manipulate files in the file system you can use the following functions:
|
|
|
|
<p>
|
|
<blockquote>
|
|
<tt><b>file_exists(fname)</b></tt>
|
|
Returns whether the file with the given name exists (true) or not (false).<br>
|
|
<tt><b>file_delete(fname)</b></tt>
|
|
Deletes the file with the given name.<br>
|
|
<tt><b>file_rename(oldname,newname)</b></tt>
|
|
Renames the file with name oldname into newname.<br>
|
|
<tt><b>file_copy(fname,newname)</b></tt>
|
|
Copies the file fname to the newname.<br>
|
|
<tt><b>directory_exists(dname)</b></tt>
|
|
Returns whether the indicated directory does exist.
|
|
The name must include the full path, not a relative path.<br>
|
|
<tt><b>directory_create(dname)</b></tt>
|
|
Creates a directory with the given name (including the path towards it) if it does not exist.
|
|
The name must include the full path, not a relative path.<br>
|
|
<tt><b>file_find_first(mask,attr)</b></tt>
|
|
Returns the name of the first file that satisfies the mask and the
|
|
attributes. If no such file exists, the empty string is returned.
|
|
The mask can contain a path and can contain wildchars, for example
|
|
'C:\temp\*.doc'. The attributes give the additional files you want
|
|
to see. (So the normal files are always returned when they satisfy
|
|
the mask.) You can add up the following constants to see the
|
|
type of files you want:<br>
|
|
|
|
<blockquote>
|
|
<tt><b>fa_readonly</b> read-only files</tt><br>
|
|
<tt><b>fa_hidden</b> hidden files</tt><br>
|
|
<tt><b>fa_sysfile</b> system files</tt><br>
|
|
<tt><b>fa_volumeid</b> volume-id files</tt><br>
|
|
<tt><b>fa_directory</b> directories</tt><br>
|
|
<tt><b>fa_archive</b> archived files</tt><br>
|
|
</blockquote>
|
|
<tt><b>file_find_next()</b></tt>
|
|
Returns the name of the next file that satisfies the previously given mask
|
|
and the attributes. If no such file exists, the empty string is returned.<br>
|
|
<tt><b>file_find_close()</b></tt>
|
|
Must be called after handling all files to free memory.<br>
|
|
<tt><b>file_attributes(fname,attr)</b></tt>
|
|
Returns whether the file has all the attributes given in attr.
|
|
Use a combination of the constants indicated above.<br>
|
|
</blockquote>
|
|
|
|
<p>
|
|
The following functions can be used to change file names. Note that these
|
|
functions do not work on the actual files they only deal with the strings.
|
|
|
|
<p>
|
|
<blockquote>
|
|
<tt><b>filename_name(fname)</b></tt>
|
|
Returns the name part of the indicated file name, with the extension but without the path.<br>
|
|
<tt><b>filename_path(fname)</b></tt>
|
|
Returns the path part of the indicated file name, including the final backslash.<br>
|
|
<tt><b>filename_dir(fname)</b></tt>
|
|
Returns the directory part of the indicated file name, which normally
|
|
is the same as the path except for the final backslash.<br>
|
|
<tt><b>filename_drive(fname)</b></tt>
|
|
Returns the drive information of the filename.<br>
|
|
<tt><b>filename_ext(fname)</b></tt>
|
|
Returns the extension part of the indicated file name, including the leading dot.<br>
|
|
<tt><b>filename_change_ext(fname,newext)</b></tt>
|
|
Returns the indicated file name, with the extension (including the dot)
|
|
changed to the new extension. By using an empty string as the new
|
|
extension you can remove the extension.<br>
|
|
</blockquote>
|
|
|
|
<p>
|
|
In rare situations you might need to read data from binary files. The following
|
|
low-level routines exist for this:
|
|
|
|
<p>
|
|
<blockquote>
|
|
<tt><b>file_bin_open(fname,mod)</b></tt>
|
|
Opens the file with the indicated name. The mode indicates what
|
|
can be done with the file: 0 = reading, 1 = writing, 2 = both reading
|
|
and writing). When the file does not exist it is created.
|
|
The function returns the id of the file that must be
|
|
used in the other functions. You can open multiple files at the same
|
|
time (32 max). Don't forget to close them once you are finished with them.<br>
|
|
<tt><b>file_bin_rewrite(fileid)</b></tt>
|
|
Rewrites the file with the given file id, that is, clears it and
|
|
starts writing at the start.<br>
|
|
<tt><b>file_bin_close(fileid)</b></tt>
|
|
Closes the file with the given file id.<br>
|
|
<tt><b>file_bin_size(fileid)</b></tt>
|
|
Returns the size (in bytes) of the file with the given file id.<br>
|
|
<tt><b>file_bin_position(fileid)</b></tt>
|
|
Returns the current position (in bytes; 0 is the first position)
|
|
of the file with the given file id.<br>
|
|
<tt><b>file_bin_seek(fileid,pos)</b></tt>
|
|
Moves the current position of the file to the indicated position.
|
|
To append to a file move the position to the size of the file before writing.<br>
|
|
<tt><b>file_bin_write_byte(fileid,byte)</b></tt>
|
|
Writes a byte of data to the file with the given file id.<br>
|
|
<tt><b>file_bin_read_byte(fileid)</b></tt>
|
|
Reads a byte of data from the file and returns this.<br>
|
|
</blockquote>
|
|
|
|
<p>
|
|
If the player has checked secure mode in his preferences, for a number of
|
|
these routines, you are not allowed to specify a path, and only files in
|
|
the application folder can e.g. be written.
|
|
|
|
<p>
|
|
If you included files in the game executable and did not automatically export them at the
|
|
start of the game, you can use the following functions to do this.
|
|
|
|
<p>
|
|
<blockquote>
|
|
<tt><b>export_include_file(fname)</b></tt>
|
|
Exports the included file with the name fname. This must be a string variable,
|
|
so don't forget the quotes.<br>
|
|
<tt><b>export_include_file_location(fname,location)</b></tt>
|
|
Exports the included file with the name fname to the given location. Location must contain
|
|
the path and the filename.<br>
|
|
<tt><b>discard_include_file(fname)</b></tt>
|
|
Discard the included file with the name fname, freeing the memory used. This must be a string variable,
|
|
so don't forget the quotes.<br>
|
|
</blockquote>
|
|
|
|
<p>
|
|
The following four read-only variables can be useful:
|
|
|
|
<p>
|
|
<blockquote>
|
|
<tt><b>game_id*</b></tt>
|
|
Unique identifier for the game. You can use this if you need a unique file name.<br>
|
|
<tt><b>working_directory*</b></tt>
|
|
Working directory for the game. (Not including the final backslash.)<br>
|
|
<tt><b>program_directory*</b></tt>
|
|
Directory in which the game executable is stored. (Not including the final backslash.)
|
|
When you run a standalone game this is normally the same as the working directory unless
|
|
the game e.g. opens a file using the file selector. Note that when testing a
|
|
game you are creating the program and working directory will be different. In that
|
|
case the working directory is the place where the editable version is stored while
|
|
the program directory is a temporary directory for testing.<br>
|
|
<tt><b>temp_directory*</b></tt>
|
|
Temporary directory created for the game. (Not including the final backslash.)
|
|
You can store temporary files here. They will be removed at the end of the game.
|
|
</blockquote>
|
|
|
|
<p>
|
|
In certain situations you might want to give players the possibility of providing
|
|
command line arguments to the game they are running (for example to create
|
|
cheats or special modes). To get these arguments you can use the following
|
|
two routines.
|
|
|
|
<p>
|
|
<blockquote>
|
|
<tt><b>parameter_count()</b></tt>
|
|
Returns the number of command-line parameters. The actual parameters can be retrieved with
|
|
the following function.<br>
|
|
<tt><b>parameter_string(n)</b></tt>
|
|
Returns command-line parameters n. The first parameter has index 1. The last one has
|
|
index parameter_count(). Index 0 is a special one. It is the filename of the
|
|
game executable (including the path).<br>
|
|
</blockquote>
|
|
|
|
<p>
|
|
You can read the value of environment variables using the following function:
|
|
|
|
<p>
|
|
<blockquote>
|
|
<tt><b>environment_get_variable(name)</b></tt>
|
|
Returns the value (a string) of the environment variable with the given name.
|
|
</blockquote>
|
|
|
|
<p>
|
|
Finally, if you are interested in the size of the disk and the free space, you
|
|
can use the following functions:
|
|
</p>
|
|
|
|
<p>
|
|
<blockquote>
|
|
<tt><b>disk_size(drive)</b></tt>
|
|
Returns the size of the indicated drive in bytes. <tt>drive</tt> must be a
|
|
capital letter, e.g. 'C'. If you do not provide the drive, the
|
|
drive of the current working directory is used.<br>
|
|
<tt><b>disk_free(drive)</b></tt>
|
|
Returns the amount of free space on the indicated drive in bytes. <tt>drive</tt> must be a
|
|
capital letter, e.g. 'C'. If you do not provide the drive, the
|
|
drive of the current working directory is used.<br>
|
|
</blockquote>
|
|
|
|
|
|
<!--END-->
|
|
</body>
|
|
</html>
|
|
|
|
<!-- KEYWORDS
|
|
files
|
|
folders
|
|
directories
|
|
game id
|
|
working directory
|
|
temporary directory
|
|
program directory
|
|
file I/O
|
|
handling files
|
|
saving information
|
|
reading from file
|
|
writing to file
|
|
text files
|
|
binary files
|
|
file attributes
|
|
file names
|
|
parameters
|
|
command line parameters
|
|
environment variables
|
|
exporting files
|
|
|
|
file_text_open_read()
|
|
file_text_open_write()
|
|
file_text_open_append()
|
|
file_text_close()
|
|
file_text_write_string()
|
|
file_text_write_real()
|
|
file_text_writeln()
|
|
file_text_read_string()
|
|
file_text_read_real()
|
|
file_text_readln()
|
|
file_text_eof()
|
|
file_text_eoln()
|
|
file_exists()
|
|
file_delete()
|
|
file_rename()
|
|
file_copy()
|
|
directory_exists()
|
|
directory_create()
|
|
file_find_first()
|
|
file_find_next()
|
|
file_find_close()
|
|
file_attributes()
|
|
filename_name()
|
|
filename_path()
|
|
filename_dir()
|
|
filename_drive()
|
|
filename_ext()
|
|
filename_change_ext()
|
|
file_bin_open()
|
|
file_bin_rewrite()
|
|
file_bin_close()
|
|
file_bin_position()
|
|
file_bin_size()
|
|
file_bin_seek()
|
|
file_bin_write_byte()
|
|
file_bin_read_byte()
|
|
export_include_file()
|
|
export_include_file_location()
|
|
discard_include_file()
|
|
parameter_count()
|
|
parameter_string()
|
|
environment_get_variable()
|
|
disk_size()
|
|
disk_free()
|
|
fa_readonly
|
|
fa_hidden
|
|
fa_sysfile
|
|
fa_volumeid
|
|
fa_directory
|
|
fa_archive
|
|
game_id
|
|
working_directory
|
|
temp_directory
|
|
program_directory
|
|
--> |