From 5609d76ed7d8026b3bcaeb02fb42bd9ba2f27c96 Mon Sep 17 00:00:00 2001 From: Mattes D Date: Wed, 24 Dec 2014 20:02:51 +0100 Subject: APIDump: Updated the player block placement documentation. The hooks now have fewer parameters but are called on all player-placed blocks (#1618). --- MCServer/Plugins/APIDump/APIDesc.lua | 2 ++ MCServer/Plugins/APIDump/Hooks/OnPlayerPlacedBlock.lua | 10 +++++----- MCServer/Plugins/APIDump/Hooks/OnPlayerPlacingBlock.lua | 10 +++++----- src/Entities/Player.h | 3 ++- 4 files changed, 14 insertions(+), 11 deletions(-) diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index ba3763724..b2c7108e9 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -1840,7 +1840,9 @@ a_Player:OpenWindow(Window); MoveToWorld = { Params = "WorldName", Return = "bool", Return = "Moves the player to the specified world. Returns true if successful." }, OpenWindow = { Params = "{{cWindow|Window}}", Return = "", Notes = "Opens the specified UI window for the player." }, PermissionMatches = { Params = "Permission, Template", Return = "bool", Notes = "(STATIC) Returns true if the specified permission matches the specified template. The template may contain wildcards." }, + PlaceBlock = { Params = "BlockX, BlockY, BlockZ, BlockType, BlockMeta", Return = "bool", Notes = "Places a block while impersonating the player. The {{OnPlayerPlacingBlock|HOOK_PLAYER_PLACING_BLOCK}} hook is called before the placement, and if it succeeds, the block is placed and the {{OnPlayerPlacedBlock|HOOK_PLAYER_PLACED_BLOCK}} hook is called. Returns true iff the block is successfully placed. Assumes that the block is in a currently loaded chunk." }, Respawn = { Params = "", Return = "", Notes = "Restores the health, extinguishes fire, makes visible and sends the Respawn packet." }, + SendBlocksAround = { Params = "BlockX, BlockY, BlockZ, [Range]", Return = "", Notes = "Sends all the world's blocks in Range from the specified coords to the player, as a BlockChange packet. Range defaults to 1 (only one block sent)." }, SendMessage = { Params = "Message", Return = "", Notes = "Sends the specified message to the player." }, SendMessageFailure = { Params = "Message", Return = "", Notes = "Prepends Rose [INFO] / colours entire text (depending on ShouldUseChatPrefixes()) and sends message to player. For a command that failed to run because of insufficient permissions, etc." }, SendMessageFatal = { Params = "Message", Return = "", Notes = "Prepends Red [FATAL] / colours entire text (depending on ShouldUseChatPrefixes()) and sends message to player. For something serious, such as a plugin crash, etc." }, diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerPlacedBlock.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerPlacedBlock.lua index 54888a6db..6445a76b4 100644 --- a/MCServer/Plugins/APIDump/Hooks/OnPlayerPlacedBlock.lua +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerPlacedBlock.lua @@ -12,7 +12,11 @@ return 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. + before the placement.

+

+ If the client action results in multiple blocks being placed (such as a bed or a door), each separate + block is reported through this hook. All the blocks are already present in the world before the first + instance of this hook is called. ]], Params = { @@ -20,10 +24,6 @@ return { 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" }, }, diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerPlacingBlock.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerPlacingBlock.lua index 2a928390b..4241a09aa 100644 --- a/MCServer/Plugins/APIDump/Hooks/OnPlayerPlacingBlock.lua +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerPlacingBlock.lua @@ -15,7 +15,11 @@ return 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. + the placement.

+

+ If the client action results in multiple blocks being placed (such as a bed or a door), each separate + block is reported through this hook and only if all of them succeed, all the blocks are placed. If + any one of the calls are refused by the plugin, all the blocks are refused and reverted on the client. ]], Params = { @@ -23,10 +27,6 @@ return { 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" }, }, diff --git a/src/Entities/Player.h b/src/Entities/Player.h index 33ab5293c..b94d2659e 100644 --- a/src/Entities/Player.h +++ b/src/Entities/Player.h @@ -442,7 +442,8 @@ public: /** Calls the block-placement hook and places the block in the world, unless refused by the hook. If the hook prevents the placement, sends the current block at the specified coords back to the client. - Assumes that all the blocks are in currently loaded chunks. */ + Assumes that the block is in a currently loaded chunk. + Returns true if the block is successfully placed. */ bool PlaceBlock(int a_BlockX, int a_BlockY, int a_BlockZ, BLOCKTYPE a_BlockType, NIBBLETYPE a_BlockMeta); /** Sends the block in the specified range around the specified coord to the client -- cgit v1.2.3