Event Scripts

All events can be bound to JavaScript or Lua script files, so that the script gets executed every time the event is called. Multiple scripts can be bound to the same event, and multiple events can be bound to the same script. You can even bind a script to commands and events at the same time.

Just like with command scripts, the first comment section of the script should contain a metadata section. Events just have one possible metadata tag: @events, followed by one or multiple event names separated by space character.

Example Script (JS)

// The following line binds the script to the event "playerLevelUp":
// @events playerLevelUp

// Import the game dll to get access to all game objects like "GameManager"
importAssembly('Assembly-CSharp');

// The global variable "event" contains the event data as documented in the Event List page
var text = "[FF6666]" + event.clientInfo.playerName + " just reached level " + event.newLevel + "!";

// Send the text as chat message to all players
GameManager.Instance.GameMessageServer(null, EnumGameMessages.Chat, text, "Server", false, "", false);

Global Variables

Additionally to the standard global variables, event scripts have these variables set:

Type	Variable	Description
object	event	Event-specific data object as described in event list
string	eventType	Name of the event that triggered this script, like "playerLevelUp"

Performance Impact

While logging has close to zero performance impact (~0.01 ms per event), starting the scripting engine and executing a script can take around 15 ms per event. This is still neglectible for most events, but you should avoid using scripts for events that are executed many times a second.

Since this obviously depends on your server hardware, best is to test it yourself. Remember: You can disable scripts just by adding an underscore (_) in front of the filename; no restart required.

Troubleshooting

Events are not triggered

If an event is not triggered as expected, check out the server log. Scripting Mod lists all scripts that are registered, and also lists when/if scripts are ignored for any reason.

Examples:

... [SCRIPTING MOD] Registered command "dj-test-lua" from script dj-test-lua.lua.
... [SCRIPTING MOD] Registered event "playerLevelUp" from script event-playerLevelUp.js.
... [SCRIPTING MOD] Script file _event-chatMessage.js is ignored because it starts with underscore.
... [SCRIPTING MOD] Script file event-nothing.js is ignored because it defines neither command names nor events.

Error messages don't appear in-game

Because the scripts are not executed by a particular player, the error output won't be sent to a player's in-game console but only shown in the server log.