Improve this page

Events

Events are used to trigger scripts when different things in-game occur. You can create an event binding by changing the third icon into the icon of a grass block with an arrow as shown below.

1. Change this icon to the grass block icon as shown in the image. This tells the mod that you want to bind it to an event.
2. Clicking the white triangle you select what type of event you want the mod to look for.
3. Clicking the square you select what script you want the mod to run upon the event trigger.

local args = {...}
log( args )
--or for the lazy
--log{ ... }

In all event pages that show a table in an image they use these 2 lines of code to show the event details.

The first argument will always be "event" and the second argument will be the name of the event.

Player

AirChanged

This event fires when underwater or leaving it and the amount of air you have has changed. If the air level is -6 and the player is underwater still during the next 3 ticks they will take damage and the air level will be reset to 0. Air will decrease by 1 every 3 ticks. In Minecraft the max amount of air is 300, this has been scaled down to 100.

Args:

3. current amount of air
4. amount changed (gain/loss)

Here we can see the player’s air has just been restored to 100 (from -3) after having been under water long enough to take damage

ArmourDurability

This event is called whenever the damage amount on your armour changes. (Also triggers when equipping / equipping armour)

Args:

3. current armour values (in a table)
4. armour changes (in a table)

For the provided tables, index 1 is the boots, 4 is the helmet.

Seen here, the player has just damaged their boots and lost 1 durability on them.

ArrowFired

This event is triggered when ever a bow has been released (if not pulled back enough it wont fire the arrow, but still triggers the script) After version 7.2.1 event details are correctly included.

Args:

3. the bow (item info)
4. how long the bow was charged for
5. has ammo

AttackEntity

This event is fired when you attack any entity.

Args:

3. attacked entity info

AttackReady

This event is triggered when the player has finished swinging their arm and can attack at full power again.

No special args for this function.

BlockInteract

This event is triggered when you hit USE on a block.

Args:

3. block pos
4. held item
5. "main hand" / "off hand"
6. block side [up, down, north, east, south, west]

BreakItem

Event is triggered when an item is broken.You got the extended warranty, right?
Args:

3. The item that broke

Death

This event triggers when the player dies. (tragic…)

There are no special arguments.

DimensionChanged

This event is triggered whenever the player changes dimensions.

Common dimensions ids:

Args:

3. Dimension entered
4. Dimension left

1.14.3+

1.12.2

EntityInteract

This event triggers when hitting the USE key on an entity. If the main hand does not consume this event then it may also be re triggered for the offhand.

Args:

3. Entity info
4. Item used to interact with (before the interaction)
5. "main hand" or "off hand"

HealthChanged

This event is triggered whenever the players health has changed.

Args:

3. Current health
4. Amount changed
5. Damage type

Here the player has healed from 19 health to 20.

HotbarChanged

This event is fired whenever the player changes the selected hotbar item either through scrolling or pressing 1-9 on their keyboard.

Args:

3. Currently selected hotbar index
4. The hotbar index ranges from 1 to 9

Example where the player has just selected their 7th slot

HungerChanged

This event is triggered whenever the players hunger level changes.

Args:

3. Current hunger level
4. Amount changed

Here you can see that the player has just lost 1 of 20 hunger points and is currently at 17 of 20

ItemCrafted

This event is triggered when ever you craft an item.

Args:

3. Item crafted
4. Crafting matrix before crafting

Shows that atleast 1 sugar was crafted from a matrix where 14 sugar cane were in the top left slot (Image from version 7.2.1 update needed)

ItemDurability

This event is fired whenever the durability of the held item changes.

Args:

3. The item
4. Durability change

ItemPickup

This event is fired whenever you pick up an item.

Args:

3. Item picked up

ItemTossed

This event is fired when you toss an item.

Args:

3. Item picked up

JoinWorld

The JoinWorld event is fired when the player (you) joins any world. (Single player or multi player)

Left shows a single player world, Right shows a server.
localhost shows up on both the 5 and 7 because the server was named after it’s IP

LeaveWorld

This event is triggered when you disconnect from a server or single player game.

There are no special arguments added to this event.

PlayerIgnited

This event is triggered when the player either catches fire or is extinguished.

Args:

3. Is currently on fire (boolean)

PotionStatus

This event is triggered while a potion effect is applied to the player.

This event will be re-triggered as the duration values on the potion effects change. The interval used to determine how frequently to call this event can be configured in the mod settings.

Showing the current setting:

log( getSettings().events.potionStatusFrequency )

The rule here is that when the potions remaining duration measured in ticks -1 is divisible by the frequency, the event is triggered ( (duration-1) % frequency == 0 )

Args:

3. Potion details

Respawn

The Respawn event triggers after the player dies and presses Respawn.Good as new!\

This event has no special arguments.

SaturationChanged

This event is triggered when the players saturation level is changed.

Args:

3. Current saturation level
4. Amount changed

UseBed

Triggered when the player enters a bed.

No special args for this event.

UseItem

This event is triggered while the use key is being held or when it is released. This only works for items with a use action (like food, potions, bows, etc) not blocks being placed.

Args:

3. item being used
4. 72000-ticks held
5. phase (start, tick, stop)

Its default value is 20 (once per second)

WakeUp

This event triggers when a player exits a bed (regardless of time change).
It will also trigger if manual exiting the bed.

No special args for this function.

XP

This event fires whenever the amount of experience the player has or the number of levels they have changes.

Args:

3. Current experience points (the bar)
4. Current level
5. Change in points
6. Change in level

GUI

Actionbar

The Actionbar event fires whenever text is displayed above the hotbar. An example is when playing a record

Args:

3. displayed text
4. is the text is colorized ( cycles through colors )

Chat

The chat event is triggered a chat message whenever any text is added to the chat (except by log).

Args:

3. Formatted Text
4. Unformulated Text
5. Extras

Extras can be tooltips, functions or click actions.
In the example below you can see that the &T code makes it so clicking on the players name will type /msg Player366 without sending.

ChatFilter

The chat filter event is used to change incoming text and replace it with new text before showing it in the chat.

Args:

3. Formatted text
4. Unformatted text
5. Extras

Example:

local args = {...}
log( args )
return args[3]:gsub("Amazing Server", "lagging"), table.unpack(args[5])

ChatSendFilter

The ChatSendFilter event is triggered whenever the you are about to send a chat message. This allows you to either edit the text before sending it or cancel the message entirely.

Args:

3. Text to send

Example:

local args = {...}
log( args )
return args[3]:gsub("btw","by the way")

ContainerOpen

This event is triggered anytime you open a GUI that has an inventory.

Args:

3. GUI controlls (isOpen, close, inventory)
4. Container type (used to get the inventory mapping)

GuiClosed

This event is called when a GUI is closed.

No special arguments for this event.

GuiOpened

This event is triggered whenever any GUI is opened.

Args:

3. controls
4. GUI name

Controls always include isOpen and close functions. For vanilla GUIs additional functions are included. For any gui with an inventory arg 3 should also include a value inventory with controls for that inventory’s contents.

Anvil\

Villlager

Enchantment table

Sign

Book (1.14.4+)

Book (1.12.2), Contains all of the above with the following changes:

Command Block

World

PlayerJoin

Triggered whenever a player joins the game. This event does not rely on the Player has joined the game message and will work even if a server has hidden those messages.

Args:

3. Players name

PlayerLeave

This event triggers when any player leaves the server. This event’s implementation does not rely on the Player left the game messages and will work even if a server has hidden those messages.

Args:

3. the player who left. <span class="flavorText">(Good bye friend!)</span>

Sound

This event is triggered when any sound is played in game (but not by playSound or getSound).

Args:

3. Sound name
4. extra info
5. controls including

https://www.digminecraft.com/lists/sound_list_pc.php has an interactive list of sounds and sound IDs that may be useful.

Title

The title event is triggered whenever a player is shown a title in game.

Args:

3. title text
4. subtitle text (if none then it's "" )
5. display time in ticks
6. fade in time in ticks
7. fade out time in ticks

Weather

This event is triggered whenever the weather changes in game.
Weather will not normal change directly from clear to thunder or from thunder directly to clear.
It will instead transition through rain.

Args:

3. Current weather

WorldSaved

This event is triggered whenever your single player game is saved.

No special arguments for this event.

Other

Anything

This event is the catch all event. Anything except for chat filters will trigger this. Key and mouse events will also trigger this.

Args will match as described in other events.

ProfileLoaded

This event is fired whenever the current Bindings profile has been changed.

Args:

3. Profile name

A profile named Documentation has just been loaded

Startup

This event is triggered right after the mod has been loaded and is an excellent time load any functions that you want to be available for the remainder of the time the game runs.

No special args for this event

This example code will run every script that exists in a folder named “startup” and can be a neat way to run multiple scripts during startup without cluttering your bindings menu.

local files = filesystem.list("~macros/startup")

toast("Startup","loading files...")
for a, b in pairs(files) do
  local pass, err = pRun("~macros/startup/"..b)
  if not pass then
    log("&cstartup&7/&c"..b.."&4 "..err)
  end
end