6 files changed, 90 insertions, 12 deletions

diff --git a/MCServer/Plugins/APIDump/Hooks/OnDisconnect.lua b/MCServer/Plugins/APIDump/Hooks/OnDisconnect.lua
index a3301a8c6..204cb63d2 100644
--- a/MCServer/Plugins/APIDump/Hooks/OnDisconnect.lua
+++ b/MCServer/Plugins/APIDump/Hooks/OnDisconnect.lua
@@ -2,23 +2,33 @@ return
 {
 	HOOK_DISCONNECT =
 	{
-		CalledWhen = "A player has explicitly disconnected.",
+		CalledWhen = [[
+			A client has disconnected, either by explicitly sending the disconnect packet (in older protocols) or
+			their connection was terminated
+		]],
 		DefaultFnName = "OnDisconnect",  -- also used as pagename
 		Desc = [[
-			This hook is called when a client is about to be disconnected from the server, for whatever reason.
-			
-			<p><b>Note that this hook will be removed after <1.7 protocol support is removed, as it was originally a hook for
-			the client sending the server a disconnect packet, which no longer happens.</b></p>
+			This hook is called when a client has disconnected from the server, for whatever reason. It is also
+			called when the client sends the Disconnect packet (only in pre-1.7 protocols). This hook is not called
+			for server ping connections.</p>
+			<p>
+			Note that the hook is called even for connections to players who failed to auth. In such a case there's
+			no {{cPlayer}} object associated with the client.</p>
+			<p>
+			See also the {{OnHandshake|HOOK_HANDSHAKE}} hook which is called when the client connects (and presents
+			a handshake message, so that they are not just status-pinging). If you need to store a per-player
+			object, use the {{OnPlayerJoined|HOOK_PLAYER_JOINED}} and {{OnPlayerDestroyed|HOOK_PLAYER_DESTROYED}}
+			hooks instead, those are guaranteed to have the {{cPlayer}} object associated.
 		]],
 		Params =
 		{
-			{ Name = "Player", Type = "{{cPlayer}}", Notes = "The player who has disconnected" },
+			{ Name = "Client", Type = "{{cClientHandle}}", Notes = "The client 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.
 			If the function returns true, no other plugins are called for this event. In either case,
-			the player is disconnected.
+			the client is disconnected.
 		]],
 	},  -- HOOK_DISCONNECT
 }
diff --git a/MCServer/Plugins/APIDump/Hooks/OnEntityAddEffect.lua b/MCServer/Plugins/APIDump/Hooks/OnEntityAddEffect.lua
new file mode 100644
index 000000000..1d1658a6f
--- /dev/null
+++ b/MCServer/Plugins/APIDump/Hooks/OnEntityAddEffect.lua
@@ -0,0 +1,33 @@
+return
+{
+	HOOK_ENTITY_ADD_EFFECT =
+	{
+		CalledWhen = "An entity effect is about to get added to an entity.",
+		DefaultFnName = "OnEntityAddEffect",  -- also used as pagename
+		Desc = [[
+			This hook is called whenever an entity effect is about to be added to an entity. The plugin may
+			disallow the addition by returning true.</p>
+			<p>Note that this hook only fires for adding the effect, but not for the actual effect application. See
+			also the {{OnEntityRemoveEffect|HOOK_ENTITY_REMOVE_EFFECT}} for notification about effects expiring /
+			removing, and {{OnEntityApplyEffect|HOOK_ENTITY_APPLY_EFFECT}} for the actual effect application to the
+			entity.
+		]],
+		Params =
+		{
+			{ Name = "Entity", Type = "{{cEntity}}", Notes = "The entity to which the effect is about to be added" },
+			{ Name = "EffectType", Type = "number", Notes = "The type of the effect to be added. One of the effXXX constants." },
+			{ Name = "EffectDuration", Type = "number", Notes = "The duration of the effect to be added, in ticks." },
+			{ Name = "EffectIntensity", Type = "number", Notes = "The intensity (level) of the effect to be added. " },
+			{ Name = "DistanceModifier", Type = "number", Notes = "The modifier for the effect intensity, based on distance. Used mainly for splash potions." },
+		},
+		Returns = [[
+			If the plugin returns true, the effect will not be added 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 effect is added to the entity.
+		]],
+	},  -- HOOK_EXECUTE_COMMAND
+}
+
+
+
+
diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerFoodLevelChange.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerFoodLevelChange.lua
new file mode 100644
index 000000000..53637d5f1
--- /dev/null
+++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerFoodLevelChange.lua
@@ -0,0 +1,27 @@
+return
+{
+	HOOK_PLAYER_FOOD_LEVEL_CHANGE =
+	{
+		CalledWhen = "Called before the player food level changed. Plugin may override",
+		DefaultFnName = "OnPlayerFoodLevelChange", -- also used as pagename
+		Desc = [[
+			This hook is called before the food level changes.
+			The food level is not changed yet, plugins may choose
+			to refuse the change.
+		]],
+		Params =
+		{
+			{ Name = "Player", Type = "{{cPlayer}}", Notes = "The player who changes the food level." },
+			{ Name = "NewFoodLevel", Type = "number", Notes = "The new food level." },
+		},
+		Returns = [[
+			If the function returns false or no value, the next plugin's callback is called. Afterwards, the
+			server changes the food level of the player. If the function returns true, no
+			other callback is called for this event and the player's food level doesn't change.
+		]],
+	}, -- HOOK_PLAYER_FOOD_LEVEL_CHANGE
+};
+
+
+
+
diff --git a/MCServer/Plugins/APIDump/Hooks/OnPlayerUsedBlock.lua b/MCServer/Plugins/APIDump/Hooks/OnPlayerUsedBlock.lua
index 4c91ea89e..9a0e036b9 100644
--- a/MCServer/Plugins/APIDump/Hooks/OnPlayerUsedBlock.lua
+++ b/MCServer/Plugins/APIDump/Hooks/OnPlayerUsedBlock.lua
@@ -2,7 +2,7 @@ return
 {
 	HOOK_PLAYER_USED_BLOCK =
 	{
-		CalledWhen = "A player has just used a block (chest, furnace…). Notification only.",
+		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
diff --git a/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua b/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua
index 1588d420c..72cf85821 100644
--- a/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua
+++ b/MCServer/Plugins/APIDump/Hooks/OnProjectileHitBlock.lua
@@ -10,6 +10,11 @@ return
 		Params =
 		{
 			{ Name = "ProjectileEntity", Type = "{{cProjectileEntity}}", Notes = "The projectile that hit an entity." },
+			{ Name = "BlockX", Type = "number", Notes = "The X-coord where the projectile hit." },
+			{ Name = "BlockY", Type = "number", Notes = "The Y-coord where the projectile hit." },
+			{ Name = "BlockZ", Type = "number", Notes = "The Z-coord where the projectile hit." },
+			{ Name = "BlockFace", Type = "number", Notes = "The side of the block where the projectile hit." },
+			{ Name = "BlockHitPos", Type = "Vector3d", Notes = "The exact position where the projectile hit." },
 		},
 		Returns = [[
 			If the function returns false or no value, the next plugin's callback is called. If the function
diff --git a/MCServer/Plugins/APIDump/Hooks/OnWeatherChanging.lua b/MCServer/Plugins/APIDump/Hooks/OnWeatherChanging.lua
index d36164e8e..bb809af11 100644
--- a/MCServer/Plugins/APIDump/Hooks/OnWeatherChanging.lua
+++ b/MCServer/Plugins/APIDump/Hooks/OnWeatherChanging.lua
@@ -6,7 +6,7 @@ return
 		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>
+			override the new weather being set.</p>
 			<p>
 			The new weather setting is sent to the clients only after this hook has been processed.</p>
 			<p>
@@ -19,9 +19,12 @@ return
 			{ 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.
+			The hook handler can return up to two values. If the first value is false or not present, the server
+			calls other plugins' callbacks and finally sets the weather. If it is true, the server doesn't call any
+			more callbacks for this hook. The second value returned is used as the new weather. If no value is
+			given, the weather from the parameters is used as the weather. Returning false as the first value and a
+			specific weather constant as the second value makes the server call the rest of the hook handlers with
+			the new weather value.
 		]],
 	},  -- HOOK_WEATHER_CHANGING
 }