Difference between revisions of "LevelScripts"

From Wolfire Games Wiki
Jump to: navigation, search
(Improve description of the tiers of level script files)
(List of hook functions)
Line 13: Line 13:
 
# Multiple per-mod level hook scripts ('''<LevelHookFile>something.as</LevelHookFile>''', inside mod.xml)
 
# Multiple per-mod level hook scripts ('''<LevelHookFile>something.as</LevelHookFile>''', inside mod.xml)
  
== List of hook functions ==
+
== List of Data/Scripts/level.as hook functions ==
  
  // Required - called when the level is first loaded
+
=== Required in Data/Scripts/level.as ===
  void Init(string level_name) {
 
  }
 
  
  // Required - Note: Not called on per-mod level scripts.
+
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.
  // 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.
+
  void Init(string level_name) { }
   // Only called if the game is not frozen/paused. Can be empty
+
   // Called when the level is first loaded.
   // Note: Only for a level-specific level script. Don't define in per-mod level scripts or in the base level script
+
   // Be careful, this may be called before some objects or script params are present in the level.
  void Update() {
+
   // It is most useful for setting initial values for file-scope angelscript state.
  }
 
  
   // Required - hook to allow the base level script and per-mod level scripts to regularly update themselves on each game tick.
+
  void Update(int is_paused) { }
   // is_paused is 0 if not paused, and 1 if paused. Can be empty.
+
   // Called regularly by the engine so you can perform work, or detect that the game is paused.
  // Note: Only for the base level script, and per-mod level scripts. Don't define in level-specific level scripts
+
   // It may be useful to do initialization once in this function, if you need objects or level script params to be present.
  void Update(int is_paused) {
 
  }
 
  
   // Required for base level script, Optional for level-specific level script, and per-mod level scripts.
+
  void ReceiveMessage(string message) { }
   // Hook to allow messages to be passed between level scripts, or from moving object scripts to level scripts
+
   // Called when level-wide messages have been sent by the engine, or by objects in levels.
  void ReceiveMessage(string) {
+
   // 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.
  
  // Required - hook to allow the level script to draw a custom GUI. Can be empty
+
   void HotspotExit(string str, MovementObject @mo) { }
   void DrawGUI() {
+
   // Triggered when any hotspot is exited by a movement object
   }
 
  
  // Required for base level script and for per-mod level scripts.
+
   void HotspotEnter(string str, MovementObject @mo) { }
  // Hook to handle resizing a custom GUI when the game window has been resized
+
   // Triggered when any hotspot is entered by a movement object
   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 DrawGUI() { }
  void DrawGUI2() {
+
   // Serves as an update function for script-defined GUIs
   }
 
  
  // Optional - called when a hotspot inside the level is entered by a moving object.
+
   void SetWindowDimensions(int width, int height) { }
  // Note: called after any "HotspotExit" hook is called.
+
   // Allows a script-defined GUI to resize itself when the window gets resized
  // TODO: What is str?
 
   void HotspotEnter(string str, MovementObject @mo) {
 
   }
 
  
  // Optional - called when a hotspot inside the level is exited by a moving object.
+
   void SaveHistoryState(SavedChunk@ chunk) { }
  // Note: called before any "HotspotEnter" hook is called.
+
   // Allows the level script to save extra undo state
  // TODO: What is str?
 
   void HotspotExit(string str, MovementObject @mo) {
 
   }
 
  
  // Optional - hook to allow receiving incoming network communication in the game client.
+
   void ReadChunk(SavedChunk@ chunk) { }
  // Called when a network TCP packet has been receieved
+
   // Allows the level script to retrieve extra redo state
  // 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.
+
  bool HasFocus() { return false; }
   // TODO: What is this used for?
+
   // Old unused function.
  void SaveHistoryState(SavedChunk@ chunk) {
+
   // Reserved, though, so be careful to just make this function return false, and not use it for anything
  }
 
  
  // Required for base level script, not called on level-specific level script, or per-mod level scripts.
+
=== Optional in Data/Scripts/level.as ===
   // TODO: What is this used for?
+
 
   void ReadChunk(SavedChunk@ chunk) {
+
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)

Revision as of 21:14, 24 July 2017

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 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)