diff options
Diffstat (limited to 'MCServer/Plugins/APIDump')
| -rw-r--r-- | MCServer/Plugins/APIDump/Classes/Plugins.lua | 1 | ||||
| -rw-r--r-- | MCServer/Plugins/APIDump/Hooks/OnChat.lua | 3 | ||||
| -rw-r--r-- | MCServer/Plugins/APIDump/Hooks/OnExecuteCommand.lua | 23 | ||||
| -rw-r--r-- | MCServer/Plugins/APIDump/main_APIDump.lua | 2 |
4 files changed, 21 insertions, 8 deletions
diff --git a/MCServer/Plugins/APIDump/Classes/Plugins.lua b/MCServer/Plugins/APIDump/Classes/Plugins.lua index ff5d4a180..87f864950 100644 --- a/MCServer/Plugins/APIDump/Classes/Plugins.lua +++ b/MCServer/Plugins/APIDump/Classes/Plugins.lua @@ -68,6 +68,7 @@ cPluginManager.AddHook(cPluginManager.HOOK_CHAT, OnChatMessage); CallPlugin = { Params = "PluginName, FunctionName, [FunctionArgs...]", Return = "[FunctionRets]", Notes = "(STATIC) Calls the specified function in the specified plugin, passing all the given arguments to it. If it succeeds, it returns all the values returned by that function. If it fails, returns no value at all. Note that only strings, numbers, bools, nils and classes can be used for parameters and return values; tables and functions cannot be copied across plugins." }, DoWithPlugin = { Params = "PluginName, CallbackFn", Return = "bool", Notes = "(STATIC) Calls the CallbackFn for the specified plugin, if found. A plugin can be found even if it is currently unloaded, disabled or errored, the callback should check the plugin status. If the plugin is not found, this function returns false, otherwise it returns the bool value that the callback has returned. The CallbackFn has the following signature: <pre class=\"prettyprint lang-lua\">function ({{cPlugin|Plugin}})</pre>" }, ExecuteCommand = { Params = "{{cPlayer|Player}}, CommandStr", Return = "{{cPluginManager#CommandResult|CommandResult}}", Notes = "Executes the command as if given by the specified Player. Checks permissions." }, + ExecuteConsoleCommand = { Params = "CommandStr", Return = "bool, string", Notes = "Executes the console command as if given by the admin on the console. If the command is successfully executed, returns true and the text that would be output to the console normally. On error it returns false and an error message." }, FindPlugins = { Params = "", Return = "", Notes = "<b>OBSOLETE</b>, use RefreshPluginList() instead"}, ForceExecuteCommand = { Params = "{{cPlayer|Player}}, CommandStr", Return = "{{cPluginManager#CommandResult|CommandResult}}", Notes = "Same as ExecuteCommand, but doesn't check permissions" }, ForEachCommand = { Params = "CallbackFn", Return = "bool", Notes = "Calls the CallbackFn function for each command that has been bound using BindCommand(). The CallbackFn has the following signature: <pre class=\"prettyprint lang-lua\">function(Command, Permission, HelpString)</pre> If the callback returns true, the enumeration is aborted and this API function returns false; if it returns false or no value, the enumeration continues with the next command, and the API function returns true." }, diff --git a/MCServer/Plugins/APIDump/Hooks/OnChat.lua b/MCServer/Plugins/APIDump/Hooks/OnChat.lua index d98df008a..a15d09cc7 100644 --- a/MCServer/Plugins/APIDump/Hooks/OnChat.lua +++ b/MCServer/Plugins/APIDump/Hooks/OnChat.lua @@ -7,7 +7,8 @@ return Desc = [[ A plugin may implement an OnChat() function and register it as a Hook to process chat messages from the players. The function is then called for every in-game message sent from any player. Note that - commands are handled separately using a command framework API. + registered in-game commands are not sent through this hook. Use the + {{OnExecuteCommand|HOOK_EXECUTE_COMMAND}} to intercept registered in-game commands. ]], Params = { { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who sent the message" }, diff --git a/MCServer/Plugins/APIDump/Hooks/OnExecuteCommand.lua b/MCServer/Plugins/APIDump/Hooks/OnExecuteCommand.lua index dadc4e94f..79b7bb055 100644 --- a/MCServer/Plugins/APIDump/Hooks/OnExecuteCommand.lua +++ b/MCServer/Plugins/APIDump/Hooks/OnExecuteCommand.lua @@ -2,7 +2,10 @@ return { HOOK_EXECUTE_COMMAND = { - CalledWhen = "A player executes an in-game command, or the admin issues a console command. Note that built-in console commands are exempt to this hook - they are always performed and the hook is not called.", + CalledWhen = [[ + A player executes an in-game command, or the admin issues a console command. Note that built-in + console commands are exempt to this hook - they are always performed and the hook is not called. + ]], DefaultFnName = "OnExecuteCommand", -- also used as pagename Desc = [[ A plugin may implement a callback for this hook to intercept both in-game commands executed by the @@ -11,17 +14,25 @@ return server.</p> <p> If the command is in-game, the first parameter to the hook function is the {{cPlayer|player}} who's - executing the command. If the command comes from the server console, the first parameter is nil. + executing the command. If the command comes from the server console, the first parameter is nil.</p> + <p> + The server calls this hook even for unregistered (unknown) console commands. However, it doesn't call + the hook for unregistered in-game commands, simply because there's no way to distinguish between a + command and a chat message. If a plugin needs to intercept unknown in-game commands, it should use the + {{OnChat|HOOK_CHAT}} hook. ]], Params = { { Name = "Player", Type = "{{cPlayer}}", Notes = "For in-game commands, the player who has sent the message. For console commands, nil" }, - { Name = "Command", Type = "table of strings", Notes = "The command and its parameters, broken into a table by spaces" }, + { Name = "CommandSplit", Type = "array-table of strings", Notes = "The command and its parameters, broken into a table by spaces" }, + { Name = "EntireCommand", Type = "string", Notes = "The entire command as a single string" }, }, Returns = [[ - If the plugin returns true, the command will be blocked and none of the remaining hook handlers will - be called. If the plugin returns false, MCServer calls all the remaining hook handlers and finally - the command will be executed. + If the plugin returns false, MCServer calls all the remaining hook handlers and finally the command + will be executed. If the plugin returns true, the none of the remaining hook handlers will be called. + In this case the plugin can return a second value, specifying whether what the command result should + be set to, one of the {{cPluginManager#CommandResult|CommandResult}} constants. If not + provided, the value defaults to crBlocked. ]], }, -- HOOK_EXECUTE_COMMAND } diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua index 013ec7bef..4ca06b974 100644 --- a/MCServer/Plugins/APIDump/main_APIDump.lua +++ b/MCServer/Plugins/APIDump/main_APIDump.lua @@ -285,7 +285,7 @@ local function WriteHtmlHook(a_Hook, a_HookNav) for _, param in ipairs(a_Hook.Params) do f:write("<tr><td>", param.Name, "</td><td>", LinkifyString(param.Type, HookName), "</td><td>", LinkifyString(param.Notes, HookName), "</td></tr>\n"); end - f:write("</table>\n<p>" .. (a_Hook.Returns or "") .. "</p>\n\n"); + f:write("</table>\n<p>" .. LinkifyString(a_Hook.Returns or "", HookName) .. "</p>\n\n"); f:write([[<hr /><h1>Code examples</h1><h2>Registering the callback</h2>]]); f:write("<pre class=\"prettyprint lang-lua\">\n"); f:write([[cPluginManager:AddHook(cPluginManager.]] .. a_Hook.Name .. ", My" .. a_Hook.DefaultFnName .. [[);]]); |