flewkey/cuberite-2a
1
0
Fork 0
Code Releases Activity

APIDump: Fixed the WritingPlugin article.

Browse Source 
The code is no longer weirdly indented in the browser, and links are relative to the API docs root.
This commit is contained in:
madmaxoft 2013-12-27 14:46:07 +01:00
parent f0ca18d72a
commit 270d79d47b
1 changed files with 101 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

193
MCServer/Plugins/APIDump/Writing-a-MCServer-plugin.html
View File

@ -2,7 +2,6 @@
<html> <html>
<head> <head>
<!--MCServer, a divison of McDonalds Enterprises-->
<title>MCS Plugin Tutorial</title> <title>MCS Plugin Tutorial</title>
<link rel="stylesheet" type="text/css" href="main.css" /> <link rel="stylesheet" type="text/css" href="main.css" />
<link rel="stylesheet" type="text/css" href="prettify.css" /> <link rel="stylesheet" type="text/css" href="prettify.css" />
@ -35,26 +34,26 @@
Format it like so: Format it like so:
</p> </p>
<pre class="prettyprint lang-lua"> <pre class="prettyprint lang-lua">
local PLUGIN local PLUGIN
function Initialize( Plugin )
Plugin:SetName( "DerpyPlugin" )
Plugin:SetVersion( 1 )
PLUGIN = Plugin
-- Hooks function Initialize(Plugin)
Plugin:SetName("DerpyPlugin")
local PluginManager = cPluginManager:Get() Plugin:SetVersion(1)
-- Command bindings
PLUGIN = Plugin
LOG( "Initialised " .. Plugin:GetName() .. " v." .. Plugin:GetVersion() ) -- Hooks
return true
end local PluginManager = cPluginManager:Get()
-- Command bindings
function OnDisable()
LOG(PLUGIN:GetName() .. " is shutting down...") LOG("Initialised " .. Plugin:GetName() .. " v." .. Plugin:GetVersion())
end return true
end
function OnDisable()
LOG(PLUGIN:GetName() .. " is shutting down...")
end
</pre> </pre>
<p> <p>
Now for an explanation of the basics. Now for an explanation of the basics.
@ -72,7 +71,7 @@
<h2>Registering hooks</h2> <h2>Registering hooks</h2>
<p> <p>
Hooks are things that MCServer calls when an internal event occurs. For example, a hook is fired when a player places a block, moves, Hooks are things that MCServer calls when an internal event occurs. For example, a hook is fired when a player places a block, moves,
logs on, eats, and many other things. For a full list, see <a href="http://mc-server.xoft.cz/LuaAPI/">the API documentation</a>. logs on, eats, and many other things. For a full list, see <a href="index.html">the API documentation</a>.
</p> </p>
<p> <p>
A hook can be either informative or overridable. In any case, returning false will not trigger a response, but returning true will cancel A hook can be either informative or overridable. In any case, returning false will not trigger a response, but returning true will cancel
@ -84,7 +83,7 @@
To register a hook, insert the following code template into the "-- Hooks" area in the previous code example. To register a hook, insert the following code template into the "-- Hooks" area in the previous code example.
</p> </p>
<pre class="prettyprint lang-lua"> <pre class="prettyprint lang-lua">
cPluginManager.AddHook(cPluginManager.HOOK_NAME_HERE, FunctionNameToBeCalled) cPluginManager.AddHook(cPluginManager.HOOK_NAME_HERE, FunctionNameToBeCalled)
</pre> </pre>
<p> <p>
What does this code do? What does this code do?
@ -98,22 +97,22 @@
So in total, this is a working representation of what we have so far covered. So in total, this is a working representation of what we have so far covered.
</p> </p>
<pre class="prettyprint lang-lua"> <pre class="prettyprint lang-lua">
function Initialize( Plugin ) function Initialize(Plugin)
Plugin:SetName( "DerpyPlugin" ) Plugin:SetName("DerpyPlugin")
Plugin:SetVersion( 1 ) Plugin:SetVersion(1)
cPluginManager.AddHook(cPluginManager.HOOK_PLAYER_MOVING, OnPlayerMoving) cPluginManager.AddHook(cPluginManager.HOOK_PLAYER_MOVING, OnPlayerMoving)
local PluginManager = cPluginManager:Get()
-- Command bindings
LOG( "Initialised " .. Plugin:GetName() .. " v." .. Plugin:GetVersion() ) local PluginManager = cPluginManager:Get()
return true -- Command bindings
end
LOG("Initialised " .. Plugin:GetName() .. " v." .. Plugin:GetVersion())
function OnPlayerMoving(Player) -- See API docs for parameters of all hooks return true
return true -- Prohibit player movement, see docs for whether a hook is cancellable end
end
function OnPlayerMoving(Player) -- See API docs for parameters of all hooks
return true -- Prohibit player movement, see docs for whether a hook is cancellable
end
</pre> </pre>
<p> <p>
So, that code stops the player from moving. Not particularly helpful, but yes :P. Note that ALL documentation is available So, that code stops the player from moving. Not particularly helpful, but yes :P. Note that ALL documentation is available
@ -126,11 +125,11 @@
We firstly add this template to the "-- Command bindings" section of the initial example: We firstly add this template to the "-- Command bindings" section of the initial example:
</p> </p>
<pre class="prettyprint lang-lua"> <pre class="prettyprint lang-lua">
-- ADD THIS IF COMMAND DOES NOT REQUIRE A PARAMETER (/explode) -- ADD THIS IF COMMAND DOES NOT REQUIRE A PARAMETER (/explode)
PluginManager:BindCommand("/commandname", "permissionnode", FunctionToCall, " - Description of command") PluginManager:BindCommand("/commandname", "permissionnode", FunctionToCall, " - Description of command")
-- ADD THIS IF COMMAND DOES REQUIRE A PARAMETER (/explode Notch) -- ADD THIS IF COMMAND DOES REQUIRE A PARAMETER (/explode Notch)
PluginManager:BindCommand("/commandname", "permissionnode", FunctionToCall, " ~ Description of command and parameter(s)") PluginManager:BindCommand("/commandname", "permissionnode", FunctionToCall, " ~ Description of command and parameter(s)")
</pre> </pre>
<p> <p>
What does it do, and why are there two? What does it do, and why are there two?
@ -171,17 +170,17 @@
your code in. Since MCS brings all the files together on JIT compile, we don't need to worry about requiring any files or such. Simply follow the below examples: your code in. Since MCS brings all the files together on JIT compile, we don't need to worry about requiring any files or such. Simply follow the below examples:
</p> </p>
<pre class="prettyprint lang-lua"> <pre class="prettyprint lang-lua">
-- Format: §yellow[INFO] §white%text% (yellow [INFO], white text following it) -- Format: §yellow[INFO] §white%text% (yellow [INFO], white text following it)
-- Use: Informational message, such as instructions for usage of a command -- Use: Informational message, such as instructions for usage of a command
SendMessage(Player, "Usage: /explode [player]") SendMessage(Player, "Usage: /explode [player]")
-- Format: §green[INFO] §white%text% (green [INFO] etc.) -- Format: §green[INFO] §white%text% (green [INFO] etc.)
-- Use: Success message, like when a command executes successfully -- Use: Success message, like when a command executes successfully
SendMessageSuccess(Player, "Notch was blown up!") SendMessageSuccess(Player, "Notch was blown up!")
-- Format: §rose[INFO] §white%text% (rose coloured [INFO] etc.) -- Format: §rose[INFO] §white%text% (rose coloured [INFO] etc.)
-- Use: Failure message, like when a command was entered correctly but failed to run, such as when the destination player wasn't found in a /tp command -- Use: Failure message, like when a command was entered correctly but failed to run, such as when the destination player wasn't found in a /tp command
SendMessageFailure(Player, "Player Salted was not found") SendMessageFailure(Player, "Player Salted was not found")
</pre> </pre>
<p> <p>
Those are the basics. If you want to output text to the player for a reason other than the three listed above, and you want to colour the text, simply concatenate Those are the basics. If you want to output text to the player for a reason other than the three listed above, and you want to colour the text, simply concatenate
@ -193,51 +192,63 @@
So, a working example that checks the validity of a command, and blows up a player, and also refuses pickup collection to players with >100ms ping. So, a working example that checks the validity of a command, and blows up a player, and also refuses pickup collection to players with >100ms ping.
</p> </p>
<pre class="prettyprint lang-lua"> <pre class="prettyprint lang-lua">
function Initialize( Plugin ) function Initialize(Plugin)
Plugin:SetName( "DerpyPluginThatBlowsPeopleUp" ) Plugin:SetName("DerpyPluginThatBlowsPeopleUp")
Plugin:SetVersion( 9001 ) Plugin:SetVersion(9001)
local PluginManager = cPluginManager:Get()
PluginManager:BindCommand("/explode", "derpyplugin.explode", Explode, " ~ Explode a player");
cPluginManager.AddHook(cPluginManager.HOOK_COLLECTING_PICKUP, OnCollectingPickup) local PluginManager = cPluginManager:Get()
PluginManager:BindCommand("/explode", "derpyplugin.explode", Explode, " ~ Explode a player");
LOG( "Initialised " .. Plugin:GetName() .. " v." .. Plugin:GetVersion() ) cPluginManager.AddHook(cPluginManager.HOOK_COLLECTING_PICKUP, OnCollectingPickup)
return true
end LOG("Initialised " .. Plugin:GetName() .. " v." .. Plugin:GetVersion())
return true
function Explode(Split, Player) end
if #Split ~= 2
SendMessage(Player, "Usage: /explode [playername]") -- There was more or less than one argument (excluding the /explode bit) function Explode(Split, Player)
else if (#Split ~= 2) then
local ExplodePlayer = function(Explodee) -- Create a callback ExplodePlayer with parameter Explodee, which MCS calls for every player on the server -- There was more or less than one argument (excluding the "/explode" bit)
if (Explodee:GetName() == Split[2] then -- If the player we are currently at is the one we specified as the parameter... -- Send the proper usage to the player and exit
Player:GetWorld():DoExplosionAt(Explodee:GetPosX(), Explodee:GetPosY(), Explodee:GetPosZ(), false, esPlugin) -- Explode 'em; see API docs for further details of this function SendMessage(Player, "Usage: /explode [playername]")
SendMessageSuccess(Player, Split[2] .. " was successfully exploded") -- Success! return true
return true -- Break out end
end
end -- Create a callback ExplodePlayer with parameter Explodee, which MCS calls for every player on the server
local HasExploded = false
cRoot:Get():FindAndDoWithPlayer(Split[2], ExplodePlayer) -- Tells MCS to loop through all players and call the callback above with the Player object it has found local ExplodePlayer = function(Explodee)
-- If the player we are currently at is the one we specified as the parameter
SendMessageFailure(Player, Split[2] .. " was not found") -- We have not broken out so far, therefore, the player must not exist, send failure if (Explodee:GetName() == Split[2]) then
end -- Create an explosion at the same position as they are; see <a href="cWorld.html">API docs</a> for further details of this function
Player:GetWorld():DoExplosionAt(Explodee:GetPosX(), Explodee:GetPosY(), Explodee:GetPosZ(), false, esPlugin)
return true -- Concluding return SendMessageSuccess(Player, Split[2] .. " was successfully exploded")
end HasExploded = true;
return true -- Signalize to MCS that we do not need to call this callback for any more players
function OnCollectingPickup(Player, Pickup) -- Again, see the API docs for parameters of all hooks. In this case, it is a Player and Pickup object end
if (Player:GetClientHandle():GetPing() > 100) then -- Get ping of player, in milliseconds end
return true -- Discriminate against high latency - you don't get drops :D
else -- Tell MCS to loop through all players and call the callback above with the Player object it has found
return false -- You do get the drops! Yay~ cRoot:Get():FindAndDoWithPlayer(Split[2], ExplodePlayer)
end
end if not(HasExploded) then
-- We have not broken out so far, therefore, the player must not exist, send failure
SendMessageFailure(Player, Split[2] .. " was not found")
end
return true
end
function OnCollectingPickup(Player, Pickup) -- Again, see the API docs for parameters of all hooks. In this case, it is a Player and Pickup object
if (Player:GetClientHandle():GetPing() > 100) then -- Get ping of player, in milliseconds
return true -- Discriminate against high latency - you don't get drops :D
else
return false -- You do get the drops! Yay~
end
end
</pre> </pre>
<p> <p>
Make sure to read the comments for a description of what everything does. Also be sure to return true for all <b>command</b> handlers, unless you want MCS to print out an "Unknown command" message Make sure to read the comments for a description of what everything does. Also be sure to return true for all <b>command</b> handlers, unless you want MCS to print out an "Unknown command" message
when the command gets executed :P. Make sure to follow standards - use CoreMessaging.lua functions for messaging, dashes for no parameter commands and tildes for vice versa, when the command gets executed :P. Make sure to follow standards - use CoreMessaging.lua functions for messaging, dashes for no parameter commands and tildes for vice versa,
and finally, <a href="http://mc-server.xoft.cz/LuaAPI/">the API documentation</a> is your friend! and finally, <a href="index.html">the API documentation</a> is your friend!
</p> </p>
<p> <p>
Happy coding ;) Happy coding ;)
@ -247,7 +258,5 @@
prettyPrint(); prettyPrint();
</script> </script>
</div> </div>
<hr />
<footer>This tutorial was brought you by Aperture Science, in conjunction with McDonalds Enterprises.<br /></footer>
</body> </body>
</html> </html>