summaryrefslogtreecommitdiffstats
path: root/MCServer/Plugins/APIDump
diff options
context:
space:
mode:
Diffstat (limited to 'MCServer/Plugins/APIDump')
-rw-r--r--MCServer/Plugins/APIDump/APIDesc.lua1683
-rw-r--r--MCServer/Plugins/APIDump/Classes/BlockEntities.lua243
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnBlockToPickups.lua62
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnChat.lua29
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnChunkAvailable.lua27
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnChunkGenerated.lua67
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnChunkGenerating.lua35
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnChunkUnloaded.lua28
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnChunkUnloading.lua30
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnCollectingPickup.lua32
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnCraftingNoRecipe.lua32
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnDisconnect.lua32
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnExecuteCommand.lua31
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnExploded.lua49
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnExploding.lua50
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnHandshake.lua29
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnHopperPullingItem.lua30
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnHopperPushingItem.lua30
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnKilling.lua33
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnLogin.lua31
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerAnimation.lua28
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerBreakingBlock.lua36
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerBrokenBlock.lua36
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerEating.lua27
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerJoined.lua29
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerLeftClick.lua47
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerMoving.lua27
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerPlacedBlock.lua40
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerPlacingBlock.lua45
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerRightClick.lua37
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerRightClickingEntity.lua27
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerShooting.lua32
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerSpawned.lua32
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerTossingItem.lua30
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerUsedBlock.lua46
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerUsedItem.lua46
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerUsingBlock.lua46
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPlayerUsingItem.lua47
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPostCrafting.lua36
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnPreCrafting.lua37
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnSpawnedEntity.lua31
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnSpawnedMonster.lua30
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnSpawningEntity.lua32
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnSpawningMonster.lua33
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnTakeDamage.lua31
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnTick.lua29
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnUpdatedSign.lua38
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnUpdatingSign.lua58
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnWeatherChanged.lua28
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnWeatherChanging.lua32
-rw-r--r--MCServer/Plugins/APIDump/Hooks/OnWorldTick.lua29
-rw-r--r--MCServer/Plugins/APIDump/main_APIDump.lua33
52 files changed, 2036 insertions, 1682 deletions
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.</p>
- <p>
- 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:
-<pre class="prettyprint lang-lua">
--- 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
-);
-</pre>
- ]],
- },
- }, -- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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 =</pre>]], },
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:
<pre class="prettyprint lang-lua">
-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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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 <i>SetUseDefaultXXX(false)</i> 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- FIXME: There is no OnCollectedPickup() callback.</p>
- <p>
- FIXME: This callback is called even if the pickup doesn't fit into the player's inventory.</p>
- ]],
- 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.</p>
- <p>
- 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.</p>
- <p>
- Note that this callback is not called if the client drops the connection or is kicked by the
- server.</p>
- <p>
- FIXME: There is no callback for "client destroying" that would be called in all circumstances.</p>
- ]],
- 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.</p>
- <p>
- 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.</p>
- <p>
- See also {{OnExploding|HOOK_EXPLODING}} for a similar hook called before the explosion.</p>
- <p>
- 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:
- <table>
- <tr><th>Source</th><th>SourceData Type</th><th>Notes</th></tr>
- <tr><td>esPrimedTNT</td><td>{{cTNTEntity}}</td><td>An exploding primed TNT entity</td></tr>
- <tr><td>esCreeper</td><td>{{cCreeper}}</td><td>An exploding creeper or charged creeper</td></tr>
- <tr><td>esBed</td><td>{{Vector3i}}</td><td>A bed exploding in the Nether or in the End. The bed coords are given.</td></tr>
- <tr><td>esEnderCrystal</td><td>{{Vector3i}}</td><td>An ender crystal exploding upon hit. The block coords are given.</td></tr>
- <tr><td>esGhastFireball</td><td>{{cGhastFireballEntity}}</td><td>A ghast fireball hitting ground or an {{cEntity|entity}}.</td></tr>
- <tr><td>esWitherSkullBlack</td><td><i>TBD</i></td><td>A black wither skull hitting ground or an {{cEntity|entity}}.</td></tr>
- <tr><td>esWitherSkullBlue</td><td><i>TBD</i></td><td>A blue wither skull hitting ground or an {{cEntity|entity}}.</td></tr>
- <tr><td>esWitherBirth</td><td><i>TBD</i></td><td>A wither boss being created</td></tr>
- <tr><td>esOther</td><td><i>TBD</i></td><td>Any other previously unspecified type.</td></tr>
- <tr><td>esPlugin</td><td>object</td><td>An explosion created by a plugin. The plugin may specify any kind of data.</td></tr>
- </table></p>
- ]],
- 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.</p>
- <p>
- See also {{OnExploded|HOOK_EXPLODED}} for a similar hook called after the explosion.</p>
- <p>
- 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:
- <table>
- <tr><th>Source</th><th>SourceData Type</th><th>Notes</th></tr>
- <tr><td>esPrimedTNT</td><td>{{cTNTEntity}}</td><td>An exploding primed TNT entity</td></tr>
- <tr><td>esCreeper</td><td>{{cCreeper}}</td><td>An exploding creeper or charged creeper</td></tr>
- <tr><td>esBed</td><td>{{Vector3i}}</td><td>A bed exploding in the Nether or in the End. The bed coords are given.</td></tr>
- <tr><td>esEnderCrystal</td><td>{{Vector3i}}</td><td>An ender crystal exploding upon hit. The block coords are given.</td></tr>
- <tr><td>esGhastFireball</td><td>{{cGhastFireballEntity}}</td><td>A ghast fireball hitting ground or an {{cEntity|entity}}.</td></tr>
- <tr><td>esWitherSkullBlack</td><td><i>TBD</i></td><td>A black wither skull hitting ground or an {{cEntity|entity}}.</td></tr>
- <tr><td>esWitherSkullBlue</td><td><i>TBD</i></td><td>A blue wither skull hitting ground or an {{cEntity|entity}}.</td></tr>
- <tr><td>esWitherBirth</td><td><i>TBD</i></td><td>A wither boss being created</td></tr>
- <tr><td>esOther</td><td><i>TBD</i></td><td>Any other previously unspecified type.</td></tr>
- <tr><td>esPlugin</td><td>object</td><td>An explosion created by a plugin. The plugin may specify any kind of data.</td></tr>
- </table></p>
- ]],
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- For the list of animations that are sent by the client, see the
- <a href="http://wiki.vg/Protocol#0x12">Protocol wiki</a>.
- ]],
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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
- <a href="http://wiki.vg/Protocol#0x0E">protocol documentation</a> 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- ]],
- }, -- 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}}.</p>
- <p>
- Use the {{cPlayer}}:GetWorld() function to get the world to which the block belongs.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- Use the {{cPlayer}}:GetWorld() function to get the world to which the block belongs.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- To get the world at which the right-click occurred, use the {{cPlayer}}:GetWorld() function.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- To get the world at which the right-click occurred, use the {{cPlayer}}:GetWorld() function.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
- <p>
- The new weather setting is sent to the clients only after this hook has been processed.</p>
- <p>
- 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.</p>
- <p>
- 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.</p>
+ <p>
+ 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:
+<pre class="prettyprint lang-lua">
+-- 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
+);
+</pre>
+ ]],
+ },
+ }, -- 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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 <i>SetUseDefaultXXX(false)</i> 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ FIXME: There is no OnCollectedPickup() callback.</p>
+ <p>
+ FIXME: This callback is called even if the pickup doesn't fit into the player's inventory.</p>
+ ]],
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ Note that this callback is not called if the client drops the connection or is kicked by the
+ server.</p>
+ <p>
+ FIXME: There is no callback for "client destroying" that would be called in all circumstances.</p>
+ ]],
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ See also {{OnExploding|HOOK_EXPLODING}} for a similar hook called before the explosion.</p>
+ <p>
+ 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:
+ <table>
+ <tr><th>Source</th><th>SourceData Type</th><th>Notes</th></tr>
+ <tr><td>esPrimedTNT</td><td>{{cTNTEntity}}</td><td>An exploding primed TNT entity</td></tr>
+ <tr><td>esCreeper</td><td>{{cCreeper}}</td><td>An exploding creeper or charged creeper</td></tr>
+ <tr><td>esBed</td><td>{{Vector3i}}</td><td>A bed exploding in the Nether or in the End. The bed coords are given.</td></tr>
+ <tr><td>esEnderCrystal</td><td>{{Vector3i}}</td><td>An ender crystal exploding upon hit. The block coords are given.</td></tr>
+ <tr><td>esGhastFireball</td><td>{{cGhastFireballEntity}}</td><td>A ghast fireball hitting ground or an {{cEntity|entity}}.</td></tr>
+ <tr><td>esWitherSkullBlack</td><td><i>TBD</i></td><td>A black wither skull hitting ground or an {{cEntity|entity}}.</td></tr>
+ <tr><td>esWitherSkullBlue</td><td><i>TBD</i></td><td>A blue wither skull hitting ground or an {{cEntity|entity}}.</td></tr>
+ <tr><td>esWitherBirth</td><td><i>TBD</i></td><td>A wither boss being created</td></tr>
+ <tr><td>esOther</td><td><i>TBD</i></td><td>Any other previously unspecified type.</td></tr>
+ <tr><td>esPlugin</td><td>object</td><td>An explosion created by a plugin. The plugin may specify any kind of data.</td></tr>
+ </table></p>
+ ]],
+ 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.</p>
+ <p>
+ See also {{OnExploded|HOOK_EXPLODED}} for a similar hook called after the explosion.</p>
+ <p>
+ 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:
+ <table>
+ <tr><th>Source</th><th>SourceData Type</th><th>Notes</th></tr>
+ <tr><td>esPrimedTNT</td><td>{{cTNTEntity}}</td><td>An exploding primed TNT entity</td></tr>
+ <tr><td>esCreeper</td><td>{{cCreeper}}</td><td>An exploding creeper or charged creeper</td></tr>
+ <tr><td>esBed</td><td>{{Vector3i}}</td><td>A bed exploding in the Nether or in the End. The bed coords are given.</td></tr>
+ <tr><td>esEnderCrystal</td><td>{{Vector3i}}</td><td>An ender crystal exploding upon hit. The block coords are given.</td></tr>
+ <tr><td>esGhastFireball</td><td>{{cGhastFireballEntity}}</td><td>A ghast fireball hitting ground or an {{cEntity|entity}}.</td></tr>
+ <tr><td>esWitherSkullBlack</td><td><i>TBD</i></td><td>A black wither skull hitting ground or an {{cEntity|entity}}.</td></tr>
+ <tr><td>esWitherSkullBlue</td><td><i>TBD</i></td><td>A blue wither skull hitting ground or an {{cEntity|entity}}.</td></tr>
+ <tr><td>esWitherBirth</td><td><i>TBD</i></td><td>A wither boss being created</td></tr>
+ <tr><td>esOther</td><td><i>TBD</i></td><td>Any other previously unspecified type.</td></tr>
+ <tr><td>esPlugin</td><td>object</td><td>An explosion created by a plugin. The plugin may specify any kind of data.</td></tr>
+ </table></p>
+ ]],
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ For the list of animations that are sent by the client, see the
+ <a href="http://wiki.vg/Protocol#0x12">Protocol wiki</a>.
+ ]],
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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
+ <a href="http://wiki.vg/Protocol#0x0E">protocol documentation</a> 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ ]],
+ }, -- 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}}.</p>
+ <p>
+ Use the {{cPlayer}}:GetWorld() function to get the world to which the block belongs.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ Use the {{cPlayer}}:GetWorld() function to get the world to which the block belongs.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ To get the world at which the right-click occurred, use the {{cPlayer}}:GetWorld() function.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ To get the world at which the right-click occurred, use the {{cPlayer}}:GetWorld() function.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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.</p>
+ <p>
+ The new weather setting is sent to the clients only after this hook has been processed.</p>
+ <p>
+ 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.</p>
+ <p>
+ 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)