Eventtype

Introduction

Events are used for communication between different parts of the client. For example the chat log is registered to the CHAT_MSG_CHANNEL event. When the client receives a chat message the event is triggered and the received string passed along with it. The event callback in the chat log now appends the string to the log.

A very basic example using the TARGET_CHANGED event. It's triggered whenever the target changes. There are three ways to register an object with the event.

A table with OnEvent callback:

-- define a table. this table is the "object" that gets registered with event
target = {}
 
-- define a function called OnEvent within this table. It's called when the event is triggered. 
-- It has at least one argument, the name of the event that is passed to it
-- the remaining arguments are optional event data
function target:OnEvent(event, data)
    -- this way it is possible to handle multiple events with one table
    if event == "TARGET_CHANGED" then
        -- the only action is to print something
        print("Target Changed")
    end
end               
 
-- register the table with the event
RegisterEvent(target, "TARGET_CHANGED")

A table with TARGET_CHANGED callback:

-- define a table. this table is the "object" that gets registered with event
target = {}
 
-- define a function called TARGET_CHANGED within this table. It's called when the event is triggered.
-- It has at least one argument, the name of the event that is passed to it
-- the remaining arguments are optional event data
function target:TARGET_CHANGED(event, data)
    -- the only action is to print something
    print("Target Changed")
end               
 
-- register the table with the event
RegisterEvent(target, "TARGET_CHANGED")

A callback directly:

-- define the function that will be registered with the event
-- It has at least one argument, the name of the event that is passed to it
-- the remaining arguments are optional event data
function eventhandler(event, data)
    -- this way it is possible to handle multiple events with one function
    if event == "TARGET_CHANGED" then
        -- the only action is to print something
        print("Target Changed")
    end
end               
 
-- register the function with the event
RegisterEvent(eventhandler, "TARGET_CHANGED")

Triggering Events

You can trigger an event with the ProcessEvent function. This lets you create your own custom events as well as triggering the standard ones.

--define some data to send with the event
local data = {}
data.name = "Joe SpaceGuy"
data.energylevel = 9001
 
--send the event
ProcessEvent("MY_CUSTOM_EVENT", data)

Notes

Calling RegisterEvent twice with the same arguments will result in the same table receiving an event twice, which is generally not wanted. Use ReloadInterface or UnregisterEvent to get rid previously registered tables before registering new ones.

Passing locally defined tables to RegisterEvent doesn't work. example:

do
    local tab = {}
    function tab:OnEvent() print("this doesn't work") end
    RegisterEvent(tab, "MYEVENT")
end

the table needs a strong reference:

do
    local tab = {}
    function tab:OnEvent() print("this does work") end
    RegisterEvent(tab, "MYEVENT")
    tab_strong = tab
end

Eventlist

The client provides a set of predefined events.

Known events are:

ACTIVATE_CHAT_CHANNEL

Description:

ACTIVATE_CHAT_GROUP

Description:

ACTIVATE_CHAT_GUILD

Description:

ACTIVATE_CHAT_MISSION

Description:

ACTIVATE_CHAT_PRIVATE

Description:

ACTIVATE_CHAT_SAY

Description:

ACTIVATE_CHAT_SECTOR

Description:

ACTIVATE_CHAT_USER

Description:

ASSIGNOWNERKEY_DIALOG

Description:
Triggered when the station requests a key assignment

AUTOAIM_MODE_CHANGED

Description:

CHANGE_ACTIVE_CHATTAB

Description:

CHARINFOMENU_TOGGLE

Description:
Charinfo menu was toggled with /charinfo command or key bind.
Arguments: None.

CHAT_CANCELLED

Description:
Triggered when esc is pressed in chat entry box.
Arguments: None.

CHAT_DONE

Description:
Triggered when enter is pressed in chat entry box.
Arguments: None.

CHAT_ENTERED

Description:
Triggers after CHAT_DONE and echos back the text entered into the chat bar.
text the text entered on the chat bar.

CHAT_MSG_BAR1

Description:
A message from an Itani in the station bar.
Arguments:

CHAT_MSG_BAR2

Description:
A message from a Serco in the station bar.
Arguments:

CHAT_MSG_BAR3

Description:
A message from a UIT in the station bar.

Arguments:

CHAT_MSG_BAR

Description:

CHAT_MSG_BARENTER

Description:
A message stating that a player has entered the bar.

Arguments:

CHAT_MSG_BARLEAVE

Description:
A message stating that a player has left the bar.

Arguments:

CHAT_MSG_BARLIST

Description:
A message listing the players currently in the bar.

Arguments:

CHAT_MSG_BAR_EMOTE1

Description:
An emote (/me) message from an Itani in the station bar.

Arguments:

CHAT_MSG_BAR_EMOTE2

Description:
An emote (/me) message from a Serco in the station bar.

Arguments:

CHAT_MSG_BAR_EMOTE3

Description:
An emote (/me) message from a UIT in the station bar.

Arguments:

CHAT_MSG_BAR_EMOTE

Description:

CHAT_MSG_BUDDYNOTE

Description:

CHAT_MSG_CHANNEL

Description:
Message on inactive channel.

Arguments:
data = {string name, string msg, int faction = factionid, int channelid}

CHAT_MSG_CHANNEL_ACTIVE

Description:
Message on active channel.

Arguments:
data = {string name, string msg, int faction = factionid, int channelid}

CHAT_MSG_CHANNEL_EMOTE

Description: An emote (/me) message in channel chat

Arguments: data = {string name, string msg, int faction = factionid, int channelid}

CHAT_MSG_CHANNEL_EMOTE_ACTIVE

Description:

CHAT_MSG_CONFIRMATION

Description:

CHAT_MSG_DEATH

Description:

CHAT_MSG_DISABLED

Description:

CHAT_MSG_ERROR

Description:

CHAT_MSG_GLOBAL_SERVER

Description:

CHAT_MSG_GROUP

Description:
A message from a player in your group.

Arguments:

CHAT_MSG_GROUP_NOTIFICATION

Description:
eg. Group death notification
Arguments:
data = {string msg, int location = sectorid}

CHAT_MSG_GUIDE

Description:
A message from a guide.

Arguments:

CHAT_MSG_GUILD

Description:
A message from guildmate.

Arguments:
data = {string msg, string name, int location = sectorid, int faction = factionid}

CHAT_MSG_GUILD_EMOTE

Description:
An emote (/me) message from a guildmate.

Arguments:
data = {string msg, string name, int location = sectorid, int faction = factionid}

CHAT_MSG_GUILD_MOTD

Description:
Not used, instead guild MOTD triggers CHAT_MSG_SERVER event.

CHAT_MSG_INCOMINGBUDDYNOTE

Description:

CHAT_MSG_MISSION

Description:

CHAT_MSG_MOTD

Description:

CHAT_MSG_NATION

Description:
A message on nation chat. Depreciated.

CHAT_MSG_PRINT

Description:
Processing this event calls print function with msg as argument (and possibly does other stuff), it's triggered by echo command.
Arguments:
data = {string msg}

CHAT_MSG_PRIVATE

Description:
An incoming private message from another player.

Arguments:
data = {string msg, string name}

CHAT_MSG_PRIVATEOUTGOING

Description:
An outgoing private message to another player.
Causes outgoing message to be shown in chat. For example using SendChat function to send a priavate message will not cause it to be displayed, in this case it's required to trigger this event.

Arguments:
data = {string msg, string name}

CHAT_MSG_SECTOR

Description:
A message from a player in the sector.

Arguments:

CHAT_MSG_SECTORD

Description:
A message from the sector daemon.

Sends messages: (only way to get those messages, as far as i know)
'You lost/won the duel.'
'PLYAER_NAME sent you XXX credits.'


Arguments:
data = {string msg}

CHAT_MSG_SECTORD_MISSION

Description:
A mission message from the sector daemon.

Top5 listing at racetracks triggers this event too.

Arguments:
data = {string msg, int missionid}

CHAT_MSG_SECTORD_SECTOR

Description:
A sector message from the sector daemon (temp KOS standing messages and the 'You've been caught in an Ion Storm.' messages)

Arguments:

CHAT_MSG_SECTOR_EMOTE

Description:
An emote (/me) message from a player in-sector.

Arguments:

CHAT_MSG_SERVER

Description:
Messages triggered by events such as
'*** Your buddy [name] logged off/on.'
Arguments:
msg - table containing string with the message

CHAT_MSG_SERVER_CHANNEL

Description:

CHAT_MSG_SERVER_CHANNEL_ACTIVE

Description:

CHAT_MSG_SERVER_GUILD

Description:

CHAT_MSG_SERVER_SECTOR

Description:
Messages triggered by (or that trigger) this event:

'You are entering [location].'
Arguments:
msg - string containing the message

CHAT_MSG_SYSTEM

Description:
A message from another player in your system.

Arguments:

CHAT_SCROLL_DOWN

Description:

CHAT_SCROLL_UP

Description:

CINEMATIC_START

Description:
Called when an ingame cinematic is started. Examples include the undocking animation and the warping sequences.

Arguments:

COMMAND

Description: A command is executed, such as /echo.
Arguments:
command_id - unique integer id corresponding to the command which was executed. For example, /echo is 20.
args - list of string arguments to the command. For example, "/echo a b c" will receive {'a', 'b', 'c'}. nil if there are no arguments.

CONQUERED_SECTORS_UPDATED

Description:

DESIRED_SPEED_CHANGED

Description:

EMOTE_ENTERED

Description:

ENTERED_STATION

Description:
Triggered when entering station.
Arguments:
None.

ENTERING_STATION

Description:

ENTER_ZONE_dock

Description:

ENTER_ZONE_NFZ

Description:

ENTER_ZONE_wormhole

Description:

FLIGHT_MODE_CHANGED

Description:

FORGIVENESS_DIALOG

Description:

GROUP_CREATED

Description:
Triggered when you create a group before anyone joins.
Arguments:
none

GROUP_MEMBER_DIED

Description:

GROUP_MEMBER_HEALTH_UPDATE

Description:
Triggered when a group members health is updated for any reason and you're in the same sector.
Arguments:
charid character id of the group member
(number) unknown
percent percent health they are now at
(number) unknown

GROUP_MEMBER_JOINED

Description:
Triggers when someone joins your group
Arguments:
name character name of the joiner

GROUP_MEMBER_KILLED

Description:
Triggers when a group member kills someone
Arguments:
charid character id of the deceased
charid character id of the killer
sectorid sector id where the event took place
weaponname name of the weapon used
(number) unknown

GROUP_MEMBER_LEFT

Description:
Triggers when a group member leaves the group
Arguments:
charid character id of the member who left the group

GROUP_MEMBER_LOCATION_CHANGED

Description:
Triggers when a group members location changes
Arguments:
charid character id of the member who changed their location

GROUP_MEMBER_UPDATE

Description:

GROUP_OWNER_CHANGED

Description:

GROUP_SELF_INVITED

Description:

GROUP_SELF_JOINED

Description:

GROUP_SELF_LEFT

Description:
Triggers when you leave a group but are not kicked.
Arguments:
none

GUILD_ACTIVITY_LOG

Description:

GUILD_BALANCE_UPDATED

Description:

GUILD_BANK_LOG

Description:

GUILD_MEMBERS_UPDATED

Description:

GUILD_MEMBER_ADDED

Description:
Triggered when guild member logs on or joins the guild.
Arguments:
charid charid of added guild member.
rank 0=member, 1=lieutenant, 2=council member, 3=council member and lieutenant, 4=commander

GUILD_MEMBER_REMOVED

Description:
Triggered when guild member logs off or leaves the guild.
Arguments:
charid charid of removed guild member.
reason 0=logoff, 1=resign, 2=kicked out by commander/lieutenant, 3=voted out by council.

GUILD_MEMBER_UPDATED

Description:

GUILD_MOTD_UPDATED

Description:

GUILD_PRIVILEGES_UPDATED

Description:

GUNNER_KICKED

Description:

GUNNER_LEFT

Description:

HUD_HELP_TOGGLE

Description:

HUD_HIDE

Description:

HUD_INVENTORY_TOGGLE

Description:

HUD_MODE_TOGGLE

Description:

HUD_RELOADING

Description:
Triggered after rHUDxscale but before the HUD is reloaded

HUD_RELOADED

Description:
Triggered after the HUD is reloaded by rHUDxscale

HUD_SHOW

Description:

HUD_SKIRMISH_CLOSE

Description:

HUD_SKIRMISH_OPEN

Description:

HUD_SKIRMISH_UPDATE

Description:

HUD_TOGGLE

Description:

HUD_UPDATE

Description:

INVENTORY_ADD

Description:
Arguments:(itemid)
itemid itemid of added item

INVENTORY_RECEIVED

Description:

INVENTORY_REMOVE

Description:

INVENTORY_UPDATE

Description:

JETTISONMENU_TOGGLE

Description:

JUMP_OUT_CINEMATIC_FINISHED

Description:
Called when the sector jump-out cinematic is finished.

Arguments:

KEYADDED

Description:
Triggered after a key was added to the keychain
Arguments:
key id of added key

KEYINFO_DIALOG

Description:

KEYREMOVED

Description:
Triggered after a key was removed from the keychain
Arguments:
key id of removed key

LEAVE_ZONE_dock

Description:

LEAVE_ZONE_NFZ

Description:

LEAVE_ZONE_wormhole

Description:

LEAVING_STATION

Description:

LOGIN_FAILED

Description:

LOGIN_SUCCESSFUL

Description:

MISSIONLIST_UPDATED

Description:

MISSION_ADDED

Description:

MISSION_NOTIFICATION

Description:

MISSION_QUESTION_OPEN

Description: Triggered when the user opens the "info" screen to consider accepting a mission, OR after RequestMissionExtendedDescription is called.
Arguments:
- string extended description - the text which appears in the info screen
- string s - usually "Accept", but not always
- string missionid - mission id (Note that it is in string form, so "1234" instead of 1234)
- int stationid - station id

MISSION_REMOVED

Description:

MISSION_TIMER_START

Description:

MISSION_TIMER_STOP

Description:

MISSION_UPDATED

Description:

MSG_LOGOFF_TIMER

Description:
Logoff and explode countdowns and abort messages.

Arguments: (string msg)

MSG_NOTIFICATION

Description:
Occurs when a message is overlaid to the center of your HUD; eg. when you attempt to mine with a full inventory.
Arguments: (string msg, ...? unknown)

NAVMENU_TOGGLE

Description:

NAVROUTE_ADD

Description:

NAVROUTE_CHANGED

Description:

NAVROUTE_SAVE

Description:

NAVROUTE_UNDOLAST

Description:

OBJECT_INFO_UPDATED

Description:

OPEN_SURVEY

Description:

PLAYERLIST_CLOSE

Description:

PLAYERLIST_TOGGLE

Description:

PLAYER_DEATH_CINEMATIC_FINISHED

Description:

PLAYER_DIED

Description:
Triggered when player in the sector dies.
Arguments:(int died = charid, int killed = charid)
died - charid of player who died
killed - charid of player who killed him
weaponid - weaponid of the weapon which scored the kill

PLAYER_ENTERED_GAME

Description:

PLAYER_ENTERED_SECTOR

Description: Called whenever a player enters the sector you are in. When you first enter a sector it is called for every player and NPC currently in the sector. When you are entering a sector the first return value is 0 everything following is a character id but when you are already in the sector and another npc/player joins it returns a charid without starting with 0
Arguments: int charid

PLAYER_GOT_HIT

Description:
Triggered when player gets shot.
Arguments: (int attacked = charid, attacker = charid, unknown, boolean damaged)

unknown - seems proportional to damage but not quite the same
damaged - true when taking damage, false when being healed

PLAYER_GUILD_TAG_UPDATED

Description:

PLAYER_HIT

Description:

PLAYER_HOME_CHANGED

Description:

PLAYER_LEFT_SECTOR

Description:

PLAYERLIST_TOGGLE

Description:
Playerlist was toggled with command or keybind.
Arguments: None.

PLAYER_LOGGED_OUT

Description:

PLAYER_RECEIVED_NEW_ACCOMPLISHMENTS

Description:

PLAYER_STATS_UPDATED

Description:

PLAYER_UPDATE

Description:

PLAYER_UPDATE_ACCOMPLISHMENTS

Description:

PLAYER_UPDATE_FACTIONSTANDINGS

Description:

PLAYER_UPDATE_SKILLS

Description:

PLAYER_UPDATE_STATS

Description:

PLUGINS_LOADED

Description:
Triggered right after the plugin load sequence has completed.

PROXIMITY_ALERT

Description:

PUSH_TO_TALK

Description:

QUIT

Description:

SECTOR_ALIGNMENT_UPDATED

Description:

SECTOR_CHANGED

Description:
Triggered on entering a sector

Arguments:
sectorid - sectorid of the entered sector.

SECTOR_LOADED

Description:

SECTOR_LOADING

Description:

SERVER_DISCONNECTED

Description:

SHIP_CHANGED

Description:

SHIP_SPAWNED

Description:

SHIP_SPAWN_CINEMATIC_FINISHED

Description:

SHIP_UPDATED

Description:

SHOW_STATION

Description:

START

Description:

STATION_TURRET_HEALTH_UPDATE

Description:

STATION_UPDATED

Description:

STATION_UPDATE_DESIREDITEMS

Description:

STATION_UPDATE_PRICE

Description:

STATION_UPDATE_REQUESTED

Description:

STORM_STARTED

Description: Triggered when entering a sector which has an ion storm.
Arguments: None

STORM_STOPPED

Description: Triggered when entering a sector which does not have an Ion Storm (eg. from entering the game, performing a sector jump, performing a wormhole jump, or respawning). Also triggers if you are in a sector with an Ion Storm and that storm ends.
Arguments: None

SYSMENU_TOGGLE

Description:

SYSTEM_BEST_PRICE

Description:
Triggered when the best sell price of an item in the active ships cargo hold changes
Arguments:(item, price, station)

item itemid of changed item
price new price
station locationid of station with highest price

TARGET_CHANGED

Description:
Arguments: None.

TARGET_HEALTH_UPDATE

Description:

TARGET_SCANNED

Description:
Triggered when an object (ship or asteroid depending on scanner equipped) is scanned.
Causes HUD.scaninfo to be updated.
Arguments: (scaninfo, nodeid, objectid)

scaninfo string containing information about scan result. Same thing that's displayed in top right corner of the hud (HUD.scaninfo.title)
possible values:
- 'Object too far to scan\n' (note the trailing newline)
- for asteroids list of ore contents with one line per each ore, where line is: '[ore name] Ore: [percent]%'
- list of cargo for cargo scanners etc.

nodeid nodeid of scanned object.
objectid objectid of scanned object.

TERMINATE

Description:

TOUCH_PRESSED

Description:
Triggered when a Touch Region is pressed.

Arguments: (regionid, Xpos, Ypos)

regionid number identifying the region pressed
Xpos X position touched on the screen
Ypos Y position touched on the screen

TOUCH_RELEASED

Description:
Triggered when a Touch Region is released.

Arguments: (regionid, Xpos, Ypos)

regionid number identifying the region pressed
Xpos X position touched on the screen
Ypos Y position touched on the screen

TRANSACTION_COMPLETED

Description:

TRANSACTION_FAILED

Description:

TURRET_SPAWNED

Description:

TURRET_SPAWN_CINEMATIC_FINISHED

Description:

UNLOAD_INTERFACE

Description:
Raised when interface is about to be reloaded.

Arguments:

UPDATE_BUDDY_LIST

Description:

UPDATE_CHARACTER_LIST

Description:

UPDATE_CHARINFO

Description:

UPDATE_DUEL_INFO

Description:

UPDATE_FRIENDKEY_LIST

Description:

UPDATE_NEWS

Description:

UPDATE_NEWS_HEADLINES

Description:

VOICECHAT_PLAYER_LISTEN_STATUS

Description:

VOICECHAT_PLAYER_MUTE_STATUS

Description:

VOICECHAT_PLAYER_TALK_STATUS

Description:

WAITING_FOR_CAPSHIP_LAUNCH

Description:

WARP_OUT_CINEMATIC_FINISHED

Description:
Called when the wormhole warp-out cinematic is finished.

Arguments:

WEAPON_GROUP_CHANGED

Description:

WEAPON_PROGRESS_START

Description:

WEAPON_PROGRESS_STOP

Description:

rHUDxscale

Description:

TURRET_OCCUPIED

Description:

TURRET_EMPTY

Description:

TURRET_DEAD

Description: