From 9d7e638aa2f0aa2528c3bf230b791159a62354e6 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 09:00:28 +0200 Subject: APIDump: Documented HOOK_CHUNK_AVAILABLE. --- MCServer/Plugins/APIDump/APIDesc.lua | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index dc04d3e81..de25dd761 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2136,6 +2136,27 @@ end; the second value is not provided, the original message is used. ]], }, -- HOOK_CHAT + + HOOK_CHUNK_AVAILABLE = + { + CalledWhen = "A chunk has just been added to world, either generated or loaded. ", + DefaultFnName = "OnChunkAvailable", -- also used as pagename + Desc = [[ + This hook is called after a chunk is either generated or loaded from the disk. The chunk is + already available for manipulation using the {{cWorld}} API. This is a notification-only callback, + there is no behavior that plugins could override. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "The world to which the chunk belongs" }, + { Name = "ChunkX", Type = "number", Notes = "X-coord of the chunk" }, + { Name = "ChunkZ", Type = "number", Notes = "Z-coord of the chunk" }, + }, + 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_CHUNK_AVAILABLE }, -- Hooks[] -- cgit v1.2.3 From 26fbefdcbf55d881cc28d43da24192f5d4fb8e9f Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 09:03:54 +0200 Subject: APIDump: The undocumented hooks template now has 8 params. This allows for easier copypasting, hooks with less than 9 params don't need an extra copy-paste for a new param entry. --- MCServer/Plugins/APIDump/main.lua | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/main.lua b/MCServer/Plugins/APIDump/main.lua index 3827668e3..b4208d208 100644 --- a/MCServer/Plugins/APIDump/main.lua +++ b/MCServer/Plugins/APIDump/main.lua @@ -330,6 +330,13 @@ function DumpAPIHtml() f:write("\t\t\tDesc = [[]],\n"); f:write("\t\t\tParams =\n\t\t\t{\n"); f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); f:write("\t\t\tReturns = [[]],\n"); f:write("\t\t}, -- " .. hook .. "\n"); end -- cgit v1.2.3 From 23b4aa48201783dc26816d9df58c3cf66ce2737b Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 09:10:33 +0200 Subject: APIDump: Documented HOOK_CHUNK_GENERATED. --- MCServer/Plugins/APIDump/APIDesc.lua | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index de25dd761..03d90a8fb 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2157,6 +2157,32 @@ end; returns true, no other callback is called for this event. ]], }, -- HOOK_CHUNK_AVAILABLE + + HOOK_CHUNK_GENERATED = + { + CalledWhen = "After a chunk was generated. Notification only.", + DefaultFnName = "OnChunkGenerated", -- also used as pagename + Desc = [[ + This hook is called when world generator finished its work on a chunk. The chunk data has already + been generated and is about to be stored in the {{cWorld|world}}. A plugin may provide some + last-minute finishing touches to the generated data. Note that the chunk is not yet stored in the + world, so regular {{cWorld}} block API will not work! Instead, use the {{cChunkDesc}} object + received as the parameter. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "The world to which the chunk will be added" }, + { Name = "ChunkX", Type = "number", Notes = "X-coord of the chunk" }, + { Name = "ChunkZ", Type = "number", Notes = "Z-coord of the chunk" }, + { Name = "ChunkDesc", Type = "{{cChunkDesc}}", Notes = "Generated chunk data. Plugins may still modify the chunk data contained." }, + }, + Returns = [[ + If the plugin returns false or no value, MCServer will call other plugins' callbacks for this event. + If a plugin returns true, no other callback is called for this event.

+

+ In either case, MCServer will then store the data from ChunkDesc as the chunk's contents in the world. + ]], + }, -- HOOK_CHUNK_GENERATED }, -- Hooks[] -- cgit v1.2.3 From 8f5ed6511a958a1ed66cbbdfd5939f224475bb05 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 09:30:13 +0200 Subject: APIDump: Added example to HOOK_CHUNK_GENERATED. --- MCServer/Plugins/APIDump/APIDesc.lua | 37 ++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 03d90a8fb..586c3ae03 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2182,6 +2182,43 @@ end;

In either case, MCServer will then store the data from ChunkDesc as the chunk's contents in the world. ]], + CodeExamples = + { + { + Title = "Generate emerald ore", + Desc = "This example callback function generates one block of emerald ore in each chunk, under the condition that the randomly chosen location is in an ExtremeHills biome.", + Code = [[ +function OnChunkGenerated(a_World, a_ChunkX, a_ChunkZ, a_ChunkDesc) + -- Generate a psaudorandom value that is always the same for the same X/Z pair, but is otherwise random enough: + -- This is actually similar to how MCServer does its noise functions + local PseudoRandom = (a_ChunkX * 57 + a_ChunkZ) * 57 + 19785486 + PseudoRandom = PseudoRandom * 8192 + PseudoRandom; + PseudoRandom = ((PseudoRandom * (PseudoRandom * PseudoRandom * 15731 + 789221) + 1376312589) % 0x7fffffff; + PseudoRandom = PseudoRandom / 7; + + -- Based on the PseudoRandom value, choose a location for the ore: + local OreX = PseudoRandom % 16; + local OreY = 2 + ((PseudoRandom / 16) % 20); + local OreZ = (PseudoRandom / 320) % 16; + + -- Check if the location is in ExtremeHills: + if (a_ChunkDesc:GetBiome(OreX, OreZ) ~= biExtremeHills) then + return false; + end + + -- Only replace allowed blocks with the ore: + local CurrBlock = a_ChunDesc:GetBlockType(OreX, OreY, OreZ); + if ( + (CurrBlock == E_BLOCK_STONE) or + (CurrBlock == E_BLOCK_DIRT) or + (CurrBlock == E_BLOCK_GRAVEL) + ) then + a_ChunkDesc:SetBlockTypeMeta(OreX, OreY, OreZ, E_BLOCK_EMERALD_ORE, 0); + end +end; + ]], + }, + } , -- CodeExamples }, -- HOOK_CHUNK_GENERATED }, -- Hooks[] -- cgit v1.2.3 From 42b65c164d0979494dd7bfea214434f912c2f4e3 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 09:32:55 +0200 Subject: APIDump: Fixed undocumented hook param generator. --- MCServer/Plugins/APIDump/main.lua | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/main.lua b/MCServer/Plugins/APIDump/main.lua index b4208d208..87583be0e 100644 --- a/MCServer/Plugins/APIDump/main.lua +++ b/MCServer/Plugins/APIDump/main.lua @@ -329,14 +329,15 @@ function DumpAPIHtml() f:write("\t\t\tDefaultFnName = \"On\", -- also used as pagename\n"); f:write("\t\t\tDesc = [[]],\n"); f:write("\t\t\tParams =\n\t\t\t{\n"); - f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); - f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); - f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); - f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); - f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); - f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); - f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); - f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n"); + f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n"); + f:write("\t\t\t},\n"); f:write("\t\t\tReturns = [[]],\n"); f:write("\t\t}, -- " .. hook .. "\n"); end -- cgit v1.2.3 From fb209757f0ad3c19f2925af00ac323236fd86741 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 09:41:06 +0200 Subject: APIDump: Documented HOOK_CHUNK_GENERATING. --- MCServer/Plugins/APIDump/APIDesc.lua | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 586c3ae03..578d6aeab 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2167,7 +2167,9 @@ end; been generated and is about to be stored in the {{cWorld|world}}. A plugin may provide some last-minute finishing touches to the generated data. Note that the chunk is not yet stored in the world, so regular {{cWorld}} block API will not work! Instead, use the {{cChunkDesc}} object - received as the parameter. + received as the parameter.

+

+ See also the {{OnChunkGenerating|HOOK_CHUNK_GENERATING}} hook. ]], Params = { @@ -2220,6 +2222,36 @@ end; }, } , -- CodeExamples }, -- HOOK_CHUNK_GENERATED + + HOOK_CHUNK_GENERATING = + { + CalledWhen = "A chunk is about to be generated. Plugin can override the built-in generator.", + DefaultFnName = "OnChunkGenerating", -- also used as pagename + Desc = [[ + This hook is called before the world generator starts generating a chunk. The plugin may provide + some or all parts of the generation, by-passing the built-in generator. The function is given access + to the {{cChunkDesc|ChunkDesc}} object representing the contents of the chunk. It may override parts + of the built-in generator by using the object's SetUseDefaultXXX(false) functions. After all + the callbacks for a chunk have been processed, the server will generate the chunk based on the + {{cChunkDesc|ChunkDesc}} description - those parts that are set for generating (by default + everything) are generated, the rest are read from the ChunkDesc object.

+

+ See also the {{OnChunkGenerated|HOOK_CHUNK_GENERATED}} hook. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "The world to which the chunk will be added" }, + { Name = "ChunkX", Type = "number", Notes = "X-coord of the chunk" }, + { Name = "ChunkZ", Type = "number", Notes = "Z-coord of the chunk" }, + { Name = "ChunkDesc", Type = "{{cChunkDesc}}", Notes = "Generated chunk data." }, + }, + Returns = [[ + If this function returns true, the server will not call any other plugin with the same chunk. If + this function returns false, the server will call the rest of the plugins with the same chunk, + possibly overwriting the ChunkDesc's contents. + ]], + }, -- HOOK_CHUNK_GENERATING + }, -- Hooks[] -- cgit v1.2.3 From 37ea7ec0c1e9b278a53d0cc1485e216099ea1eee Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 15:46:01 +0200 Subject: APIDump: Documented HOOK_CHUNK_UNLOADED. --- MCServer/Plugins/APIDump/APIDesc.lua | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 578d6aeab..6be0b6887 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2252,6 +2252,28 @@ end; ]], }, -- HOOK_CHUNK_GENERATING + HOOK_CHUNK_UNLOADED = + { + CalledWhen = "A chunk has been unloaded from the memory.", + DefaultFnName = "OnChunkUnloaded", -- also used as pagename + Desc = [[ + This hook is called when a chunk is unloaded from the memory. Though technically still in memory, + the plugin should behave as if the chunk was already not present. In particular, {{cWorld}} block + API should not be used in the area of the specified chunk. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "The world from which the chunk is unloading" }, + { Name = "ChunkX", Type = "number", Notes = "X-coord of the chunk" }, + { Name = "ChunkZ", Type = "number", Notes = "Z-coord of the chunk" }, + }, + 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. There is no behavior that plugins could + override. + ]], + }, -- HOOK_CHUNK_UNLOADED + }, -- Hooks[] -- cgit v1.2.3 From 0b71b3bd141816869eb19b3a9841a8d16f5e4be9 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 15:50:11 +0200 Subject: APIDump: Documented HOOK_CHUNK_UNLOADING. --- MCServer/Plugins/APIDump/APIDesc.lua | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 6be0b6887..013b3c69e 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2274,6 +2274,29 @@ end; ]], }, -- HOOK_CHUNK_UNLOADED + HOOK_CHUNK_UNLOADING = + { + CalledWhen = " A chunk is about to be unloaded from the memory. Plugins may refuse the unload.", + DefaultFnName = "OnChunkUnloading", -- also used as pagename + Desc = [[ + MCServer calls this function when a chunk is about to be unloaded from the memory. A plugin may + force MCServer to keep the chunk in memory by returning true.

+

+ FIXME: The return value should be used only for event propagation stopping, not for the actual + decision whether to unload. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "The world from which the chunk is unloading" }, + { Name = "ChunkX", Type = "number", Notes = "X-coord of the chunk" }, + { Name = "ChunkZ", Type = "number", Notes = "Z-coord of the chunk" }, + }, + Returns = [[ + If the function returns false or no value, the next plugin's callback is called and finally MCServer + unloads the chunk. If the function returns true, no other callback is called for this event and the + chunk is left in the memory. + ]], + }, -- HOOK_CHUNK_UNLOADING }, -- Hooks[] -- cgit v1.2.3 From c8702e15bbced0a655d08761ea9173950445238c Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 15:53:41 +0200 Subject: APIDump: Documented HOOK_COLLECTING_PICKUP. --- MCServer/Plugins/APIDump/APIDesc.lua | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 013b3c69e..6044b0a0a 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2297,6 +2297,33 @@ end; chunk is left in the memory. ]], }, -- HOOK_CHUNK_UNLOADING + + HOOK_COLLECTING_PICKUP = + { + CalledWhen = "Player is about to collect a pickup. Plugin can refuse / override behavior. ", + DefaultFnName = "OnCollectingPickup", -- also used as pagename + Desc = [[ + This hook is called when a player is about to collect a pickup. Plugins may refuse the action.

+

+ Pickup collection happens within the world tick, so if the collecting is refused, it will be tried + again in the next world tick, as long as the player is within reach of the pickup.

+

+ FIXME: There is no OnCollectedPickup() callback.

+

+ FIXME: This callback is called even if the pickup doesn't fit into the player's inventory.

+ ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who's collecting the pickup" }, + { Name = "Pickup", Type = "{{cPickup}}", Notes = "The pickup being collected" }, + }, + Returns = [[ + If the function returns false or no value, MCServer calls other plugins' callbacks and finally the + pickup is collected. If the function returns true, no other plugins are called for this event and + the pickup is not collected. + ]], + }, -- HOOK_COLLECTING_PICKUP + }, -- Hooks[] -- cgit v1.2.3 From f546a0e180cf153ed53ea0fc083f7954901e15e6 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 16:02:32 +0200 Subject: APIDump: Documented HOOK_CRAFTING_NO_RECIPE. --- MCServer/Plugins/APIDump/APIDesc.lua | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 6044b0a0a..adc3a9835 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2324,6 +2324,32 @@ end; ]], }, -- HOOK_COLLECTING_PICKUP + HOOK_CRAFTING_NO_RECIPE = + { + CalledWhen = " No built-in crafting recipe is found. Plugin may provide a recipe.", + DefaultFnName = "OnCraftingNoRecipe", -- also used as pagename + Desc = [[ + This callback is called when a player places items in their {{cCraftingGrid|crafting grid}} and + MCServer cannot find a built-in {{cCraftingRecipe|recipe}} for the combination. Plugins may provide + a recipe for the ingredients given. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player whose crafting is reported in this hook" }, + { Name = "Grid", Type = "{{cCraftingGrid}}", Notes = "Contents of the player's crafting grid" }, + { Name = "Recipe", Type = "{{cCraftingRecipe}}", Notes = "The recipe that will be used (can be filled by plugins)" }, + }, + Returns = [[ + If the function returns false or no value, no recipe will be used. If the function returns true, no + other plugin will have their callback called for this event and MCServer will use the crafting + recipe in Recipe.

+

+ FIXME: To allow plugins give suggestions and overwrite other plugins' suggestions, we should change + the behavior with returning false, so that the recipe will still be used, but fill the recipe with + empty values by default. + ]], + }, -- HOOK_CRAFTING_NO_RECIPE + }, -- Hooks[] -- cgit v1.2.3 From ca285563d95d34ab8c9c57b9de948216c073d6c2 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 16:04:43 +0200 Subject: APIDump: Fixed info missing from cCraftingRecipe. --- MCServer/Plugins/APIDump/APIDesc.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index adc3a9835..35d50a861 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -546,7 +546,7 @@ World:ForEachChestInChunk(Player:GetChunkX(), Player:GetChunkZ(), Desc = [[ This class is used to represent a crafting recipe, either a built-in one, or one created dynamically in a plugin. It is used only as a parameter for {{OnCraftingNoRecipe|OnCraftingNoRecipe}}, {{OnPostCrafting|OnPostCrafting}} and {{OnPreCrafting|OnPreCrafting}} hooks. Plugins may use it to inspect or modify a crafting recipe that a player views in their crafting window, either at a crafting table or the survival inventory screen.

-

Internally, the class contains a {{cItem|cItem}} for the result. +

Internally, the class contains a {{cCraftingGrid}} for the ingredients and a {{cItem}} for the result. ]], Functions = { -- cgit v1.2.3 From 56bc94139d1982ec2a3f779bd8d66eab64ddca1c Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 16:12:32 +0200 Subject: APIDump: Documented HOOK_DISCONNECT. --- MCServer/Plugins/APIDump/APIDesc.lua | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 35d50a861..7530c3857 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2350,6 +2350,32 @@ end; ]], }, -- HOOK_CRAFTING_NO_RECIPE + HOOK_DISCONNECT = + { + CalledWhen = "A player has explicitly disconnected.", + DefaultFnName = "OnDisconnect", -- also used as pagename + Desc = [[ + This hook is called when a client sends the disconnect packet and is about to be disconnected from + the server.

+

+ Note that this callback is not called if the client drops the connection or is kicked by the + server.

+

+ FIXME: There is no callback for "client destroying" that would be called in all circumstances.

+ ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who has disconnected" }, + { Name = "Reason", Type = "string", Notes = "The reason that the client has sent in the disconnect packet" }, + }, + Returns = [[ + If the function returns false or no value, MCServer calls other plugins' callbacks for this event + and finally broadcasts a disconnect message to the player's world. If the function returns true, no + other plugins are called for this event and the disconnect message is not broadcast. In either case, + the player is disconnected. + ]], + }, -- HOOK_DISCONNECT + }, -- Hooks[] -- cgit v1.2.3 From 66d8c1b3067efc2893b9db3cc434cadc769382cc Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 16:13:39 +0200 Subject: APIDump: Updated the template for undocumented hooks. --- MCServer/Plugins/APIDump/main.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/main.lua b/MCServer/Plugins/APIDump/main.lua index 87583be0e..8c07144f2 100644 --- a/MCServer/Plugins/APIDump/main.lua +++ b/MCServer/Plugins/APIDump/main.lua @@ -327,7 +327,7 @@ function DumpAPIHtml() f:write("\t\t" .. hook .. " =\n\t\t{\n"); f:write("\t\t\tCalledWhen = \"\",\n"); f:write("\t\t\tDefaultFnName = \"On\", -- also used as pagename\n"); - f:write("\t\t\tDesc = [[]],\n"); + f:write("\t\t\tDesc = [[\n\t\t\t\t\n\t\t\t]],\n"); f:write("\t\t\tParams =\n\t\t\t{\n"); f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n"); f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n"); @@ -338,7 +338,7 @@ function DumpAPIHtml() f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n"); f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n"); f:write("\t\t\t},\n"); - f:write("\t\t\tReturns = [[]],\n"); + f:write("\t\t\tReturns = [[\n\t\t\t\t\n\t\t\t]],\n"); f:write("\t\t}, -- " .. hook .. "\n"); end end -- cgit v1.2.3 From 112e96ae9b17156cb18192421728a538ed0c51e4 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 16:20:32 +0200 Subject: APIDump: Documented HOOK_EXECUTE_COMMAND. --- MCServer/Plugins/APIDump/APIDesc.lua | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 7530c3857..e49c09ec8 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2376,6 +2376,31 @@ end; ]], }, -- HOOK_DISCONNECT + 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.", + 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 + players and console commands executed by the server admin. The function is called for every in-game + command sent from any player and for those server console commands that are not built in in the + server.

+

+ 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. + ]], + 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" }, + }, + 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. + ]], + }, -- HOOK_EXECUTE_COMMAND + }, -- Hooks[] -- cgit v1.2.3 From 211b03a87082c3a99c171326afd79163274d663c Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 16:43:39 +0200 Subject: APIDump: Documented HOOK_EXPLODED. --- MCServer/Plugins/APIDump/APIDesc.lua | 43 ++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index e49c09ec8..0ef93b400 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2401,6 +2401,49 @@ end; ]], }, -- HOOK_EXECUTE_COMMAND + HOOK_EXPLODED = + { + CalledWhen = "An explosion has happened", + DefaultFnName = "OnExploded", -- also used as pagename + Desc = [[ + This hook is called after an explosion has been processed in a world.

+

+ See also {{OnHookExploding|HOOK_EXPLODING}} for a similar hook called before the explosion.

+

+ The explosion carries with it the type of its source - whether it's a creeper exploding, or TNT, + etc. It also carries the identification of the actual source. The exact type of the identification + depends on the source kind: + + + + + + + + + + + + +
SourceSourceData TypeNotes
esPrimedTNT{{cTNTEntity}}An exploding primed TNT entity
esCreeper{{cCreeper}}An exploding creeper or charged creeper
esBed{{Vector3i}}A bed exploding in the Nether or in the End. The bed coords are given.
esEnderCrystal{{Vector3i}}An ender crystal exploding upon hit. The block coords are given.
esGhastFireball{{cGhastFireballEntity}}A ghast fireball hitting ground or an {{cEntity|entity}}.
esWitherSkullBlackTBDA black wither skull hitting ground or an {{cEntity|entity}}.
esWitherSkullBlueTBDA blue wither skull hitting ground or an {{cEntity|entity}}.
esWitherBirthTBDA wither boss being created
esOtherTBDAny other previously unspecified type.
esPluginobjectAn explosion created by a plugin. The plugin may specify any kind of data.

+ ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "The world where the explosion happened" }, + { Name = "ExplosionSize", Type = "number", Notes = "The relative explosion size" }, + { Name = "CanCauseFire", Type = "bool", Notes = "True if the explosion has turned random air blocks to fire (such as a ghast fireball)" }, + { Name = "X", Type = "number", Notes = "X-coord of the explosion center" }, + { Name = "Y", Type = "number", Notes = "Y-coord of the explosion center" }, + { Name = "Z", Type = "number", Notes = "Z-coord of the explosion center" }, + { Name = "Source", Type = "eExplosionSource", Notes = "Source of the explosion. See the table above." }, + { Name = "SourceData", Type = "varies", Notes = "Additional data for the source. The exact type varies by the source. See the table above." }, + }, + 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. There is no overridable behaviour. + ]], + }, -- HOOK_EXPLODED + }, -- Hooks[] -- cgit v1.2.3 From c360849fa0fe016adb8186f09a862090b3858b06 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 16:53:13 +0200 Subject: APIDump: Documented HOOK_EXPLODING. --- MCServer/Plugins/APIDump/APIDesc.lua | 44 ++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 0ef93b400..871b04543 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2444,6 +2444,50 @@ end; ]], }, -- HOOK_EXPLODED + HOOK_EXPLODING = + { + CalledWhen = "An explosion is about to be processed", + DefaultFnName = "OnExploding", -- also used as pagename + Desc = [[ + This hook is called before an explosion has been processed in a world.

+

+ See also {{OnHookExploded|HOOK_EXPLODED}} for a similar hook called after the explosion.

+

+ The explosion carries with it the type of its source - whether it's a creeper exploding, or TNT, + etc. It also carries the identification of the actual source. The exact type of the identification + depends on the source kind: + + + + + + + + + + + + +
SourceSourceData TypeNotes
esPrimedTNT{{cTNTEntity}}An exploding primed TNT entity
esCreeper{{cCreeper}}An exploding creeper or charged creeper
esBed{{Vector3i}}A bed exploding in the Nether or in the End. The bed coords are given.
esEnderCrystal{{Vector3i}}An ender crystal exploding upon hit. The block coords are given.
esGhastFireball{{cGhastFireballEntity}}A ghast fireball hitting ground or an {{cEntity|entity}}.
esWitherSkullBlackTBDA black wither skull hitting ground or an {{cEntity|entity}}.
esWitherSkullBlueTBDA blue wither skull hitting ground or an {{cEntity|entity}}.
esWitherBirthTBDA wither boss being created
esOtherTBDAny other previously unspecified type.
esPluginobjectAn explosion created by a plugin. The plugin may specify any kind of data.

+ ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "The world where the explosion happens" }, + { Name = "ExplosionSize", Type = "number", Notes = "The relative explosion size" }, + { Name = "CanCauseFire", Type = "bool", Notes = "True if the explosion will turn random air blocks to fire (such as a ghast fireball)" }, + { Name = "X", Type = "number", Notes = "X-coord of the explosion center" }, + { Name = "Y", Type = "number", Notes = "Y-coord of the explosion center" }, + { Name = "Z", Type = "number", Notes = "Z-coord of the explosion center" }, + { Name = "Source", Type = "eExplosionSource", Notes = "Source of the explosion. See the table above." }, + { Name = "SourceData", Type = "varies", Notes = "Additional data for the source. The exact type varies by the source. See the table above." }, + }, + Returns = [[ + If the function returns false or no value, the next plugin's callback is called, and finally + MCServer will process the explosion - destroy blocks and push + hurt entities. If the function + returns true, no other callback is called for this event and the explosion will not occur. + ]], + }, -- HOOK_EXPLODING + }, -- Hooks[] -- cgit v1.2.3 From 5c24d5acd7adcfa5a0bd121275f54b7d67505afb Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 16:59:45 +0200 Subject: APIDump: Documented HOOK_HANDSHAKE. --- MCServer/Plugins/APIDump/APIDesc.lua | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 871b04543..12665888b 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2488,6 +2488,29 @@ end; ]], }, -- HOOK_EXPLODING + HOOK_HANDSHAKE = + { + CalledWhen = "A client is connecting.", + DefaultFnName = "OnHandshake", -- also used as pagename + Desc = [[ + This hook is called when a client sends the Handshake packet. At this stage, only the client IP and + (unverified) username are known. Plugins may refuse access to the server based on this + information.

+

+ Note that the username is not authenticated - the authentication takes place only after this hook is + processed. + ]], + Params = + { + { Name = "Client", Type = "{{cClientHandle}}", Notes = "The client handle representing the connection. Note that there's no {{cPlayer}} object for this client yet." }, + { Name = "UserName", Type = "string", Notes = "The username presented in the packet. Note that this username is unverified." }, + }, + Returns = [[ + If the function returns false, the user is let in to the server. If the function returns true, no + other plugin's callback is called, the user is kicked and the connection is closed. + ]], + }, -- HOOK_HANDSHAKE + }, -- Hooks[] -- cgit v1.2.3 From 626c52929c3064c2864a1115828ba715a1f8b6df Mon Sep 17 00:00:00 2001 From: tonibm19 Date: Mon, 14 Oct 2013 17:02:11 +0200 Subject: Stairs crafting fixes Fixes #233 Added Stone Brick Stairs crafting recipe and added alternative crafting recipes for Nether Brick Stairs and Quartz Stairs --- MCServer/crafting.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'MCServer') diff --git a/MCServer/crafting.txt b/MCServer/crafting.txt index 6140ca3a6..0e3c48d70 100644 --- a/MCServer/crafting.txt +++ b/MCServer/crafting.txt @@ -1,4 +1,3 @@ - # This file describes the crafting recipes that MCServer knows. # The syntax is as follows: # = # @@ -96,7 +95,11 @@ BrickStairs, 4 = BrickBlock, 3:1, 2:2, 3:2, 1:3, 2:3, 3:3 SandstoneStairs, 4 = Sandstone, 1:1, 1:2, 2:2, 1:3, 2:3, 3:3 SandstoneStairs, 4 = Sandstone, 3:1, 2:2, 3:2, 1:3, 2:3, 3:3 NetherBrickStairs, 4 = NetherBrick, 1:1, 1:2, 2:2, 1:3, 2:3, 3:3 +NetherBrickStairs, 4 = NetherBrick, 3:1, 2:2, 3:2, 1:3, 2:3, 3:3 quartzstairs, 4 = QuartzBlock, 1:1, 1:2, 2:2, 1:3, 2:3, 3:3 +quartzstairs, 4 = QuartzBlock, 3:1, 2:2, 3:2, 1:3, 2:3, 3:3 +StoneBrickStairs, 4 = StoneBrick, 1:1, 1:2, 2:2, 1:3, 2:3, 3:3 +StoneBrickStairs, 4 = StoneBrick, 3:1, 2:2, 3:2, 1:3, 2:3, 3:3 SnowBlock = SnowBall, 1:1, 1:2, 2:1, 2:2 ClayBlock = Clay, 1:1, 1:2, 2:1, 2:2 BrickBlock = Brick, 1:1, 1:2, 2:1, 2:2 -- cgit v1.2.3 From bf5f4603d9447816ed89cbe1ddfd51f97bb67f9d Mon Sep 17 00:00:00 2001 From: Alexander Harkness Date: Mon, 14 Oct 2013 16:57:57 +0100 Subject: Add the first line back. --- MCServer/crafting.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'MCServer') diff --git a/MCServer/crafting.txt b/MCServer/crafting.txt index 0e3c48d70..5132bf436 100644 --- a/MCServer/crafting.txt +++ b/MCServer/crafting.txt @@ -1,3 +1,4 @@ + # This file describes the crafting recipes that MCServer knows. # The syntax is as follows: # = # -- cgit v1.2.3 From 9969c1906016d2cb1a7e856fca72d16ec54c3687 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 21:15:55 +0200 Subject: APIDump: Documented HOOK_HOPPER_PULLING_ITEM. --- MCServer/Plugins/APIDump/APIDesc.lua | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 12665888b..6b0ce9abb 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2511,6 +2511,29 @@ end; ]], }, -- HOOK_HANDSHAKE + HOOK_HOPPER_PULLING_ITEM = + { + CalledWhen = "A hopper is pulling an item from another block entity.", + DefaultFnName = "OnHopperPullingItem", -- also used as pagename + Desc = [[ + This callback is called whenever a hopper transfers an item from another block item into its own + internal storage. A plugin may decide to disallow the move by returning true. Note that in such a + case, the hook may be called again for the same hopper, with different slot numbers. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "World where the hopper resides" }, + { Name = "Hopper", Type = "{{cHopperEntity}}", Notes = "The hopper that is pulling the item" }, + { Name = "DstSlot", Type = "number", Notes = "The destination slot in the hopper's {{cItemGrid|internal storage}}" }, + { Name = "SrcBlockEntity", Type = "{{cBlockEntityWithItems}}", Notes = "The block entity that is losing the item" }, + { Name = "SrcSlot", Type = "number", Notes = "Slot in SrcBlockEntity from which the item will be pulled" }, + }, + 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 and the hopper will not pull the item. + ]], + }, -- HOOK_HOPPER_PULLING_ITEM + }, -- Hooks[] -- cgit v1.2.3 From 315af4450d8d7c4b746652eaa92347a3f5775da7 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 21:45:08 +0200 Subject: APIDump: Documented HOOK_HOPPER_PUSHING_ITEM. --- MCServer/Plugins/APIDump/APIDesc.lua | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 6b0ce9abb..69fcd6eb1 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2516,9 +2516,10 @@ end; CalledWhen = "A hopper is pulling an item from another block entity.", DefaultFnName = "OnHopperPullingItem", -- also used as pagename Desc = [[ - This callback is called whenever a hopper transfers an item from another block item into its own - internal storage. A plugin may decide to disallow the move by returning true. Note that in such a - case, the hook may be called again for the same hopper, with different slot numbers. + This callback is called whenever a {{cHopperEntity|hopper}} transfers an {{cItem|item}} from another + block entity into its own internal storage. A plugin may decide to disallow the move by returning + true. Note that in such a case, the hook may be called again for the same hopper, with different + slot numbers. ]], Params = { @@ -2534,6 +2535,30 @@ end; ]], }, -- HOOK_HOPPER_PULLING_ITEM + HOOK_HOPPER_PUSHING_ITEM = + { + CalledWhen = "A hopper is pushing an item into another block entity. ", + DefaultFnName = "OnHopperPushingItem", -- also used as pagename + Desc = [[ + This hook is called whenever a {{cHopperEntity|hopper}} transfers an {{cItem|item}} from its own + internal storage into another block entity. A plugin may decide to disallow the move by returning + true. Note that in such a case, the hook may be called again for the same hopper and block, with + different slot numbers. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "World where the hopper resides" }, + { Name = "Hopper", Type = "{{cHopperEntity}}", Notes = "The hopper that is pushing the item" }, + { Name = "SrcSlot", Type = "number", Notes = "Slot in the hopper that will lose the item" }, + { Name = "DstBlockEntity", Type = "{{cBlockEntityWithItems}}", Notes = " The block entity that will receive the item" }, + { Name = "DstSlot", Type = "number", Notes = " Slot in DstBlockEntity's internal storage where the item will be stored" }, + }, + 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 and the hopper will not push the item. + ]], + }, -- HOOK_HOPPER_PUSHING_ITEM + }, -- Hooks[] -- cgit v1.2.3 From a632f1d579298b2e0222b5f8ce6608c9b062dac4 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 21:45:47 +0200 Subject: APIDump: Documented HOOK_KILLING. --- MCServer/Plugins/APIDump/APIDesc.lua | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 69fcd6eb1..4ea95b4da 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2559,6 +2559,33 @@ end; ]], }, -- HOOK_HOPPER_PUSHING_ITEM + HOOK_KILLING = + { + CalledWhen = "A player or a mob is dying.", + DefaultFnName = "OnKilling", -- also used as pagename + Desc = [[ + This hook is called whenever a {{cPawn|pawn}}'s (a player's or a mob's) health reaches zero. This + means that the pawn is about to be killed, unless a plugin "revives" them by setting their health + back to a positive value.

+

+ FIXME: There is no HOOK_KILLED notification hook yet; this is deliberate because HOOK_KILLED has + been recently renamed to HOOK_KILLING, and plugins need to be updated. Once updated, the HOOK_KILLED + notification will be implemented. + ]], + Params = + { + { Name = "Victim", Type = "{{cPawn}}", Notes = "The player or mob that is about to be killed" }, + { Name = "Killer", Type = "{{cEntity}}", Notes = "The entity that has caused the victim to lose the last point of health. May be nil for environment damage" }, + }, + Returns = [[ + If the function returns false or no value, MCServer calls other plugins with this event. If the + function returns true, no other plugin is called for this event.

+

+ In either case, the victim's health is then re-checked and if it is greater than zero, the victim is + "revived" with that health amount. If the health is less or equal to zero, the victim is killed. + ]], + }, -- HOOK_KILLING + }, -- Hooks[] -- cgit v1.2.3 From 862397856d4f42861b9b8bb4560e907310ce6fd8 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 21:46:25 +0200 Subject: APIDump: Documented HOOK_LOGIN. --- MCServer/Plugins/APIDump/APIDesc.lua | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 4ea95b4da..3c9ee9421 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2586,6 +2586,31 @@ end; ]], }, -- HOOK_KILLING + HOOK_LOGIN = + { + CalledWhen = "Right after player authentication. If auth is disabled, right after the player sends their name.", + DefaultFnName = "OnLogin", -- also used as pagename + Desc = [[ + This hook is called whenever a client logs in. It is called right before the client's name is sent + to be authenticated. Plugins may refuse the client from accessing the server. Note that when this + callback is called, the {{cPlayer}} object for this client doesn't exist yet - the client has no + representation in any world. To process new players when their world is known, use a later callback, + such as {{OnPlayerJoined|HOOK_PLAYER_JOINED}} or {{OnPlayerSpawned|HOOK_PLAYER_SPAWNED}}. + ]], + Params = + { + { Name = "Client", Type = "{{cClientHandle}}", Notes = "The client handle representing the connection" }, + { Name = "ProtocolVersion", Type = "number", Notes = "Versio of the protocol that the client is talking" }, + { Name = "UserName", Type = "string", Notes = "The name that the client has presented for authentication. This name will be given to the {{cPlayer}} object when it is created for this client." }, + }, + Returns = [[ + If the function returns true, no other plugins are called for this event and the client is kicked. + If the function returns false or no value, MCServer calls other plugins' callbacks and finally + sends an authentication request for the client's username to the auth server. If the auth server + is disabled in the server settings, the player object is immediately created. + ]], + }, -- HOOK_LOGIN + }, -- Hooks[] -- cgit v1.2.3 From e4bb796c6b03374ef5fcf02acee710900cacb5bb Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 21:57:23 +0200 Subject: APIDump: Removed HOOK_MAX and HOOK_NUM_HOOKS from documentation. They're not really hooks, just constants for the maximum. --- MCServer/Plugins/APIDump/main.lua | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/main.lua b/MCServer/Plugins/APIDump/main.lua index 8c07144f2..6ae4a6b0f 100644 --- a/MCServer/Plugins/APIDump/main.lua +++ b/MCServer/Plugins/APIDump/main.lua @@ -180,7 +180,12 @@ function DumpAPIHtml() -- Extract hook constants: for name, obj in pairs(cPluginManager) do - if (type(obj) == "number") and (name:match("HOOK_.*")) then + if ( + (type(obj) == "number") and + name:match("HOOK_.*") and + (name ~= "HOOK_MAX") and + (name ~= "HOOK_NUM_HOOKS") + ) then table.insert(Hooks, { Name = name }); end end -- cgit v1.2.3 From d34fa4970ac56c3624654f148faafce096243fe7 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 14 Oct 2013 22:01:10 +0200 Subject: APIDump: Documented HOOK_PLAYER_ANIMATION. --- MCServer/Plugins/APIDump/APIDesc.lua | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 3c9ee9421..e7ed25cdc 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2611,6 +2611,27 @@ end; ]], }, -- HOOK_LOGIN + HOOK_PLAYER_ANIMATION = + { + CalledWhen = "A client has sent an Animation packet (0x12)", + DefaultFnName = "OnPlayerAnimation", -- also used as pagename + Desc = [[ + This hook is called when the server receives an Animation packet (0x12) from the client.

+

+ For the list of animations that are sent by the client, see the + Protocol wiki. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player from whom the packet was received" }, + { Name = "Animation", Type = "number", Notes = "The kind of animation" }, + }, + Returns = [[ + If the function returns false or no value, the next plugin's callback is called. Afterwards, the + server broadcasts the animation packet to all nearby clients. If the function returns true, no other + callback is called for this event and the packet is not broadcasted. + ]], + }, -- HOOK_PLAYER_ANIMATION }, -- Hooks[] -- cgit v1.2.3 From 5e71b3011623a47167e555259259cde026817099 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Tue, 15 Oct 2013 08:03:46 +0200 Subject: APIDump: Documented HOOK_PLAYER_BREAKING_BLOCK. --- MCServer/Plugins/APIDump/APIDesc.lua | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index e7ed25cdc..af4818755 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2632,6 +2632,36 @@ end; callback is called for this event and the packet is not broadcasted. ]], }, -- HOOK_PLAYER_ANIMATION + + HOOK_PLAYER_BREAKING_BLOCK = + { + CalledWhen = "Just before a player breaks a block. Plugin may override / refuse. ", + DefaultFnName = "OnPlayerBreakingBlock", -- also used as pagename + Desc = [[ + This hook is called when a {{cPlayer|player}} breaks a block, before the block is actually broken in + the {{cWorld|World}}. Plugins may refuse the breaking. + + See also the {{OnPlayerBrokenBlock|HOOK_PLAYER_BROKEN_BLOCK}} hook for a similar hook called after + the block is broken. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who is digging the block" }, + { Name = "BlockX", Type = "number", Notes = "X-coord of the block" }, + { Name = "BlockY", Type = "number", Notes = "Y-coord of the block" }, + { Name = "BlockZ", Type = "number", Notes = "Z-coord of the block" }, + { Name = "BlockFace", Type = "number", Notes = "Face of the block upon which the player is acting. One of the BLOCK_FACE_ constants" }, + { Name = "BlockType", Type = "BLOCKTYPE", Notes = "The block type of the block being broken" }, + { Name = "BlockMeta", Type = "NIBBLETYPE", Notes = "The block meta of the block being broken " }, + }, + Returns = [[ + If the function returns false or no value, other plugins' callbacks are called, and then the block + is broken. If the function returns true, no other plugin's callback is called and the block breaking + is cancelled. The server re-sends the block back to the player to replace it (the player's client + already thinks the block was broken). + ]], + }, -- HOOK_PLAYER_BREAKING_BLOCK + }, -- Hooks[] -- cgit v1.2.3 From eb466334adaac7ee6ff6c1993e4969739ae28b6d Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Tue, 15 Oct 2013 08:11:01 +0200 Subject: APIDump: Documented HOOK_PLAYER_BROKEN_BLOCK. --- MCServer/Plugins/APIDump/APIDesc.lua | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index af4818755..efc0c6dc6 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2639,8 +2639,8 @@ end; DefaultFnName = "OnPlayerBreakingBlock", -- also used as pagename Desc = [[ This hook is called when a {{cPlayer|player}} breaks a block, before the block is actually broken in - the {{cWorld|World}}. Plugins may refuse the breaking. - + the {{cWorld|World}}. Plugins may refuse the breaking.

+

See also the {{OnPlayerBrokenBlock|HOOK_PLAYER_BROKEN_BLOCK}} hook for a similar hook called after the block is broken. ]], @@ -2662,6 +2662,35 @@ end; ]], }, -- HOOK_PLAYER_BREAKING_BLOCK + HOOK_PLAYER_BROKEN_BLOCK = + { + CalledWhen = "After a player has broken a block. Notification only.", + DefaultFnName = "OnPlayerBrokenBlock", -- also used as pagename + Desc = [[ + This function is called after a {{cPlayer|player}} breaks a block. The block is already removed + from the {{cWorld|world}} and {{cPickup|pickups}} have been spawned. To get the world in which the + block has been dug, use the {{cPlayer}}:GetWorld() function.

+

+ See also the {{OnPlayerBreakingBlock|HOOK_PLAYER_BREAKING_BLOCK}} hook for a similar hook called + before the block is broken. To intercept the creation of pickups, see the + {{OnBlockToPickups|HOOK_BLOCK_TO_PICKUPS}} hook. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who broke the block" }, + { Name = "BlockX", Type = "number", Notes = "X-coord of the block" }, + { Name = "BlockY", Type = "number", Notes = "Y-coord of the block" }, + { Name = "BlockZ", Type = "number", Notes = "Z-coord of the block" }, + { Name = "BlockFace", Type = "number", Notes = "Face of the block upon which the player interacted. One of the BLOCK_FACE_ constants" }, + { Name = "BlockType", Type = "BLOCKTYPE", Notes = "The block type of the block" }, + { Name = "BlockMeta", Type = "NIBBLETYPE", Notes = "The block meta of the block" }, + }, + 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_BROKEN_BLOCK + }, -- Hooks[] -- cgit v1.2.3 From b902c0b29e72098242bb81caabb99e333fb2da97 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Tue, 15 Oct 2013 08:18:08 +0200 Subject: APIDump: Documented HOOK_PLAYER_EATING. --- MCServer/Plugins/APIDump/APIDesc.lua | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index efc0c6dc6..84e7588db 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2691,6 +2691,26 @@ end; ]], }, -- HOOK_PLAYER_BROKEN_BLOCK + HOOK_PLAYER_EATING = + { + CalledWhen = "When the player starts eating", + DefaultFnName = "OnPlayerEating", -- also used as pagename + Desc = [[ + This hook gets called when the {{cPlayer|player}} starts eating, after the server checks that the + player can indeed eat (is not satiated and is holding food). Plugins may still refuse the eating by + returning true. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who started eating" }, + }, + Returns = [[ + If the function returns false or no value, the server calls the next plugin handler, and finally + lets the player eat. If the function returns true, the server doesn't call any more callbacks for + this event and aborts the eating. A "disallow" packet is sent to the client. + ]], + }, -- HOOK_PLAYER_EATING + }, -- Hooks[] -- cgit v1.2.3 From 90dc2c55d8273c4a9d4429f7f4473cbf3302f1a4 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Tue, 15 Oct 2013 08:24:44 +0200 Subject: APIDump: Documented HOOK_PLAYER_JOINED. --- MCServer/Plugins/APIDump/APIDesc.lua | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 84e7588db..b464a10e6 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2711,6 +2711,28 @@ end; ]], }, -- HOOK_PLAYER_EATING + HOOK_PLAYER_JOINED = + { + CalledWhen = "After Login and before Spawned, before being added to world. ", + DefaultFnName = "OnPlayerJoined", -- also used as pagename + Desc = [[ + This hook is called whenever a {{cPlayer|player}} has completely logged in. If authentication is + enabled, this function is called after their name has been authenticated. It is called after + {{OnLogin|HOOK_LOGIN}} and before {{OnPlayerSpawned|HOOK_PLAYER_SPAWNED}}, right after the player's + entity is created, but not added to the world yet. The player is not yet visible to other players. + This is a notification-only event, plugins wishing to refuse player's entry should kick the player + using the {{cPlayer}}:Kick() function. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who has joined the game" }, + }, + Returns = [[ + If the function returns false or no value, other plugins' callbacks are called. If the function + returns true, no other callbacks are called for this event. Either way the player is let in. + ]], + }, -- HOOK_PLAYER_JOINED + }, -- Hooks[] -- cgit v1.2.3 From 19e176be20ce9fb9fede053f773c46da2e8f362f Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Tue, 15 Oct 2013 11:30:41 +0200 Subject: APIDump: Documented HOOK_PLAYER_LEFT_CLICK. --- MCServer/Plugins/APIDump/APIDesc.lua | 40 ++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index b464a10e6..02f6a8d3c 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2733,6 +2733,46 @@ end; ]], }, -- HOOK_PLAYER_JOINED + HOOK_PLAYER_LEFT_CLICK = + { + CalledWhen = "A left-click packet is received from the client. Plugin may override / refuse.", + DefaultFnName = "OnPlayerLeftClick", -- also used as pagename + Desc = [[ + This hook is called when MCServer receives a left-click packet from the {{cClientHandle|client}}. It + is called before any processing whatsoever is performed on the packet, meaning that hacked / + malicious clients may be trigerring this event very often and with unchecked parameters. Therefore + plugin authors are advised to use extreme caution with this callback.

+

+ Plugins may refuse the default processing for the packet, causing MCServer to behave as if the + packet has never arrived. This may, however, create inconsistencies in the client - the client may + think that they broke a block, while the server didn't process the breaking, etc. For this reason, + if a plugin refuses the processing, MCServer sends the block specified in the packet back to the + client (as if placed anew), if the status code specified a block-break action. For other actions, + plugins must rectify the situation on their own.

+

+ The client sends the left-click packet for several other occasions, such as dropping the held item + (Q keypress) or shooting an arrow. This is reflected in the Status code. Consult the + protocol documentation for details on the actions. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player whose client sent the packet" }, + { Name = "BlockX", Type = "number", Notes = "X-coord of the block" }, + { Name = "BlockY", Type = "number", Notes = "Y-coord of the block" }, + { Name = "BlockZ", Type = "number", Notes = "Z-coord of the block" }, + { Name = "BlockFace", Type = "number", Notes = "Face of the block upon which the player interacted. One of the BLOCK_FACE_ constants" }, + { Name = "Action", Type = "number", Notes = "Action to be performed on the block (\"status\" in the protocol docs)" }, + }, + Returns = [[ + If the function returns false or no value, MCServer calls other plugins' callbacks and finally sends + the packet for further processing.

+

+ If the function returns true, no other plugins are called, processing is halted. If the action was a + block dig, MCServer sends the block specified in the coords back to the client. The packet is + dropped. + ]], + }, -- HOOK_PLAYER_LEFT_CLICK + }, -- Hooks[] -- cgit v1.2.3 From deb2d89506b3c23a26b9e0de4143506894b8bfbb Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Tue, 15 Oct 2013 14:48:29 +0200 Subject: APIDump: Documented HOOK_PLAYER_MOVING and HOOK_PLAYER_PLACED_BLOCK. --- MCServer/Plugins/APIDump/APIDesc.lua | 53 ++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 02f6a8d3c..3982f8b4c 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2773,6 +2773,59 @@ end; ]], }, -- HOOK_PLAYER_LEFT_CLICK + HOOK_PLAYER_MOVING = + { + CalledWhen = "Player tried to move in the tick being currently processed. Plugin may refuse movement.", + DefaultFnName = "OnPlayerMoving", -- also used as pagename + Desc = [[ + This function is called in each server tick for each {{cPlayer|player}} that has sent any of the + player-move packets. Plugins may refuse the movement. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who has moved. The object already has the new position stored in it." }, + }, + Returns = [[ + If the function returns true, movement is prohibited. FIXME: The player's client is not informed.

+

+ If the function returns false or no value, other plugins' callbacks are called and finally the new + position is permanently stored in the cPlayer object.

+ ]], + }, -- HOOK_PLAYER_MOVING + + HOOK_PLAYER_PLACED_BLOCK = + { + CalledWhen = "After a player has placed a block. Notification only.", + DefaultFnName = "OnPlayerPlacedBlock", -- also used as pagename + Desc = [[ + This hook is called after a {{cPlayer|player}} has placed a block in the {{cWorld|world}}. The block + is already added to the world and the corresponding item removed from player's + {{cInventory|inventory}}.

+

+ Use the {{cPlayer}}:GetWorld() function to get the world to which the block belongs.

+

+ See also the {{OnPlayerPlacingBlock|HOOK_PLAYER_PLACING_BLOCK}} hook for a similar hook called + before the placement. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who placed the block" }, + { Name = "BlockX", Type = "number", Notes = "X-coord of the block" }, + { Name = "BlockY", Type = "number", Notes = "Y-coord of the block" }, + { Name = "BlockZ", Type = "number", Notes = "Z-coord of the block" }, + { Name = "BlockFace", Type = "number", Notes = "Face of the existing block upon which the player interacted. One of the BLOCK_FACE_ constants" }, + { Name = "CursorX", Type = "number", Notes = "X-coord of the cursor within the block face (0 .. 15)" }, + { Name = "CursorY", Type = "number", Notes = "Y-coord of the cursor within the block face (0 .. 15)" }, + { Name = "CursorZ", Type = "number", Notes = "Z-coord of the cursor within the block face (0 .. 15)" }, + { Name = "BlockType", Type = "BLOCKTYPE", Notes = "The block type of the block" }, + { Name = "BlockMeta", Type = "NIBBLETYPE", Notes = "The block meta of the block" }, + }, + Returns = [[ + If this function returns false or no value, MCServer calls other plugins with the same event. If + this function returns true, no other plugin is called for this event. + ]], + }, -- HOOK_PLAYER_PLACED_BLOCK + }, -- Hooks[] -- cgit v1.2.3 From 9be35e122223b19eab76cac045144f1e572a1adb Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Tue, 15 Oct 2013 14:58:33 +0200 Subject: APIDump: Documented HOOK_PLAYER_PLACING_BLOCK. --- MCServer/Plugins/APIDump/APIDesc.lua | 38 ++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 3982f8b4c..b4b2e11a3 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2826,6 +2826,44 @@ end; ]], }, -- HOOK_PLAYER_PLACED_BLOCK + HOOK_PLAYER_PLACING_BLOCK = + { + CalledWhen = "Just before a player places a block. Plugin may override / refuse.", + DefaultFnName = "OnPlayerPlacingBlock", -- also used as pagename + Desc = [[ + This hook is called just before a {{cPlayer|player}} places a block in the {{cWorld|world}}. The + block is not yet placed, plugins may choose to override the default behavior or refuse the placement + at all.

+

+ Note that the client already expects that the block has been placed. For that reason, if a plugin + refuses the placement, MCServer sends the old block at the provided coords to the client.

+

+ Use the {{cPlayer}}:GetWorld() function to get the world to which the block belongs.

+

+ See also the {{OnPlayerPlacedBlock|HOOK_PLAYER_PLACED_BLOCK}} hook for a similar hook called after + the placement. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who is placing the block" }, + { Name = "BlockX", Type = "number", Notes = "X-coord of the block" }, + { Name = "BlockY", Type = "number", Notes = "Y-coord of the block" }, + { Name = "BlockZ", Type = "number", Notes = "Z-coord of the block" }, + { Name = "BlockFace", Type = "number", Notes = "Face of the existing block upon which the player is interacting. One of the BLOCK_FACE_ constants" }, + { Name = "CursorX", Type = "number", Notes = "X-coord of the cursor within the block face (0 .. 15)" }, + { Name = "CursorY", Type = "number", Notes = "Y-coord of the cursor within the block face (0 .. 15)" }, + { Name = "CursorZ", Type = "number", Notes = "Z-coord of the cursor within the block face (0 .. 15)" }, + { Name = "BlockType", Type = "BLOCKTYPE", Notes = "The block type of the block" }, + { Name = "BlockMeta", Type = "NIBBLETYPE", Notes = "The block meta of the block" }, + }, + Returns = [[ + If this function returns false or no value, MCServer calls other plugins with the same event and + finally places the block and removes the corresponding item from player's inventory. If this + function returns true, no other plugin is called for this event, MCServer sends the old block at + the specified coords to the client and drops the packet. + ]], + }, -- HOOK_PLAYER_PLACING_BLOCK + }, -- Hooks[] -- cgit v1.2.3 From b079676290cdd6be5b6e3fd84f46b8d25f959b9e Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Tue, 15 Oct 2013 17:35:34 +0200 Subject: APIDump: Documented HOOK_POST_CRAFTING. --- MCServer/Plugins/APIDump/APIDesc.lua | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index b4b2e11a3..9430f370d 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2864,6 +2864,35 @@ end; ]], }, -- HOOK_PLAYER_PLACING_BLOCK + HOOK_POST_CRAFTING = + { + CalledWhen = "After the built-in recipes are checked and a recipe was found.", + DefaultFnName = "OnPostCrafting", -- also used as pagename + Desc = [[ + This hook is called when a {{cPlayer|player}} changes contents of their + {{cCraftingGrid|crafting grid}}, after the recipe has been established by MCServer. Plugins may use + this to modify the resulting recipe or provide an alternate recipe.

+

+ If a plugin implements custom recipes, it should do so using the {{OnPreCrafting|HOOK_PRE_CRAFTING}} + hook, because that will save the server from going through the built-in recipes. The + HOOK_POST_CRAFTING hook is intended as a notification, with a chance to tweak the result.

+

+ Note that this hook is not called if a built-in recipe is not found; + {{OnCraftingNoRecipe|HOOK_CRAFTING_NO_RECIPE}} is called instead in such a case. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who has changed their crafting grid contents" }, + { Name = "Grid", Type = "{{cCraftingGrid}}", Notes = "The new crafting grid contents" }, + { Name = "Recipe", Type = "{{cCraftingRecipe}}", Notes = "The recipe that MCServer has decided to use (can be tweaked by plugins)" }, + }, + Returns = [[ + If the function returns false or no value, other plugins' callbacks are called. If the function + returns true, no other callbacks are called for this event. In either case, MCServer uses the value + of Recipe as the recipe to be presented to the player. + ]], + }, -- HOOK_POST_CRAFTING + }, -- Hooks[] -- cgit v1.2.3 From edd1a670edf97500aa9a8f68fd2ea0b68bcc8d55 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Tue, 15 Oct 2013 17:43:41 +0200 Subject: APIDump: Documented HOOK_PRE_CRAFTING. --- MCServer/Plugins/APIDump/APIDesc.lua | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 9430f370d..caa0f6bd8 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2893,6 +2893,36 @@ end; ]], }, -- HOOK_POST_CRAFTING + HOOK_PRE_CRAFTING = + { + CalledWhen = "Before the built-in recipes are checked.", + DefaultFnName = "OnPreCrafting", -- also used as pagename + Desc = [[ + This hook is called when a {{cPlayer|player}} changes contents of their + {{cCraftingGrid|crafting grid}}, before the built-in recipes are searched for a match by MCServer. + Plugins may use this hook to provide a custom recipe.

+

+ If you intend to tweak built-in recipes, use the {{OnPostCrafting|HOOK_POST_CRAFTING}} hook, because + that will be called once the built-in recipe is matched.

+

+ Also note a third hook, {{OnCraftingNoRecipe|HOOK_CRAFTING_NO_RECIPE}}, that is called when MCServer + cannot find any built-in recipe for the given ingredients. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who has changed their crafting grid contents" }, + { Name = "Grid", Type = "{{cCraftingGrid}}", Notes = "The new crafting grid contents" }, + { Name = "Recipe", Type = "{{cCraftingRecipe}}", Notes = "The recipe that MCServer will use. Modify this object to change the recipe" }, + }, + Returns = [[ + If the function returns false or no value, other plugins' callbacks are called and then MCServer + searches the built-in recipes. The Recipe output parameter is ignored in this case.

+

+ If the function returns true, no other callbacks are called for this event and MCServer uses the + recipe stored in the Recipe output parameter. + ]], + }, -- HOOK_PRE_CRAFTING + }, -- Hooks[] -- cgit v1.2.3 From 167d8d346ec0fd0b150116619fa3cde760e3e369 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Tue, 15 Oct 2013 17:55:01 +0200 Subject: APIDump: Documented HOOK_SPAWNED_ENTITY. --- MCServer/Plugins/APIDump/APIDesc.lua | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index caa0f6bd8..f2a0cbaa2 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2923,6 +2923,26 @@ end; ]], }, -- HOOK_PRE_CRAFTING + HOOK_SPAWNED_ENTITY = + { + CalledWhen = "After an entity is spawned in the world.", + DefaultFnName = "OnSpawnedEntity", -- also used as pagename + Desc = [[ + This callback is called after the server spawns an {{cEntity|entity}}. This is an information-only + callback, the entity is already spawned by the time it is called. If the entity spawned is a + {{cMonster|monster}}, the {{OnSpawnedMonster|HOOK_SPAWNED_MONSTER}} hook is called before this hook. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "The world in which the entity has spawned" }, + { Name = "Entity", Type = "{{cEntity}} descentant", Notes = "The entity that has spawned" }, + }, + 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_SPAWNED_ENTITY + }, -- Hooks[] -- cgit v1.2.3 From 44ec010e154853419d53ef88b82bf6dbf1fec747 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Tue, 15 Oct 2013 17:58:39 +0200 Subject: APIDump: Documented HOOK_SPAWNED_MONSTER. --- MCServer/Plugins/APIDump/APIDesc.lua | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index f2a0cbaa2..3dcfb188d 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2928,7 +2928,7 @@ end; CalledWhen = "After an entity is spawned in the world.", DefaultFnName = "OnSpawnedEntity", -- also used as pagename Desc = [[ - This callback is called after the server spawns an {{cEntity|entity}}. This is an information-only + This hook is called after the server spawns an {{cEntity|entity}}. This is an information-only callback, the entity is already spawned by the time it is called. If the entity spawned is a {{cMonster|monster}}, the {{OnSpawnedMonster|HOOK_SPAWNED_MONSTER}} hook is called before this hook. ]], @@ -2943,6 +2943,26 @@ end; ]], }, -- HOOK_SPAWNED_ENTITY + HOOK_SPAWNED_MONSTER = + { + CalledWhen = "After a monster is spawned in the world", + DefaultFnName = "OnSpawnedMonster", -- also used as pagename + Desc = [[ + This hook is called after the server spawns a {{cMonster|monster}}. This is an information-only + callback, the monster is already spawned by the time it is called. After this hook is called, the + {{OnSpawnedEntity|HOOK_SPAWNED_ENTITY}} is called for the monster entity. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "The world in which the monster has spawned" }, + { Name = "Monster", Type = "{{cMonster}} descendant", Notes = "The monster that has spawned" }, + }, + 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_SPAWNED_MONSTER + }, -- Hooks[] -- cgit v1.2.3 From ba6c2b9ef4173da0717f335754c1660ce32e4abf Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Tue, 15 Oct 2013 18:06:06 +0200 Subject: APIDump: Documented HOOK_SPAWNING_ENTITY. --- MCServer/Plugins/APIDump/APIDesc.lua | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 3dcfb188d..42762a9ad 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2930,7 +2930,11 @@ end; Desc = [[ This hook is called after the server spawns an {{cEntity|entity}}. This is an information-only callback, the entity is already spawned by the time it is called. If the entity spawned is a - {{cMonster|monster}}, the {{OnSpawnedMonster|HOOK_SPAWNED_MONSTER}} hook is called before this hook. + {{cMonster|monster}}, the {{OnSpawnedMonster|HOOK_SPAWNED_MONSTER}} hook is called before this + hook.

+

+ See also the {{OnSpawningEntity|HOOK_SPAWNING_ENTITY}} hook for a similar hook called before the + entity is spawned. ]], Params = { @@ -2950,7 +2954,10 @@ end; Desc = [[ This hook is called after the server spawns a {{cMonster|monster}}. This is an information-only callback, the monster is already spawned by the time it is called. After this hook is called, the - {{OnSpawnedEntity|HOOK_SPAWNED_ENTITY}} is called for the monster entity. + {{OnSpawnedEntity|HOOK_SPAWNED_ENTITY}} is called for the monster entity.

+

+ See also the {{OnSpawningMonster|HOOK_SPAWNING_MONSTER}} hook for a similar hook called before the + monster is spawned. ]], Params = { @@ -2963,6 +2970,31 @@ end; ]], }, -- HOOK_SPAWNED_MONSTER + HOOK_SPAWNING_ENTITY = + { + CalledWhen = "Before an entity is spawned in the world.", + DefaultFnName = "OnSpawningEntity", -- also used as pagename + Desc = [[ + This hook is called before the server spawns an {{cEntity|entity}}. The plugin can either modify the + entity before it is spawned, or disable the spawning altogether. If the entity spawning is a + monster, the {{OnSpawningMonster|HOOK_SPAWNING_MONSTER}} hook is called before this hook.

+

+ See also the {{OnSpawnedEntity|HOOK_SPAWNED_ENTITY}} hook for a similar hook called after the + entity is spawned. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "The world in which the entity will spawn" }, + { Name = "Entity", Type = "{{cEntity}} descentant", Notes = "The entity that will spawn" }, + }, + Returns = [[ + If the function returns false or no value, the next plugin's callback is called. Finally, the server + spawns the entity with whatever parameters have been set on the {{cEntity}} object by the callbacks. + If the function returns true, no other callback is called for this event and the entity is not + spawned. + ]], + }, -- HOOK_SPAWNING_ENTITY + }, -- Hooks[] -- cgit v1.2.3 From 9c7ca813d283b42fae5ce6839aec5bff3181d0eb Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Tue, 15 Oct 2013 18:12:37 +0200 Subject: APIDump: Documented HOOK_SPAWNING_MONSTER. --- MCServer/Plugins/APIDump/APIDesc.lua | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 42762a9ad..8b62df24d 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2995,6 +2995,32 @@ end; ]], }, -- HOOK_SPAWNING_ENTITY + HOOK_SPAWNING_MONSTER = + { + CalledWhen = "Before a monster is spawned in the world.", + DefaultFnName = "OnSpawningMonster", -- also used as pagename + Desc = [[ + This hook is called before the server spawns a {{cMonster|monster}}. The plugins may modify the + monster's parameters in the {{cMonster}} class, or disallow the spawning altogether. This hook is + called before the {{OnSpawningEntity|HOOK_SPAWNING_ENTITY}} is called for the monster entity.

+

+ See also the {{OnSpawnedMonster|HOOK_SPAWNED_MONSTER}} hook for a similar hook called after the + monster is spawned. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "The world in which the entity will spawn" }, + { Name = "Monster", Type = "{{cMonster}} descentant", Notes = "The monster that will spawn" }, + }, + Returns = [[ + If the function returns false or no value, the next plugin's callback is called. Finally, the server + spawns the monster with whatever parameters the plugins set in the cMonster parameter.

+

+ If the function returns true, no other callback is called for this event and the monster won't + spawn. + ]], + }, -- HOOK_SPAWNING_MONSTER + }, -- Hooks[] -- cgit v1.2.3 From c9a9a30fa54f2c41290ba4a99e3575ad3f5373f8 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Tue, 15 Oct 2013 18:42:33 +0200 Subject: APIDump: Linkification supports #anchors. This implements #198. --- MCServer/Plugins/APIDump/main.lua | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/main.lua b/MCServer/Plugins/APIDump/main.lua index 6ae4a6b0f..163c505b2 100644 --- a/MCServer/Plugins/APIDump/main.lua +++ b/MCServer/Plugins/APIDump/main.lua @@ -617,8 +617,39 @@ end -- Make a link out of anything with the special linkifying syntax {{link|title}} function LinkifyString(a_String) - local txt = a_String:gsub("{{([^|}]*)|([^}]*)}}", "%2") -- {{link|title}} - txt = txt:gsub("{{([^|}]*)}}", "%1") -- {{LinkAndTitle}} + local function CreateLink(Link, Title) + if (Link:sub(1, 7) == "http://") then + -- The link is a full absolute URL, do not modify, do not track: + return "" .. Title .. ""; + end + local idxHash = Link:find("#"); + if (idxHash ~= nil) then + -- The link contains an anchor: + if (idxHash == 1) then + -- Anchor in the current page, no need to track: + return "" .. Title .. ""; + end + -- Anchor in another page: + -- TODO: track this link + return "" .. Title .. ""; + end + -- Link without anchor: + -- TODO; track this link + return "" .. Title .. ""; + end + + local txt = a_String:gsub("{{([^|}]*)|([^}]*)}}", CreateLink) -- {{link|title}} + + txt = txt:gsub("{{([^|}]*)}}", -- {{LinkAndTitle}} + function(LinkAndTitle) + local idxHash = LinkAndTitle:find("#"); + if (idxHash ~= nil) then + -- The LinkAndTitle contains a hash, remove the hashed part from the title: + return CreateLink(LinkAndTitle, LinkAndTitle:sub(1, idxHash - 1)); + end + return CreateLink(LinkAndTitle, LinkAndTitle); + end + ); return txt; end -- cgit v1.2.3 From 17aff20666defab01006ea4ca56dc4f2f8cba9ac Mon Sep 17 00:00:00 2001 From: Alexander Harkness Date: Tue, 15 Oct 2013 19:57:00 +0100 Subject: Added HOOK_PLAYER_RIGHT_CLICK --- MCServer/Plugins/APIDump/APIDesc.lua | 46 +++++++++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 8 deletions(-) (limited to 'MCServer') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 8b62df24d..2bede6323 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -364,8 +364,8 @@ g_APIDesc = }, Constants = { - Color = { Notes = "The first character of the color-code-sequence, §" }, - Delimiter = { Notes = "The first character of the color-code-sequence, §" }, + Color = { Notes = "The first character of the color-code-sequence, §" }, + Delimiter = { Notes = "The first character of the color-code-sequence, §" }, Random = { Notes = "Random letters and symbols animate instead of the text" }, Plain = { Notes = "Resets all formatting to normal" }, }, @@ -2029,14 +2029,14 @@ World:ForEachEntity( GetTime = {Return = "number", Notes = "Returns the current OS time, as a unix time stamp (number of seconds since Jan 1, 1970)"}, IsValidBlock = {Params = "BlockType", Return = "bool", Notes = "Returns true if BlockType is a known block type"}, IsValidItem = {Params = "ItemType", Return = "bool", Notes = "Returns true if ItemType is a known item type"}, - ItemToFullString = {Params = "{{cItem|cItem}}", Return = "string", Notes = "Returns the string representation of the item, in the format “ItemTypeText:ItemDamage * Count”"}, + ItemToFullString = {Params = "{{cItem|cItem}}", Return = "string", Notes = "Returns the string representation of the item, in the format “ItemTypeText:ItemDamage * Count”"}, ItemToString = {Params = "{{cItem|cItem}}", Return = "string", Notes = "Returns the string representation of the item type"}, ItemTypeToString = {Params = "ItemType", Return = "string", Notes = "Returns the string representation of ItemType "}, - LOG = {Params = "string", Notes = "Logs a text into the server console using “normal” severity (gray text) "}, - LOGERROR = {Params = "string", Notes = "Logs a text into the server console using “error” severity (black text on red background)"}, - LOGINFO = {Params = "string", Notes = "Logs a text into the server console using “info” severity (yellow text)"}, - LOGWARN = {Params = "string", Notes = "Logs a text into the server console using “warning” severity (red text); OBSOLETE"}, - LOGWARNING = {Params = "string", Notes = "Logs a text into the server console using “warning” severity (red text)"}, + LOG = {Params = "string", Notes = "Logs a text into the server console using “normal” severity (gray text) "}, + LOGERROR = {Params = "string", Notes = "Logs a text into the server console using “error” severity (black text on red background)"}, + LOGINFO = {Params = "string", Notes = "Logs a text into the server console using “info” severity (yellow text)"}, + LOGWARN = {Params = "string", Notes = "Logs a text into the server console using “warning” severity (red text); OBSOLETE"}, + LOGWARNING = {Params = "string", Notes = "Logs a text into the server console using “warning” severity (red text)"}, NoCaseCompare = {Params = "string, string", Return = "number", Notes = "Case-insensitive string comparison; returns 0 if the strings are the same"}, ReplaceString = {Params = "full-string, to-be-replaced-string, to-replace-string", Notes = "Replaces *each* occurence of to-be-replaced-string in full-string with to-replace-string"}, StringSplit = {Params = "string, Seperator", Return = "list", Notes = "Seperates string into multiple by splitting every time Seperator is encountered."}, @@ -2864,6 +2864,36 @@ end; ]], }, -- HOOK_PLAYER_PLACING_BLOCK + HOOK_PLAYER_RIGHT_CLICK = + { + CalledWhen = "A right-click packet is received from the client. Plugin may override / refuse.", + DefaultFnName = "OnPlayerRightClick", -- also used as pagename + Desc = [[ + This hook is called when MCServer receives a right-click packet from the {{cClientHandle|client}}. It + is called before any processing whatsoever is performed on the packet, meaning that hacked / + malicious clients may be trigerring this event very often and with unchecked parameters. Therefore + plugin authors are advised to use extreme caution with this callback.

+

+ Plugins may refuse the default processing for the packet, causing MCServer to behave as if the + packet has never arrived. This may, however, create inconsistencies in the client - the client may + think that they placed a block, while the server didn't process the placing, etc. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player whose client sent the packet" }, + { Name = "BlockX", Type = "number", Notes = "X-coord of the block" }, + { Name = "BlockY", Type = "number", Notes = "Y-coord of the block" }, + { Name = "BlockZ", Type = "number", Notes = "Z-coord of the block" }, + { Name = "BlockFace", Type = "number", Notes = "Face of the block upon which the player interacted. One of the BLOCK_FACE_ constants" }, + }, + Returns = [[ + If the function returns false or no value, MCServer calls other plugins' callbacks and finally sends + the packet for further processing.

+

+ If the function returns true, no other plugins are called, processing is halted. + ]], + }, -- HOOK_PLAYER_RIGHT_CLICK + HOOK_POST_CRAFTING = { CalledWhen = "After the built-in recipes are checked and a recipe was found.", -- cgit v1.2.3