Directives
Introduction
Available Directives
Introduction
Directives are used to direct HCGE as to how to read a script function from its file(s). They serve to create local declarations, call for opening additional files, etc.
Available Directives
Note: The variables effectively "created" by this Directive are very "temporary" (they are not "static"). Their values will most likely be destroyed after the Function has finished processing due to other Functions making use of the reserved register pool for automatic Aliases. If a value must be preserved, it must be stored in a unique variable referenced by a manually-assigned local Alias Name or a Globally-defined Alias Name instead
Note: These assignments are made at load-time, not run-time, meaning that the first automatic assignment for each Function uses Register 200. This means that a Function using automatically-assigned Aliases can not use a "_RunFunc(_???)" Command to immediately run another Function that also uses automatically-assigned Aliases (although using a "_CallFunc(_???)" Command to cause a Function to run later will have no consequences)
Advanced: The above issue may be circumvented by manually preventing useful Aliases from receiving the same assigned ID values. For example, a calling Function may create one useful automatically-assigned Alias, and the Function to be called may avoid breaking that assignment by first declaring one dummy Alias that will never be used, and then declaring its first useful Alias. A similar method can be used to allow the called Function to access the local Alias from the Calling Function (just properly name and use the "dummy" Alias)
;Function 0 - Calling Function
.Alias CallingFuncVar1 ;Declare an automatic Alias for this Function (Will reference Register 200)
;Do some things...
#_RunFunc
: 1
;Do some other things...
# End
;Function 1 - Called Function
.Alias CallingFuncVar1 ;Declare a dummy Automatic Alias to avoid the space used by Function 0 (Will reference Register 200. Can be read to obtain the value set by Function 0 if desired)
.Alias CalledFuncVar1 ;Declare an automatic Alias for this Function (Will reference Register 201)
;Do some things...
# End
Manual Assignment
When necessary, local Aliases can be manually assigned a specific type and Constant Value or Variable ID.
This type of declaration requires either two or three parameters- Alias Name, Variable Type Override (optional), and Value/Variable ID, as in the following examples:
; Name Type ID
.Alias Const_Val 4 ;Declare an Alias named "Const_Val" that represents the literal value 4
.Alias BI_Reg R 6 ;Declare an Alias named "BI_Reg" that references Built-In Register 6
.Alias BI_ChrCnst P C1 ;Declare an Alias named "BI_ChrCnst" that references Built-In Player Constant 1
.Alias BI_ChrVar P A9 ;Declare an Alias named "BI_ChrVar" that references Built-In Player Variable 9
.Alias BI_ObjVar O 3 ;Declare an Alias named "BI_ObjrVar" that references Built-In Object Variable 3
.Alias U_Reg U8 ;Declare an Alias named "U_Reg" that references User Register 8
.Alias U_ChrCnst C2 ;Declare an Alias named "U_ChrCnst" that references User Player Constant 2
.Alias U_ChrVar A5 ;Declare an Alias named "U_ChrVar" that references User Player Variable 8
.Alias E_ObjVar E0 ;Declare an Alias named "E_ObjVar" that references "Extra" Object Variable 0
.Alias Var_ID C U7 ;Declare an Alias named "Var_ID" threats the variable ID of User Register 7 as a Constant (literal) Value
.Alias NewName _OldName ;Declare an Alias named "NewName" that will behave exactly the same as the globally-defined Alias "OldName"
For clarity, valid "Variable Type Identifiers" are:
R - Treat the value as a Built-In or User Register ID
P - Treat the value as a Built-In or User Player Constant or Variable ID
O - Treat the value as a Built-In or "Extra" Object Variable ID
C - Treat the value as a Constant (Literal) Value
As shown, Variable Type Tags may be used when assigning a variable ID to the Alias, and the use of these tags can make the "Variable Type Override" parameter unnecessary (as this makes the variable type explicit), in which case it can be omitted. The parameter may, however, still be used either as visible re-enforcement of the desired type, or to override the type as shown in the "Var_ID" example, which converts the ID of a User-made Player Variable so that it can be used as a literal value in calculations instead of as a reference to a value stored in a variable
If a Variable Type Tag is not used, the value is assumed to be a Constant (Literal) Value. This means that when a Built-in Variable type that does not have a Variable Type Tag is used, the Variable Type Override parameter is required if the value is meant to be used as a variable reference
Include
This Directive can be used to cause a Function to include script code from an external file. This will cause HCGE to
treat the Function currently being read as if the entire body of code within the named file was pasted directly into
the Function at the position where the directive was placed
This is useful for maintaining a single instance of code that is used multiple times throughout the complete code set
for a game, such as a task performed by several Object or Player Movement Functions, or to create duplicates of,
for example, an Animation Function that must be used to add multiple instances of the same graphic to a single object
at different offsets (due to the fact that Functions are limited to a single running instance per Object/Player to
prevent repeated calling from restarting or stacking the Function, automatically testing for whether or not a Function
is currently running, and thus speeding up some processes)
.Include "Macro\SomeCode.def" ;Behave as if the code within the file "SomeCode.def" in the folder "Macro" was pasted directly into this file, at this position
Included files may also use this directive themselves, but file inclusion may only be nested 5 levels deep