Events

An event is a moment the server offers to your scripts. A script answers an event by having its name. This page lists every event the server raises, what it hands to main, and what the script's answer changes.

If scripts are new to you, read An introduction to scripting first.

Reading the tables#

Script name. What to call the script. Capital letters do not matter. Where a name ends in a word in braces, such as JoinMap{map}, put a number there: JoinMap12. You can have the general script, the numbered one, or both.

main is given. The values the event hands over, by the names to use for them. Write only the ones you need, in any order. All are whole numbers (int) unless marked.

Answering false. What return false; stops. A dash means the event only tells you something happened, and its answer is ignored: write its main with void.

Where a general script and a numbered one both exist, either can answer false.

Some numbers come up throughout:

The server#

Joining and leaving#

Chat#

Command is how a world adds chat commands of its own. commandName is the word after the slash, and the four parameters are the words after it, with everything left over in the last.

bool main(int player, string commandName, string parameter0)
{
  if (commandName.ToLower() == "home")
  {
    PlayerWarp(player, 1, 5, 5);
    return false;
  }

  return true;
}

Moving#

Tiles#

These run when a player steps onto a tile the map's author marked.

A damage tile does nothing by itself. The DamageTile script decides what stepping on one means:

void main(int player, int damage)
{
  SetPlayerHP(player, Math.Max(1, GetPlayerHP(player) - damage));
  PlayerMessage(player, "The lava burns you!", BrightRed);
}

Items#

Two of these run at more moments than their names suggest:

• GetObj also runs after an item is bought from an NPC or given by a script. Its answer is ignored then. On a pickup inventorySlot is 0, because the item has no slot yet, and mapItemIndex is its place on the ground. Otherwise inventorySlot is where the item landed and mapItemIndex is -1. quantity is how many, for money and ammunition, or how much wear the item has left. For anything that should happen once a player has an item, GotObj is the simpler choice.
• DropObj also runs when a player dies, alongside DieDropObj, and either can save the item. DropObj{item} runs as well for the item a player pays an NPC in a trade, with its answer ignored.

Combat#

In a name, {monster} is the kind of monster: MonsterDie7 runs when a monster of kind 7 dies.

A value marked ref is one the script may change. Write ref in front of it in main, and the server uses what you leave there:

bool main(int player, int monsterIndex, ref int damage)
{
  // Double damage once the world's clock passes hour 20.
  if (GetTime() >= 20)
  {
    damage = damage * 2;
  }

  return true;
}

Damage is kept between 0 and 255.

The game's arithmetic#

Ten more events ask a script to work something out. Every world starts with a script for each, described in the introduction. If one is missing or quarantined, the server uses its own rule.

Trading and the bank#

BuyObj and SellObj only exist with a number. All three are asked about every trade, and any one of them can refuse it.

Guilds#

Every guild event tells you something happened. None can refuse it.

Staff commands#

These run when somebody with the right to use a command uses it. player is the person who typed it.

GodWarpToMe and GodWarpMeTo are given five whole numbers, matched by position: the player who typed the command, the other player, and the map, x and y of the destination. Write the ones you need in that order, under any names.

Timers and your own scripts#

A script started by ScriptTimer or MicroTimer is given one value, the player it was started for. A script run by another with RunScript is given what that script passed.

Neither kind has an event's list of names to match against, so values are matched by position: main takes them in the order they were given, under any names you like.

void main(int player)
{
  PlayerMessage(player, "Time is up!", BrightRed);
}