Headcannon Game Engine Script Commands - File IO
Index:
HCGE Standard Files:
| (D) (E) | _LoadLevel |
| (D) (E) | _LoadTiles |
| (D) (E) | _LoadObjects |
| (D) (E) | _SaveLevel |
| (D) (E) | _SaveTiles |
| (D) (E) | _SaveObjects |
User-Managed Files:
| (D) (E) | _File_Open |
| (D) (E) | _File_Close |
| (D) (E) | _File_GetPos |
| (D) (E) | _File_Seek |
| (D) (E) | _File_ReadBYTEs_Reg |
| (D) (E) | _File_ReadWORDs_Reg |
| (D) (E) | _File_ReadDWORDs_Reg |
| (D) (E) | _File_ReadBYTEs_Chr |
| (D) (E) | _File_ReadWORDs_Chr |
| (D) (E) | _File_ReadDWORDs_Chr |
| (D) (E) | _File_ReadBYTEs_Obj |
| (D) (E) | _File_ReadWORDs_Obj |
| (D) (E) | _File_ReadDWORDs_Obj |
| (D) (E) | _File_WriteBYTEs_Reg |
| (D) (E) | _File_WriteWORDs_Reg |
| (D) (E) | _File_WriteDWORDs_Reg |
| (D) (E) | _File_WriteBYTEs_Chr |
| (D) (E) | _File_WriteWORDs_Chr |
| (D) (E) | _File_WriteDWORDs_Chr |
| (D) (E) | _File_WriteBYTEs_Obj |
| (D) (E) | _File_WriteWORDs_Obj |
| (D) (E) | _File_WriteDWORDs_Obj |
| (D) (E) | _File_ReadString |
| (D) (E) | _File_WriteString |
Descriptions:
HCGE Standard Files:
_LoadLevel
_LoadTiles
_LoadObjects
(ALL) (Example)
These commands load the specified data from a file whose name is specified by the given "Text", also setting that file as the "Current" file for the given type in preparation for saving
If the file does not exist, the current data for the given type will be cleared, and the file will be created if/when the corresponding _Save??? Command is used, or if/when data of this type is saved from within the corresponding editor
Parameters:
- Text ID
ID number of the Text string that contains the filename of the
data to load
When this Command is used by a Status Script Function,
this ID references a Status Script Text
When this Command is used by any other Function, it references Text from a Game Def
or a Zone Def. In this case, the "G" and "Z" tags may be used to reference "Game" and "Zone" Texts, respectively
The "R" or "r" tags may be used to obtain the ID value from a Register
The filename in the Text string must be relative to the "Program Folder", not to the folder that contains
the file in which it appears.
_SaveLevel
_SaveTiles
_SaveObjects
(ALL) (REG) (Example)
Saves the current state of the currently-loaded data of the specified type to the file whose name is specified by the given "Text"
In the case of Object Layout, any Objects that are flagged for "Resetting" will do so before the save occurs, and only Objects that are flagged as saveable will be written to the file
Parameters:
- Text ID
ID of the "Text" that contains the desired filename. The "G", and "Z" tags may be used to reference
Text from the "Game Def", or the current Zone's "Zone Def", respectively
Entering "_Current" in place of this value will save the data to the "Current" File,
the data file of the specified type that was last loaded by Script
The "R" or "r" tags may be used to obtain the ID value from a Register
The filename in the Text string must be relative to the "Program Folder", not to the folder that contains
the file in which it appears.
User-Managed Files:
_File_Open
(ALL) (REG) (Example)
Opens the file whose name is given by the specified "Game/Zone" Text as the current Read or Write file. Only one file of each type can be open at once
If the file cannot be opened, an error will not be displayed automatically, so that this Command can be invisibly used for testing the existence of a file. To ensure that the file was opened successfully, the _If(FileOpen) conditional Command should be used
Parameters:
- Text ID
ID of the "Text" that contains the desired filename. The "G", and "Z" tags may be used to reference
Text from the "Game Def", or the current Zone's "Zone Def", respectively.
The "R" or "r" tags may be used to obtain the ID value from a Register
The filename in the Text string must be relative to the "Program Folder", not to the folder that contains
the file in which it appears.
- Access
Specifies the type of access to open the file for:
| 0 | - | _FileType_Read | - | Open the specified file as the current Read File, if it exists |
| 1 | - | _FileType_Write | - | Open the specified file as the current Write file. If it does not exist, it will be created, and if it does exist, it will be overwritten |
| 2 | - | _FileType_ReWrite | - | Open the specified file as the current Write file. If it does not exist, it will be created, and if it does exist, any contents that are not explicitly destroyed by Write operations will be preserved |
_File_Close
(ALL) (Example)
Closes the currently-open file of the specified access type
Parameters:
- Access
Specifies the access type of the file that should be closed:
| 0 | - | _FileType_Read | - | Close the file that is currently open for Read access |
| 1 | - | _FileType_Write | - | Close the file that is currently open for Write access |
_File_GetPos
(ALL) (Example)
Retrieve the current file position of the the currently-open file of the specified access type and store it in the given Register
Parameters:
- Access
Specifies the access type of the file whose current position should be obtained:
| 0 | - | _FileType_Read | - | Obtain the current position of the file that is currently open for Read access |
| 1 | - | _FileType_Write | - | Obtain the current position of the file that is currently open for Write access |
- Dest Reg
ID of the Register into which to store the retrieved file position.
The "U" tag may be used to specify a user-defined Register. Otherwise, the ID will refer to a Game Register
_File_Seek
(ALL) (Example)
Manually adjusts the current file position of the currently-open file of the specified access type to the specified location, relative to the specified reference point
This Command is for "Random Access" reads/writes; it is not necessary to "seek" between sequential data reads/writes, as those operations automatically update the file position
Parameters:
- Access
Specifies the access type of the file whose current position should be adjusted:
| 0 | - | _FileType_Read | - | "Seek" the current read position of the file that is currently open for Read access |
| 1 | - | _FileType_Write | - | "Seek" the current write position of the file that is currently open for Write access |
- Offset
The number of bytes to "seek" from the given "Start Position"
- Start Position
Specifies the file location to which the given offset should be added to calculate the adjustment:
| 0 | - | _FileSeek_Set | - | Seek to the exact location specified |
| 1 | - | _FileSeek_Cur | - | Add the given relative location to the current file read/write location |
| 1 | - | _FileSeek_End | - | Add the given relative location to the file's end location |
_File_ReadBYTEs_Reg
_File_ReadWORDs_Reg
_File_ReadDWORDs_Reg
_File_ReadBYTEs_Chr
_File_ReadWORDs_Chr
_File_ReadDWORDs_Chr
_File_ReadBYTEs_Obj
_File_ReadWORDs_Obj
_File_ReadDWORDs_Obj
(ALL) (REG) (Example)
Reads the given number of values of the specified size from the currently-open Read-access file and store them sequentially into variables of the specified type, starting at the given variable ID
These Commands automatically adjust the current position of the file as the data is being read; the file will then be positioned on the byte immediately following the last value that was read
Parameters:
- Var ID
In the case of "Registers", "Var ID" is the ID of the first "Register" into which the data being read should be stored. The "U" tag may be used
to specify a user-defined Register. Otherwise, the ID will refer to a Game Register
In the case of Player Variables, "Var ID" is the ID of the first Player Variable into which the data being read should be stored. The capital "A"
tag may be used to specify an "Active" variable, the lower-case "a" to specify a user-
defined "Active" variable, and the lower-case "c" to specify a user-defined Constant.
Otherwise, the ID will refer to one of the Player's required Constants
In the case of Object Variables, "Var ID" is the ID of the Object Variable into which the data being read should be stored. The "E" tag may
be used to specify an "Extra" variable. Otherwise, the ID will refer to one of the
Object's standard variables
- Length
Specifies the number of values to load from the file and into the given variables
The "R" or "r" tags may be used to obtain the length value from a Register
_File_WriteBYTEs_Reg
_File_WriteWORDs_Reg
_File_WriteDWORDs_Reg
_File_WriteBYTEs_Chr
_File_WriteWORDs_Chr
_File_WriteDWORDs_Chr
_File_WriteBYTEs_Obj
_File_WriteWORDs_Obj
_File_WriteDWORDs_Obj
(ALL) (REG) (Example)
Sequentially writes the given number of values of the specified size from the variables of the specified type into the currently-open Write-access file, starting at the given variable ID
These Commands automatically adjust the current position of the file as the data is being written; the file will then be positioned at the byte immediately following the last value that was written
Parameters:
- Var ID
In the case of "Registers", "Var ID" is the ID of the first "Register" from which the data should be read. The "U" tag may be used
to specify a user-defined Register. Otherwise, the ID will refer to a Game Register
In the case of Player Variables, "Var ID" is the ID of the first Player Variable from which the data should be read. The capital "A"
tag may be used to specify an "Active" variable, the lower-case "a" to specify a user-
defined "Active" variable, and the lower-case "c" to specify a user-defined Constant.
Otherwise, the ID will refer to one of the Player's required Constants
In the case of Object Variables, "Var ID" is the ID of the Object Variable from which the data should be read. The "E" tag may
be used to specify an "Extra" variable. Otherwise, the ID will refer to one of the
Object's standard variables
- Length
Specifies the number of values to write to the file from the given variables
The "R" or "r" tags may be used to obtain the length value from a Register
_File_ReadString
(ALL) (REG) (Example)
Read a string of characters from the currently-open Read-access file into the given "Game/Zone" Text. Characters will be read from the file until the given terminator character is found. A 0 will automatically be placed at the end of the incoming Text string for termination as required by HCGE; the terminator character read from the file will not be stored into the "Game/Zone" Text
This Command automatically adjusts the current position of the file as the data is being read; the file will then be positioned at the byte immediately following the terminator character
Parameters:
- Text ID
ID of the "Text" into which the string should be read. The "G", and "Z" tags may be used to reference
Text from the "Game Def", or the current Zone's "Zone Def", respectively
The "R" or "r" tags may be used to obtain the ID value from a Register
The given "Text" must have been defined within the current Game Def or Zone Def, and the number of characters read from the file must not excede the number of characters that were used to initialize it
- Terminator
Byte value (A number 0-255 in decimal, Hex, or Binary form) or ASCII Character (Identified with a single quote mark ('), such as "'A") that terminates the string
_File_WriteString
(ALL) (REG) (Example)
Write a string of characters from the given "Game/Zone" Text into the currently-open Write-access file. Characters will be read from the "Game/Zone" Text until the value 0 is found
A terminator byte/character is not automatically appended to the outgoing string, so as to allow un-terminated strings, or the use of any desired character as a terminator. If the string must be terminated (such as when it must be read by _File_ReadString), A _File_WriteBYTEs_??? Command must be used to manually write a terminator byte/character
This Command automatically adjusts the current position of the file as the data is being written; the file will then be positioned at the byte immediately following the last valid character within the string
Parameters:
- Text ID
ID of the "Text" from which which the string should be read. The "G", and "Z" tags may be used to reference
Text from the "Game Def", or the current Zone's "Zone Def", respectively
The "R" or "r" tags may be used to obtain the ID value from a Register
Examples:
#_LoadLevel ;Load an HCGE Level Layout File from the file whose path and name are given by "Zone" Text 0
: Z1 ;"Zone" Text 0
; ----------
#_LoadTiles ;Load an HCGE Tile File from the file whose path and name are given by "Game" Text 2
: G2 ;"Game" Text 2
; ----------
#_LoadObjects ;Load an HCGE Object Layout File from the file whose path and name are given by the Game Text whose ID is stored in User Register 5
: R5 ;Value of User Register 5
_SaveLevel
_SaveTiles
_SaveObjects
(Description)
#_SaveLevel ;Save the current Level Layout to the file whose path and name are given by "Zone" Text 7
: Z7 ;"Zone" Text 7
; ----------
#_SaveTiles ;Save the current Tileset to the file whose path and name are given by the Game Text whose ID is stored in User Register 13
: R13 ;Value of User Register 13
; ----------
#_SaveObjects ;Save the current Object Layout to the Object Layout File that was last loaded by the _LoadObjects Command
:_Current ;The "Current" Object Layout File
User-Managed Files:
#_File_Open ;Open the file whose path and name are given by Zone Text 3 as the current Read-access file
: Z3 ;(Text) Zone Text 3
:_FileType_Read ;(Access) Open for Read access
; ----------
#_File_Open ;Open the file whose path and name are given by the Game Text whose ID is stored in User Register 6 as the current Write-access file, destroying the original file if one already existed
: R6 ;(Text) Value of User Register 6
:_FileType_Write ;(Access) Open for Write access, destroy any existing file of the same name
; ----------
#_File_Open ;Open the file whose path and name are given by Game Text 8 as the current Write-access file, preserving any portion of an existing file that isn't explicitly overwritten
: G8 ;(Text) Game Text 8
:_FileType_ReWrite ;(Access) Open for Write access, leave any existing file of the same name in-tact except for areas that are explicitly overwritten
_File_Close
(Description)
#_File_Close ;Close the file that is currently open for Read-access
:_FileType_Read ;(Access) Affect the current Read-access file
; ----------
#_File_Close ;Close the file that is currently open for Write-access
:_FileType_Write ;(Access) Affect the current Write-access file
_File_GetPos
(Description)
#_File_GetPos ;Get the current position of the file that is currently open for Read-access and store it in User Register 3
:_FileType_Read ;(Access) Test the current Read-access file
: U3 ;(Reg) User Register 3
; ----------
#_File_GetPos ;Get the current position of the file that is currently open for Write-access and store it in User Register 12
:_FileType_Write ;(Access) Test the current Write-access file
: U12 ;(Reg) User Register 12
_File_Seek
(Description)
#_File_Seek ;Set the current position of the file that is currently open for Read-access back to its start
:_FileType_Read ;(Access) Affect the current Read-access file
: 0 ;(Offset) 0 bytes away from the starting position
:_FileSeek_Set ;(Pos) Seek relative to the start of the file
; ----------
#_File_Seek ;Set the current position of the file that is currently open for Write-access to be four bytes ahead of where it is currently
:_FileType_Write ;(Access) Affect the current Write-access file
: 4 ;(Offset) 4 bytes ahead of the starting position
:_FileSeek_Cur ;(Pos) Seek relative to the file's current position
; ----------
#_File_Seek ;Set the current position of the file that is currently open for Read-access to 2 bytes from the file's end
:_FileType_Read ;(Access) Affect the current Read-access file
: -2 ;(Offset) 2 bytes in front of the starting position
:_FileSeek_End ;(Pos) Seek relative to the end of the file
_File_ReadBYTEs_Reg
_File_ReadWORDs_Reg
_File_ReadDWORDs_Reg
_File_ReadBYTEs_Chr
_File_ReadWORDs_Chr
_File_ReadDWORDs_Chr
_File_ReadBYTEs_Obj
_File_ReadWORDs_Obj
_File_ReadDWORDs_Obj
(Description)
#_File_ReadBYTEs_Reg ;Read 8 BYTE-size values from the file that is currently open for Read-access into consecutive Registers, starting with User Register 14
: U14 ;(Reg) User Register 14
: 8 ;(Len) Read 8 values
; ----------
#_File_ReadWORDs_Chr ;Read 4 WORD-size values from the file that is currently open for Read-access into consecutive Player variables for the Player currently "Fetched" to "Reference 2", starting with User-created "Active Variable" 26
: a26 ;(Chr2) User-created "Active Variable" 26 of the Player "Fetched" to "Reference 2"
: 4 ;(Len) Read 4 values
; ----------
#_File_ReadDWORDs_Obj ;Read the number of DWORD-size values specified by the value in User Register 9 from the file that is currently open for Read-access into consecutive Object variables for the Object currently "Fetched" to "Reference 2", starting with User-created "Extra Variable" 33
: E33 ;(Obj2) "Extra Variable" 33 of the Object "Fetched" to "Reference 2"
: R9 ;(Len) Value stored in User Register 9
_File_WriteBYTEs_Reg
_File_WriteWORDs_Reg
_File_WriteDWORDs_Reg
_File_WriteBYTEs_Chr
_File_WriteWORDs_Chr
_File_WriteDWORDs_Chr
_File_WriteBYTEs_Obj
_File_WriteWORDs_Obj
_File_WriteDWORDs_Obj
(Description)
#_File_ReadBYTEs_Reg ;Write 2 BYTE-size values from consecutive Registers, Starting with User Register 5, into the file that is currently open for Write-access
: U5 ;(Reg) User Register 5
: 2 ;(Len) Write 2 values
; ----------
#_File_ReadWORDs_Chr ;Write 6 WORD-size values from consecutive Player Variables for the Player currently "Fetched" to "Reference 2", starting with User-created "Active Variable" 11, into the file that is currently open for Write-access
: a11 ;(Chr2) User-created "Active Variable" 11 of the Player "Fetched" to "Reference 2"
: 6 ;(Len) Write 6 values
; ----------
#_File_ReadDWORDs_Obj ;Write the number of DWORD-size values specified by the value in User Register 7 from Object variables for the Object currently "Fetched" to "Reference 2", starting with User-created "Extra Variable" 20, into the file that is currently open for Write-access
: E20 ;(Obj2) "Extra Variable" 20 of the Object "Fetched" to "Reference 2"
: R7 ;(Len) Value stored in User Register 7
_File_ReadString
(Description)
#_File_ReadString ;Read characters from the file that is currently open for Read-access until the value 0 (NULL-Terminator) is found, and store them into "Game" Text 1
: G1 ;(Text ID) "Game" Text 1
: 0
; ----------
#_File_ReadString ;Read characters from the file that is currently open for Read-access until the value $0A (ASCII NewLine terminator) is found, and store them into "Zone" Text 17
: Z17 ;(Text ID) "Zone" Text 17
: $A
; ----------
#_File_ReadString ;Read characters from the file that is currently open for Read-access until a '*' (asterisk/star) character is found, and store them into the "Game" Text whose ID is stored in User Register 48
: R48 ;(Text ID) Value stored in User Register 48
: '*
_File_WriteString
(Description)
#_File_WriteString ;Write all characters from "Game" Text 15 into the file that is currently open for Write-access as a non-terminated string
: G15 ;(Text ID) "Game" Text 15
; ----------
#_File_WriteString ;Write all characters from "Zone" Text 22 into the file that is currently open for Write-access as a non-terminated string
: Z22 ;(Text ID) "Zone" Text 22
; ----------
#_File_WriteString ;Write all characters from the "Game" Text whose ID is stored in User Register 31 into the file that is currently open for Write-access as a non-terminated string
: R31 ;(Text ID) Value stored in User Register 31