LevelScripts

Level scripts allow you to set up level-wide code that will get run, regardless of what characters, items, and hotspots exist in that level.

Script Tiers

The order that the engine calls into level scripts is as follows:

level.as (in the file Data/Scripts/level.as)

Only one of these scripts is ever active at a time, since it is either defined by the base game, or by a mod, and only one mod is allowed to be active at the same time that changes this file. The game will tell you "File Conflict Detected" if you try to activate a second mod that overrides the file.

The engine will call into this script for every level in the game. You can override this script in mods, but it is best to only do this as a last resort, since this can make your mod incompatible with other script mods that also override the same file.

One script per-level (<script>some_dir/something.as</script>, defined by Edit -> Set Level Script...)

Only one of these scripts is ever active at a time, since it is defined per-level, and you cannot have more than one level running at the same time.

The specific path for this script is found in the <script> XML tag inside each level XML file. This can be changed in the UI under Editor -> Top Bar -> Edit -> Set Level Script....

You can override this script in your mods, but it requires you to make a per-level change, and only one such script can be active for a given level.

One script per-mod (<LevelHookFile>some_dir/something.as</LevelHookFile>, inside each mod's mod.xml file

Many of these scripts can be active at the same time, though only one such script can be defined for each mod that you have active.

You have to manually add this XML tag the mod.xml that you make for your mod. Functions in this script are run for every level in the game, and every mod can add their own level hook script.

The disadvantage to it is that you can't as easily override default level script behavior. For the most part, changes in this file are limited to adding on additional behavior, rather than altering existing behavior in the base level script.

Documentation

Documentation of the functions, classes, and object instances that you can access inside a level script are available in an automatically generated file on your hard drive:

1. On Windows: My Documents\Wolfire\Overgrowth\aslevel_docs.h
2. On Mac: ~/Library/Application Support/Overgrowth/aslevel_docs.h
3. On Linux: ~/.local/share/Overgrowth/aslevel_docs.h

The list of available functions, classes, and object instances can change with each version of the game, so keep checking back on this aslevel_docs.h file to see the most up to date information.

List of Data/Scripts/level.as hook functions

Required in Data/Scripts/level.as

These functions are required, and must be present in level.as. If you override that file in your mod, you must include all of these functions.

 void Init(string level_name) { }
 // Called when the level is first loaded.
 // Be careful, this may be called before some objects or script params are present in the level.
 // It is most useful for setting initial values for file-scope angelscript state.

 void Update(int is_paused) { }
 // Called regularly by the engine so you can perform work, or detect that the game is paused.
 // It may be useful to do initialization once in this function, if you need objects or level script params to be present.

 void ReceiveMessage(string message) { }
 // Called when level-wide messages have been sent by the engine, or by objects in levels.
 // Objects in levels (such as characters or hotspots) can send this using level.SendMessage("some message string");.
 // Parameters can be sent by separating them with spaces, and putting quotes around parameters that might contain spaces,
 //   then using the TokenIterator object.

 void HotspotExit(string str, MovementObject @mo) { }
 // Triggered when any hotspot is exited by a movement object

 void HotspotEnter(string str, MovementObject @mo) { }
 // Triggered when any hotspot is entered by a movement object

 void DrawGUI() { }
 // Serves as an update function for script-defined GUIs

 void SetWindowDimensions(int width, int height) { }
 // Allows a script-defined GUI to resize itself when the window gets resized

 void SaveHistoryState(SavedChunk@ chunk) { }
 // Allows the level script to save extra undo state

 void ReadChunk(SavedChunk@ chunk) { }
 // Allows the level script to retrieve extra redo state

 bool HasFocus() { return false; }
 // Old unused function.
 // Reserved, though, so be careful to just make this function return false, and not use it for anything

Optional in Data/Scripts/level.as

These functions are optional, but will be called if they are present in level.as.

 void IncomingTCPData(uint socket, array<uint8>@ data) { }
 // Optional - Networking hook for when network data comes in over a socket you've created

 void DrawGUI2() { }
 // Optional - A second pass for updating script-defined GUIs, in case you need to do something with two passes (e.g. layout)

List of per_level_script.as hook functions

Note that the specific path and filename of each of these scripts is defined in each level's XML file, and there can only be one such script defined per level.

Required in per_level_script.as

These functions are required, and must be present in <script>some_dir/per_level_script.as</script>. If you override that script file in your mod, or override the level file, you must include all of these functions.

 void Init(string level_name) { }
 // Called when the level is first loaded.
 // Be careful, this may be called before some objects or script params are present in the level.
 // It is most useful for setting initial values for file-scope angelscript state.

 void Update() { }
 // Called regularly by the engine so you can perform work.
 // This function will not be called if the game is paused.
 // It may be useful to do initialization once in this function, if you need objects or level script params to be present.

 void DrawGUI() { }
 // Serves as an update function for script-defined GUIs

 bool HasFocus() { return false; }
 // Old unused function.
 // Reserved, though, so be careful to just make this function return false, and not use it for anything

Optional in per_level_script.as

These functions are optional, but will be called if they are present in <script>some_dir/per_level_script.as</script>.

 void ReceiveMessage(string message) { }
 // Called when level-wide messages have been sent by the engine, or by objects in levels.
 // Objects in levels (such as characters or hotspots) can send this using level.SendMessage("some message string");.
 // Parameters can be sent by separating them with spaces, and putting quotes around parameters that might contain spaces,
 //   then using the TokenIterator object.

 void IncomingTCPData(uint socket, array<uint8>@ data) { }
 // Optional - Networking hook for when network data comes in over a socket you've created

 void DrawGUI2() { }
 // Optional - A second pass for updating script-defined GUIs, in case you need to do something with two passes (e.g. layout)

List of per_mod_script.as hook functions

Note that the specific path and filename of each of these scripts is defined in each mod's mod.xml file, and there can only be one such script defined per mod.

Required in per_mod_script.as

These functions are required, and must be present in <LevelHookFile>some_dir/something.as</LevelHookFile>. If you add this level hook script in your mod, you must include all of these functions.

 void Init(string level_name) { }
 // Called when the level is first loaded.
 // Be careful, this may be called before some objects or script params are present in the level.
 // It is most useful for setting initial values for file-scope angelscript state.

 void Update(int is_paused) { }
 // Called regularly by the engine so you can perform work, or detect that the game is paused.
 // It may be useful to do initialization once in this function, if you need objects or level script params to be present.

 void DrawGUI() { }
 // Serves as an update function for script-defined GUIs

 void SetWindowDimensions(int width, int height) { }
 // Allows a script-defined GUI to resize itself when the window gets resized

Optional in per_mod_script.as

These functions are optional, but will be called if they are present in <LevelHookFile>some_dir/something.as</LevelHookFile>.

 void ReceiveMessage(string message) { }
 // Called when level-wide messages have been sent by the engine, or by objects in levels.
 // Objects in levels (such as characters or hotspots) can send this using level.SendMessage("some message string");.
 // Parameters can be sent by separating them with spaces, and putting quotes around parameters that might contain spaces,
 //   then using the TokenIterator object.

 void IncomingTCPData(uint socket, array<uint8>@ data) { }
 // Optional - Networking hook for when network data comes in over a socket you've created

 void DrawGUI2() { }
 // Optional - A second pass for updating script-defined GUIs, in case you need to do something with two passes (e.g. layout)