diff options
Diffstat (limited to 'Server/Plugins/APIDump')
| -rw-r--r-- | Server/Plugins/APIDump/APIDesc.lua | 52 | ||||
| -rw-r--r-- | Server/Plugins/APIDump/Classes/Plugins.lua | 4 | ||||
| -rw-r--r-- | Server/Plugins/APIDump/Classes/World.lua | 88 | ||||
| -rw-r--r-- | Server/Plugins/APIDump/Hooks/OnPlayerOpeningWindow.lua | 20 | ||||
| -rw-r--r-- | Server/Plugins/APIDump/InfoFile.html | 28 | ||||
| -rw-r--r-- | Server/Plugins/APIDump/main_APIDump.lua | 2 |
6 files changed, 144 insertions, 50 deletions
diff --git a/Server/Plugins/APIDump/APIDesc.lua b/Server/Plugins/APIDump/APIDesc.lua index 9e920d429..ce6277533 100644 --- a/Server/Plugins/APIDump/APIDesc.lua +++ b/Server/Plugins/APIDump/APIDesc.lua @@ -202,7 +202,7 @@ return Type = "string", }, }, - Notes = "Returns the name of the sound that is played when placing the block of this type.", + Notes = "(<b>DEPRECATED</b>) Not used by cuberite internally and always returns an empty string.", }, GetSpreadLightFalloff = { @@ -378,16 +378,6 @@ return Type = "bool", Notes = "Can a piston break this block?", }, - m_PlaceSound = - { - Type = "string", - Notes = "The name of the sound that is placed when a block is placed.", - }, - m_RequiresSpecialTool = - { - Type = "bool", - Notes = "Does this block require a tool to drop?", - }, m_SpreadLightFalloff = { Type = "number", @@ -6703,7 +6693,7 @@ These ItemGrids are available in the API and can be manipulated by the plugins, }, { Name = "Lore", - Type = "string", + Type = "table", IsOptional = true, }, }, @@ -6957,10 +6947,10 @@ These ItemGrids are available in the API and can be manipulated by the plugins, Type = "number", Notes = "The item type. One of E_ITEM_ or E_BLOCK_ constants", }, - m_Lore = + m_LoreTable = { - Type = "string", - Notes = "The lore for an item. Line breaks are represented by the ` character.", + Type = "table", + Notes = "The lore for an item. Represented as an array table of lines.", }, m_RepairCost = { @@ -8039,6 +8029,17 @@ This class is used by plugins wishing to display a custom window to the player, }, Notes = "Returns the cItemGrid object representing the internal storage in this window", }, + SetOnClicked = + { + Params = + { + { + Name = "OnClickedCallback", + Type = "function", + }, + }, + Notes = "Sets the function that the window will call when it is about to process a click from a player. See {{#additionalinfo_1|below}} for the signature of the callback function.", + }, SetOnClosing = { Params = @@ -8071,6 +8072,17 @@ This class is used by plugins wishing to display a custom window to the player, ]], }, { + Header = "OnClicked Callback", + Contents = [[ + This callback, settable via the SetOnClicked() function, will be called when the player clicks a slot in the window. The callback can cancel the click.</p> +<pre class="prettyprint lang-lua"> +function OnWindowClicked(a_Window, a_Player, a_SlotNum, a_ClickAction, a_ClickedItem) +</pre> + <p> + The a_Window parameter is the cLuaWindow object representing the window, a_Player is the player who made the click, a_SlotNum is the slot the player clicked, a_ClickAction is the type of click the player made, and a_ClickedItem is the item the player clicked on, if applicable. If the function returns true, the click is cancelled (internally, the server resends the window slots to the player to keep the player in sync). + ]], + }, + { Header = "OnClosing Callback", Contents = [[ This callback, settable via the SetOnClosing() function, will be called when the player tries to close the window, or the window is closed for any other reason (such as a player disconnecting).</p> @@ -8096,7 +8108,7 @@ function OnWindowSlotChanged(a_Window, a_SlotNum) { Header = "Example", Contents = [[ - This example is taken from the Debuggers plugin, used to test the API functionality. It opens a window and refuse to close it 3 times. It also logs slot changes to the server console. + This example is taken from the Debuggers plugin, used to test the API functionality. It opens a window and refuse to close it 3 times. It also logs slot changes to the server console and prevents shift-clicking in the window. <pre class="prettyprint lang-lua"> -- Callback that refuses to close the window twice, then allows: local Attempt = 1; @@ -8111,10 +8123,18 @@ local OnSlotChanged = function(Window, SlotNum) LOG("Window \"" .. Window:GetWindowTitle() .. "\" slot " .. SlotNum .. " changed."); end +-- Prevent shift-clicking: +local OnClicked = function(Window, ClickingPlayer, SlotNum, ClickAction, ClickedItem) + if ClickAction == caShiftLeftClick then + return true + end +end + -- Set window contents: -- a_Player is a cPlayer object received from the outside of this code fragment local Window = cLuaWindow(cWindow.wtHopper, 3, 3, "TestWnd"); Window:SetSlot(a_Player, 0, cItem(E_ITEM_DIAMOND, 64)); +Window:SetOnClicked(OnClicked); Window:SetOnClosing(OnClosing); Window:SetOnSlotChanged(OnSlotChanged); diff --git a/Server/Plugins/APIDump/Classes/Plugins.lua b/Server/Plugins/APIDump/Classes/Plugins.lua index c00735412..e22f4e3a0 100644 --- a/Server/Plugins/APIDump/Classes/Plugins.lua +++ b/Server/Plugins/APIDump/Classes/Plugins.lua @@ -840,6 +840,10 @@ cPluginManager.AddHook(cPluginManager.HOOK_CHAT, OnChatMessage); { Notes = "Called when the player has moved and the movement is now being applied.", }, + HOOK_PLAYER_OPENING_WINDOW = + { + Notes = "Called when the player is about to open a window. The plugin can return true to cancel the window opening.", + }, HOOK_PLAYER_PLACED_BLOCK = { Notes = "Called when the player has just placed a block", diff --git a/Server/Plugins/APIDump/Classes/World.lua b/Server/Plugins/APIDump/Classes/World.lua index e452db2ff..62d71828f 100644 --- a/Server/Plugins/APIDump/Classes/World.lua +++ b/Server/Plugins/APIDump/Classes/World.lua @@ -3353,53 +3353,77 @@ function OnAllChunksAvailable()</pre> All return values from the callbacks are i }, WakeUpSimulators = { - Params = { + Params = { - Name = "BlockX", - Type = "number", - }, - { - Name = "BlockY", - Type = "number", + { + Name = "Block", + Type = "Vector3i", + }, }, + Notes = "Wakes up the simulators for the specified block.", + }, + { + Params = { - Name = "BlockZ", - Type = "number", + { + Name = "BlockX", + Type = "number", + }, + { + Name = "BlockY", + Type = "number", + }, + { + Name = "BlockZ", + Type = "number", + }, }, + Notes = "Wakes up the simulators for the specified block. (DEPRECATED, use vector-parametered version)", }, - Notes = "Wakes up the simulators for the specified block.", }, WakeUpSimulatorsInArea = { - Params = { + Params = { - Name = "MinBlockX", - Type = "number", - }, - { - Name = "MaxBlockX", - Type = "number", - }, - { - Name = "MinBlockY", - Type = "number", - }, - { - Name = "MaxBlockY", - Type = "number", - }, - { - Name = "MinBlockZ", - Type = "number", + { + Name = "Area", + Type = "cCuboid", + }, }, + Notes = "Wakes up the simulators for all the blocks in the specified area (edges inclusive).", + }, + { + Params = { - Name = "MaxBlockZ", - Type = "number", + { + Name = "MinBlockX", + Type = "number", + }, + { + Name = "MaxBlockX", + Type = "number", + }, + { + Name = "MinBlockY", + Type = "number", + }, + { + Name = "MaxBlockY", + Type = "number", + }, + { + Name = "MinBlockZ", + Type = "number", + }, + { + Name = "MaxBlockZ", + Type = "number", + }, }, + Notes = "Wakes up the simulators for all the blocks in the specified area (edges inclusive). (DEPRECATED, use vector-parametered version)", }, - Notes = "Wakes up the simulators for all the blocks in the specified area (edges inclusive).", }, }, AdditionalInfo = diff --git a/Server/Plugins/APIDump/Hooks/OnPlayerOpeningWindow.lua b/Server/Plugins/APIDump/Hooks/OnPlayerOpeningWindow.lua new file mode 100644 index 000000000..04563df89 --- /dev/null +++ b/Server/Plugins/APIDump/Hooks/OnPlayerOpeningWindow.lua @@ -0,0 +1,20 @@ +return +{ + HOOK_PLAYER_OPENING_WINDOW = + { + CalledWhen = "Called when a player is about to open a window", + DefaultFnName = "OnPlayerOpeningWindow", -- also used as pagename + Desc = [[ + This hook is called when a player is about to open a window, e.g. when they click on a chest or a furnace. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who is opening the window" }, + { Name = "Window", Type = "{{cWindow}}", Notes = "The window that is being opened" }, + }, + Returns = [[ + If the function returns false or no value, the next plugin's callback is called, and finally + Cuberite will process the opening window. If the function returns true, no other callback is called for this event. + ]], + }, -- HOOK_PLAYER_OPENING_WINDOW +} diff --git a/Server/Plugins/APIDump/InfoFile.html b/Server/Plugins/APIDump/InfoFile.html index e293931f2..4b35a41be 100644 --- a/Server/Plugins/APIDump/InfoFile.html +++ b/Server/Plugins/APIDump/InfoFile.html @@ -20,6 +20,7 @@ <li><a href="#Commands">Commands table</a></li> <li><a href="#ConsoleCommands">ConsoleCommands table</a></li> <li><a href="#Permissions">Permissions table</a></li> + <li><a href="#Categories">Categories table</a></li> <li><a href="#Using">Using the file in code</a></li> <li><a href="#Examples">Examples</a></li> </ul> @@ -34,7 +35,10 @@ <p>Last, but not least, we want to make a plugin repository on the web in the future, a repository that would store plugins, their descriptions, comments. It makes sense that the centralized information can be parsed by the repository automatically, so that advanced things, such as searching for a plugin based on a command, or determining whether two plugins collide command-wise, are possible.</p> - <p>After this file format has been devised, a tool has been written that allows for an easy generation of the documentation for the plugin in various formats. It outputs the documentation in a format that is perfect for pasting into the forum. It generates documentation in a Markup format to use in README.md on GitHub and similar sites. The clever thing is that you don't need to keep all those formats in sync manually - you edit the Info.lua file and this tool will re-generate the documentation for you.</p> + <p>A tool has been written that allows for an easy generation of the documentation for the plugin in various formats. It outputs the documentation in a format that is perfect for pasting into the forum. It generates documentation in a Markup format to use in README.md on GitHub and similar sites. The clever thing is that you don't need to keep all those formats in sync manually - you edit the Info.lua file and this tool will re-generate the documentation for you. + <br> + To generate documentation for the plugin, activate the DumpInfo plugin on a cuberite server with your plugin installed, and use the webadmin interface to "Dump" the plugin information. This will create a README.md suitable for uploading to your git repo, and a forum_info.txt, which can be copy-pasted into a forum post. + </p> <p>So to sum up, the Info.lua file contains the plugins' commands, console commands, their permissions and possibly the overall plugin documentation, in a structured manner that can be parsed by a program, yet is human readable and editable.</p> @@ -56,6 +60,7 @@ g_PluginInfo = Commands = {}, ConsoleCommands = {}, Permissions = {}, + Categories = {}, } </pre> <p>As you can see, the structure is pretty straightforward. Note that the order of the elements inside the table is not important (Lua property).</p> @@ -115,6 +120,7 @@ Commands = ["/cmd2"] = { Alias = {"/c2", "//c2" }, + Category = "Something", Subcommands = { sub1 = -- This declares a "/cmd2 sub1" command @@ -150,6 +156,8 @@ Commands = <p>The permission element specifies that the command is only available with the specified permission. Note that the permission for subcommand's parent isn't checked when the subcommand is called. This means that specifying the permission for a command that has subcommands has no effect whatsoever, but is discouraged because we may add processing for that in the future.</p> + <p>The optional Categories table provides descriptions for command categories in the generated documentation. The documentation generator will group the commands by their specified Category ("General" by default) and each category will have the specified description written to it.</p> + <p>The ParameterCombinations table is used only for generating the documentation, it lists the various combinations of parameters that the command supports. It's worth specifying even if the command supports only one combination, because that combination will get documented this way.</p> <p>The Alias member specifies any possible aliases for the command. Each alias is registered separately and if there is a subcommand table, it is applied to all aliases, just as one would expect. You can specify either a single string as the value (if there's only one alias), or a table of strings for multiple aliases. Commands with no aliases do not need to specify this member at all.</p> @@ -217,6 +225,24 @@ Permissions = <hr /> + <a name="Categories"><h2>Categories</h2></a> + + <p>The optional Categories table provides descriptions for categories in the generated documentation. Commands can have categories with or without category descriptions in this table. The documentation generator will output a table of listed categories along with their description.</p> +<pre class="prettyprint lang-lua"> +Categories = +{ + General = + { + Description = "A general, yet somehow vague description of the default category." + }, + Something = + { + Description = "Some descriptive words which form sentences pertaining to this set of commands use and goals." + }, +}, +</pre> + + <hr /> <a name="Using"><h2>Using the file in code</h2></a> <p>Just writing the Info.lua file and saving it to the plugin folder is not enough for it to actually be used. Your plugin needs to include the following boilerplate code, preferably in its Initialize() function:</p> diff --git a/Server/Plugins/APIDump/main_APIDump.lua b/Server/Plugins/APIDump/main_APIDump.lua index 0f1476ef7..fd243b25f 100644 --- a/Server/Plugins/APIDump/main_APIDump.lua +++ b/Server/Plugins/APIDump/main_APIDump.lua @@ -168,7 +168,7 @@ end --- Returns the timestamp in HTML format -- The timestamp will be inserted to all generated HTML files local function GetHtmlTimestamp() - return string.format("<div id='timestamp'>Generated on %s, Build ID %s, Commit %s</div>", + return string.format("<div id='timestamp'>Generated by <a href='https://github.com/cuberite/cuberite/tree/master/Server/Plugins/APIDump'>APIDump</a> on %s, Build ID %s, Commit %s</div>", os.date("%Y-%m-%d %H:%M:%S"), cRoot:GetBuildID(), cRoot:GetBuildCommitID() ) |