From 086c8b1834bfca6a4af912abbd13fd570f7b0b33 Mon Sep 17 00:00:00 2001 From: Mattes D Date: Wed, 16 Dec 2015 15:04:47 +0100 Subject: Revised the explosion-related Lua API and docs. Fixes #2746. --- Server/Plugins/APIDump/APIDesc.lua | 15 +++++++++++++- Server/Plugins/APIDump/Hooks/OnExploded.lua | 17 ++-------------- Server/Plugins/APIDump/Hooks/OnExploding.lua | 23 +++++++--------------- .../Plugins/APIDump/Writing-a-Cuberite-plugin.html | 7 ++++--- Server/Plugins/APIDump/main_APIDump.lua | 2 +- 5 files changed, 28 insertions(+), 36 deletions(-) (limited to 'Server') diff --git a/Server/Plugins/APIDump/APIDesc.lua b/Server/Plugins/APIDump/APIDesc.lua index 67689a2a5..be9f60662 100644 --- a/Server/Plugins/APIDump/APIDesc.lua +++ b/Server/Plugins/APIDump/APIDesc.lua @@ -2858,6 +2858,18 @@ end TrimString = {Params = "string", Return = "string", Notes = "Trims whitespace at both ends of the string"}, md5 = {Params = "string", Return = "string", Notes = "OBSOLETE, use the {{cCryptoHash}} functions instead.
Converts a string to a raw binary md5 hash."}, }, + Constants = + { + esBed = { Notes = "A bed explosion. The SourceData param is the {{Vector3i|position}} of the bed." }, + esEnderCrystal = { Notes = "An ender crystal entity explosion. The SourceData param is the {{cEntity|ender crystal entity}} object." }, + esGhastFireball = { Notes = "A ghast fireball explosion. The SourceData param is the {{cGhastFireballEntity|ghast fireball entity}} object." }, + esMonster = { Notes = "A monster explosion (creeper). The SourceData param is the {{cMonster|monster entity}} object." }, + esOther = { Notes = "Any other explosion. The SourceData param is unused." }, + esPlugin = { Notes = "An explosion started by a plugin, without any further information. The SourceData param is unused. "}, + esPrimedTNT = { Notes = "A TNT explosion. The SourceData param is the {{cTNTEntity|TNT entity}} object."}, + esWitherBirth = { Notes = "An explosion at a wither's birth. The SourceData param is the {{cMonster|wither entity}} object." }, + esWitherSkull = { Notes = "A wither skull explosion. The SourceData param is the {{cWitherSkullEntity|wither skull entity}} object." }, + }, ConstantGroups = { BlockTypes = @@ -2961,7 +2973,7 @@ end These constants are used to differentiate the various sources of explosions. They are used in the {{OnExploded|HOOK_EXPLODED}} hook, {{OnExploding|HOOK_EXPLODING}} hook and in the {{cWorld}}:DoExplosionAt() function. These constants also dictate the type of the additional - data provided with the explosions, such as the exploding {{cCreeper|creeper}} entity or the + data provided with the explosions, such as the exploding creeper {{cEntity|entity}} or the {{Vector3i|coords}} of the exploding bed. ]], }, @@ -3037,6 +3049,7 @@ end "cHopperEntity.__cBlockEntityWindowOwner__", "cLuaWindow.__cItemGrid__cListener__", "Globals._CuberiteInternal_.*", -- Ignore all internal Cuberite constants + "Globals.esMax", }, IgnoreVariables = diff --git a/Server/Plugins/APIDump/Hooks/OnExploded.lua b/Server/Plugins/APIDump/Hooks/OnExploded.lua index 6a01542ab..daca31237 100644 --- a/Server/Plugins/APIDump/Hooks/OnExploded.lua +++ b/Server/Plugins/APIDump/Hooks/OnExploded.lua @@ -11,20 +11,7 @@ return

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

+ depends on the source kind, see the {{Globals#ExplosionSource|esXXX}} constants' descriptions for details. ]], Params = { @@ -35,7 +22,7 @@ return { 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." }, + { Name = "SourceData", Type = "varies", Notes = "Additional data for the source. The exact type varies by the source. See the {{Globals#ExplosionSource|esXXX}} constants' descriptions." }, }, Returns = [[ If the function returns false or no value, the next plugin's callback is called. If the function diff --git a/Server/Plugins/APIDump/Hooks/OnExploding.lua b/Server/Plugins/APIDump/Hooks/OnExploding.lua index e21b41be0..873202dc3 100644 --- a/Server/Plugins/APIDump/Hooks/OnExploding.lua +++ b/Server/Plugins/APIDump/Hooks/OnExploding.lua @@ -11,20 +11,7 @@ return

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

+ depends on the source kind, see the {{Globals#ExplosionSource|esXXX}} constants' descriptions for details ]], Params = { @@ -35,12 +22,16 @@ return { 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." }, + { Name = "SourceData", Type = "varies", Notes = "Additional data for the source. The exact type varies by the source. See the {{Globals#ExplosionSource|esXXX}} constants' description." }, }, Returns = [[ If the function returns false or no value, the next plugin's callback is called, and finally Cuberite 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. + returns true, no other callback is called for this event and the explosion will not occur.

+

+ The hook handler may return up to two more values after the initial bool. The second returned value + overrides the CanCauseFire parameter for subsequent hook calls and the final explosion, the third + returned value overrides the ExplosionSize parameter for subsequent hook calls and the final explosion. ]], }, -- HOOK_EXPLODING } diff --git a/Server/Plugins/APIDump/Writing-a-Cuberite-plugin.html b/Server/Plugins/APIDump/Writing-a-Cuberite-plugin.html index 2b6af0d82..a75a925b3 100644 --- a/Server/Plugins/APIDump/Writing-a-Cuberite-plugin.html +++ b/Server/Plugins/APIDump/Writing-a-Cuberite-plugin.html @@ -209,10 +209,11 @@ function Explode(Split, Player) -- Create a callback ExplodePlayer with parameter Explodee, which Cuberite calls for every player on the server local HasExploded = false local ExplodePlayer = function(Explodee) - -- If the player we are currently at is the one we specified as the parameter + -- If the player name matches exactly if (Explodee:GetName() == Split[2]) then - -- Create an explosion at the same position as they are; see API docs for further details of this function - Player:GetWorld():DoExplosionAt(Explodee:GetPosX(), Explodee:GetPosY(), Explodee:GetPosZ(), false, esPlugin) + -- Create an explosion of force level 2 at the same position as they are + -- see API docs for further details of this function + Player:GetWorld():DoExplosionAt(2, Explodee:GetPosX(), Explodee:GetPosY(), Explodee:GetPosZ(), false, esPlugin) Player:SendMessageSuccess(Split[2] .. " was successfully exploded") HasExploded = true; return true -- Signalize to Cuberite that we do not need to call this callback for any more players diff --git a/Server/Plugins/APIDump/main_APIDump.lua b/Server/Plugins/APIDump/main_APIDump.lua index 68c843016..872fa60f4 100644 --- a/Server/Plugins/APIDump/main_APIDump.lua +++ b/Server/Plugins/APIDump/main_APIDump.lua @@ -786,7 +786,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) cf:write("

"); cf:write(LinkifyString(group.TextBefore or "", Source)); WriteConstantTable(group.Constants, a_InheritedName or a_ClassAPI.Name); - cf:write(LinkifyString(group.TextAfter or "", Source), "

"); + cf:write(LinkifyString(group.TextAfter or "", Source), "

"); end end end -- cgit v1.2.3