Callback functions in Lua scripts fired upon certain events.

On this page you'll find descriptions and code snippets describing the functions that is called in the script upon hub events (such as a new user joined).

A event is a lua function that will be called by the hub up on certain events. You can place either of the following functions in your lua script to get notification whenever there is a hub event.
The Hex Script plugin tries only once to lookup any of these functions. If not found, the plugin will not try to call them again before the script is reloaded.

• The OnLoad() callback
• The OnUnload() callback
• The OnError(sErrorString) callback
• The OnPmToBot(iBotId, iUserId, sData) callback
• The OnTrigger(iTriggerId, iUserId, bIsPm, sParameters) callback
• The OnUserJoined(iUserId) callback
• The OnUserParts(iUserId) callback
• The OnCommand(iUserId, sData) callback
• The OnUnknownCommand(iUserId, sData) callback
• The OnSaveSettings() callback
• The OnNickChange(iUserId, sOldNick, sNewNick) callback
• The OnChatMessage(iUserId, sData) callback
• The OnPublicMessage(iUserId, sData) callback
• The OnScriptMessage(iMessageCode, sSender, sData) callback
• The BannedUserJoins0(sIp, sFlags) callback
• The BannedUserJoins1(sIp, sFlags) callback
• The BannedUserJoins2(iUserId, sNick, sIp, sOp, sReason, bPermanent) callback

The OnLoad() callback

This function is called when the script is being loaded.
You can use this callback to load settings and other information kept over sessions.

Return true to continue execution, or false to terminate the script.

function OnLoad()
	-- Initializing code here
	
	return true
end

The OnUnload() callback

This function is called when the script is being unloaded/stopped.
This function does not return a value.

function OnUnload()
	-- Save configuration, ect.
end

The OnError(sErrorString) callback

This function is called when there is an error in the script.
Return true to continue execution, or false to terminate the script.

Parameters:

• sErrorString = A ascii string with the error message.

function OnError(sErrorString)
	-- Handle the error and possibly exit
	return true
end

The OnPmToBot(iBotId, iUserId, sData) callback

This function is fired whenever a bot registered by a script receives a private message.
You can use the iBotId to check if its a bot you registered.
Bots are registered with Bot class This function does not return a value.

Parameters:

• iBotId = The identifier of the bot who received a PM
• iUserId = The identifier of the user sent the PM
• sData = A string containing the message the user sent

function OnPmToBot(iBotId, iUserId, sData)
	if mybot:GetBotId() == iBotId then
		-- A pm to a bot we have previously registered.
	end
end

The OnTrigger(iTriggerId, iUserId, bIsPm, sParameters) callback

This function is fired when a trigger registered by a script is used.
You can use iTriggerId to check if its a trigger you registered.
Triggers are registered with Trigger class This function does not return a value.

Parameters:

• iTriggerId = The identifier of the trigger
• iUserId = The identifier of the user sent the PM
• bIsPm = A boolean indicating if the trigger was sent in a PM to the hub bot
• sParameters = A string containing the parameters used with the trigger

function OnTrigger(iTriggerId, iUserId, bIsPm, sParameters)
	if mytrigger:GetTriggerId() == iTriggerId then
		-- a trigger we registered is being used
		print("Lua: TrigId="..iTriggerId.." UserId="..iUserId.."Parameters="..sParameters)
	end
end

The OnUserJoined(iUserId) callback

This function is called when a user joined the hub (completed login).
This function does not return a value.

Parameters:

• iUserId = The identifier of the user who joined the hub.

function OnUserJoined(iUserId)
	-- New user connected to the hub
end

The OnUserParts(iUserId) callback

This function is called when a user parts (leaves) the hub.
This function does not return a value.

Parameters:

• iUserId = The identifier of the user who joined the hub.

function OnUserParts(iUserId)
	-- A user disconnected from the hub
end

The OnCommand(iUserId, sData) callback

This function is called whenever a user sends a command to the hub.
This function returns a boolean.
true = the hub will continue to process this command.
false = the hub will not continue to process this command, and the script manager will not call other lua scripts for this command.

Parameters:

• iUserId = The identifier of the user who joined the hub.
• sData = The command the user send to the hub (e.g. "$ConnectToMe nick ip:port|")

function OnCommand(iUserId, sData)
	local usr = Hex.User(iUserId)
	print("A user with nick: "..usr:GetNick().." send a command: "..sData)
	return true
end

The OnUnknownCommand(iUserId, sData) callback

This function is called whenever a user sends a unknown command to the hub.
This function returns a boolean.
true = the hub will continue to process this command.
false = the hub will not continue to process this command, and the script manager will not call other lua scripts for this command.

Parameters:

• iUserId = The identifier of the user who joined the hub.
• sData = The command the user send to the hub (e.g. "$VoidCommand ...|")

function OnUnknownCommand(iUserId, sData)
	local usr = Hex.User(iUserId)
	print("A user with nick: "..usr:GetNick().." send a unknown command: "..sData)
	return true
end

The OnSaveSettings() callback

This function is called if the hubowner or any of its admins invoked save settings from either the GUI or with a trigger.
This function does not return a value.

function OnSaveSettings()
	-- Dump settings to file
end

The OnNickChange(iUserId, sOldNick, sNewNick) callback

This function gives you notification whenever a user changed nickname.
This function does not return a value.

Parameters:

• iUserId = The identifier of the user whos nickname was changed.
• sOldNick = The previous nickname
• sNewNick = The nickname changed to

OnNickChange(iUserId, sOldNick, sNewNick)
	-- process nick name change here
end

The OnChatMessage(iUserId, sData) callback

This function is called whenever a user sends a chat message.
This function returns a boolean.
true = the hub will continue to process this message.
false = the hub will not continue to process this message, and the script manager will not call other lua scripts for this message.

Parameters:

• iUserId = The identifier of the user who sent the chat message.
• sData = The chat message (can be either a pm or a mainchat message)

function OnChatMessage(iUserId, sData)
	-- process it
	return true
end

The OnPublicMessage(iUserId, sData) callback

This function is called whenever a public message is broadcasted.
This function returns a boolean.
true = the hub will continue to process this message.
false = the hub will not continue to process this message, and the script manager will not call other lua scripts for this message.

Parameters:

• iUserId = The identifier of the user who sent the message.
• sData = The message about to be sent

function OnPublicMessage(iUserId, sData)
	-- process it
	return true
end

The OnScriptMessage(iMessageCode, sSender, sData) callback

This function is called whenever a message from another script is available.
This function does not return a value.

To send a message use Hex.SendScriptMessage(sReceiver, iMessageCode, sData)

Parameters:

• iMessageCode = a number provided by the sender
• sSender = filename of the script that sent the message
• sData = the string data provided by the sender

function OnScriptMessage(iMessageCode, sSender, sData)
	print("Message recived from: "..sSender.." with message code: "..iMessageCode.." Message: "..sData)
end

The BannedUserJoins0(sIp, sFlags) callback

This function will be called when a banned user tryes to join the hub (_ban0_).
This function returns a boolean. True = reject user, false = accept user.

Parameters:

• sIp = the network address of the user in dotted notation.
• sFlags = a whitespace delimited string with flags or nil if no flags.

Flags:

	"LOCKED" => hub is locked
	"DDOSFLT" => DDoS filter
	"BAN0" => _ban0_
	"PROXY" => IP was detected as proxy
	"CONNFLDUSR" => connection flood detected from user
	"CONNFLD" => connection flood detected from multiple IPs
	"SCKERR" => socket error
	"PERM" => the user is permanent banned

function BannedUserJoins0(sIp, sFlags)
	if sFlags ~= nil then
		pritnt("Ban0: "..sIp.." flags: "..sFlags)
	else
		pritnt("Ban0: "..sIp.." flags: nil")
	end
	return true
end

The BannedUserJoins1(sIp, sFlags) callback

This function will be called when a banned user tryes to join the hub (_ban1_).
This function returns a boolean. True = reject user, false = accept user.

Parameters:

• sIp = the network address of the user in dotted notation.
• sFlags = a whitespace delimited string with flags or nil if no flags.

Flags:

	"ADDR" => IP / MAC is banned, _ban1_
	"CONNFLD" => reconnect flood detected
	"CLONES" => number of clones exceeded
	"ISP" => incorrect ISP
	"CC" => incorrect country
	"LOGIN" => too many concurrent logins
	"NOACC" => attempt to join a private hub with no account
	"FULL" => user limit exceeded
	"PORTS" => user connected twice on different hub ports
	"PREFIX" => user is trying to join with a reserved prefix
	"PERM" => the user is permanent banned

function BannedUserJoins1(sIp, sFlags)
	if sFlags ~= nil then
		pritnt("Ban1: "..sIp.." flags: "..sFlags)
	else
		pritnt("Ban1: "..sIp.." flags: nil")
	end
	return true
end

The BannedUserJoins2(iUserId, sNick, sIp, sOp, sReason, bPermanent) callback

This function will be called when a banned user tryes to join the hub (_ban2_).
This function returns a boolean. True = reject user, false = accept user.

Parameters:

• iUserId = identifier of the user who tryes to join the hub.
• sNick = nickname of the banned user.
• sIp = IP of the banned user.
• sOp = nickname of the operator who banned the user (hub-security nickname if this is an auto-ban).
• sReason = reason why the user is banned, this parameter may be a nil value.
• bPermanent = true if the ban is permanent.

Remarks: All these parameters is taken from hexhub unmodified. If hexhub passes a NULL pointer, it will be nil in lua!

function BannedUserJoins2(iUserId, sNick, sIp, sOp, sReason, bPermanent)
	return true
end

---