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.

There are multiple tiers of level scripts:

1. level.as (in the file Data/Scripts/level.as). 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.
2. The <script>per_level_script.as</script> XML tag inside a 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.
3. The <LevelHookFile>all_level_script.as</script> XML tag inside a mod XML file. 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.

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

1. level.as (in the file Data/Scripts/level.as)
2. One per-level script (<script>something.as</script>, defined by Edit -> Set Level Script...)
3. Multiple per-mod level hook scripts (<LevelHookFile>something.as</LevelHookFile>, inside mod.xml)

List of hook functions

 // Required - called when the level is first loaded
 void Init(string level_name) {
 }

 // Required - Note: Not called on per-mod level scripts.
 // TODO: What is this this used for?
 bool HasFocus() {
     return false;
 }

 // Required - hook to allow a level-specific script to regularly update itself on each game tick.
 // Only called if the game is not frozen/paused. Can be empty
 // Note: Only for a level-specific level script. Don't define in per-mod level scripts or in the base level script
 void Update() {
 }

 // Required - hook to allow the base level script and per-mod level scripts to regularly update themselves on each game tick.
 // is_paused is 0 if not paused, and 1 if paused. Can be empty.
 // Note: Only for the base level script, and per-mod level scripts. Don't define in level-specific level scripts
 void Update(int is_paused) {
 }

 // Required for base level script, Optional for level-specific level script, and per-mod level scripts.
 // Hook to allow messages to be passed between level scripts, or from moving object scripts to level scripts
 void ReceiveMessage(string) {
 }

 // Required - hook to allow the level script to draw a custom GUI. Can be empty
 void DrawGUI() {
 }

 // Required for base level script and for per-mod level scripts.
 // Hook to handle resizing a custom GUI when the game window has been resized
 void SetWindowDimensions(int new_width, int new_height) {
 }

 // Optional - additional hook called as a second pass after the entire first set of DrawGUI hooks have been called
 void DrawGUI2() {
 }

 // Optional - called when a hotspot inside the level is entered by a moving object.
 // Note: called after any "HotspotExit" hook is called.
 // TODO: What is str?
 void HotspotEnter(string str, MovementObject @mo) {
 }

 // Optional - called when a hotspot inside the level is exited by a moving object.
 // Note: called before any "HotspotEnter" hook is called.
 // TODO: What is str?
 void HotspotExit(string str, MovementObject @mo) {
 }

 // Optional - hook to allow receiving incoming network communication in the game client.
 // Called when a network TCP packet has been receieved
 // Note: Requires more setup in order to get any data or even be called, like a connection to the server.
 // See Data/ExampleMods/example_tcp_socket_mod
 void IncomingTCPData(uint socket, array<uint8>@ data) {
 }

 // Required for base level script, not called on level-specific level script, or per-mod level scripts.
 // TODO: What is this used for?
 void SaveHistoryState(SavedChunk@ chunk) {
 }

 // Required for base level script, not called on level-specific level script, or per-mod level scripts.
 // TODO: What is this used for?
 void ReadChunk(SavedChunk@ chunk) {
 }