summaryrefslogtreecommitdiffstats
path: root/MCServer/Plugins/APIDump
diff options
context:
space:
mode:
Diffstat (limited to 'MCServer/Plugins/APIDump')
-rw-r--r--MCServer/Plugins/APIDump/APIDesc.lua60
1 files changed, 60 insertions, 0 deletions
diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua
index a71a35099..444d697fa 100644
--- a/MCServer/Plugins/APIDump/APIDesc.lua
+++ b/MCServer/Plugins/APIDump/APIDesc.lua
@@ -1466,6 +1466,66 @@ Sign entities are saved and loaded from disk when the chunk they reside in is sa
Constants =
{
},
+ AdditionalInfo =
+ {
+ {
+ Header = "Using callbacks",
+ Contents = [[
+ To avoid problems with stale objects, the cWorld class will not let plugins get a direct pointer
+ to an {{cEntity|entity}}, {{cBlockEntity|block entity}} or a {{cPlayer|player}}. Such an object
+ could be modified or even destroyed by another thread while the plugin holds it, so it would be
+ rather unsafe.</p>
+ <p>
+ Instead, the cWorld provides access to these objects using callbacks. The plugin provides a
+ function that is called and receives the object as a parameter; cWorld guarantees that while
+ the callback is executing, the object will stay valid. If a plugin needs to "remember" the
+ object outside of the callback, it needs to store the entity ID, blockentity coords or player
+ name.</p>
+ <p>
+ The following code examples show how to use the callbacks</p>
+ <p>
+ This code teleports player Player to another player named ToName in the same world:
+<pre>
+-- Player is a cPlayer object
+-- ToName is a string
+-- World is a cWorld object
+World:ForEachPlayer(
+ function (a_OtherPlayer)
+ if (a_OtherPlayer:GetName() == ToName) then
+ Player:TeleportToEntity(a_OtherPlayer);
+ end
+);
+</pre></p>
+ <p>
+ This code fills each furnace in the chunk with 64 coals:
+<pre>
+-- Player is a cPlayer object
+-- World is a cWorld object
+World:ForEachFurnaceInChunk(Player:GetChunkX(), Player:GetChunkZ(),
+ function (a_Furnace)
+ a_Furnace:SetFuelSlot(cItem(E_ITEM_COAL, 64));
+ end
+);
+</pre></p>
+ <p>
+ This code teleports all spiders up by 100 blocks:
+<pre>
+-- World is a cWorld object
+World:ForEachEntity(
+ function (a_Entity)
+ if not(a_Entity:IsMob()) then
+ return;
+ end
+ local Monster = tolua.cast(a_Entity, "cMonster"); -- Get the cMonster out of cEntity, now that we know the entity represents one.
+ if (Monster:GetMobType() == cMonster.mtSpider) then
+ Monster:TeleportToCoords(Monster:GetPosX(), Monster:GetPosY() + 100, Monster:GetPosZ());
+ end
+ end
+);
+</pre></p>
+ ]],
+ },
+ }, -- AdditionalInfo
},
TakeDamageInfo =