Re-usable Procedures
Context: HL Kit … Kit Reference
Procedures provide the means to define script logic in a single location and re-use that logic within multiple scripts by calling the procedure from each of those scripts. Procedures are an extremely convenient tool and are used regularly for a variety of purposes.
There are a number of important considerations that come in to play when using procedures. Some are fundamental to the nature of procedures, while others are selectable, allowing you to choose between various capabilities to better tailor the procedure to your needs.
The topics below summarize each of these considerations.
Inherit Caller's Context
When invoked, procedures inherit the initial script context of their caller. For example, if a Description script calls a procedure, the pick or thing that is the initial context of the script is also the initial context within the procedure. There is one exception to this, which is discussed in the topic on "Any" Procedures (below).
No Parameters
Unlike most programming languages, procedures have no parameters. You cannot pass parameters to procedures in the way that traditional programming languages do. However, you can pass information between caller and procedure via the use of variables (see below).
Inherit Caller's Local Variables
Procedures inherit all local variables of the calling script. However, you must still declare each local variable within the procedure so that the compiler knows that you intend to use them. When that is done, the value of each variable will be inherited when the procedure is called and can be accessed normally via the variable within the procedure. Using local variables, you can pass information between the calling script and the procedure. Changes made to variables within the procedure will remain in effect upon return to the calling script, so you can use this technique to pass information both from the script into the procedure and back out from the procedure to the calling script upon return.
Script Type Vs. Context
All procedures must be assigned either a specific script type or a more general script context. This assignment dictates important behaviors for the procedure that impact which scripts can legally call the procedure. Scripts can only call procedures that are assigned a compatible classification. Either the script type must match exactly or the script context must match generally. For example, you cannot call a procedure with "container" context from within an Eval Script, since that script has a "pick" context.
There is a distinct advantage to designating a specific script type for a procedure. If a script calls a procedure with the same script type, then the procedure has full access to all of the special symbols defined for the script. The special symbols behave just like inherited variables and are shared back and forth. If a procedure does not share the identical script type, special symbols are not accessible.
There is a different advantage to using a more general script context for a procedure. By using a general script context, a procedure becomes much more versatile. The procedure can be used from multiple different scripts of different types. For many scripts, using a matching context is preferable, since the procedure can then be re-used by more scripts.
The complete list of script types and contexts available for procedures is specified within the Kit Reference documentation.
"Any" Procedures
There is a special type of procedure that can be called from absolutely any script. In order to make this possible, though, the procedure must make an additional concession to ensure compatability. The procedure possesses no initial script context. This is because the same procedure could be called from different scripts, where each calling script has a different initial context.
The implications of having no context are significant. Without an initial context, the procedure cannot perform transitions to anything based on an initial context. This means that the only things that can be done are to either operate upon variables (which are shared with the caller) or specify a "safe" context and transition from there. For example, the procedure is always free to start with the "hero" context and locate the specific information it needs, since there is always a hero that can be identified and used.
Calling Other Procedures
Procedures are allowed to call other procedures. All of the rules above apply to procedures that are called from other procedures. The same variable space is shared, all of the special symbols are shared, and all of the rules regarding script type and context apply equally to any procedure, even one that is not called directly from a script.
