From d9dc241e6fe669585d7c0b13d55818a22e1c76bc Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Sat, 23 Nov 2013 21:26:24 +0100 Subject: [PATCH] APIDump: The descriptions are read from multiple files. All the files in the Classes subfolder are read for class descriptions, and in the Hooks subfolder for the hook descriptions. --- MCServer/Plugins/APIDump/APIDesc.lua | 1683 +---------------- .../Plugins/APIDump/Classes/BlockEntities.lua | 243 +++ .../APIDump/Hooks/OnBlockToPickups.lua | 62 + MCServer/Plugins/APIDump/Hooks/OnChat.lua | 29 + .../APIDump/Hooks/OnChunkAvailable.lua | 27 + .../APIDump/Hooks/OnChunkGenerated.lua | 67 + .../APIDump/Hooks/OnChunkGenerating.lua | 35 + .../Plugins/APIDump/Hooks/OnChunkUnloaded.lua | 28 + .../APIDump/Hooks/OnChunkUnloading.lua | 30 + .../APIDump/Hooks/OnCollectingPickup.lua | 32 + .../APIDump/Hooks/OnCraftingNoRecipe.lua | 32 + .../Plugins/APIDump/Hooks/OnDisconnect.lua | 32 + .../APIDump/Hooks/OnExecuteCommand.lua | 31 + MCServer/Plugins/APIDump/Hooks/OnExploded.lua | 49 + .../Plugins/APIDump/Hooks/OnExploding.lua | 50 + .../Plugins/APIDump/Hooks/OnHandshake.lua | 29 + .../APIDump/Hooks/OnHopperPullingItem.lua | 30 + .../APIDump/Hooks/OnHopperPushingItem.lua | 30 + MCServer/Plugins/APIDump/Hooks/OnKilling.lua | 33 + MCServer/Plugins/APIDump/Hooks/OnLogin.lua | 31 + .../APIDump/Hooks/OnPlayerAnimation.lua | 28 + .../APIDump/Hooks/OnPlayerBreakingBlock.lua | 36 + .../APIDump/Hooks/OnPlayerBrokenBlock.lua | 36 + .../Plugins/APIDump/Hooks/OnPlayerEating.lua | 27 + .../Plugins/APIDump/Hooks/OnPlayerJoined.lua | 29 + .../APIDump/Hooks/OnPlayerLeftClick.lua | 47 + .../Plugins/APIDump/Hooks/OnPlayerMoving.lua | 27 + .../APIDump/Hooks/OnPlayerPlacedBlock.lua | 40 + .../APIDump/Hooks/OnPlayerPlacingBlock.lua | 45 + .../APIDump/Hooks/OnPlayerRightClick.lua | 37 + .../Hooks/OnPlayerRightClickingEntity.lua | 27 + .../APIDump/Hooks/OnPlayerShooting.lua | 32 + .../Plugins/APIDump/Hooks/OnPlayerSpawned.lua | 32 + .../APIDump/Hooks/OnPlayerTossingItem.lua | 30 + .../APIDump/Hooks/OnPlayerUsedBlock.lua | 46 + .../APIDump/Hooks/OnPlayerUsedItem.lua | 46 + .../APIDump/Hooks/OnPlayerUsingBlock.lua | 46 + .../APIDump/Hooks/OnPlayerUsingItem.lua | 47 + .../Plugins/APIDump/Hooks/OnPostCrafting.lua | 36 + .../Plugins/APIDump/Hooks/OnPreCrafting.lua | 37 + .../Plugins/APIDump/Hooks/OnSpawnedEntity.lua | 31 + .../APIDump/Hooks/OnSpawnedMonster.lua | 30 + .../APIDump/Hooks/OnSpawningEntity.lua | 32 + .../APIDump/Hooks/OnSpawningMonster.lua | 33 + .../Plugins/APIDump/Hooks/OnTakeDamage.lua | 31 + MCServer/Plugins/APIDump/Hooks/OnTick.lua | 29 + .../Plugins/APIDump/Hooks/OnUpdatedSign.lua | 38 + .../Plugins/APIDump/Hooks/OnUpdatingSign.lua | 58 + .../APIDump/Hooks/OnWeatherChanged.lua | 28 + .../APIDump/Hooks/OnWeatherChanging.lua | 32 + .../Plugins/APIDump/Hooks/OnWorldTick.lua | 29 + MCServer/Plugins/APIDump/main_APIDump.lua | 33 + 52 files changed, 2036 insertions(+), 1682 deletions(-) create mode 100644 MCServer/Plugins/APIDump/Classes/BlockEntities.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnBlockToPickups.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnChat.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnChunkAvailable.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnChunkGenerated.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnChunkGenerating.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnChunkUnloaded.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnChunkUnloading.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnCollectingPickup.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnCraftingNoRecipe.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnDisconnect.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnExecuteCommand.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnExploded.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnExploding.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnHandshake.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnHopperPullingItem.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnHopperPushingItem.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnKilling.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnLogin.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerAnimation.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerBreakingBlock.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerBrokenBlock.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerEating.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerJoined.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerLeftClick.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerMoving.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerPlacedBlock.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerPlacingBlock.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerRightClick.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerRightClickingEntity.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerShooting.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerSpawned.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerTossingItem.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerUsedBlock.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerUsedItem.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerUsingBlock.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPlayerUsingItem.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPostCrafting.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnPreCrafting.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnSpawnedEntity.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnSpawnedMonster.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnSpawningEntity.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnSpawningMonster.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnTakeDamage.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnTick.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnUpdatedSign.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnUpdatingSign.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnWeatherChanged.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnWeatherChanging.lua create mode 100644 MCServer/Plugins/APIDump/Hooks/OnWorldTick.lua diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 82ba5ba45..1ad5bf5e4 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -302,56 +302,6 @@ g_APIDesc = }, -- AdditionalInfo }, -- cBlockArea - cBlockEntity = - { - Desc = [[ - Block entities are simply blocks in the world that have persistent data, such as the text for a sign - or contents of a chest. All block entities are also saved in the chunk data of the chunk they reside in. - The cBlockEntity class acts as a common ancestor for all the individual block entities. - ]], - - Functions = - { - GetBlockType = { Params = "", Return = "BLOCKTYPE", Notes = "Returns the blocktype which is represented by this blockentity. This is the primary means of type-identification" }, - GetChunkX = { Params = "", Return = "number", Notes = "Returns the chunk X-coord of the block entity's chunk" }, - GetChunkZ = { Params = "", Return = "number", Notes = "Returns the chunk Z-coord of the block entity's chunk" }, - GetPosX = { Params = "", Return = "number", Notes = "Returns the block X-coord of the block entity's block" }, - GetPosY = { Params = "", Return = "number", Notes = "Returns the block Y-coord of the block entity's block" }, - GetPosZ = { Params = "", Return = "number", Notes = "Returns the block Z-coord of the block entity's block" }, - GetRelX = { Params = "", Return = "number", Notes = "Returns the relative X coord of the block entity's block within the chunk" }, - GetRelZ = { Params = "", Return = "number", Notes = "Returns the relative Z coord of the block entity's block within the chunk" }, - GetWorld = { Params = "", Return = "{{cWorld|cWorld}}", Notes = "Returns the world to which the block entity belongs" }, - }, - }, - - cBlockEntityWithItems = - { - Desc = [[ - This class is a common ancestor for all {{cBlockEntity|block entities}} that provide item storage. - Internally, the object has a {{cItemGrid|cItemGrid}} object for storing the items; this ItemGrid is - accessible through the API. The storage is a grid of items, items in it can be addressed either by a slot - number, or by XY coords within the grid. If a UI window is opened for this block entity, the item storage - is monitored for changes and the changes are immediately sent to clients of the UI window. - ]], - - Inherits = "cBlockEntity", - - Functions = - { - GetContents = { Params = "", Return = "{{cItemGrid|cItemGrid}}", Notes = "Returns the cItemGrid object representing the items stored within this block entity" }, - GetSlot = - { - { Params = "SlotNum", Return = "{{cItem|cItem}}", Notes = "Returns the cItem for the specified slot number. Returns nil for invalid slot numbers" }, - { Params = "X, Y", Return = "{{cItem|cItem}}", Notes = "Returns the cItem for the specified slot coords. Returns nil for invalid slot coords" }, - }, - SetSlot = - { - { Params = "SlotNum, {{cItem|cItem}}", Return = "", Notes = "Sets the cItem for the specified slot number. Ignored if invalid slot number" }, - { Params = "X, Y, {{cItem|cItem}}", Return = "", Notes = "Sets the cItem for the specified slot coords. Ignored if invalid slot coords" }, - }, - }, - }, - cBoundingBox = { Desc = [[ @@ -430,45 +380,6 @@ g_APIDesc = }, }, - cChestEntity = - { - Desc = [[ - A chest entity is a {{cBlockEntityWithItems|cBlockEntityWithItems}} descendant that represents a chest - in the world. Note that doublechests consist of two separate cChestEntity objects, they do not collaborate - in any way.

-

- To manipulate a chest already in the game, you need to use {{cWorld}}'s callback mechanism with - either DoWithChestAt() or ForEachChestInChunk() function. See the code example below - ]], - - Inherits = "cBlockEntityWithItems", - - Constants = - { - ContentsHeight = { Notes = "Height of the contents' {{cItemGrid|ItemGrid}}, as required by the parent class, {{cBlockEntityWithItems}}" }, - ContentsWidth = { Notes = "Width of the contents' {{cItemGrid|ItemGrid}}, as required by the parent class, {{cBlockEntityWithItems}}" }, - }, - AdditionalInfo = - { - { - Header = "Code example", - Contents = [[ - The following example code sets the top-left item of each chest in the same chunk as Player to - 64 * diamond: -

--- Player is a {{cPlayer}} object instance
-local World = Player:GetWorld();
-World:ForEachChestInChunk(Player:GetChunkX(), Player:GetChunkZ(),
-	function (ChestEntity)
-		ChestEntity:SetSlot(0, 0, cItem(E_ITEM_DIAMOND, 64));
-	end
-);
-
- ]], - }, - }, -- AdditionalInfo - }, - cChunkDesc = { Desc = [[ @@ -693,47 +604,6 @@ end }, }, -- cCuboid - cDispenserEntity = - { - Desc = [[ - This class represents a dispenser block entity in the world. Most of this block entity's - functionality is implemented in the {{cDropSpenserEntity|cDropSpenserEntity}} class that represents - the behavior common with a {{cDropperEntity|dropper}} entity. - ]], - Inherits = "cDropSpenserEntity", - }, - - cDropperEntity = - { - Desc = [[ - This class represents a dropper block entity in the world. Most of this block entity's functionality - is implemented in the {{cDropSpenserEntity|cDropSpenserEntity}} class that represents the behavior - common with the {{cDispenserEntity|dispenser}} entity.

-

- An object of this class can be created from scratch when generating chunks ({{OnChunkGenerated|OnChunkGenerated}} and {{OnChunkGenerating|OnChunkGenerating}} hooks). - ]], - Inherits = "cDropSpenserEntity", - }, -- cDropperEntity - - cDropSpenserEntity = - { - Desc = [[ - This is a class that implements behavior common to both {{cDispenserEntity|dispensers}} and {{cDropperEntity|droppers}}. - ]], - Functions = - { - Activate = { Params = "", Return = "", Notes = "Sets the block entity to dropspense an item in the next tick" }, - AddDropSpenserDir = { Params = "BlockX, BlockY, BlockZ, BlockMeta", Return = "BlockX, BlockY, BlockZ", Notes = "Adjusts the block coords to where the dropspenser items materialize" }, - SetRedstonePower = { Params = "IsPowered", Return = "", Notes = "Sets the redstone status of the dropspenser. If the redstone power goes from off to on, the dropspenser will be activated" }, - }, - Constants = - { - ContentsWidth = { Notes = "Width (X) of the {{cItemGrid}} representing the contents" }, - ContentsHeight = { Notes = "Height (Y) of the {{cItemGrid}} representing the contents" }, - }, - Inherits = "cBlockEntityWithItems"; - }, -- cDropSpenserEntity - cEnchantments = { Desc = [[ @@ -987,45 +857,6 @@ cFile:Delete("/usr/bin/virus.exe"); Inherits = "cProjectileEntity", } , - cFurnaceEntity = - { - Desc = [[ - This class represents a furnace block entity in the world.

-

- See also {{cRoot}}'s GetFurnaceRecipe() and GetFurnaceFuelBurnTime() functions - ]], - Functions = - { - GetCookTimeLeft = { Params = "", Return = "number", Notes = "Returns the time until the current item finishes cooking, in ticks" }, - GetFuelBurnTimeLeft = { Params = "", Return = "number", Notes = "Returns the time until the current fuel is depleted, in ticks" }, - GetFuelSlot = { Params = "", Return = "{{cItem|cItem}}", Notes = "Returns the item in the fuel slot" }, - GetInputSlot = { Params = "", Return = "{{cItem|cItem}}", Notes = "Returns the item in the input slot" }, - GetOutputSlot = { Params = "", Return = "{{cItem|cItem}}", Notes = "Returns the item in the output slot" }, - GetTimeCooked = { Params = "", Return = "number", Notes = "Returns the time that the current item has been cooking, in ticks" }, - HasFuelTimeLeft = { Params = "", Return = "bool", Notes = "Returns true if there's time before the current fuel is depleted" }, - SetFuelSlot = { Params = "{{cItem|cItem}}", Return = "", Notes = "Sets the item in the fuel slot" }, - SetInputSlot = { Params = "{{cItem|cItem}}", Return = "", Notes = "Sets the item in the input slot" }, - SetOutputSlot = { Params = "{{cItem|cItem}}", Return = "", Notes = "Sets the item in the output slot" }, - }, - Constants = - { - fsInput = { Notes = "Index of the input slot" }, - fsFuel = { Notes = "Index of the fuel slot" }, - fsOutput = { Notes = "Index of the output slot" }, - ContentsWidth = { Notes = "Width (X) of the {{cItemGrid|cItemGrid}} representing the contents" }, - ContentsHeight = { Notes = "Height (Y) of the {{cItemGrid|cItemGrid}} representing the contents" }, - }, - ConstantGroups = - { - SlotIndices = - { - Include = "fs.*", - TextBefore = "When using the GetSlot() or SetSlot() function, use these constants for slot index:", - }, - }, - Inherits = "cBlockEntityWithItems" - }, -- cFurnaceEntity - cGhastFireballEntity = { Desc = "", @@ -1052,24 +883,6 @@ cFile:Delete("/usr/bin/virus.exe"); }, }, -- cGroup - cHopperEntity = - { - Desc = [[ - This class represents a hopper block entity in the world. - ]], - Functions = - { - GetOutputBlockPos = { Params = "BlockMeta", Return = "bool, BlockX, BlockY, BlockZ", Notes = "Returns whether the hopper is attached, and if so, the block coords of the block receiving the output items, based on the given meta." }, - }, - Constants = - { - ContentsHeight = { Notes = "Height (Y) of the internal {{cItemGrid}} representing the hopper contents." }, - ContentsWidth = { Notes = "Width (X) of the internal {{cItemGrid}} representing the hopper contents." }, - TICKS_PER_TRANSFER = { Notes = "Number of ticks between when the hopper transfers items." }, - }, - Inherits = "cBlockEntityWithItems", - }, -- cHopperEntity - cIniFile = { Desc = [[ @@ -1512,22 +1325,6 @@ end }, }, -- cItems - cJukeboxEntity = - { - Desc = [[ - This class represents a jukebox in the world. It can play the records, either when the - {{cPlayer|player}} uses the record on the jukebox, or when a plugin instructs it to play. - ]], - Inherits = "cBlockEntity", - Functions = - { - EjectRecord = { Params = "", Return = "", Notes = "Ejects the current record as a {{cPickup|pickup}}. No action if there's no current record. To remove record without generating the pickup, use SetRecord(0)" }, - GetRecord = { Params = "", Return = "number", Notes = "Returns the record currently present. Zero for no record, E_ITEM_*_DISC for records." }, - PlayRecord = { Params = "", Return = "", Notes = "Plays the currently present record. No action if there's no current record." }, - SetRecord = { Params = "number", Return = "", Notes = "Sets the currently present record. Use zero for no record, or E_ITEM_*_DISC for records." }, - }, - }, -- cJukeboxEntity - cLineBlockTracer = { Desc = [[Objects of this class provide an easy-to-use interface to tracing lines through individual @@ -1775,25 +1572,6 @@ a_Player:OpenWindow(Window); Inherits = "cPawn", }, -- cMonster - cNoteEntity = - { - Desc = [[ - This class represents a note block entity in the world. It takes care of the note block's pitch, - and also can play the sound, either when the {{cPlayer|player}} right-clicks it, redstone activates - it, or upon a plugin's request.

-

- The pitch is stored as an integer between 0 and 24. - ]], - Functions = - { - GetPitch = { Params = "", Return = "number", Notes = "Returns the current pitch set for the block" }, - IncrementPitch = { Params = "", Return = "", Notes = "Adds 1 to the current pitch. Wraps around to 0 when the pitch cannot go any higher." }, - MakeSound = { Params = "", Return = "", Notes = "Plays the sound for all {{cClientHandle|clients}} near this block." }, - SetPitch = { Params = "Pitch", Return = "", Notes = "Sets a new pitch for the block." }, - }, - Inherits = "cBlockEntity", - }, -- cNoteEntity - cPawn = { Desc = [[cPawn is a controllable pawn object, controlled by either AI or a player. cPawn inherits all functions and members of {{cEntity}} @@ -2170,21 +1948,6 @@ end }, }, -- cServer - cSignEntity = - { - Desc = [[ - A sign entity represents a sign in the world. This class is only used when generating chunks, so - that the plugins may generate signs within new chunks. See the code example in {{cChunkDesc}}. - ]], - Functions = - { - GetLine = { Params = "LineIndex", Return = "string", Notes = "Returns the specified line. LineIndex is expected between 0 and 3. Returns empty string and logs to server console when LineIndex is invalid." }, - SetLine = { Params = "LineIndex, LineText", Return = "", Notes = "Sets the specified line. LineIndex is expected between 0 and 3. Logs to server console when LineIndex is invalid." }, - SetLines = { Params = "Line1, Line2, Line3, Line4", Return = "", Notes = "Sets all the sign's lines at once." }, - }, - Inherits = "cBlockEntity"; - }, -- cSignEntity - cThrownEggEntity = { Desc = "", @@ -2708,7 +2471,7 @@ TakeDamageInfo =]], }, The TDI is passed as the second parameter in the HOOK_TAKE_DAMAGE hook, and can be used to modify the damage before it is applied to the receiver:

-function Plugin:OnTakeDamage(Receiver, TDI)
+function OnTakeDamage(Receiver, TDI)
 	LOG("Damage: Raw ".. TDI.RawDamage .. ", Final:" .. TDI.FinalDamage);
 
 	-- If the attacker is a spider, make it deal 999 points of damage (insta-death spiders):
@@ -3018,1449 +2781,6 @@ end
 	},
 
 
-	Hooks =
-	{
-		HOOK_BLOCK_TO_PICKUPS =
-		{
-			CalledWhen = "A block is about to be dug ({{cPlayer|player}}, {{cEntity|entity}} or natural reason), plugins may override what pickups that will produce.",
-			DefaultFnName = "OnBlockToPickups",  -- also used as pagename
-			Desc = [[
-				This callback gets called whenever a block is about to be dug. This includes {{cPlayer|players}}
-				digging blocks, entities causing blocks to disappear ({{cTNTEntity|TNT}}, Endermen) and natural
-				causes (water washing away a block). Plugins may override the amount and kinds of pickups this
-				action produces.
-			]],
-			Params =
-			{
-				{ Name = "World", Type = "{{cWorld}}", Notes = "The world in which the block resides" },
-				{ Name = "Digger", Type = "{{cEntity}} descendant", Notes = "The entitycausing the digging. May be a {{cPlayer}}, {{cTNTEntity}} or even nil (natural causes)" },
-				{ 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 = "BlockType", Type = "BLOCKTYPE", Notes = "Block type of the block" },
-				{ Name = "BlockMeta", Type = "NIBBLETYPE", Notes = "Block meta of the block" },
-				{ Name = "Pickups", Type = "{{cItems}}", Notes = "Items that will be spawned as pickups" },
-			},
-			Returns = [[
-				If the function returns false or no value, the next callback in the hook chain will be called. If
-				the function returns true, no other callbacks in the chain will be called.

-

- Either way, the server will then spawn pickups specified in the Pickups parameter, so to disable - pickups, you need to Clear the object first, then return true. - ]], - CodeExamples = - { - { - Title = "Modify pickups", - Desc = "This example callback function makes tall grass drop diamonds when digged by natural causes (washed away by water).", - Code = [[ -function OnBlockToPickups(a_World, a_Digger, a_BlockX, a_BlockY, a_BlockZ, a_BlockType, a_BlockMeta, a_Pickups) - if (a_Digger ~= nil) then - -- Not a natural cause - return false; - end - if (a_BlockType ~= E_BLOCK_TALL_GRASS) then - -- Not a tall grass being washed away - return false; - end - - -- Remove all pickups suggested by MCServer: - a_Pickups:Clear(); - - -- Drop a diamond: - a_Pickups:Add(cItem(E_ITEM_DIAMOND)); - return true; -end; - ]], - }, - } , -- CodeExamples - }, -- HOOK_BLOCK_TO_PICKUPS - - HOOK_CHAT = - { - CalledWhen = "Player sends a chat message", - DefaultFnName = "OnChat", -- also used as pagename - Desc = [[ - A plugin may implement an OnChat() function and register it as a Hook to process chat messages from - the players. The function is then called for every in-game message sent from any player. Note that - commands are handled separately using a command framework API. - ]], - Params = { - { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who sent the message" }, - { Name = "Message", Type = "string", Notes = "The message" }, - }, - Returns = [[ - The plugin may return 2 values. The first is a boolean specifying whether the hook handling is to be - stopped or not. If it is false, the message is broadcast to all players in the world. If it is true, - no message is broadcast and no further action is taken.

-

- The second value is specifies the message to broadcast. This way, plugins may modify the message. If - 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 - - 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.

-

- See also the {{OnChunkGenerating|HOOK_CHUNK_GENERATING}} 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. 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. - ]], - 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 - - 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 - - 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 - - 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 - - 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 - - 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 - - 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 - - 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 - - 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 {{OnExploding|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 - - 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 {{OnExploded|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 - - 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 - - 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 {{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 = - { - { 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 - - 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 - - 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 - - HOOK_LOGIN = - { - CalledWhen = "Right before 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 - - 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 - - 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 - - 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 - - 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 - - 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 - - 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 - - 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 - - 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 - - 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_PLAYER_RIGHT_CLICKING_ENTITY = - { - CalledWhen = "A player has right-clicked an entity. Plugins may override / refuse.", - DefaultFnName = "OnPlayerRightClickingEntity", -- also used as pagename - Desc = [[ - This hook is called when the {{cPlayer|player}} right-clicks an {{cEntity|entity}}. Plugins may - override the default behavior or even cancel the default processing. - ]], - Params = - { - { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who has right-clicked the entity" }, - { Name = "Entity", Type = "{{cEntity}} descendant", Notes = "The entity that has been right-clicked" }, - }, - Returns = [[ - If the functino returns false or no value, MCServer calls other plugins' callbacks and finally does - the default processing for the right-click. If the function returns true, no other callbacks are - called and the default processing is skipped. - ]], - }, -- HOOK_PLAYER_RIGHT_CLICKING_ENTITY - - HOOK_PLAYER_SHOOTING = - { - CalledWhen = "When the player releases the bow, shooting an arrow (other projectiles: unknown)", - DefaultFnName = "OnPlayerShooting", -- also used as pagename - Desc = [[ - This hook is called when the {{cPlayer|player}} shoots their bow. It is called for the actual - release of the {{cArrowEntity|arrow}}. FIXME: It is currently unknown whether other - {{cProjectileEntity|projectiles}} (snowballs, eggs) trigger this hook.

-

- To get the player's position and direction, use the {{cPlayer}}:GetEyePosition() and - cPlayer:GetLookVector() functions. Note that for shooting a bow, the position for the arrow creation - is not at the eye pos, some adjustments are required. FIXME: Export the {{cPlayer}} function for - this adjustment. - ]], - Params = - { - { Name = "Player", Type = "{{cPlayer}}", Notes = "The player shooting" }, - }, - Returns = [[ - If the function returns false or no value, the next plugin's callback is called, and finally - MCServer creates the projectile. If the functino returns true, no other callback is called and no - projectile is created. - ]], - }, -- HOOK_PLAYER_SHOOTING - - HOOK_PLAYER_SPAWNED = - { - CalledWhen = "After a player (re)spawns in the world to which they belong to.", - DefaultFnName = "OnPlayerSpawned", -- also used as pagename - Desc = [[ - This hook is called after a {{cPlayer|player}} has spawned in the world. It is called after - {{OnLogin|HOOK_LOGIN}} and {{OnPlayerJoined|HOOK_PLAYER_JOINED}}, after the player name has been - authenticated, the initial worldtime, inventory and health have been sent to the player and the - player spawn packet has been broadcast to all players near enough to the player spawn place. This is - a notification-only event, plugins wishing to refuse player's entry should kick the player using the - {{cPlayer}}:Kick() function.

-

- This hook is also called when the player respawns after death (and a respawn packet is received from - the client, meaning the player has already clicked the Respawn button). - ]], - Params = - { - { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who has (re)spawned" }, - }, - 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. There is no overridable behavior. - ]], - }, -- HOOK_PLAYER_SPAWNED - - HOOK_PLAYER_TOSSING_ITEM = - { - CalledWhen = "A player is tossing an item. Plugin may override / refuse.", - DefaultFnName = "OnPlayerTossingItem", -- also used as pagename - Desc = [[ - This hook is called when a {{cPlayer|player}} has tossed an item (Q keypress). The - {{cPickup|pickup}} has not been spawned yet. Plugins may disallow the tossing, but in that case they - need to clean up - the player's client already thinks the item has been tossed so the - {{cInventory|inventory}} needs to be re-sent to the player.

-

- To get the item that is about to be tossed, call the {{cPlayer}}:GetEquippedItem() function. - ]], - Params = - { - { Name = "Player", Type = "{{cPlayer}}", Notes = "The player tossing an item" }, - }, - Returns = [[ - If the function returns false or no value, other plugins' callbacks are called and finally MCServer - creates the pickup for the item and tosses it, using {{cPlayer}}:TossItem. If the function returns - true, no other callbacks are called for this event and MCServer doesn't toss the item. - ]], - }, -- HOOK_PLAYER_TOSSING_ITEM - - HOOK_PLAYER_USED_BLOCK = - { - CalledWhen = "A player has just used a block (chest, furnace…). Notification only.", - DefaultFnName = "OnPlayerUsedBlock", -- also used as pagename - Desc = [[ - This hook is called after a {{cPlayer|player}} has right-clicked a block that can be used, such as a - {{cChestEntity|chest}} or a lever. It is called after MCServer processes the usage (sends the UI - handling packets / toggles redstone). Note that for UI-related blocks, the player is most likely - still using the UI. This is a notification-only event.

-

- Note that the block coords given in this callback are for the (solid) block that is being clicked, - not the air block between it and the player.

-

- To get the world at which the right-click occurred, use the {{cPlayer}}:GetWorld() function.

-

- See also the {{OnPlayerUsingBlock|HOOK_PLAYER_USING_BLOCK}} for a similar hook called before the - use, the {{OnPlayerUsingItem|HOOK_PLAYER_USING_ITEM}} and {{OnPlayerUsedItem|HOOK_PLAYER_USED_ITEM}} - for similar hooks called when a player interacts with any block with a usable item in hand, such as - a bucket. - ]], - Params = - { - { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who used the block" }, - { Name = "BlockX", Type = "number", Notes = "X-coord of the clicked block" }, - { Name = "BlockY", Type = "number", Notes = "Y-coord of the clicked block" }, - { Name = "BlockZ", Type = "number", Notes = "Z-coord of the clicked block" }, - { Name = "BlockFace", Type = "number", Notes = "Face of clicked block which has been clicked. One of the BLOCK_FACE_ constants" }, - { Name = "CursorX", Type = "number", Notes = "X-coord of the cursor crosshair on the block being clicked" }, - { Name = "CursorY", Type = "number", Notes = "Y-coord of the cursor crosshair on the block being clicked" }, - { Name = "CursorZ", Type = "number", Notes = "Z-coord of the cursor crosshair on the block being clicked" }, - { Name = "BlockType", Type = "number", Notes = "Block type of the clicked block" }, - { Name = "BlockMeta", Type = "number", Notes = "Block meta of the clicked block" }, - }, - 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. - ]], - }, -- HOOK_PLAYER_USED_BLOCK - - HOOK_PLAYER_USED_ITEM = - { - CalledWhen = "A player has used an item in hand (bucket...)", - DefaultFnName = "OnPlayerUsedItem", -- also used as pagename - Desc = [[ - This hook is called after a {{cPlayer|player}} has right-clicked a block with an {{cItem|item}} that - can be used (is not placeable, is not food and clicked block is not use-able), such as a bucket or a - hoe. It is called after MCServer processes the usage (places fluid / turns dirt to farmland). - This is an information-only hook, there is no way to cancel the event anymore.

-

- Note that the block coords given in this callback are for the (solid) block that is being clicked, - not the air block between it and the player.

-

- To get the world at which the right-click occurred, use the {{cPlayer}}:GetWorld() function. To get - the item that the player is using, use the {{cPlayer}}:GetEquippedItem() function.

-

- See also the {{OnPlayerUsingItem|HOOK_PLAYER_USING_ITEM}} for a similar hook called before the use, - the {{OnPlayerUsingBlock|HOOK_PLAYER_USING_BLOCK}} and {{OnPlayerUsedBlock|HOOK_PLAYER_USED_BLOCK}} - for similar hooks called when a player interacts with a block, such as a chest. - ]], - Params = - { - { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who used the item" }, - { Name = "BlockX", Type = "number", Notes = "X-coord of the clicked block" }, - { Name = "BlockY", Type = "number", Notes = "Y-coord of the clicked block" }, - { Name = "BlockZ", Type = "number", Notes = "Z-coord of the clicked block" }, - { Name = "BlockFace", Type = "number", Notes = "Face of clicked block which has been clicked. One of the BLOCK_FACE_ constants" }, - { Name = "CursorX", Type = "number", Notes = "X-coord of the cursor crosshair on the block being clicked" }, - { Name = "CursorY", Type = "number", Notes = "Y-coord of the cursor crosshair on the block being clicked" }, - { Name = "CursorZ", Type = "number", Notes = "Z-coord of the cursor crosshair on the block being clicked" }, - { Name = "BlockType", Type = "number", Notes = "Block type of the clicked block" }, - { Name = "BlockMeta", Type = "number", Notes = "Block meta of the clicked block" }, - }, - 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. - ]], - }, -- HOOK_PLAYER_USED_ITEM - - HOOK_PLAYER_USING_BLOCK = - { - CalledWhen = "Just before a player uses a block (chest, furnace...). Plugin may override / refuse.", - DefaultFnName = "OnPlayerUsingBlock", -- also used as pagename - Desc = [[ - This hook is called when a {{cPlayer|player}} has right-clicked a block that can be used, such as a - {{cChestEntity|chest}} or a lever. It is called before MCServer processes the usage (sends the UI - handling packets / toggles redstone). Plugins may refuse the interaction by returning true.

-

- Note that the block coords given in this callback are for the (solid) block that is being clicked, - not the air block between it and the player.

-

- To get the world at which the right-click occurred, use the {{cPlayer}}:GetWorld() function.

-

- See also the {{OnPlayerUsedBlock|HOOK_PLAYER_USED_BLOCK}} for a similar hook called after the use, the - {{OnPlayerUsingItem|HOOK_PLAYER_USING_ITEM}} and {{OnPlayerUsedItem|HOOK_PLAYER_USED_ITEM}} for - similar hooks called when a player interacts with any block with a usable item in hand, such as a - bucket. - ]], - Params = - { - { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who is using the block" }, - { Name = "BlockX", Type = "number", Notes = "X-coord of the clicked block" }, - { Name = "BlockY", Type = "number", Notes = "Y-coord of the clicked block" }, - { Name = "BlockZ", Type = "number", Notes = "Z-coord of the clicked block" }, - { Name = "BlockFace", Type = "number", Notes = "Face of clicked block which has been clicked. One of the BLOCK_FACE_ constants" }, - { Name = "CursorX", Type = "number", Notes = "X-coord of the cursor crosshair on the block being clicked" }, - { Name = "CursorY", Type = "number", Notes = "Y-coord of the cursor crosshair on the block being clicked" }, - { Name = "CursorZ", Type = "number", Notes = "Z-coord of the cursor crosshair on the block being clicked" }, - { Name = "BlockType", Type = "number", Notes = "Block type of the clicked block" }, - { Name = "BlockMeta", Type = "number", Notes = "Block meta of the clicked block" }, - }, - Returns = [[ - If the function returns false or no value, other plugins' callbacks are called and then MCServer - processes the interaction. If the function returns true, no other callbacks are called for this - event and the interaction is silently dropped. - ]], - }, -- HOOK_PLAYER_USING_BLOCK - - HOOK_PLAYER_USING_ITEM = - { - CalledWhen = "Just before a player uses an item in hand (bucket...). Plugin may override / refuse.", - DefaultFnName = "OnPlayerUsingItem", -- also used as pagename - Desc = [[ - This hook is called when a {{cPlayer|player}} has right-clicked a block with an {{cItem|item}} that - can be used (is not placeable, is not food and clicked block is not use-able), such as a bucket or a - hoe. It is called before MCServer processes the usage (places fluid / turns dirt to farmland). - Plugins may refuse the interaction by returning true.

-

- Note that the block coords given in this callback are for the (solid) block that is being clicked, - not the air block between it and the player.

-

- To get the world at which the right-click occurred, use the {{cPlayer}}:GetWorld() function. To get - the item that the player is using, use the {{cPlayer}}:GetEquippedItem() function.

-

- See also the {{OnPlayerUsedItem|HOOK_PLAYER_USED_ITEM}} for a similar hook called after the use, the - {{OnPlayerUsingBlock|HOOK_PLAYER_USING_BLOCK}} and {{OnPlayerUsedBlock|HOOK_PLAYER_USED_BLOCK}} for - similar hooks called when a player interacts with a block, such as a chest. - ]], - Params = - { - { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who is using the item" }, - { Name = "BlockX", Type = "number", Notes = "X-coord of the clicked block" }, - { Name = "BlockY", Type = "number", Notes = "Y-coord of the clicked block" }, - { Name = "BlockZ", Type = "number", Notes = "Z-coord of the clicked block" }, - { Name = "BlockFace", Type = "number", Notes = "Face of clicked block which has been clicked. One of the BLOCK_FACE_ constants" }, - { Name = "CursorX", Type = "number", Notes = "X-coord of the cursor crosshair on the block being clicked" }, - { Name = "CursorY", Type = "number", Notes = "Y-coord of the cursor crosshair on the block being clicked" }, - { Name = "CursorZ", Type = "number", Notes = "Z-coord of the cursor crosshair on the block being clicked" }, - { Name = "BlockType", Type = "number", Notes = "Block type of the clicked block" }, - { Name = "BlockMeta", Type = "number", Notes = "Block meta of the clicked block" }, - }, - Returns = [[ - If the function returns false or no value, other plugins' callbacks are called and then MCServer - processes the interaction. If the function returns true, no other callbacks are called for this - event and the interaction is silently dropped. - ]], - }, -- HOOK_PLAYER_USING_ITEM - - 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 - - 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 - - HOOK_SPAWNED_ENTITY = - { - CalledWhen = "After an entity is spawned in the world.", - DefaultFnName = "OnSpawnedEntity", -- also used as pagename - 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.

-

- See also the {{OnSpawningEntity|HOOK_SPAWNING_ENTITY}} hook for a similar hook called before the - entity is spawned. - ]], - 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 - - 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.

-

- See also the {{OnSpawningMonster|HOOK_SPAWNING_MONSTER}} hook for a similar hook called before the - monster is spawned. - ]], - 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 - - 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 - - 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 - - HOOK_TAKE_DAMAGE = - { - CalledWhen = "An {{cEntity|entity}} is taking any kind of damage", - DefaultFnName = "OnTakeDamage", -- also used as pagename - Desc = [[ - This hook is called when any {{cEntity}} descendant, such as a {{cPlayer|player}} or a - {{cMonster|mob}}, takes any kind of damage. The plugins may modify the amount of damage or effects - with this hook by editting the {{TakeDamageInfo}} object passed.

-

- This hook is called after the final damage is calculated, including all the possible weapon - {{cEnchantments|enchantments}}, armor protection and potion effects. - ]], - Params = - { - { Name = "Receiver", Type = "{{cEntity}} descendant", Notes = "The entity taking damage" }, - { Name = "TDI", Type = "{{TakeDamageInfo}}", Notes = "The damage type, cause and effects. Plugins may modify this object to alter the final damage applied." }, - }, - Returns = [[ - If the function returns false or no value, other plugins' callbacks are called and then the server - applies the final values from the TDI object to Receiver. If the function returns true, no other - callbacks are called, and no damage nor effects are applied. - ]], - }, -- HOOK_TAKE_DAMAGE - - HOOK_TICK = - { - CalledWhen = "Every server tick (approximately 20 times per second)", - DefaultFnName = "OnTick", -- also used as pagename - Desc = [[ - This hook is called every game tick (50 msec, or 20 times a second). If the server is overloaded, - the interval is larger, which is indicated by the TimeDelta parameter.

-

- This hook is called in the context of the server-tick thread, that is, the thread that takes care of - {{cClientHandle|client connections}} before they're assigned to {{cPlayer|player entities}}, and - processing console commands. - ]], - Params = - { - { Name = "TimeDelta", Type = "number", Notes = "The number of milliseconds elapsed since the last server tick. Will not be less than 50 msec." }, - }, - Returns = [[ - If the function returns false or no value, other plugins' callbacks are called. If the function - returns true, no other callbacks are called. There is no overridable behavior. - ]], - }, -- HOOK_TICK - - HOOK_UPDATED_SIGN = - { - CalledWhen = "After the sign text is updated. Notification only.", - DefaultFnName = "OnUpdatedSign", -- also used as pagename - Desc = [[ - This hook is called after a sign has had its text updated. The text is already updated at this - point.

-

The update may have been caused either by a {{cPlayer|player}} directly updating the sign, or by - a plugin changing the sign text using the API.

-

- See also the {{OnUpdatingSign|HOOK_UPDATING_SIGN}} hook for a similar hook called before the update, - with a chance to modify the text. - ]], - Params = - { - { Name = "World", Type = "{{cWorld}}", Notes = "The world in which the sign resides" }, - { Name = "BlockX", Type = "number", Notes = "X-coord of the sign" }, - { Name = "BlockY", Type = "number", Notes = "Y-coord of the sign" }, - { Name = "BlockZ", Type = "number", Notes = "Z-coord of the sign" }, - { Name = "Line1", Type = "string", Notes = "1st line of the new text" }, - { Name = "Line2", Type = "string", Notes = "2nd line of the new text" }, - { Name = "Line3", Type = "string", Notes = "3rd line of the new text" }, - { Name = "Line4", Type = "string", Notes = "4th line of the new text" }, - { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who is changing the text. May be nil for non-player updates." } - }, - Returns = [[ - If the function returns false or no value, other plugins' callbacks are called. If the function - returns true, no other callbacks are called. There is no overridable behavior. - ]], - }, -- HOOK_UPDATED_SIGN - HOOK_UPDATING_SIGN = - { - CalledWhen = "Before the sign text is updated. Plugin may modify the text / refuse.", - DefaultFnName = "OnUpdatingSign", -- also used as pagename - Desc = [[ - This hook is called when a sign text is about to be updated, either as a result of player's - manipulation or any other event, such as a plugin setting the sign text. Plugins may modify the text - or refuse the update altogether.

-

- See also the {{OnUpdatedSign|HOOK_UPDATED_SIGN}} hook for a similar hook called after the update. - ]], - Params = - { - { Name = "World", Type = "{{cWorld}}", Notes = "The world in which the sign resides" }, - { Name = "BlockX", Type = "number", Notes = "X-coord of the sign" }, - { Name = "BlockY", Type = "number", Notes = "Y-coord of the sign" }, - { Name = "BlockZ", Type = "number", Notes = "Z-coord of the sign" }, - { Name = "Line1", Type = "string", Notes = "1st line of the new text" }, - { Name = "Line2", Type = "string", Notes = "2nd line of the new text" }, - { Name = "Line3", Type = "string", Notes = "3rd line of the new text" }, - { Name = "Line4", Type = "string", Notes = "4th line of the new text" }, - { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who is changing the text. May be nil for non-player updates." } - }, - Returns = [[ - The function may return up to five values. If the function returns true as the first value, no other - callbacks are called for this event and the sign is not updated. If the function returns no value or - false as its first value, other plugins' callbacks are called.

-

- The other up to four values returned are used to update the sign text, line by line, respectively. - Note that other plugins may again update the texts (if the first value returned is false). - ]], - CodeExamples = - { - { - Title = "Add player signature", - Desc = "The following example appends a player signature to the last line, if the sign is updated by a player:", - Code = [[ -function OnUpdatingSign(World, BlockX, BlockY, BlockZ, Line1, Line2, Line3, Line4, Player) - if (Player == nil) then - -- Not changed by a player - return false; - end - - -- Sign with playername, allow other plugins to interfere: - return false, Line1, Line2, Line3, Line4 .. Player:GetName(); -end - ]], - } - } , - }, -- HOOK_UPDATING_SIGN - - HOOK_WEATHER_CHANGED = - { - CalledWhen = "The weather has changed", - DefaultFnName = "OnWeatherChanged", -- also used as pagename - Desc = [[ - This hook is called after the weather has changed in a {{cWorld|world}}. The new weather has already - been sent to the clients.

-

- See also the {{OnWeatherChanging|HOOK_WEATHER_CHANGING}} hook for a similar hook called before the - change. - ]], - Params = - { - { Name = "World", Type = "{{cWorld}}", Notes = "World for which the weather has changed" }, - }, - 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 behavior. - ]], - }, -- HOOK_WEATHER_CHANGED - - HOOK_WEATHER_CHANGING = - { - CalledWhen = "The weather is about to change", - DefaultFnName = "OnWeatherChanging", -- also used as pagename - Desc = [[ - This hook is called when the current weather has expired and a new weather is selected. Plugins may - override the new weather setting.

-

- The new weather setting is sent to the clients only after this hook has been processed.

-

- See also the {{OnWeatherChanged|HOOK_WEATHER_CHANGED}} hook for a similar hook called after the - change. - ]], - Params = - { - { Name = "World", Type = "{{cWorld}}", Notes = "World for which the weather is changing" }, - { Name = "Weather", Type = "number", Notes = "The newly selected weather. One of wSunny, wRain, wStorm" }, - }, - Returns = [[ - If the function returns false or no value, the server calls other plugins' callbacks and finally - sets the weather. If the function returns true, the server takes the second returned value (wSunny - by default) and sets it as the new weather. No other plugins' callbacks are called in this case. - ]], - }, -- HOOK_WEATHER_CHANGING - - HOOK_WORLD_TICK = - { - CalledWhen = "Every world tick (about 20 times per second), separately for each world", - DefaultFnName = "OnWorldTick", -- also used as pagename - Desc = [[ - This hook is called for each {{cWorld|world}} every tick (50 msec, or 20 times a second). If the - world is overloaded, the interval is larger, which is indicated by the TimeDelta parameter.

-

- This hook is called in the world's tick thread context and thus has access to all world data - guaranteed without blocking. - ]], - Params = - { - { Name = "World", Type = "{{cWorld}}", Notes = "World that is ticking" }, - { Name = "TimeDelta", Type = "number", Notes = "The number of milliseconds since the previous game tick. Will not be less than 50 msec" }, - }, - 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 behavior. - ]], - }, -- HOOK_WORLD_TICK - - }, -- Hooks[] - - IgnoreClasses = { "coroutine", @@ -4518,4 +2838,3 @@ end - diff --git a/MCServer/Plugins/APIDump/Classes/BlockEntities.lua b/MCServer/Plugins/APIDump/Classes/BlockEntities.lua new file mode 100644 index 000000000..cf258160c --- /dev/null +++ b/MCServer/Plugins/APIDump/Classes/BlockEntities.lua @@ -0,0 +1,243 @@ +return +{ + cBlockEntity = + { + Desc = [[ + Block entities are simply blocks in the world that have persistent data, such as the text for a sign + or contents of a chest. All block entities are also saved in the chunk data of the chunk they reside in. + The cBlockEntity class acts as a common ancestor for all the individual block entities. + ]], + + Functions = + { + GetBlockType = { Params = "", Return = "BLOCKTYPE", Notes = "Returns the blocktype which is represented by this blockentity. This is the primary means of type-identification" }, + GetChunkX = { Params = "", Return = "number", Notes = "Returns the chunk X-coord of the block entity's chunk" }, + GetChunkZ = { Params = "", Return = "number", Notes = "Returns the chunk Z-coord of the block entity's chunk" }, + GetPosX = { Params = "", Return = "number", Notes = "Returns the block X-coord of the block entity's block" }, + GetPosY = { Params = "", Return = "number", Notes = "Returns the block Y-coord of the block entity's block" }, + GetPosZ = { Params = "", Return = "number", Notes = "Returns the block Z-coord of the block entity's block" }, + GetRelX = { Params = "", Return = "number", Notes = "Returns the relative X coord of the block entity's block within the chunk" }, + GetRelZ = { Params = "", Return = "number", Notes = "Returns the relative Z coord of the block entity's block within the chunk" }, + GetWorld = { Params = "", Return = "{{cWorld|cWorld}}", Notes = "Returns the world to which the block entity belongs" }, + }, + }, + + cBlockEntityWithItems = + { + Desc = [[ + This class is a common ancestor for all {{cBlockEntity|block entities}} that provide item storage. + Internally, the object has a {{cItemGrid|cItemGrid}} object for storing the items; this ItemGrid is + accessible through the API. The storage is a grid of items, items in it can be addressed either by a slot + number, or by XY coords within the grid. If a UI window is opened for this block entity, the item storage + is monitored for changes and the changes are immediately sent to clients of the UI window. + ]], + + Inherits = "cBlockEntity", + + Functions = + { + GetContents = { Params = "", Return = "{{cItemGrid|cItemGrid}}", Notes = "Returns the cItemGrid object representing the items stored within this block entity" }, + GetSlot = + { + { Params = "SlotNum", Return = "{{cItem|cItem}}", Notes = "Returns the cItem for the specified slot number. Returns nil for invalid slot numbers" }, + { Params = "X, Y", Return = "{{cItem|cItem}}", Notes = "Returns the cItem for the specified slot coords. Returns nil for invalid slot coords" }, + }, + SetSlot = + { + { Params = "SlotNum, {{cItem|cItem}}", Return = "", Notes = "Sets the cItem for the specified slot number. Ignored if invalid slot number" }, + { Params = "X, Y, {{cItem|cItem}}", Return = "", Notes = "Sets the cItem for the specified slot coords. Ignored if invalid slot coords" }, + }, + }, + }, + + cChestEntity = + { + Desc = [[ + A chest entity is a {{cBlockEntityWithItems|cBlockEntityWithItems}} descendant that represents a chest + in the world. Note that doublechests consist of two separate cChestEntity objects, they do not collaborate + in any way.

+

+ To manipulate a chest already in the game, you need to use {{cWorld}}'s callback mechanism with + either DoWithChestAt() or ForEachChestInChunk() function. See the code example below + ]], + + Inherits = "cBlockEntityWithItems", + + Constants = + { + ContentsHeight = { Notes = "Height of the contents' {{cItemGrid|ItemGrid}}, as required by the parent class, {{cBlockEntityWithItems}}" }, + ContentsWidth = { Notes = "Width of the contents' {{cItemGrid|ItemGrid}}, as required by the parent class, {{cBlockEntityWithItems}}" }, + }, + AdditionalInfo = + { + { + Header = "Code example", + Contents = [[ + The following example code sets the top-left item of each chest in the same chunk as Player to + 64 * diamond: +

+-- Player is a {{cPlayer}} object instance
+local World = Player:GetWorld();
+World:ForEachChestInChunk(Player:GetChunkX(), Player:GetChunkZ(),
+	function (ChestEntity)
+		ChestEntity:SetSlot(0, 0, cItem(E_ITEM_DIAMOND, 64));
+	end
+);
+
+ ]], + }, + }, -- AdditionalInfo + }, + + cDispenserEntity = + { + Desc = [[ + This class represents a dispenser block entity in the world. Most of this block entity's + functionality is implemented in the {{cDropSpenserEntity|cDropSpenserEntity}} class that represents + the behavior common with a {{cDropperEntity|dropper}} entity. + ]], + Inherits = "cDropSpenserEntity", + }, + + cDropperEntity = + { + Desc = [[ + This class represents a dropper block entity in the world. Most of this block entity's functionality + is implemented in the {{cDropSpenserEntity|cDropSpenserEntity}} class that represents the behavior + common with the {{cDispenserEntity|dispenser}} entity.

+

+ An object of this class can be created from scratch when generating chunks ({{OnChunkGenerated|OnChunkGenerated}} and {{OnChunkGenerating|OnChunkGenerating}} hooks). + ]], + Inherits = "cDropSpenserEntity", + }, -- cDropperEntity + + cDropSpenserEntity = + { + Desc = [[ + This is a class that implements behavior common to both {{cDispenserEntity|dispensers}} and {{cDropperEntity|droppers}}. + ]], + Functions = + { + Activate = { Params = "", Return = "", Notes = "Sets the block entity to dropspense an item in the next tick" }, + AddDropSpenserDir = { Params = "BlockX, BlockY, BlockZ, BlockMeta", Return = "BlockX, BlockY, BlockZ", Notes = "Adjusts the block coords to where the dropspenser items materialize" }, + SetRedstonePower = { Params = "IsPowered", Return = "", Notes = "Sets the redstone status of the dropspenser. If the redstone power goes from off to on, the dropspenser will be activated" }, + }, + Constants = + { + ContentsWidth = { Notes = "Width (X) of the {{cItemGrid}} representing the contents" }, + ContentsHeight = { Notes = "Height (Y) of the {{cItemGrid}} representing the contents" }, + }, + Inherits = "cBlockEntityWithItems"; + }, -- cDropSpenserEntity + + cFurnaceEntity = + { + Desc = [[ + This class represents a furnace block entity in the world.

+

+ See also {{cRoot}}'s GetFurnaceRecipe() and GetFurnaceFuelBurnTime() functions + ]], + Functions = + { + GetCookTimeLeft = { Params = "", Return = "number", Notes = "Returns the time until the current item finishes cooking, in ticks" }, + GetFuelBurnTimeLeft = { Params = "", Return = "number", Notes = "Returns the time until the current fuel is depleted, in ticks" }, + GetFuelSlot = { Params = "", Return = "{{cItem|cItem}}", Notes = "Returns the item in the fuel slot" }, + GetInputSlot = { Params = "", Return = "{{cItem|cItem}}", Notes = "Returns the item in the input slot" }, + GetOutputSlot = { Params = "", Return = "{{cItem|cItem}}", Notes = "Returns the item in the output slot" }, + GetTimeCooked = { Params = "", Return = "number", Notes = "Returns the time that the current item has been cooking, in ticks" }, + HasFuelTimeLeft = { Params = "", Return = "bool", Notes = "Returns true if there's time before the current fuel is depleted" }, + SetFuelSlot = { Params = "{{cItem|cItem}}", Return = "", Notes = "Sets the item in the fuel slot" }, + SetInputSlot = { Params = "{{cItem|cItem}}", Return = "", Notes = "Sets the item in the input slot" }, + SetOutputSlot = { Params = "{{cItem|cItem}}", Return = "", Notes = "Sets the item in the output slot" }, + }, + Constants = + { + fsInput = { Notes = "Index of the input slot" }, + fsFuel = { Notes = "Index of the fuel slot" }, + fsOutput = { Notes = "Index of the output slot" }, + ContentsWidth = { Notes = "Width (X) of the {{cItemGrid|cItemGrid}} representing the contents" }, + ContentsHeight = { Notes = "Height (Y) of the {{cItemGrid|cItemGrid}} representing the contents" }, + }, + ConstantGroups = + { + SlotIndices = + { + Include = "fs.*", + TextBefore = "When using the GetSlot() or SetSlot() function, use these constants for slot index:", + }, + }, + Inherits = "cBlockEntityWithItems" + }, -- cFurnaceEntity + + cHopperEntity = + { + Desc = [[ + This class represents a hopper block entity in the world. + ]], + Functions = + { + GetOutputBlockPos = { Params = "BlockMeta", Return = "bool, BlockX, BlockY, BlockZ", Notes = "Returns whether the hopper is attached, and if so, the block coords of the block receiving the output items, based on the given meta." }, + }, + Constants = + { + ContentsHeight = { Notes = "Height (Y) of the internal {{cItemGrid}} representing the hopper contents." }, + ContentsWidth = { Notes = "Width (X) of the internal {{cItemGrid}} representing the hopper contents." }, + TICKS_PER_TRANSFER = { Notes = "Number of ticks between when the hopper transfers items." }, + }, + Inherits = "cBlockEntityWithItems", + }, -- cHopperEntity + + cJukeboxEntity = + { + Desc = [[ + This class represents a jukebox in the world. It can play the records, either when the + {{cPlayer|player}} uses the record on the jukebox, or when a plugin instructs it to play. + ]], + Inherits = "cBlockEntity", + Functions = + { + EjectRecord = { Params = "", Return = "", Notes = "Ejects the current record as a {{cPickup|pickup}}. No action if there's no current record. To remove record without generating the pickup, use SetRecord(0)" }, + GetRecord = { Params = "", Return = "number", Notes = "Returns the record currently present. Zero for no record, E_ITEM_*_DISC for records." }, + PlayRecord = { Params = "", Return = "", Notes = "Plays the currently present record. No action if there's no current record." }, + SetRecord = { Params = "number", Return = "", Notes = "Sets the currently present record. Use zero for no record, or E_ITEM_*_DISC for records." }, + }, + }, -- cJukeboxEntity + + cNoteEntity = + { + Desc = [[ + This class represents a note block entity in the world. It takes care of the note block's pitch, + and also can play the sound, either when the {{cPlayer|player}} right-clicks it, redstone activates + it, or upon a plugin's request.

+

+ The pitch is stored as an integer between 0 and 24. + ]], + Functions = + { + GetPitch = { Params = "", Return = "number", Notes = "Returns the current pitch set for the block" }, + IncrementPitch = { Params = "", Return = "", Notes = "Adds 1 to the current pitch. Wraps around to 0 when the pitch cannot go any higher." }, + MakeSound = { Params = "", Return = "", Notes = "Plays the sound for all {{cClientHandle|clients}} near this block." }, + SetPitch = { Params = "Pitch", Return = "", Notes = "Sets a new pitch for the block." }, + }, + Inherits = "cBlockEntity", + }, -- cNoteEntity + + cSignEntity = + { + Desc = [[ + A sign entity represents a sign in the world. This class is only used when generating chunks, so + that the plugins may generate signs within new chunks. See the code example in {{cChunkDesc}}. + ]], + Functions = + { + GetLine = { Params = "LineIndex", Return = "string", Notes = "Returns the specified line. LineIndex is expected between 0 and 3. Returns empty string and logs to server console when LineIndex is invalid." }, + SetLine = { Params = "LineIndex, LineText", Return = "", Notes = "Sets the specified line. LineIndex is expected between 0 and 3. Logs to server console when LineIndex is invalid." }, + SetLines = { Params = "Line1, Line2, Line3, Line4", Return = "", Notes = "Sets all the sign's lines at once." }, + }, + Inherits = "cBlockEntity"; + }, -- cSignEntity +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnBlockToPickups.lua b/MCServer/Plugins/APIDump/Hooks/OnBlockToPickups.lua new file mode 100644 index 000000000..e6f115f37 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnBlockToPickups.lua @@ -0,0 +1,62 @@ +return +{ + HOOK_BLOCK_TO_PICKUPS = + { + CalledWhen = "A block is about to be dug ({{cPlayer|player}}, {{cEntity|entity}} or natural reason), plugins may override what pickups that will produce.", + DefaultFnName = "OnBlockToPickups", -- also used as pagename + Desc = [[ + This callback gets called whenever a block is about to be dug. This includes {{cPlayer|players}} + digging blocks, entities causing blocks to disappear ({{cTNTEntity|TNT}}, Endermen) and natural + causes (water washing away a block). Plugins may override the amount and kinds of pickups this + action produces. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "The world in which the block resides" }, + { Name = "Digger", Type = "{{cEntity}} descendant", Notes = "The entity causing the digging. May be a {{cPlayer}}, {{cTNTEntity}} or even nil (natural causes)" }, + { 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 = "BlockType", Type = "BLOCKTYPE", Notes = "Block type of the block" }, + { Name = "BlockMeta", Type = "NIBBLETYPE", Notes = "Block meta of the block" }, + { Name = "Pickups", Type = "{{cItems}}", Notes = "Items that will be spawned as pickups" }, + }, + Returns = [[ + If the function returns false or no value, the next callback in the hook chain will be called. If + the function returns true, no other callbacks in the chain will be called.

+

+ Either way, the server will then spawn pickups specified in the Pickups parameter, so to disable + pickups, you need to Clear the object first, then return true. + ]], + CodeExamples = + { + { + Title = "Modify pickups", + Desc = "This example callback function makes tall grass drop diamonds when digged by natural causes (washed away by water).", + Code = [[ +function OnBlockToPickups(a_World, a_Digger, a_BlockX, a_BlockY, a_BlockZ, a_BlockType, a_BlockMeta, a_Pickups) + if (a_Digger ~= nil) then + -- Not a natural cause + return false; + end + if (a_BlockType ~= E_BLOCK_TALL_GRASS) then + -- Not a tall grass being washed away + return false; + end + + -- Remove all pickups suggested by MCServer: + a_Pickups:Clear(); + + -- Drop a diamond: + a_Pickups:Add(cItem(E_ITEM_DIAMOND)); + return true; +end; + ]], + }, + } , -- CodeExamples + }, -- HOOK_BLOCK_TO_PICKUPS +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnChat.lua b/MCServer/Plugins/APIDump/Hooks/OnChat.lua new file mode 100644 index 000000000..d98df008a --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnChat.lua @@ -0,0 +1,29 @@ +return +{ + HOOK_CHAT = + { + CalledWhen = "Player sends a chat message", + DefaultFnName = "OnChat", -- also used as pagename + Desc = [[ + A plugin may implement an OnChat() function and register it as a Hook to process chat messages from + the players. The function is then called for every in-game message sent from any player. Note that + commands are handled separately using a command framework API. + ]], + Params = { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who sent the message" }, + { Name = "Message", Type = "string", Notes = "The message" }, + }, + Returns = [[ + The plugin may return 2 values. The first is a boolean specifying whether the hook handling is to be + stopped or not. If it is false, the message is broadcast to all players in the world. If it is true, + no message is broadcast and no further action is taken.

+

+ The second value is specifies the message to broadcast. This way, plugins may modify the message. If + the second value is not provided, the original message is used. + ]], + }, -- HOOK_CHAT +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnChunkAvailable.lua b/MCServer/Plugins/APIDump/Hooks/OnChunkAvailable.lua new file mode 100644 index 000000000..61c191c57 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnChunkAvailable.lua @@ -0,0 +1,27 @@ +return +{ + 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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnChunkGenerated.lua b/MCServer/Plugins/APIDump/Hooks/OnChunkGenerated.lua new file mode 100644 index 000000000..b10dc36f5 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnChunkGenerated.lua @@ -0,0 +1,67 @@ +return +{ + 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.

+

+ See also the {{OnChunkGenerating|HOOK_CHUNK_GENERATING}} 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. 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. + ]], + 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 +} \ No newline at end of file diff --git a/MCServer/Plugins/APIDump/Hooks/OnChunkGenerating.lua b/MCServer/Plugins/APIDump/Hooks/OnChunkGenerating.lua new file mode 100644 index 000000000..0db0e2727 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnChunkGenerating.lua @@ -0,0 +1,35 @@ +return +{ + 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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnChunkUnloaded.lua b/MCServer/Plugins/APIDump/Hooks/OnChunkUnloaded.lua new file mode 100644 index 000000000..a67d5d461 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnChunkUnloaded.lua @@ -0,0 +1,28 @@ +return +{ + 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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnChunkUnloading.lua b/MCServer/Plugins/APIDump/Hooks/OnChunkUnloading.lua new file mode 100644 index 000000000..cd79e2a13 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnChunkUnloading.lua @@ -0,0 +1,30 @@ +return +{ + 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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnCollectingPickup.lua b/MCServer/Plugins/APIDump/Hooks/OnCollectingPickup.lua new file mode 100644 index 000000000..0a56df2c9 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnCollectingPickup.lua @@ -0,0 +1,32 @@ +return +{ + 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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnCraftingNoRecipe.lua b/MCServer/Plugins/APIDump/Hooks/OnCraftingNoRecipe.lua new file mode 100644 index 000000000..5137bbb25 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnCraftingNoRecipe.lua @@ -0,0 +1,32 @@ +return +{ + 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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnDisconnect.lua b/MCServer/Plugins/APIDump/Hooks/OnDisconnect.lua new file mode 100644 index 000000000..496e0d751 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnDisconnect.lua @@ -0,0 +1,32 @@ +return +{ + 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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnExecuteCommand.lua b/MCServer/Plugins/APIDump/Hooks/OnExecuteCommand.lua new file mode 100644 index 000000000..dadc4e94f --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnExecuteCommand.lua @@ -0,0 +1,31 @@ +return +{ + 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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnExploded.lua b/MCServer/Plugins/APIDump/Hooks/OnExploded.lua new file mode 100644 index 000000000..6a01542ab --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnExploded.lua @@ -0,0 +1,49 @@ +return +{ + 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 {{OnExploding|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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnExploding.lua b/MCServer/Plugins/APIDump/Hooks/OnExploding.lua new file mode 100644 index 000000000..729f2e162 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnExploding.lua @@ -0,0 +1,50 @@ +return +{ + 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 {{OnExploded|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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnHandshake.lua b/MCServer/Plugins/APIDump/Hooks/OnHandshake.lua new file mode 100644 index 000000000..6183cc506 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnHandshake.lua @@ -0,0 +1,29 @@ +return +{ + 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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnHopperPullingItem.lua b/MCServer/Plugins/APIDump/Hooks/OnHopperPullingItem.lua new file mode 100644 index 000000000..b268a76be --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnHopperPullingItem.lua @@ -0,0 +1,30 @@ +return +{ + 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 {{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 = + { + { 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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnHopperPushingItem.lua b/MCServer/Plugins/APIDump/Hooks/OnHopperPushingItem.lua new file mode 100644 index 000000000..bd5702518 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnHopperPushingItem.lua @@ -0,0 +1,30 @@ +return +{ + 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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnKilling.lua b/MCServer/Plugins/APIDump/Hooks/OnKilling.lua new file mode 100644 index 000000000..8ec1cfe2e --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnKilling.lua @@ -0,0 +1,33 @@ +return +{ + 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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnLogin.lua b/MCServer/Plugins/APIDump/Hooks/OnLogin.lua new file mode 100644 index 000000000..6859f9d11 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnLogin.lua @@ -0,0 +1,31 @@ +return +{ + HOOK_LOGIN = + { + CalledWhen = "Right before 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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerAnimation.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerAnimation.lua new file mode 100644 index 000000000..baf99834e --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerAnimation.lua @@ -0,0 +1,28 @@ +return +{ + 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 +} + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerBreakingBlock.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerBreakingBlock.lua new file mode 100644 index 000000000..18f19f247 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerBreakingBlock.lua @@ -0,0 +1,36 @@ +return +{ + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerBrokenBlock.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerBrokenBlock.lua new file mode 100644 index 000000000..e718c5d97 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerBrokenBlock.lua @@ -0,0 +1,36 @@ +return +{ + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerEating.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerEating.lua new file mode 100644 index 000000000..e77d02a96 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerEating.lua @@ -0,0 +1,27 @@ +return +{ + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerJoined.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerJoined.lua new file mode 100644 index 000000000..00805af7e --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerJoined.lua @@ -0,0 +1,29 @@ +return +{ + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerLeftClick.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerLeftClick.lua new file mode 100644 index 000000000..1d9585c55 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerLeftClick.lua @@ -0,0 +1,47 @@ +return +{ + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerMoving.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerMoving.lua new file mode 100644 index 000000000..2756529ef --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerMoving.lua @@ -0,0 +1,27 @@ +return +{ + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerPlacedBlock.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerPlacedBlock.lua new file mode 100644 index 000000000..54888a6db --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerPlacedBlock.lua @@ -0,0 +1,40 @@ +return +{ + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerPlacingBlock.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerPlacingBlock.lua new file mode 100644 index 000000000..2a928390b --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerPlacingBlock.lua @@ -0,0 +1,45 @@ +return +{ + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerRightClick.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerRightClick.lua new file mode 100644 index 000000000..d767b449d --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerRightClick.lua @@ -0,0 +1,37 @@ +return +{ + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerRightClickingEntity.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerRightClickingEntity.lua new file mode 100644 index 000000000..796622307 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerRightClickingEntity.lua @@ -0,0 +1,27 @@ +return +{ + HOOK_PLAYER_RIGHT_CLICKING_ENTITY = + { + CalledWhen = "A player has right-clicked an entity. Plugins may override / refuse.", + DefaultFnName = "OnPlayerRightClickingEntity", -- also used as pagename + Desc = [[ + This hook is called when the {{cPlayer|player}} right-clicks an {{cEntity|entity}}. Plugins may + override the default behavior or even cancel the default processing. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who has right-clicked the entity" }, + { Name = "Entity", Type = "{{cEntity}} descendant", Notes = "The entity that has been right-clicked" }, + }, + Returns = [[ + If the functino returns false or no value, MCServer calls other plugins' callbacks and finally does + the default processing for the right-click. If the function returns true, no other callbacks are + called and the default processing is skipped. + ]], + }, -- HOOK_PLAYER_RIGHT_CLICKING_ENTITY +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerShooting.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerShooting.lua new file mode 100644 index 000000000..aefae2c2f --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerShooting.lua @@ -0,0 +1,32 @@ +return +{ + HOOK_PLAYER_SHOOTING = + { + CalledWhen = "When the player releases the bow, shooting an arrow (other projectiles: unknown)", + DefaultFnName = "OnPlayerShooting", -- also used as pagename + Desc = [[ + This hook is called when the {{cPlayer|player}} shoots their bow. It is called for the actual + release of the {{cArrowEntity|arrow}}. FIXME: It is currently unknown whether other + {{cProjectileEntity|projectiles}} (snowballs, eggs) trigger this hook.

+

+ To get the player's position and direction, use the {{cPlayer}}:GetEyePosition() and + cPlayer:GetLookVector() functions. Note that for shooting a bow, the position for the arrow creation + is not at the eye pos, some adjustments are required. FIXME: Export the {{cPlayer}} function for + this adjustment. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player shooting" }, + }, + Returns = [[ + If the function returns false or no value, the next plugin's callback is called, and finally + MCServer creates the projectile. If the functino returns true, no other callback is called and no + projectile is created. + ]], + }, -- HOOK_PLAYER_SHOOTING +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerSpawned.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerSpawned.lua new file mode 100644 index 000000000..190909ee5 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerSpawned.lua @@ -0,0 +1,32 @@ +return +{ + HOOK_PLAYER_SPAWNED = + { + CalledWhen = "After a player (re)spawns in the world to which they belong to.", + DefaultFnName = "OnPlayerSpawned", -- also used as pagename + Desc = [[ + This hook is called after a {{cPlayer|player}} has spawned in the world. It is called after + {{OnLogin|HOOK_LOGIN}} and {{OnPlayerJoined|HOOK_PLAYER_JOINED}}, after the player name has been + authenticated, the initial worldtime, inventory and health have been sent to the player and the + player spawn packet has been broadcast to all players near enough to the player spawn place. This is + a notification-only event, plugins wishing to refuse player's entry should kick the player using the + {{cPlayer}}:Kick() function.

+

+ This hook is also called when the player respawns after death (and a respawn packet is received from + the client, meaning the player has already clicked the Respawn button). + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who has (re)spawned" }, + }, + 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. There is no overridable behavior. + ]], + }, -- HOOK_PLAYER_SPAWNED +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerTossingItem.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerTossingItem.lua new file mode 100644 index 000000000..85c943721 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerTossingItem.lua @@ -0,0 +1,30 @@ +return +{ + HOOK_PLAYER_TOSSING_ITEM = + { + CalledWhen = "A player is tossing an item. Plugin may override / refuse.", + DefaultFnName = "OnPlayerTossingItem", -- also used as pagename + Desc = [[ + This hook is called when a {{cPlayer|player}} has tossed an item (Q keypress). The + {{cPickup|pickup}} has not been spawned yet. Plugins may disallow the tossing, but in that case they + need to clean up - the player's client already thinks the item has been tossed so the + {{cInventory|inventory}} needs to be re-sent to the player.

+

+ To get the item that is about to be tossed, call the {{cPlayer}}:GetEquippedItem() function. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player tossing an item" }, + }, + Returns = [[ + If the function returns false or no value, other plugins' callbacks are called and finally MCServer + creates the pickup for the item and tosses it, using {{cPlayer}}:TossItem. If the function returns + true, no other callbacks are called for this event and MCServer doesn't toss the item. + ]], + }, -- HOOK_PLAYER_TOSSING_ITEM +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerUsedBlock.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerUsedBlock.lua new file mode 100644 index 000000000..4c91ea89e --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerUsedBlock.lua @@ -0,0 +1,46 @@ +return +{ + HOOK_PLAYER_USED_BLOCK = + { + CalledWhen = "A player has just used a block (chest, furnace…). Notification only.", + DefaultFnName = "OnPlayerUsedBlock", -- also used as pagename + Desc = [[ + This hook is called after a {{cPlayer|player}} has right-clicked a block that can be used, such as a + {{cChestEntity|chest}} or a lever. It is called after MCServer processes the usage (sends the UI + handling packets / toggles redstone). Note that for UI-related blocks, the player is most likely + still using the UI. This is a notification-only event.

+

+ Note that the block coords given in this callback are for the (solid) block that is being clicked, + not the air block between it and the player.

+

+ To get the world at which the right-click occurred, use the {{cPlayer}}:GetWorld() function.

+

+ See also the {{OnPlayerUsingBlock|HOOK_PLAYER_USING_BLOCK}} for a similar hook called before the + use, the {{OnPlayerUsingItem|HOOK_PLAYER_USING_ITEM}} and {{OnPlayerUsedItem|HOOK_PLAYER_USED_ITEM}} + for similar hooks called when a player interacts with any block with a usable item in hand, such as + a bucket. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who used the block" }, + { Name = "BlockX", Type = "number", Notes = "X-coord of the clicked block" }, + { Name = "BlockY", Type = "number", Notes = "Y-coord of the clicked block" }, + { Name = "BlockZ", Type = "number", Notes = "Z-coord of the clicked block" }, + { Name = "BlockFace", Type = "number", Notes = "Face of clicked block which has been clicked. One of the BLOCK_FACE_ constants" }, + { Name = "CursorX", Type = "number", Notes = "X-coord of the cursor crosshair on the block being clicked" }, + { Name = "CursorY", Type = "number", Notes = "Y-coord of the cursor crosshair on the block being clicked" }, + { Name = "CursorZ", Type = "number", Notes = "Z-coord of the cursor crosshair on the block being clicked" }, + { Name = "BlockType", Type = "number", Notes = "Block type of the clicked block" }, + { Name = "BlockMeta", Type = "number", Notes = "Block meta of the clicked block" }, + }, + 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. + ]], + }, -- HOOK_PLAYER_USED_BLOCK +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerUsedItem.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerUsedItem.lua new file mode 100644 index 000000000..998058c35 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerUsedItem.lua @@ -0,0 +1,46 @@ +return +{ + HOOK_PLAYER_USED_ITEM = + { + CalledWhen = "A player has used an item in hand (bucket...)", + DefaultFnName = "OnPlayerUsedItem", -- also used as pagename + Desc = [[ + This hook is called after a {{cPlayer|player}} has right-clicked a block with an {{cItem|item}} that + can be used (is not placeable, is not food and clicked block is not use-able), such as a bucket or a + hoe. It is called after MCServer processes the usage (places fluid / turns dirt to farmland). + This is an information-only hook, there is no way to cancel the event anymore.

+

+ Note that the block coords given in this callback are for the (solid) block that is being clicked, + not the air block between it and the player.

+

+ To get the world at which the right-click occurred, use the {{cPlayer}}:GetWorld() function. To get + the item that the player is using, use the {{cPlayer}}:GetEquippedItem() function.

+

+ See also the {{OnPlayerUsingItem|HOOK_PLAYER_USING_ITEM}} for a similar hook called before the use, + the {{OnPlayerUsingBlock|HOOK_PLAYER_USING_BLOCK}} and {{OnPlayerUsedBlock|HOOK_PLAYER_USED_BLOCK}} + for similar hooks called when a player interacts with a block, such as a chest. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who used the item" }, + { Name = "BlockX", Type = "number", Notes = "X-coord of the clicked block" }, + { Name = "BlockY", Type = "number", Notes = "Y-coord of the clicked block" }, + { Name = "BlockZ", Type = "number", Notes = "Z-coord of the clicked block" }, + { Name = "BlockFace", Type = "number", Notes = "Face of clicked block which has been clicked. One of the BLOCK_FACE_ constants" }, + { Name = "CursorX", Type = "number", Notes = "X-coord of the cursor crosshair on the block being clicked" }, + { Name = "CursorY", Type = "number", Notes = "Y-coord of the cursor crosshair on the block being clicked" }, + { Name = "CursorZ", Type = "number", Notes = "Z-coord of the cursor crosshair on the block being clicked" }, + { Name = "BlockType", Type = "number", Notes = "Block type of the clicked block" }, + { Name = "BlockMeta", Type = "number", Notes = "Block meta of the clicked block" }, + }, + 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. + ]], + }, -- HOOK_PLAYER_USED_ITEM +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerUsingBlock.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerUsingBlock.lua new file mode 100644 index 000000000..8acc84b5f --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerUsingBlock.lua @@ -0,0 +1,46 @@ +return +{ + HOOK_PLAYER_USING_BLOCK = + { + CalledWhen = "Just before a player uses a block (chest, furnace...). Plugin may override / refuse.", + DefaultFnName = "OnPlayerUsingBlock", -- also used as pagename + Desc = [[ + This hook is called when a {{cPlayer|player}} has right-clicked a block that can be used, such as a + {{cChestEntity|chest}} or a lever. It is called before MCServer processes the usage (sends the UI + handling packets / toggles redstone). Plugins may refuse the interaction by returning true.

+

+ Note that the block coords given in this callback are for the (solid) block that is being clicked, + not the air block between it and the player.

+

+ To get the world at which the right-click occurred, use the {{cPlayer}}:GetWorld() function.

+

+ See also the {{OnPlayerUsedBlock|HOOK_PLAYER_USED_BLOCK}} for a similar hook called after the use, the + {{OnPlayerUsingItem|HOOK_PLAYER_USING_ITEM}} and {{OnPlayerUsedItem|HOOK_PLAYER_USED_ITEM}} for + similar hooks called when a player interacts with any block with a usable item in hand, such as a + bucket. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who is using the block" }, + { Name = "BlockX", Type = "number", Notes = "X-coord of the clicked block" }, + { Name = "BlockY", Type = "number", Notes = "Y-coord of the clicked block" }, + { Name = "BlockZ", Type = "number", Notes = "Z-coord of the clicked block" }, + { Name = "BlockFace", Type = "number", Notes = "Face of clicked block which has been clicked. One of the BLOCK_FACE_ constants" }, + { Name = "CursorX", Type = "number", Notes = "X-coord of the cursor crosshair on the block being clicked" }, + { Name = "CursorY", Type = "number", Notes = "Y-coord of the cursor crosshair on the block being clicked" }, + { Name = "CursorZ", Type = "number", Notes = "Z-coord of the cursor crosshair on the block being clicked" }, + { Name = "BlockType", Type = "number", Notes = "Block type of the clicked block" }, + { Name = "BlockMeta", Type = "number", Notes = "Block meta of the clicked block" }, + }, + Returns = [[ + If the function returns false or no value, other plugins' callbacks are called and then MCServer + processes the interaction. If the function returns true, no other callbacks are called for this + event and the interaction is silently dropped. + ]], + }, -- HOOK_PLAYER_USING_BLOCK +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerUsingItem.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerUsingItem.lua new file mode 100644 index 000000000..09674606d --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerUsingItem.lua @@ -0,0 +1,47 @@ +return +{ + HOOK_PLAYER_USING_ITEM = + { + CalledWhen = "Just before a player uses an item in hand (bucket...). Plugin may override / refuse.", + DefaultFnName = "OnPlayerUsingItem", -- also used as pagename + Desc = [[ + This hook is called when a {{cPlayer|player}} has right-clicked a block with an {{cItem|item}} that + can be used (is not placeable, is not food and clicked block is not use-able), such as a bucket or a + hoe. It is called before MCServer processes the usage (places fluid / turns dirt to farmland). + Plugins may refuse the interaction by returning true.

+

+ Note that the block coords given in this callback are for the (solid) block that is being clicked, + not the air block between it and the player.

+

+ To get the world at which the right-click occurred, use the {{cPlayer}}:GetWorld() function. To get + the item that the player is using, use the {{cPlayer}}:GetEquippedItem() function.

+

+ See also the {{OnPlayerUsedItem|HOOK_PLAYER_USED_ITEM}} for a similar hook called after the use, the + {{OnPlayerUsingBlock|HOOK_PLAYER_USING_BLOCK}} and {{OnPlayerUsedBlock|HOOK_PLAYER_USED_BLOCK}} for + similar hooks called when a player interacts with a block, such as a chest. + ]], + Params = + { + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who is using the item" }, + { Name = "BlockX", Type = "number", Notes = "X-coord of the clicked block" }, + { Name = "BlockY", Type = "number", Notes = "Y-coord of the clicked block" }, + { Name = "BlockZ", Type = "number", Notes = "Z-coord of the clicked block" }, + { Name = "BlockFace", Type = "number", Notes = "Face of clicked block which has been clicked. One of the BLOCK_FACE_ constants" }, + { Name = "CursorX", Type = "number", Notes = "X-coord of the cursor crosshair on the block being clicked" }, + { Name = "CursorY", Type = "number", Notes = "Y-coord of the cursor crosshair on the block being clicked" }, + { Name = "CursorZ", Type = "number", Notes = "Z-coord of the cursor crosshair on the block being clicked" }, + { Name = "BlockType", Type = "number", Notes = "Block type of the clicked block" }, + { Name = "BlockMeta", Type = "number", Notes = "Block meta of the clicked block" }, + }, + Returns = [[ + If the function returns false or no value, other plugins' callbacks are called and then MCServer + processes the interaction. If the function returns true, no other callbacks are called for this + event and the interaction is silently dropped. + ]], + }, -- HOOK_PLAYER_USING_ITEM +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPostCrafting.lua b/MCServer/Plugins/APIDump/Hooks/OnPostCrafting.lua new file mode 100644 index 000000000..8af78ba62 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPostCrafting.lua @@ -0,0 +1,36 @@ +return +{ + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnPreCrafting.lua b/MCServer/Plugins/APIDump/Hooks/OnPreCrafting.lua new file mode 100644 index 000000000..b404e0e73 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnPreCrafting.lua @@ -0,0 +1,37 @@ +return +{ + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnSpawnedEntity.lua b/MCServer/Plugins/APIDump/Hooks/OnSpawnedEntity.lua new file mode 100644 index 000000000..037a90f1c --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnSpawnedEntity.lua @@ -0,0 +1,31 @@ +return +{ + HOOK_SPAWNED_ENTITY = + { + CalledWhen = "After an entity is spawned in the world.", + DefaultFnName = "OnSpawnedEntity", -- also used as pagename + 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.

+

+ See also the {{OnSpawningEntity|HOOK_SPAWNING_ENTITY}} hook for a similar hook called before the + entity is spawned. + ]], + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnSpawnedMonster.lua b/MCServer/Plugins/APIDump/Hooks/OnSpawnedMonster.lua new file mode 100644 index 000000000..c319a77ea --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnSpawnedMonster.lua @@ -0,0 +1,30 @@ +return +{ + 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.

+

+ See also the {{OnSpawningMonster|HOOK_SPAWNING_MONSTER}} hook for a similar hook called before the + monster is spawned. + ]], + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnSpawningEntity.lua b/MCServer/Plugins/APIDump/Hooks/OnSpawningEntity.lua new file mode 100644 index 000000000..c4bff3916 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnSpawningEntity.lua @@ -0,0 +1,32 @@ +return +{ + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnSpawningMonster.lua b/MCServer/Plugins/APIDump/Hooks/OnSpawningMonster.lua new file mode 100644 index 000000000..4c0519e27 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnSpawningMonster.lua @@ -0,0 +1,33 @@ +return +{ + 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 +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnTakeDamage.lua b/MCServer/Plugins/APIDump/Hooks/OnTakeDamage.lua new file mode 100644 index 000000000..608126f2b --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnTakeDamage.lua @@ -0,0 +1,31 @@ +return +{ + HOOK_TAKE_DAMAGE = + { + CalledWhen = "An {{cEntity|entity}} is taking any kind of damage", + DefaultFnName = "OnTakeDamage", -- also used as pagename + Desc = [[ + This hook is called when any {{cEntity}} descendant, such as a {{cPlayer|player}} or a + {{cMonster|mob}}, takes any kind of damage. The plugins may modify the amount of damage or effects + with this hook by editting the {{TakeDamageInfo}} object passed.

+

+ This hook is called after the final damage is calculated, including all the possible weapon + {{cEnchantments|enchantments}}, armor protection and potion effects. + ]], + Params = + { + { Name = "Receiver", Type = "{{cEntity}} descendant", Notes = "The entity taking damage" }, + { Name = "TDI", Type = "{{TakeDamageInfo}}", Notes = "The damage type, cause and effects. Plugins may modify this object to alter the final damage applied." }, + }, + Returns = [[ + If the function returns false or no value, other plugins' callbacks are called and then the server + applies the final values from the TDI object to Receiver. If the function returns true, no other + callbacks are called, and no damage nor effects are applied. + ]], + }, -- HOOK_TAKE_DAMAGE +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnTick.lua b/MCServer/Plugins/APIDump/Hooks/OnTick.lua new file mode 100644 index 000000000..d8c329253 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnTick.lua @@ -0,0 +1,29 @@ +return +{ + HOOK_TICK = + { + CalledWhen = "Every server tick (approximately 20 times per second)", + DefaultFnName = "OnTick", -- also used as pagename + Desc = [[ + This hook is called every game tick (50 msec, or 20 times a second). If the server is overloaded, + the interval is larger, which is indicated by the TimeDelta parameter.

+

+ This hook is called in the context of the server-tick thread, that is, the thread that takes care of + {{cClientHandle|client connections}} before they're assigned to {{cPlayer|player entities}}, and + processing console commands. + ]], + Params = + { + { Name = "TimeDelta", Type = "number", Notes = "The number of milliseconds elapsed since the last server tick. Will not be less than 50 msec." }, + }, + Returns = [[ + If the function returns false or no value, other plugins' callbacks are called. If the function + returns true, no other callbacks are called. There is no overridable behavior. + ]], + }, -- HOOK_TICK +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnUpdatedSign.lua b/MCServer/Plugins/APIDump/Hooks/OnUpdatedSign.lua new file mode 100644 index 000000000..937e6b981 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnUpdatedSign.lua @@ -0,0 +1,38 @@ +return +{ + HOOK_UPDATED_SIGN = + { + CalledWhen = "After the sign text is updated. Notification only.", + DefaultFnName = "OnUpdatedSign", -- also used as pagename + Desc = [[ + This hook is called after a sign has had its text updated. The text is already updated at this + point.

+

The update may have been caused either by a {{cPlayer|player}} directly updating the sign, or by + a plugin changing the sign text using the API.

+

+ See also the {{OnUpdatingSign|HOOK_UPDATING_SIGN}} hook for a similar hook called before the update, + with a chance to modify the text. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "The world in which the sign resides" }, + { Name = "BlockX", Type = "number", Notes = "X-coord of the sign" }, + { Name = "BlockY", Type = "number", Notes = "Y-coord of the sign" }, + { Name = "BlockZ", Type = "number", Notes = "Z-coord of the sign" }, + { Name = "Line1", Type = "string", Notes = "1st line of the new text" }, + { Name = "Line2", Type = "string", Notes = "2nd line of the new text" }, + { Name = "Line3", Type = "string", Notes = "3rd line of the new text" }, + { Name = "Line4", Type = "string", Notes = "4th line of the new text" }, + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who is changing the text. May be nil for non-player updates." } + }, + Returns = [[ + If the function returns false or no value, other plugins' callbacks are called. If the function + returns true, no other callbacks are called. There is no overridable behavior. + ]], + }, -- HOOK_UPDATED_SIGN +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnUpdatingSign.lua b/MCServer/Plugins/APIDump/Hooks/OnUpdatingSign.lua new file mode 100644 index 000000000..d74458182 --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnUpdatingSign.lua @@ -0,0 +1,58 @@ +return +{ + HOOK_UPDATING_SIGN = + { + CalledWhen = "Before the sign text is updated. Plugin may modify the text / refuse.", + DefaultFnName = "OnUpdatingSign", -- also used as pagename + Desc = [[ + This hook is called when a sign text is about to be updated, either as a result of player's + manipulation or any other event, such as a plugin setting the sign text. Plugins may modify the text + or refuse the update altogether.

+

+ See also the {{OnUpdatedSign|HOOK_UPDATED_SIGN}} hook for a similar hook called after the update. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "The world in which the sign resides" }, + { Name = "BlockX", Type = "number", Notes = "X-coord of the sign" }, + { Name = "BlockY", Type = "number", Notes = "Y-coord of the sign" }, + { Name = "BlockZ", Type = "number", Notes = "Z-coord of the sign" }, + { Name = "Line1", Type = "string", Notes = "1st line of the new text" }, + { Name = "Line2", Type = "string", Notes = "2nd line of the new text" }, + { Name = "Line3", Type = "string", Notes = "3rd line of the new text" }, + { Name = "Line4", Type = "string", Notes = "4th line of the new text" }, + { Name = "Player", Type = "{{cPlayer}}", Notes = "The player who is changing the text. May be nil for non-player updates." } + }, + Returns = [[ + The function may return up to five values. If the function returns true as the first value, no other + callbacks are called for this event and the sign is not updated. If the function returns no value or + false as its first value, other plugins' callbacks are called.

+

+ The other up to four values returned are used to update the sign text, line by line, respectively. + Note that other plugins may again update the texts (if the first value returned is false). + ]], + CodeExamples = + { + { + Title = "Add player signature", + Desc = "The following example appends a player signature to the last line, if the sign is updated by a player:", + Code = [[ +function OnUpdatingSign(World, BlockX, BlockY, BlockZ, Line1, Line2, Line3, Line4, Player) + if (Player == nil) then + -- Not changed by a player + return false; + end + + -- Sign with playername, allow other plugins to interfere: + return false, Line1, Line2, Line3, Line4 .. Player:GetName(); +end + ]], + } + } , + }, -- HOOK_UPDATING_SIGN +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnWeatherChanged.lua b/MCServer/Plugins/APIDump/Hooks/OnWeatherChanged.lua new file mode 100644 index 000000000..2a3bbe92b --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnWeatherChanged.lua @@ -0,0 +1,28 @@ +return +{ + HOOK_WEATHER_CHANGED = + { + CalledWhen = "The weather has changed", + DefaultFnName = "OnWeatherChanged", -- also used as pagename + Desc = [[ + This hook is called after the weather has changed in a {{cWorld|world}}. The new weather has already + been sent to the clients.

+

+ See also the {{OnWeatherChanging|HOOK_WEATHER_CHANGING}} hook for a similar hook called before the + change. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "World for which the weather has changed" }, + }, + 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 behavior. + ]], + }, -- HOOK_WEATHER_CHANGED +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnWeatherChanging.lua b/MCServer/Plugins/APIDump/Hooks/OnWeatherChanging.lua new file mode 100644 index 000000000..d36164e8e --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnWeatherChanging.lua @@ -0,0 +1,32 @@ +return +{ + HOOK_WEATHER_CHANGING = + { + CalledWhen = "The weather is about to change", + DefaultFnName = "OnWeatherChanging", -- also used as pagename + Desc = [[ + This hook is called when the current weather has expired and a new weather is selected. Plugins may + override the new weather setting.

+

+ The new weather setting is sent to the clients only after this hook has been processed.

+

+ See also the {{OnWeatherChanged|HOOK_WEATHER_CHANGED}} hook for a similar hook called after the + change. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "World for which the weather is changing" }, + { Name = "Weather", Type = "number", Notes = "The newly selected weather. One of wSunny, wRain, wStorm" }, + }, + Returns = [[ + If the function returns false or no value, the server calls other plugins' callbacks and finally + sets the weather. If the function returns true, the server takes the second returned value (wSunny + by default) and sets it as the new weather. No other plugins' callbacks are called in this case. + ]], + }, -- HOOK_WEATHER_CHANGING +} + + + + + diff --git a/MCServer/Plugins/APIDump/Hooks/OnWorldTick.lua b/MCServer/Plugins/APIDump/Hooks/OnWorldTick.lua new file mode 100644 index 000000000..657716d9e --- /dev/null +++ b/MCServer/Plugins/APIDump/Hooks/OnWorldTick.lua @@ -0,0 +1,29 @@ +return +{ + HOOK_WORLD_TICK = + { + CalledWhen = "Every world tick (about 20 times per second), separately for each world", + DefaultFnName = "OnWorldTick", -- also used as pagename + Desc = [[ + This hook is called for each {{cWorld|world}} every tick (50 msec, or 20 times a second). If the + world is overloaded, the interval is larger, which is indicated by the TimeDelta parameter.

+

+ This hook is called in the world's tick thread context and thus has access to all world data + guaranteed without blocking. + ]], + Params = + { + { Name = "World", Type = "{{cWorld}}", Notes = "World that is ticking" }, + { Name = "TimeDelta", Type = "number", Notes = "The number of milliseconds since the previous game tick. Will not be less than 50 msec" }, + }, + 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 behavior. + ]], + }, -- HOOK_WORLD_TICK +} + + + + + diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua index 9c4fb17f8..f77409f91 100644 --- a/MCServer/Plugins/APIDump/main_APIDump.lua +++ b/MCServer/Plugins/APIDump/main_APIDump.lua @@ -41,6 +41,16 @@ function Initialize(Plugin) LOG("Initialising " .. Plugin:GetName() .. " v." .. Plugin:GetVersion()) g_PluginFolder = Plugin:GetLocalFolder(); + + -- Load the API descriptions from the Classes and Hooks subfolders: + if (g_APIDesc.Classes == nil) then + g_APIDesc.Classes = {}; + end + if (g_APIDesc.Hooks == nil) then + g_APIDesc.Hooks = {}; + end + LoadAPIFiles("/Classes/", g_APIDesc.Classes); + LoadAPIFiles("/Hooks/", g_APIDesc.Hooks); -- dump all available API functions and objects: -- DumpAPITxt(); @@ -57,6 +67,29 @@ end +function LoadAPIFiles(a_Folder, a_DstTable) + local Folder = g_PluginFolder .. a_Folder; + for idx, fnam in ipairs(cFile:GetFolderContents(Folder)) do + local FileName = Folder .. fnam; + -- We only want .lua files from the folder: + if (cFile:IsFile(FileName) and fnam:match(".*%.lua$")) then + local TablesFn, Err = loadfile(FileName); + if (TablesFn == nil) then + LOGWARNING("Cannot load API descriptions from " .. FileName .. ", Lua error '" .. Err .. "'."); + else + local Tables = TablesFn(); + for k, cls in pairs(Tables) do + a_DstTable[k] = cls; + end + end -- if (TablesFn) + end -- if (is lua file) + end -- for fnam - Folder[] +end + + + + + function DumpAPITxt() LOG("Dumping all available functions to API.txt..."); function dump (prefix, a, Output)