forked from minetest-mods/irc
116 lines
3.9 KiB
Plaintext
116 lines
3.9 KiB
Plaintext
|
|
IRC Mod API
|
|
-----------
|
|
This file documents the API exported by the IRC mod.
|
|
|
|
|
|
BASICS
|
|
------
|
|
In order to allow your mod to interface with this mod, you must add `irc'
|
|
(without the quotes) to your mod's `depends.txt' file.
|
|
|
|
|
|
REFERENCE
|
|
---------
|
|
|
|
mt_irc.say ( [name ,] message )
|
|
Sends <message> to either the channel (if <name> is nil or not specified),
|
|
or to the given user (if <name> is specified).
|
|
Example:
|
|
mt_irc.say("Hello, Channel!")
|
|
mt_irc.say("john1234", "How are you?")
|
|
|
|
mt_irc.register_bot_command ( name, cmddef )
|
|
Registers a new bot command named <name>.
|
|
When an user sends a private message to the bot starting with `!name', the
|
|
command's function is called.
|
|
Here's the command definition (<cmddef>):
|
|
cmddef = {
|
|
params = "<param1> ...", -- A short help text for !help
|
|
description = "My command", -- What does the command? (one-liner)
|
|
func = function ( from, param )
|
|
-- This function gets called when the command is invoked.
|
|
-- <from> is the name of the user that invoked the command.
|
|
-- <param> is the rest of the input (after removing !command)
|
|
end,
|
|
};
|
|
Example:
|
|
mt_irc.register_bot_command("hello", {
|
|
params = nil, -- No params
|
|
description = "Greet user",
|
|
func = function ( from, param )
|
|
mt_irc.say(from, "Hello!")
|
|
end,
|
|
});
|
|
|
|
mt_irc.connected_players [ name ]
|
|
This table holds the players who are currently on the channel (may be less
|
|
than the players in the game). It is modified by the /part and /join chat
|
|
commands.
|
|
Example:
|
|
if (mt_irc.connected_players["joe"]) then
|
|
-- Joe is talking on IRC
|
|
end
|
|
|
|
mt_irc.register_callback ( name, func )
|
|
Registers a function to be called when an event happens. <name> is the name
|
|
of the event, and <func> is the function to be called. See CALLBACKS below
|
|
for more information
|
|
Example:
|
|
mt_irc.register_callback("channel_msg", function ( from, msg )
|
|
if (from == "joe") then
|
|
mt_irc.say("joe", "You are not allowed to do that!")
|
|
return true
|
|
end
|
|
end)
|
|
|
|
This mod also supplies some utility functions:
|
|
|
|
string.expandvars ( string, vars )
|
|
Expands all occurrences of the pattern "$(varname)" with the value of
|
|
`varname' in the <vars> table. Variable names not found on the table
|
|
are left verbatim in the string.
|
|
Example:
|
|
local tpl = "$(foo) $(bar) $(baz)"
|
|
local s = tpl:expandvars({ foo=1, bar="Hello" })
|
|
-- `s' now contains "1 Hello $(baz)"
|
|
|
|
In addition, all the configuration options decribed in `README.txt' are
|
|
available to other mods, though they should be considered "read only". Do
|
|
not modify these settings at runtime or you will most likely crash the
|
|
server!
|
|
|
|
|
|
CALLBACKS
|
|
---------
|
|
The `mt_irc.register_callback' function can register functions to be called
|
|
when some events happen. These are the events supported:
|
|
|
|
channel_msg ( from, message )
|
|
Called right before the bot sends a message to the channel.
|
|
<from> is the name of the user sending the message. <message> is the
|
|
unmodified message sent by the user.
|
|
Returning any value other than nil or false will prevent the message from
|
|
being sent.
|
|
Example:
|
|
mt_irc.register_callback("channel_msg", function ( from, msg )
|
|
if (from == "joe") then
|
|
mt_irc.say("joe", "You are not allowed to do that!")
|
|
return true
|
|
end
|
|
end)
|
|
|
|
private_msg ( from, to, message )
|
|
Called right before the bot sends a private message to an user.
|
|
<from> is the name of the user sending the message. <to> is the recipient
|
|
of the message. <message> is the unmodified message sent by the user.
|
|
Returning any value other than nil or false will prevent the message from
|
|
being sent.
|
|
Example:
|
|
mt_irc.register_callback("private_msg", function ( from, to, msg )
|
|
if (to == "admin") then
|
|
mt_irc.say(from, "You are not allowed to do that!")
|
|
return true
|
|
end
|
|
end)
|