From b84cd0b3c573d584d2dd73b9e3866cd990b9fd49 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Sun, 29 Dec 2013 13:15:46 +0100 Subject: APIDump: Documented OnPluginsLoaded. --- MCServer/Plugins/APIDump/Hooks/OnPluginsLoaded.lua | 79 ++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPluginsLoaded.lua (limited to 'MCServer/Plugins/APIDump') diff --git a/MCServer/Plugins/APIDump/Hooks/OnPluginsLoaded.lua b/MCServer/Plugins/APIDump/Hooks/OnPluginsLoaded.lua new file mode 100644 index 000000000..d36cdf5c5 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPluginsLoaded.lua @@ -0,0 +1,79 @@ +return +{ + HOOK_PLUGINS_LOADED = + { + CalledWhen = "All the enabled plugins have been loaded", + DefaultFnName = "OnPluginsLoaded", -- also used as pagename + Desc = [[ + This callback gets called when the server finishes loading and initializing plugins. This is the + perfect occasion for a plugin to query other plugins and possibly start communicating with them using + the {{cPluginManager}}:Call() function. + ]], + Params = {}, + Returns = [[ + The return value is ignored, all registered callbacks are called. + ]], + CodeExamples = + { + { + Title = "CoreMessaging", + Desc = [[ + This example shows how to implement the CoreMessaging functionality - messages to players will be + sent through the Core plugin, formatted by that plugin. As a fallback for when the Core plugin is + not present, the messages are sent directly by this code, unformatted. + ]], + Code = [[ +-- These are the fallback functions used when the Core is not present: +local function SendMessageFallback(a_Player, a_Message) + a_Player:SendMessage(a_Message); +end + +local function SendMessageSuccessFallback(a_Player, a_Message) + a_Player:SendMessage(a_Message); +end + +local function SendMessageFailureFallback(a_Player, a_Message) + a_Player:SendMessage(a_Message); +end + +-- These three "variables" will hold the actual functions to call. +-- By default they are initialized to the Fallback variants, but will be redirected to Core when all plugins load +SendMessage = SendMessageFallback; +SendMessageSuccess = SendMessageSuccessFallback; +SendMessageFailure = SendMessageFailureFallback; + +-- The callback tries to connect to the Core, if successful, overwrites the three functions with Core ones +local function OnPluginsLoaded() + local CorePlugin = cPluginManager:Get():GetPlugin("Core"); + if (CorePlugin == nil) then + -- The Core is not loaded, keep the Fallback functions + return; + end + + -- Overwrite the three functions with Core functionality: + SendMessage = function(a_Player, a_Message) + CorePlugin:Call("SendMessage", a_Player, a_Message); + end + SendMessageSuccess = function(a_Player, a_Message) + CorePlugin:Call("SendMessageSuccess", a_Player, a_Message); + end + SendMessageFailure = function(a_Player, a_Message) + CorePlugin:Call("SendMessageFailure", a_Player, a_Message); + end +end + +-- Global scope, register the callback: +cPluginManager.AddHook(cPluginManager.HOOK_PLUGINS_LOADED, CoreMessagingPluginsLoaded); + + +-- Usage, anywhere else in the plugin: +SendMessageFailure(a_Player, "Cannot teleport to player, the destination player " .. PlayerName .. " was not found"); + ]], + }, + } , -- CodeExamples + }, -- HOOK_PLUGINS_LOADED +} + + + + -- cgit v1.2.3 From 8406a37ac262bdf135b35f8a8f6f9170553c645e Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Sun, 29 Dec 2013 13:23:30 +0100 Subject: APIDump: The PRE html tag has tab width set to 2 spaces. --- MCServer/Plugins/APIDump/main.css | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'MCServer/Plugins/APIDump') diff --git a/MCServer/Plugins/APIDump/main.css b/MCServer/Plugins/APIDump/main.css index 797079873..aa26bd186 100644 --- a/MCServer/Plugins/APIDump/main.css +++ b/MCServer/Plugins/APIDump/main.css @@ -30,6 +30,11 @@ pre { border: 1px solid #ccc; background-color: #eee; + -moz-tab-size: 2; + -o-tab-size: 2; + -webkit-tab-size: 2; + -ms-tab-size: 2; + tab-size: 2; } body -- cgit v1.2.3 From 61af77a5c5c99ec82decc24ff8fca899f959e48a Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Sun, 29 Dec 2013 13:24:38 +0100 Subject: APIDump: Static files overwrite their destination. --- MCServer/Plugins/APIDump/main_APIDump.lua | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) (limited to 'MCServer/Plugins/APIDump') diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua index ff837ec4e..b3a95eb22 100644 --- a/MCServer/Plugins/APIDump/main_APIDump.lua +++ b/MCServer/Plugins/APIDump/main_APIDump.lua @@ -321,6 +321,7 @@ function DumpAPIHtml() cFile:CreateFolder("API/Static"); local localFolder = g_Plugin:GetLocalFolder(); for idx, fnam in ipairs(cFile:GetFolderContents(localFolder .. "/Static")) do + cFile:Delete("API/Static/" .. fnam); cFile:Copy(localFolder .. "/Static/" .. fnam, "API/Static/" .. fnam); end @@ -428,11 +429,18 @@ function DumpAPIHtml() WriteClasses(f, API, ClassMenu); WriteHooks(f, Hooks, UndocumentedHooks, HookNav); - -- Copy the static files to the output folder (overwrite any existing): - cFile:Copy(g_Plugin:GetLocalFolder() .. "/main.css", "API/main.css"); - cFile:Copy(g_Plugin:GetLocalFolder() .. "/prettify.js", "API/prettify.js"); - cFile:Copy(g_Plugin:GetLocalFolder() .. "/prettify.css", "API/prettify.css"); - cFile:Copy(g_Plugin:GetLocalFolder() .. "/lang-lua.js", "API/lang-lua.js"); + -- Copy the static files to the output folder: + local StaticFiles = + { + "main.css", + "prettify.js", + "prettify.css", + "lang-lua.js", + }; + for idx, fnam in ipairs(StaticFiles) do + cFile:Delete("API/" .. fnam); + cFile:Copy(g_Plugin:GetLocalFolder() .. "/" .. fnam, "API/" .. fnam); + end -- List the documentation problems: LOG("Listing leftovers..."); -- cgit v1.2.3 From 61254d035643de23013b8995a7385ac79a673cbd Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Sun, 29 Dec 2013 14:48:58 +0100 Subject: APIDump: Fixed a factual error in OnPluginsLoaded description. --- MCServer/Plugins/APIDump/Hooks/OnPluginsLoaded.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'MCServer/Plugins/APIDump') diff --git a/MCServer/Plugins/APIDump/Hooks/OnPluginsLoaded.lua b/MCServer/Plugins/APIDump/Hooks/OnPluginsLoaded.lua index d36cdf5c5..0d5b7271e 100644 --- a/MCServer/Plugins/APIDump/Hooks/OnPluginsLoaded.lua +++ b/MCServer/Plugins/APIDump/Hooks/OnPluginsLoaded.lua @@ -6,8 +6,8 @@ return DefaultFnName = "OnPluginsLoaded", -- also used as pagename Desc = [[ This callback gets called when the server finishes loading and initializing plugins. This is the - perfect occasion for a plugin to query other plugins and possibly start communicating with them using - the {{cPluginManager}}:Call() function. + perfect occasion for a plugin to query other plugins through {{cPluginManager}}:GetPlugin() and + possibly start communicating with them using the {{cPlugin}}:Call() function. ]], Params = {}, Returns = [[ -- cgit v1.2.3 From db935c4194b01e754a188473118055fd08e7d450 Mon Sep 17 00:00:00 2001 From: STRWarrior Date: Tue, 31 Dec 2013 14:50:46 +0100 Subject: Documented OnPlayerFished and OnPlayerFishing. --- MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua | 20 ++++++++++++++++++++ MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua | 21 +++++++++++++++++++++ 2 files changed, 41 insertions(+) create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua (limited to 'MCServer/Plugins/APIDump') diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua new file mode 100644 index 000000000..03ab5bfb9 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua @@ -0,0 +1,20 @@ +return +{ + HOOK_PLAYER_FISHED = + { + CalledWhen = "A player gets a reward from fishing.", + DefaultFnName = "OnPlayerFished", -- also used as pagename + Desc = [[ + This hook gets called when a player already has his reward from fishing. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who pulled the fish in." }, + { Name = "Reward", Type = "{{cItems}}", Notes = "The reward the player gets. It can be a fish, tressure and junk." }, + }, + Returns = [[ + If the function returns false or no value, the next plugin's callback is called. If the function returns true, no other + callback is called for this event. + ]], + }, -- HOOK_PLAYER_FISHED +} \ No newline at end of file diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua new file mode 100644 index 000000000..1989b02cd --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua @@ -0,0 +1,21 @@ +return +{ + HOOK_PLAYER_FISHING = + { + CalledWhen = "A player is about to get a reward from fishing.", + DefaultFnName = "OnPlayerFishing", -- also used as pagename + Desc = [[ + This hook gets called when a player right clicks with a fishing rod while the floater is under water. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who pulled the fish in." }, + { Name = "Reward", Type = "{{cItems}}", Notes = "The reward the player gets. It can be a fish, tressure and junk." }, + }, + Returns = [[ + If the function returns false or no value, the next plugin's callback is called. Afterwards, the + server gives the player his reward. If the function returns true, no other + callback is called for this event and the player doesn't get his reward. + ]], + }, -- HOOK_PLAYER_FISHING +} \ No newline at end of file -- cgit v1.2.3 From c5b89ea0f5561ff1569d7b9638252cf3a0d9626c Mon Sep 17 00:00:00 2001 From: STRWarrior Date: Wed, 1 Jan 2014 15:02:43 +0100 Subject: Fixed typo's in the documentation. --- MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua | 4 ++-- MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'MCServer/Plugins/APIDump') diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua index 03ab5bfb9..0ad2a3af3 100644 --- a/MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua @@ -10,11 +10,11 @@ return Params = { { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who pulled the fish in." }, - { Name = "Reward", Type = "{{cItems}}", Notes = "The reward the player gets. It can be a fish, tressure and junk." }, + { Name = "Reward", Type = "{{cItems}}", Notes = "The reward the player gets. It can be a fish, treasure and junk." }, }, Returns = [[ If the function returns false or no value, the next plugin's callback is called. If the function returns true, no other callback is called for this event. ]], }, -- HOOK_PLAYER_FISHED -} \ No newline at end of file +}; \ No newline at end of file diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua index 1989b02cd..14851c08d 100644 --- a/MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua @@ -10,7 +10,7 @@ return Params = { { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who pulled the fish in." }, - { Name = "Reward", Type = "{{cItems}}", Notes = "The reward the player gets. It can be a fish, tressure and junk." }, + { Name = "Reward", Type = "{{cItems}}", Notes = "The reward the player gets. It can be a fish, treasure and junk." }, }, Returns = [[ If the function returns false or no value, the next plugin's callback is called. Afterwards, the @@ -18,4 +18,4 @@ return callback is called for this event and the player doesn't get his reward. ]], }, -- HOOK_PLAYER_FISHING -} \ No newline at end of file +}; \ No newline at end of file -- cgit v1.2.3 From 78a876ace321648db85a9373cca2a4f03ef09873 Mon Sep 17 00:00:00 2001 From: STRWarrior Date: Wed, 1 Jan 2014 15:15:56 +0100 Subject: Using documentation Xoft recommended. --- MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'MCServer/Plugins/APIDump') diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua index 0ad2a3af3..40dd6b3cf 100644 --- a/MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerFished.lua @@ -5,7 +5,7 @@ return CalledWhen = "A player gets a reward from fishing.", DefaultFnName = "OnPlayerFished", -- also used as pagename Desc = [[ - This hook gets called when a player already has his reward from fishing. + This hook gets called after a player reels in the fishing rod. This is a notification-only hook, the reward has already been decided. If a plugin needs to modify the reward, use the {{OnPlayerFishing|HOOK_PLAYER_FISHING}} hook. ]], Params = { -- cgit v1.2.3 From d656c253c0ead77218a8236e72b678b07316bd2c Mon Sep 17 00:00:00 2001 From: STRWarrior Date: Wed, 1 Jan 2014 15:18:12 +0100 Subject: Little more documentation for OnPlayerFishing. --- MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'MCServer/Plugins/APIDump') diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua index 14851c08d..3b4731091 100644 --- a/MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerFishing.lua @@ -5,7 +5,7 @@ return CalledWhen = "A player is about to get a reward from fishing.", DefaultFnName = "OnPlayerFishing", -- also used as pagename Desc = [[ - This hook gets called when a player right clicks with a fishing rod while the floater is under water. + This hook gets called when a player right clicks with a fishing rod while the floater is under water. The reward is already descided, but the plugin may change it. ]], Params = { -- cgit v1.2.3 From 84bf32f857f890ce50c82a2612fe1bfe072886c9 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Sun, 5 Jan 2014 15:46:45 +0100 Subject: Fixed cPluginManager:AddHook() binding. Fixes #401. Old formats are still accepted, for compatibility reasons. --- MCServer/Plugins/APIDump/APIDesc.lua | 2 +- MCServer/Plugins/APIDump/Writing-a-MCServer-plugin.html | 6 +++--- MCServer/Plugins/APIDump/main_APIDump.lua | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) (limited to 'MCServer/Plugins/APIDump') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index d388d15dd..26537918e 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -1713,7 +1713,7 @@ cPluginManager.AddHook(cPluginManager.HOOK_CHAT, OnChatMessage); ForceExecuteCommand = { Params = "{{cPlayer|Player}}, CommandStr", Return = "bool", 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: 
function(Command, Permission, HelpString)
. 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." }, ForEachConsoleCommand = { Params = "CallbackFn", Return = "bool", Notes = "Calls the CallbackFn function for each command that has been bound using BindConsoleCommand(). The CallbackFn has the following signature: 
function (Command, HelpString)
. 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." }, - Get = { Params = "", Return = "cPluginManager", Notes = "Returns the single instance of the plugin manager" }, + Get = { Params = "", Return = "cPluginManager", Notes = "(STATIC) Returns the single instance of the plugin manager" }, GetAllPlugins = { Params = "", Return = "table", Notes = "Returns a table (dictionary) of all plugins, [name => {{cPlugin}}] pairing." }, GetCommandPermission = { Params = "Command", Return = "Permission", Notes = "Returns the permission needed for executing the specified command" }, GetCurrentPlugin = { Params = "", Return = "{{cPlugin}}", Notes = "Returns the {{cPlugin}} object for the calling plugin. This is the same object that the Initialize function receives as the argument." }, diff --git a/MCServer/Plugins/APIDump/Writing-a-MCServer-plugin.html b/MCServer/Plugins/APIDump/Writing-a-MCServer-plugin.html index 50e39d533..0e07cebdf 100644 --- a/MCServer/Plugins/APIDump/Writing-a-MCServer-plugin.html +++ b/MCServer/Plugins/APIDump/Writing-a-MCServer-plugin.html @@ -84,7 +84,7 @@ end To register a hook, insert the following code template into the "-- Hooks" area in the previous code example. 

-cPluginManager.AddHook(cPluginManager.HOOK_NAME_HERE, FunctionNameToBeCalled)
+cPluginManager:AddHook(cPluginManager.HOOK_NAME_HERE, FunctionNameToBeCalled)

What does this code do? @@ -102,7 +102,7 @@ function Initialize(Plugin) Plugin:SetName("DerpyPlugin") Plugin:SetVersion(1) - cPluginManager.AddHook(cPluginManager.HOOK_PLAYER_MOVING, OnPlayerMoving) + cPluginManager:AddHook(cPluginManager.HOOK_PLAYER_MOVING, OnPlayerMoving) local PluginManager = cPluginManager:Get() -- Command bindings @@ -200,7 +200,7 @@ function Initialize(Plugin) local PluginManager = cPluginManager:Get() PluginManager:BindCommand("/explode", "derpyplugin.explode", Explode, " ~ Explode a player"); - cPluginManager.AddHook(cPluginManager.HOOK_COLLECTING_PICKUP, OnCollectingPickup) + cPluginManager:AddHook(cPluginManager.HOOK_COLLECTING_PICKUP, OnCollectingPickup) LOG("Initialised " .. Plugin:GetName() .. " v." .. Plugin:GetVersion()) return true diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua index b3a95eb22..bd509dcb6 100644 --- a/MCServer/Plugins/APIDump/main_APIDump.lua +++ b/MCServer/Plugins/APIDump/main_APIDump.lua @@ -1177,7 +1177,7 @@ function WriteHtmlHook(a_Hook, a_HookNav) f:write("\n

" .. (a_Hook.Returns or "") .. "

\n\n"); f:write([[

Code examples

Registering the callback

]]); f:write("
\n");
-	f:write([[cPluginManager.AddHook(cPluginManager.]] .. a_Hook.Name .. ", My" .. a_Hook.DefaultFnName .. [[);]]);
+	f:write([[cPluginManager:AddHook(cPluginManager.]] .. a_Hook.Name .. ", My" .. a_Hook.DefaultFnName .. [[);]]);
 	f:write("
\n\n"); local Examples = a_Hook.CodeExamples or {}; for i, example in ipairs(Examples) do -- cgit v1.2.3 From 2e0fcbdcb7a773509f8d08f50c8cbeb07d612d51 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Sat, 11 Jan 2014 16:50:52 +0100 Subject: Documented the cIniFile:AddValue* functions. Now the documentation really matches the implementation. --- MCServer/Plugins/APIDump/APIDesc.lua | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'MCServer/Plugins/APIDump') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 26537918e..9b117b0fa 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -867,6 +867,10 @@ ValueName0=SomeOtherValue { Params = "KeyName, Comment", Return = "", Notes = "Adds a comment to be stored in the file under the specified key" }, }, AddKeyName = { Params = "KeyName", Returns = "number", Notes = "Adds a new key of the specified name. Returns the KeyID of the new key." }, + AddValue = { Params = "KeyName, ValueName, Value", Return = "", Notes = "Adds a new value of the specified name to the specified key. If another value of the same name exists in the key, both are kept (nonstandard INI file)" }, + AddValueB = { Params = "KeyName, ValueName, Value", Return = "", Notes = "Adds a new bool value of the specified name to the specified key. If another value of the same name exists in the key, both are kept (nonstandard INI file)" }, + AddValueF = { Params = "KeyName, ValueName, Value", Return = "", Notes = "Adds a new float value of the specified name to the specified key. If another value of the same name exists in the key, both are kept (nonstandard INI file)" }, + AddValueI = { Params = "KeyName, ValueName, Value", Return = "", Notes = "Adds a new integer value of the specified name to the specified key. If another value of the same name exists in the key, both are kept (nonstandard INI file)" }, CaseInsensitive = { Params = "", Return = "", Notes = "Sets key names' and value names' comparisons to case insensitive (default)." }, CaseSensitive = { Params = "", Return = "", Notes = "Sets key names and value names comparisons to case sensitive." }, Clear = { Params = "", Return = "", Notes = "Removes all the in-memory data. Note that , like all the other operations, this doesn't affect any file data." }, -- cgit v1.2.3