Difference between revisions of "HPL2/HPL2 Helper Scripts/LoadWatcher"
(Final draft of first version done.) |
m (Removed duplicate set-up instructions.) |
||
Line 1: | Line 1: | ||
{{TocRight}} | {{TocRight}} | ||
− | This page documents "HelperScripts_LoadWatcher.hps" - part of ''[[HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2 Helper Scripts|main page]] for more information. | + | This page documents "HelperScripts_LoadWatcher.hps" - part of ''[[HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2 Helper Scripts|main page]] for more information, including [[HPL2 Helper Scripts#Set-up|set-up instructions]]. |
=Summary= | =Summary= | ||
Line 30: | Line 30: | ||
The methods AddExtraCallback(), RemoveExtraCallback(), ClearExtraCallbacks() and IsExtraCallbackRegistered() are provided for working with extra callbacks. | The methods AddExtraCallback(), RemoveExtraCallback(), ClearExtraCallbacks() and IsExtraCallbackRegistered() are provided for working with extra callbacks. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
=Properties= | =Properties= |
Revision as of 04:49, 23 November 2023
This page documents "HelperScripts_LoadWatcher.hps" - part of HPL2 Helper Scripts, a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the main page for more information, including set-up instructions.
Summary
The script file "HelperScripts_LoadWatcher.hps" provides an "OnLoad()" global function that is called every time the level loads. This script defines an object called LoadWatcher, of the new script class cLoadWatcher. To access its properties and methods, just use "LoadWatcher." followed by the function call or property. E.g.:
LoadWatcher.AddExtraCallback("OnLoad2");
LoadWatcher.Message = "just_loaded";
OnLoad() is a top level callback that is used in the same way as OnEnter(). It can be added to the level's .hps file and used to excecute script that should happen every time the level loads. It is managed by LoadWatcher.
The difference between OnLoad() and OnEnter is that OnEnter() is only called when the player enters the map. It is not called when the player reloads a game which was saved in the map. OnLoad() will be called last, one frame after the level has started.
The syntax to use for OnLoad() is as follows:
void OnLoad(string &in asMessage)
The string argument asMessage can optionally be used to pass some information about the state of your world or story. The message can be set using the Message property or the SetMessage() function of LoadWatcher. An example use case might be to note some detail about the story progress, for example the Message property could be assigned when the player triggers a story event:
LoadWatcher.Message = "chapter2";
The string will be stored in a local variable wrapper and saved with the game. Then, the next time the level is loaded, OnLoad() will use that message as it's asMessage argument. It can be thought of as a way for the script to leave a message for itself for the next session or next life.
Each level has its own message. Changing the message only affects reloading into the level that is current at the time of changing the message. If no message has been set, or if it is set as an empty string (""), then the default message "OnLoadCallback" is used.
Another feature of LoadWatcher is that you can register extra callbacks to use alongside OnLoad(). These have the same syntax and share the same message, but they can be added and removed at any time, so that they are ready to be called on the next reload. LoadWatcher handles storing the callback names in local variable wrappers, so they are also saved with the game, and also apply only to the current level.
The methods AddExtraCallback(), RemoveExtraCallback(), ClearExtraCallbacks() and IsExtraCallbackRegistered() are provided for working with extra callbacks.
Properties
Math provides the following properties:
LoadWatcher.Message
string Message
The string property Message let's you set the global string that will be used with the OnLoad() callback next time the game is loaded, and each time after that until it is changed.
// Example:
// When a gameplay or story event has occurred, set the message.
LoadWatcher.Message = "AfterTheBigCutscene";
// Next time the level loads:
OnLoad(string &in asMessage)
{
if (asMessage == "AfterTheBigCutscene") DoStuff();
}
Methods
GameVars provides the following methods:
OnLoad() message
LoadWatcher.SetMessage()
void SetMessage(string asMessage, bool abOnce = false)
Sets the global message string that will be used with the OnLoad() callback next time the game is loaded.
abOnce is optional. It defaults to false if omitted. If it is specified as true, then the message will be used once next time the game is loaded and then cleared. If abOnce is false or omitted then the message will persist until it is changed.
- string asMessage - A message to pass to the OnLoad function when the reload happens.
- bool abOnce - Whether to clear the message after the next reload. (Optional, default = false)
// Example:
// When a gameplay or story event has occurred, set the message.
LoadWatcher.SetMessage("AfterTheBigCutscene");
// Next time the level loads:
OnLoad(string &in asMessage)
{
if (asMessage == "AfterTheBigCutscene") DoStuff();
}
Extra Callbacks
LoadWatcher.AddExtraCallback
bool AddExtraCallback(string asCallback)
Registers an additional callback to use when the level is loaded. Returns false if the callback is already registered, and true if it otherwise registered successfully.
- string asCallback - Name of the callback function to register.
// Example:
// When a gameplay or story event has occurred, add a new callback.
LoadWatcher.AddExtraCallback("OnLoadWhileDoorIsLocked");
// Next time the level loads:
OnLoad(string &in asMessage)
{
// Do normal stuff
}
OnLoadWhileDoorIsLocked(string &in asMessage)
{
// Do stuff specific to the door-locked scenario, whatever that is.
}
LoadWatcher.IsExtraCallbackRegistered
bool IsExtraCallbackRegistered(string asCallback)
Returns true if the additional callback has already been registered. This includes callbacks that have been registered in this level in a previous session.
- string asCallback - Name of the callback function to check.
// Example:
if (LoadWatcher.IsExtraCallbackRegistered("ReloadInChapter2"))
// The condition will succeed if the extra callback with that name has been registered.
LoadWatcher.RemoveExtraCallback
bool RemoveExtraCallback(string asCallback)
Un-registers an additional callback. Returns true if the callback was found and removed.
- string asCallback - Name of the callback function to remove.
// Example:
// When a gameplay or story event has occurred, add a new callback.
LoadWatcher.RemoveExtraCallback("OnLoadWhileDoorIsLocked");
// Next time the level loads:
OnLoad(string &in asMessage)
{
// Do normal stuff
}
OnLoadWhileDoorIsLocked(string &in asMessage)
{
// Do stuff specific to the door-locked scenario, whatever that is.
// If the callback has been removed, this will no longer happen.
}
LoadWatcher.ClearExtraCallbacks
void ClearExtraCallbacks()
Un-registers all extra callbacks.
// Example:
LoadWatcher.ClearExtraCallbacks();
// Now only the OnLoad() callback will be called.