From 27a9fa31108aef4313a45f4c716f2f1551537236 Mon Sep 17 00:00:00 2001 From: Tiger Wang Date: Sat, 24 May 2014 23:28:48 +0100 Subject: Updated Core --- MCServer/Plugins/Core | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'MCServer/Plugins') diff --git a/MCServer/Plugins/Core b/MCServer/Plugins/Core index 5c8557d4f..3790f78d3 160000 --- a/MCServer/Plugins/Core +++ b/MCServer/Plugins/Core @@ -1 +1 @@ -Subproject commit 5c8557d4fdfa580c100510cde07a1a778ea2e244 +Subproject commit 3790f78d3f7503ff33a423b8e73e81a275562783 -- cgit v1.2.3 From 2194238ef0b376353e7260df5a964976d0b72c5f Mon Sep 17 00:00:00 2001 From: Alexander Harkness Date: Mon, 26 May 2014 17:17:54 +0100 Subject: Update main.css --- MCServer/Plugins/APIDump/main.css | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'MCServer/Plugins') diff --git a/MCServer/Plugins/APIDump/main.css b/MCServer/Plugins/APIDump/main.css index aa26bd186..0a779bfb8 100644 --- a/MCServer/Plugins/APIDump/main.css +++ b/MCServer/Plugins/APIDump/main.css @@ -39,7 +39,8 @@ pre body { - min-width: 800px; + min-width: 400px; + max-width: 900px; width: 95%; margin: 10px auto; background-color: white; -- cgit v1.2.3 From e06f786f1151e1934890a2555de080b1a6860ec4 Mon Sep 17 00:00:00 2001 From: Alexander Harkness Date: Tue, 27 May 2014 20:24:04 +0100 Subject: Stuff. --- MCServer/Plugins/APIDump/main.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'MCServer/Plugins') diff --git a/MCServer/Plugins/APIDump/main.css b/MCServer/Plugins/APIDump/main.css index 0a779bfb8..8041e0d01 100644 --- a/MCServer/Plugins/APIDump/main.css +++ b/MCServer/Plugins/APIDump/main.css @@ -40,7 +40,7 @@ pre body { min-width: 400px; - max-width: 900px; + max-width: 1200px; width: 95%; margin: 10px auto; background-color: white; -- cgit v1.2.3 From fa78379f5a8a1eede69f36b225d684723b0bf3ae Mon Sep 17 00:00:00 2001 From: STRWarrior Date: Mon, 2 Jun 2014 11:45:32 +0200 Subject: Updated OnProjectileHitBlock documentation. --- MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'MCServer/Plugins') diff --git a/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua b/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua index 1588d420c..67d670d0a 100644 --- a/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua +++ b/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua @@ -10,6 +10,11 @@ return Params = { { Name = "ProjectileEntity", Type = "{{cProjectileEntity}}", Notes = "The projectile that hit an entity." }, + { Name = "BlockX", Type = "number", Notes = "The X-coord where the projectile hit." }, + { Name = "BlockY", Type = "number", Notes = "The Y-coord where the projectile hit." }, + { Name = "BlockZ", Type = "number", Notes = "The Z-coord where the projectile hit." }, + { Name = "BlockFace", Type = "number", Notes = "The side of the block where the projectile hit." }, + { Name = "BlockHitPos", Type = "Vector3d", Notes = "The exact position where the projectile hit." }, Returns = [[ If the function returns false or no value, the next plugin's callback is called. If the function -- cgit v1.2.3 From 4c757de9ff58ddab07fa2a337a1359b707480288 Mon Sep 17 00:00:00 2001 From: STRWarrior Date: Mon, 2 Jun 2014 11:54:45 +0200 Subject: Added OnProjectileHitBlock example in Debuggers --- MCServer/Plugins/Debuggers/Debuggers.lua | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'MCServer/Plugins') diff --git a/MCServer/Plugins/Debuggers/Debuggers.lua b/MCServer/Plugins/Debuggers/Debuggers.lua index 064d5d772..534426d25 100644 --- a/MCServer/Plugins/Debuggers/Debuggers.lua +++ b/MCServer/Plugins/Debuggers/Debuggers.lua @@ -29,7 +29,8 @@ function Initialize(Plugin) PM:AddHook(cPluginManager.HOOK_WORLD_TICK, OnWorldTick); PM:AddHook(cPluginManager.HOOK_PLUGINS_LOADED, OnPluginsLoaded); PM:AddHook(cPluginManager.HOOK_PLUGIN_MESSAGE, OnPluginMessage); - PM:AddHook(cPluginManager.HOOK_PLAYER_JOINED, OnPlayerJoined) + PM:AddHook(cPluginManager.HOOK_PLAYER_JOINED, OnPlayerJoined); + PM:AddHook(cPluginManager.HOOK_PROJECTILE_HIT_BLOCK, OnProjectileHitBlock); -- _X: Disabled so that the normal operation doesn't interfere with anything -- PM:AddHook(cPluginManager.HOOK_CHUNK_GENERATED, OnChunkGenerated); @@ -1379,3 +1380,14 @@ end + +function OnProjectileHitBlock(a_Projectile, a_BlockX, a_BlockY, a_BlockZ, a_BlockFace, a_BlockHitPos) + local BlockX, BlockY, BlockZ = AddFaceDirection(a_BlockX, a_BlockY, a_BlockZ, a_BlockFace) + local World = a_Projectile:GetWorld() + + World:SetBlock(BlockX, BlockY, BlockZ, E_BLOCK_FIRE, 0) +end + + + + -- cgit v1.2.3 From 8cf4e806ba53aea8161f4110e8c3c67d215539eb Mon Sep 17 00:00:00 2001 From: STRWarrior Date: Mon, 2 Jun 2014 13:49:05 +0200 Subject: APIDump: Fixed crash --- MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'MCServer/Plugins') diff --git a/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua b/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua index 67d670d0a..72cf85821 100644 --- a/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua +++ b/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua @@ -14,7 +14,7 @@ return { Name = "BlockY", Type = "number", Notes = "The Y-coord where the projectile hit." }, { Name = "BlockZ", Type = "number", Notes = "The Z-coord where the projectile hit." }, { Name = "BlockFace", Type = "number", Notes = "The side of the block where the projectile hit." }, - { Name = "BlockHitPos", Type = "Vector3d", Notes = "The exact position where the projectile hit." + { Name = "BlockHitPos", Type = "Vector3d", Notes = "The exact position where the projectile hit." }, }, Returns = [[ If the function returns false or no value, the next plugin's callback is called. If the function -- cgit v1.2.3 From c5d1ca7dac284bdce84fe42cc0932a432587d553 Mon Sep 17 00:00:00 2001 From: Alexander Harkness Date: Sun, 8 Jun 2014 20:54:41 +0100 Subject: Small change for easier understanding. --- MCServer/Plugins/APIDump/APIDesc.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'MCServer/Plugins') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 1423d64bc..40bfe79ac 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -1969,7 +1969,7 @@ cPluginManager.AddHook(cPluginManager.HOOK_CHAT, OnChatMessage); BroadcastChatSuccess = { Params = "Message", Return = "", Notes = "Prepends Green [INFO] / colours entire text (depending on ShouldUseChatPrefixes()) and broadcasts message. For success messages." }, BroadcastChatWarning = { Params = "Message", Return = "", Notes = "Prepends Rose [WARN] / colours entire text (depending on ShouldUseChatPrefixes()) and broadcasts message. For concerning events, such as plugin reload etc." }, CreateAndInitializeWorld = { Params = "WorldName", Return = "{{cWorld|cWorld}}", Notes = "Creates a new world and initializes it. If there is a world whith the same name it returns nil." }, - FindAndDoWithPlayer = { Params = "PlayerName, CallbackFunction", Return = "", Notes = "Calls the given callback function for the given player." }, + FindAndDoWithPlayer = { Params = "PlayerName, CallbackFunction", Return = "", Notes = "Calls the given callback function for all players with names partially (or fully) matching the name string provided." }, ForEachPlayer = { Params = "CallbackFunction", Return = "", Notes = "Calls the given callback function for each player. The callback function has the following signature: 
function Callback({{cPlayer|cPlayer}})
" }, ForEachWorld = { Params = "CallbackFunction", Return = "", Notes = "Calls the given callback function for each world. The callback function has the following signature: 
function Callback({{cWorld|cWorld}})
" }, GetCraftingRecipes = { Params = "", Return = "{{cCraftingRecipe|cCraftingRecipe}}", Notes = "Returns the CraftingRecipes object" }, -- cgit v1.2.3 From bd25069c25574f96ebf02de7360131bfe3504f04 Mon Sep 17 00:00:00 2001 From: Tiger Wang Date: Wed, 11 Jun 2014 13:21:57 +0100 Subject: Update APIDesc.lua --- MCServer/Plugins/APIDump/APIDesc.lua | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'MCServer/Plugins') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 40bfe79ac..1f43a6172 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2294,10 +2294,13 @@ end IsGameModeCreative = { Params = "", Return = "bool", Notes = "Returns true if the current gamemode is gmCreative." }, IsGameModeSurvival = { Params = "", Return = "bool", Notes = "Returns true if the current gamemode is gmSurvival." }, IsPVPEnabled = { Params = "", Return = "bool", Notes = "Returns whether PVP is enabled in the world settings." }, - IsWeatherRain = { Params = "", Return = "bool", Notes = "Returns true if the current weather is rain." }, - IsWeatherStorm = { Params = "", Return = "bool", Notes = "Returns true if the current weather is a storm." }, + IsWeatherRain = { Params = "", Return = "bool", Notes = "Returns true if the current world is raining." }, + IsWeatherRainAt = { Params = "BlockX, BlockZ", Return = "bool", Notes = "Returns true if the specified location is raining (takes into account biomes)." }, + IsWeatherStorm = { Params = "", Return = "bool", Notes = "Returns true if the current world is stormy." }, + IsWeatherStormAt = { Params = "BlockX, BlockZ", Return = "bool", Notes = "Returns true if the specified location is stormy (takes into account biomes)." }, IsWeatherSunny = { Params = "", Return = "bool", Notes = "Returns true if the current weather is sunny." }, - IsWeatherWet = { Params = "", Return = "bool", Notes = "Returns true if the current weather has any precipitation (rain or storm)." }, + IsWeatherWet = { Params = "", Return = "bool", Notes = "Returns true if the current world has any precipitation (rain or storm)." }, + IsWeatherWetAt = { Params = "BlockX, BlockZ", Return = "bool", Notes = "Returns true if the specified location has any precipitation (rain or storm) (takes into account biomes)." }, QueueBlockForTick = { Params = "BlockX, BlockY, BlockZ, TicksToWait", Return = "", Notes = "Queues the specified block to be ticked after the specified number of gameticks." }, QueueSaveAllChunks = { Params = "", Return = "", Notes = "Queues all chunks to be saved in the world storage thread" }, QueueSetBlock = { Params = "BlockX, BlockY, BlockZ, BlockType, BlockMeta, TickDelay", Return = "", Notes = "Queues the block to be set to the specified blocktype and meta after the specified amount of game ticks. Uses SetBlock() for the actual setting, so simulators are woken up and block entities are handled correctly." }, -- cgit v1.2.3 From 97bfccfdc0088705a4546d7d6369f3801946c1ba Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Wed, 11 Jun 2014 14:34:47 +0200 Subject: APIDump: Documented cBlockArea:GetCoordRange(). --- MCServer/Plugins/APIDump/APIDesc.lua | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'MCServer/Plugins') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 40bfe79ac..800d1170e 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -114,6 +114,7 @@ g_APIDesc = GetBlockSkyLight = { Params = "BlockX, BlockY, BlockZ", Return = "NIBBLETYPE", Notes = "Returns the skylight at the specified absolute coords" }, GetBlockType = { Params = "BlockX, BlockY, BlockZ", Return = "BLOCKTYPE", Notes = "Returns the block type at the specified absolute coords" }, GetBlockTypeMeta = { Params = "BlockX, BlockY, BlockZ", Return = "BLOCKTYPE, NIBBLETYPE", Notes = "Returns the block type and meta at the specified absolute coords" }, + GetCoordRange = {Params = "", Return = "MaxX, MaxY, MaxZ", Notes = "Returns the maximum relative coords in all 3 axes. See also GetSize()." }, GetDataTypes = { Params = "", Return = "number", Notes = "Returns the mask of datatypes that the object is currently holding" }, GetOrigin = { Params = "", Return = "OriginX, OriginY, OriginZ", Notes = "Returns the origin coords of where the area was read from." }, GetOriginX = { Params = "", Return = "number", Notes = "Returns the origin x-coord" }, @@ -124,7 +125,7 @@ g_APIDesc = GetRelBlockSkyLight = { Params = "RelBlockX, RelBlockY, RelBlockZ", Return = "NIBBLETYPE", Notes = "Returns the skylight at the specified relative coords" }, GetRelBlockType = { Params = "RelBlockX, RelBlockY, RelBlockZ", Return = "BLOCKTYPE", Notes = "Returns the block type at the specified relative coords" }, GetRelBlockTypeMeta = { Params = "RelBlockX, RelBlockY, RelBlockZ", Return = "BLOCKTYPE, NIBBLETYPE", Notes = "Returns the block type and meta at the specified relative coords" }, - GetSize = { Params = "", Return = "SizeX, SizeY, SizeZ", Notes = "Returns the size of the area in all 3 axes." }, + GetSize = { Params = "", Return = "SizeX, SizeY, SizeZ", Notes = "Returns the size of the area in all 3 axes. See also GetCoordRange()." }, GetSizeX = { Params = "", Return = "number", Notes = "Returns the size of the held data in the x-axis" }, GetSizeY = { Params = "", Return = "number", Notes = "Returns the size of the held data in the y-axis" }, GetSizeZ = { Params = "", Return = "number", Notes = "Returns the size of the held data in the z-axis" }, -- cgit v1.2.3 From c335b8d77346541799b9c62e4fc78ef217cc4f63 Mon Sep 17 00:00:00 2001 From: Alexander Harkness Date: Wed, 11 Jun 2014 13:34:49 +0100 Subject: Update APIDesc.lua --- MCServer/Plugins/APIDump/APIDesc.lua | 1 + 1 file changed, 1 insertion(+) (limited to 'MCServer/Plugins') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 1f43a6172..8442f6d80 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2299,6 +2299,7 @@ end IsWeatherStorm = { Params = "", Return = "bool", Notes = "Returns true if the current world is stormy." }, IsWeatherStormAt = { Params = "BlockX, BlockZ", Return = "bool", Notes = "Returns true if the specified location is stormy (takes into account biomes)." }, IsWeatherSunny = { Params = "", Return = "bool", Notes = "Returns true if the current weather is sunny." }, + IsWeatherSunnyAt = { Params = "BlockX, BlockZ", Return = "bool", Notes = "Returns true if the current weather is sunny at the specified location (takes into account biomes)." }, IsWeatherWet = { Params = "", Return = "bool", Notes = "Returns true if the current world has any precipitation (rain or storm)." }, IsWeatherWetAt = { Params = "BlockX, BlockZ", Return = "bool", Notes = "Returns true if the specified location has any precipitation (rain or storm) (takes into account biomes)." }, QueueBlockForTick = { Params = "BlockX, BlockY, BlockZ, TicksToWait", Return = "", Notes = "Queues the specified block to be ticked after the specified number of gameticks." }, -- cgit v1.2.3 From 3e7384d9210b726a12ec6244aa0419474f08c6d3 Mon Sep 17 00:00:00 2001 From: Qais Patankar Date: Thu, 12 Jun 2014 15:01:24 +0100 Subject: Fix typo in handy_functions.lua --- MCServer/Plugins/Handy/handy_functions.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'MCServer/Plugins') diff --git a/MCServer/Plugins/Handy/handy_functions.lua b/MCServer/Plugins/Handy/handy_functions.lua index c142ffd08..af43f663a 100644 --- a/MCServer/Plugins/Handy/handy_functions.lua +++ b/MCServer/Plugins/Handy/handy_functions.lua @@ -6,7 +6,7 @@ function GetHandyVersion() return HANDY_VERSION end -- Checks if handy is in proper version -function CheckForRequiedVersion( inVersion ) +function CheckForRequiredVersion( inVersion ) if( inVersion > HANDY_VERSION ) then return false end return true end @@ -213,4 +213,4 @@ end function BoolToString( inValue ) if( inValue == true ) then return 1 end return 0 -end \ No newline at end of file +end -- cgit v1.2.3 From 72043f5b0cc2e930c2a616d84a8fea25f7224c59 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Fri, 13 Jun 2014 00:09:01 +0200 Subject: APIDump: Added the Info.lua article. Fixes #504. --- MCServer/Plugins/APIDump/APIDesc.lua | 1 + MCServer/Plugins/APIDump/InfoFile.html | 246 +++++++++++++++++++++++++++++++++ 2 files changed, 247 insertions(+) create mode 100644 MCServer/Plugins/APIDump/InfoFile.html (limited to 'MCServer/Plugins') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index c97e2dbf8..19ca971e2 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2934,6 +2934,7 @@ end { -- No sorting is provided for these, they will be output in the same order as defined here { FileName = "Writing-a-MCServer-plugin.html", Title = "Writing a MCServer plugin" }, + { FileName = "InfoFile.html", Title = "Using the Info.lua file" }, { FileName = "SettingUpDecoda.html", Title = "Setting up the Decoda Lua IDE" }, { FileName = "SettingUpZeroBrane.html", Title = "Setting up the ZeroBrane Studio Lua IDE" }, { FileName = "UsingChunkStays.html", Title = "Using ChunkStays" }, diff --git a/MCServer/Plugins/APIDump/InfoFile.html b/MCServer/Plugins/APIDump/InfoFile.html new file mode 100644 index 000000000..3fff06d20 --- /dev/null +++ b/MCServer/Plugins/APIDump/InfoFile.html @@ -0,0 +1,246 @@ + + + + MCServer - Info.lua file + + + + + + + +
+

Info.lua file

+

Contents

+ + + +
+

Introduction

 + +

For a long time MCServer plugins were plagued by poor documentation. The plugins worked, people who wrote them knew how to use them, but for anyone new to the plugin it was a terrible ordeal learning how to use it. Most of the times, the plugin authors only wrote what commands the plugin supported, sometimes not even that. Then, there was a call to action to put an end to this, to make documenting the plugins easy and at the same time centralized. Thus, the Info.lua file was born.

+ +

Most plugins have some parts that are the same across all the plugins. These are commands, console commands and their permissions. If a plugin implemented a command, it would practically copy & paste the same code over and over again. So it makes sense to extract only unique information, centralize it and automate all the parts around it. This was another reason for the Info.lua file - it is a central hub of commands, console commands and their permissions.

+ +

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.

+ +

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.

+ +

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.

+ + +
+

The overall structure

 + +

The file consist of a declaration of a single Lua table, g_PluginInfo. This table contains all the information, structured, as its members. Each member can be a structure by itself. The entire file is a valid Lua source file, so any tool that syntax-checks Lua source can syntax-check this file. The file is somewhat forward- and backward- compatible, in the sense that it can be extended in any way without breaking.

+

Here's a skeleton of the file:

+
+g_PluginInfo =
+{
+	Name = "Example Plugin",
+	Date = "2014-06-12",
+	Description = "This is an example plugin that shows how to use the Info.lua file",
+	
+	-- The following members will be documented in greater detail later:
+	AdditionalInformation = {},
+	Commands = {},
+	ConsoleCommands = {},
+	Permissions = {},
+}
+
+

As you can see, the structure is pretty straightforward. Note that the order of the elements inside the table is not important (Lua property).

+ +

The first few elements are for book-keeping. They declare the plugin's name, the date in ISO-format, representing the version of the plugin, and the description. The idea is that the description sums up what the plugin is all about, within some two or three sentences.

+ + +
+

AdditionalInformation table

 + +

This table is used for more detailed description of the plugin. If there is any non-trivial setup process, dependencies, describe them here. This is where the description should get detailed. Don't worry about using several paragraphs of text here, if it makes the plugin easier to understand.

+ +

The table should have the following layout:

+
+AdditionalInformation =
+{
+	{
+		Title = "Chapter 1",
+		Contents = "Describe one big aspect of the plugin here",
+	},
+	{
+		Title = "Chapter 2",
+		Contents = "Describe another big topic",
+	},
+}
+
+

The idea here is that the tool that is used to generate the documentation from the Info.lua file will create a linkified table of contents and then each of the information elements' contents. This information should be all that is needed to successfully configure, run and manage the plugin.

+ + +
+

Commands table

 + +

The commands table lists all the commands that the plugin implements, together with their handler functions, required permissions, help strings and further information. The table supports recursion, which allows plugins to create multi-word commands easily (such as "//schematic load" and "//schematic save"), each having its own separate handler.

+ +

The table uses structure similar to the following:

+
+Commands =
+{
+	["/cmd1"] =
+	{
+		HelpString = "Performs the first action",
+		Permission = "firstplugin.cmds.1",
+		Alias = "/c1",
+		Handler = HandleCmd1,
+		ParameterCombinations =
+		{
+			{
+				Params = "x y z",
+				Help = "Performs the first action at the specified coordinates",
+			},
+			{
+				Params = "-p",
+				Help = "Performs the first action at the player's coordinates",
+			}
+		},
+	},
+	["/cmd2"] =
+	{
+		Alias = {"/c2", "//c2" },
+		Subcommands =
+		{
+			sub1 =  -- This declares a "/cmd2 sub1" command
+			{
+				HelpString = "Performs the second action's first subcommand",
+				Permission = "firstplugin.cmds.2.1",
+				Alias = "1",
+				Handler = HandleCmd2Sub1,
+				ParameterCombinations =
+				{
+					{
+						Params = "x y z",
+						Help = "Performs the second action's first subcommand at the specified coordinates",
+					},
+					{
+						Params = "-p",
+						Help = "Performs the second action's first subcommand at the player's coordinates",
+					}
+				},
+			},
+			sub2 =  -- Declares a "/cmd2 sub2" command
+			{
+				HelpString = "Performs the second action's second subcommand",
+				Permission = "firstplugin.cmds.2.2",
+				Handler = HandleCmd2Sub2,
+			},
+		},
+	},
+}
+
+ +

Although it may seem overwhelming at first, there is a "method to this madness". Each element of the Commands table defines one command. Most commands start with a slash, so the special Lua syntax for table elements with non-standard names needs to be applied (["/cmd1"] =). The command can either specify subcommands, or a handler function (specifying both is UndefinedBehavior). Subcommands uses the same structure as the entire Commands table, recursively.

+ +

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.

+ +

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.

+ +

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.

+ + +
+

ConsoleCommands table

+ +

This table serves a purpose similar to that of the Commands table, only these commands are provided for the server console. Therefore, there are no permissions specified for these commands. Since most console commands don't use a leading slash, the command names don't need the special syntax. Also, the handler function doesn't receive the Player parameter.

+ +

Here's an example of a ConsoleCommands table:

+
+ConsoleCommands =
+{
+	concmd =
+	{
+		HelpString = "Performs the console action",
+		Subcommands =
+		{
+			sub1 =
+			{
+				HelpString = "Performs the console action's first subcommand",
+				Handler = HandleConCmdSub1,
+				ParameterCombinations =
+				{
+					{
+						Params = "x y z",
+						Help = "Performs the console action's first subcommand at the specified coordinates",
+					},
+				},
+			},
+			sub2 =
+			{
+				HelpString = "Performs the console action's second subcommand",
+				Handler = HandleConCmdSub2,
+			},
+		},
+	},
+}
+
+ + +
+

Permissions table

 + +

The purpose of this table is to document permissions that the plugin uses. The documentation generator automatically collects the permissions specified in the Command table; the Permissions table adds a description for these permissions and may declare other permissions that aren't specifically included in the Command table.

+ +
+Permissions =
+{
+	["firstplugin.cmd.1.1"] =
+	{
+		Description = "Allows the players to build high towers using the first action.",
+		RecommendedGroups = "players",
+	},
+	["firstplugin.cmd.2.1"] =
+	{
+		Description = "Allows the players to kill entities using the second action. Note that this may be misused to kill other players, too.",
+		RecommendedGroups = "admins, mods",
+	},
+}
+
+ +

The RecommendedGroup element lists, in plain English, the intended groups for which the permission should be enabled on a typical server. Plugin authors are advised to create reasonable defaults, prefering security to openness, so that admins using these settings blindly don't expose their servers to malicious users.

+ + +
+

Using the file in code

 + +

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:

+
+-- Use the InfoReg shared library to process the Info.lua file:
+dofile(cPluginManager:GetPluginsPath() .. "/InfoReg.lua")
+RegisterPluginInfoCommands()
+RegisterPluginInfoConsoleCommands()
+
+ +

Of course, if your plugin doesn't have any console commands, it doesn't need to call the RegisterPluginInfoConsoleCommands() function, and similarly if it doesn't have any in-game commands, it doesn't need to call the RegisterPluginInfoCommands() function.

+ + +
+

Examples

 + +

There are several plugins that already implement this approach. You can visit them for inspiration and to see what the generated documentation looks like:

+ + + +
+ + -- cgit v1.2.3 From b0f1707d50895d47634095592f68da63621f6507 Mon Sep 17 00:00:00 2001 From: STRWarrior Date: Fri, 13 Jun 2014 23:16:52 +0200 Subject: Fixed ChunkWorx stop button giving an error --- MCServer/Plugins/ChunkWorx/chunkworx_web.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'MCServer/Plugins') diff --git a/MCServer/Plugins/ChunkWorx/chunkworx_web.lua b/MCServer/Plugins/ChunkWorx/chunkworx_web.lua index 6c5eab676..9aec38b12 100644 --- a/MCServer/Plugins/ChunkWorx/chunkworx_web.lua +++ b/MCServer/Plugins/ChunkWorx/chunkworx_web.lua @@ -43,7 +43,7 @@ function HandleRequest_Generation( Request ) local Content = "" if (Request.PostParams["AGHRRRR"] ~= nil) then GENERATION_STATE = 0 - WW_instance:SaveAllChunks() + WW_instance:QueueSaveAllChunks() WW_instance:QueueUnloadUnusedChunks() LOGERROR("" .. PLUGIN:GetName() .. " v" .. PLUGIN:GetVersion() .. ": works ABORTED by admin") end -- cgit v1.2.3