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

Updated APIDump to follow the namechange

Browse Source
This commit is contained in:
Julian Laubstein 2015-08-11 22:48:55 +02:00
parent 6308643669
commit 0958e167e8
34 changed files with 204 additions and 209 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
MCServer/Plugins/APIDump/APIDesc.lua
View File

@ -137,7 +137,7 @@ g_APIDesc =
GetSizeY = { Params = "", Return = "number", Notes = "Returns the size of the held data in the y-axis" },
GetSizeZ = { Params = "", Return = "number", Notes = "Returns the size of the held data in the z-axis" },
GetVolume = { Params = "", Return = "number", Notes = "Returns the volume of the area - the total number of blocks stored within." },
GetWEOffset = { Params = "", Return = "{{Vector3i}}", Notes = "Returns the WE offset, a data value sometimes stored in the schematic files. MCServer doesn't use this value, but provides access to it using this method. The default is {0, 0, 0}."},
GetWEOffset = { Params = "", Return = "{{Vector3i}}", Notes = "Returns the WE offset, a data value sometimes stored in the schematic files. Cuberite doesn't use this value, but provides access to it using this method. The default is {0, 0, 0}."},
HasBlockLights = { Params = "", Return = "bool", Notes = "Returns true if current datatypes include blocklight" },
HasBlockMetas = { Params = "", Return = "bool", Notes = "Returns true if current datatypes include block metas" },
HasBlockSkyLights = { Params = "", Return = "bool", Notes = "Returns true if current datatypes include skylight" },
@ -189,8 +189,8 @@ g_APIDesc =
SetRelBlockTypeMeta = { Params = "RelBlockX, RelBlockY, RelBlockZ, BlockType, BlockMeta", Return = "", Notes = "Sets the block type and meta at the specified relative coords" },
SetWEOffset =
{
{ Params = "{{Vector3i|Offset}}", Return = "", Notes = "Sets the WE offset, a data value sometimes stored in the schematic files. Mostly used for WorldEdit. MCServer doesn't use this value, but provides access to it using this method." },
{ Params = "OffsetX, OffsetY, OffsetZ", Return = "", Notes = "Sets the WE offset, a data value sometimes stored in the schematic files. Mostly used for WorldEdit. MCServer doesn't use this value, but provides access to it using this method." },
{ Params = "{{Vector3i|Offset}}", Return = "", Notes = "Sets the WE offset, a data value sometimes stored in the schematic files. Mostly used for WorldEdit. Cuberite doesn't use this value, but provides access to it using this method." },
{ Params = "OffsetX, OffsetY, OffsetZ", Return = "", Notes = "Sets the WE offset, a data value sometimes stored in the schematic files. Mostly used for WorldEdit. Cuberite doesn't use this value, but provides access to it using this method." },
},
Write =
{
@ -519,7 +519,7 @@ g_APIDesc =
SetUseDefaultFinish = { Params = "bool", Return = "", Notes = "Sets the chunk to use default finishers or not" },
SetUseDefaultHeight = { Params = "bool", Return = "", Notes = "Sets the chunk to use default height generator or not" },
SetUseDefaultStructures = { Params = "bool", Return = "", Notes = "Sets the chunk to use default structures or not" },
UpdateHeightmap = { Params = "", Return = "", Notes = "Updates the heightmap to match current contents. The plugins should do that if they modify the contents and don't modify the heightmap accordingly; MCServer expects (and checks in Debug mode) that the heightmap matches the contents when the cChunkDesc is returned from a plugin." },
UpdateHeightmap = { Params = "", Return = "", Notes = "Updates the heightmap to match current contents. The plugins should do that if they modify the contents and don't modify the heightmap accordingly; Cuberite expects (and checks in Debug mode) that the heightmap matches the contents when the cChunkDesc is returned from a plugin." },
WriteBlockArea = { Params = "{{cBlockArea|BlockArea}}, MinRelX, MinRelY, MinRelZ", Return = "", Notes = "Writes data from the block area into the chunk" },
},
AdditionalInfo =
@ -586,7 +586,7 @@ end
Kick = { Params = "Reason", Return = "", Notes = "Kicks the user with the specified reason" },
SendPluginMessage = { Params = "Channel, Message", Return = "", Notes = "Sends the plugin message on the specified channel." },
SetClientBrand = { Params = "ClientBrand", Return = "", Notes = "Sets the value of the client's brand. Normally this value is received from the client by a MC|Brand plugin message, this function lets plugins overwrite the value." },
SetLocale = { Params = "Locale", Return = "", Notes = "Sets the locale that MCServer keeps on record. Initially the locale is initialized in protocol handshake, this function allows plugins to override the stored value (but only server-side and only until the user disconnects)." },
SetLocale = { Params = "Locale", Return = "", Notes = "Sets the locale that Cuberite keeps on record. Initially the locale is initialized in protocol handshake, this function allows plugins to override the stored value (but only server-side and only until the user disconnects)." },
SetUsername = { Params = "Name", Return = "", Notes = "Sets the username" },
SetViewDistance = { Params = "ViewDistance", Return = "", Notes = "Sets the viewdistance (number of chunks loaded for the player in each direction)" },
SendBlockChange = { Params = "BlockX, BlockY, BlockZ, BlockType, BlockMeta", Return = "", Notes = "Sends a BlockChange packet to the client. This can be used to create fake blocks only for that player." },
@ -832,7 +832,7 @@ local Hash = cCryptoHash.sha1HexString("DataToHash")
{{cMonster}}:GetMonsterType() to mtSpider. GetClass(), on the other hand, returns "cSpider"
directly.</p>
<p>
Note that you should not store a cEntity object between two hooks' calls, because MCServer may
Note that you should not store a cEntity object between two hooks' calls, because Cuberite may
despawn / remove that entity in between the calls. If you need to refer to an entity later, use its
UniqueID and {{cWorld|cWorld}}'s entity manipulation functions DoWithEntityByID(), ForEachEntity()
or ForEachEntityInChunk() to access the entity again.</p>
@ -1049,7 +1049,7 @@ cFile:Delete("/usr/bin/virus.exe");
Desc = [[
This class implements a simple name-value storage represented on disk by an INI file. These files
are suitable for low-volume high-latency human-readable information storage, such as for
configuration. MCServer itself uses INI files for settings and options.</p>
configuration. Cuberite itself uses INI files for settings and options.</p>
<p>
The INI files follow this basic structure:
<pre class="prettyprint lang-ini">
@ -1557,7 +1557,7 @@ end
</p>
<p>The contents of this window are represented by a {{cWindow|cWindow}}:GetSlot() etc. or {{cPlayer|cPlayer}}:GetInventory() to access the player inventory.
</p>
<p>When creating a new cLuaWindow object, you need to specify both the window type and the contents' width and height. Note that MCServer accepts any combination of these, but opening a window for a player may crash their client if the contents' dimensions don't match the client's expectations.
<p>When creating a new cLuaWindow object, you need to specify both the window type and the contents' width and height. Note that Cuberite accepts any combination of these, but opening a window for a player may crash their client if the contents' dimensions don't match the client's expectations.
</p>
<p>To open the window for a player, call {{cPlayer|cPlayer}}:OpenWindow(). Multiple players can open window of the same cLuaWindow object. All players see the same items in the window's contents (like chest, unlike crafting table).
]],
@ -1704,7 +1704,7 @@ a_Player:OpenWindow(Window);
<p>
All the functions are static, call them using the <code>cMojangAPI:Function()</code> convention.</p>
<p>
Mojang uses two formats for UUIDs, short and dashed. MCServer works with short UUIDs internally, but
Mojang uses two formats for UUIDs, short and dashed. Cuberite works with short UUIDs internally, but
will convert to dashed UUIDs where needed - in the protocol login for example. The MakeUUIDShort()
and MakeUUIDDashed() functions are provided for plugins to use for conversion between the two
formats.</p>
@ -2065,19 +2065,19 @@ a_Player:OpenWindow(Window);
GetBuildCommitID = { Params = "", Return = "string", Notes = "(STATIC) For official builds (Travis CI / Jenkins) it returns the exact commit hash used for the build. For unofficial local builds, returns the approximate commit hash (since the true one cannot be determined), formatted as \"approx: &lt;CommitHash&gt;\"." },
GetBuildDateTime = { Params = "", Return = "string", Notes = "(STATIC) For official builds (Travic CI / Jenkins) it returns the date and time of the build. For unofficial local builds, returns the approximate datetime of the commit (since the true one cannot be determined), formatted as \"approx: &lt;DateTime-iso8601&gt;\"." },
GetBuildID = { Params = "", Return = "string", Notes = "(STATIC) For official builds (Travis CI / Jenkins) it returns the unique ID of the build, as recognized by the build system. For unofficial local builds, returns the string \"Unknown\"." },
GetBuildSeriesName = { Params = "", Return = "string", Notes = "(STATIC) For official builds (Travis CI / Jenkins) it returns the series name of the build (for example \"MCServer Windows x64 Master\"). For unofficial local builds, returns the string \"local build\"." },
GetBuildSeriesName = { Params = "", Return = "string", Notes = "(STATIC) For official builds (Travis CI / Jenkins) it returns the series name of the build (for example \"Cuberite Windows x64 Master\"). For unofficial local builds, returns the string \"local build\"." },
GetCraftingRecipes = { Params = "", Return = "{{cCraftingRecipe|cCraftingRecipe}}", Notes = "Returns the CraftingRecipes object" },
GetDefaultWorld = { Params = "", Return = "{{cWorld|cWorld}}", Notes = "Returns the world object from the default world." },
GetFurnaceFuelBurnTime = { Params = "{{cItem|Fuel}}", Return = "number", Notes = "(STATIC) Returns the number of ticks for how long the item would fuel a furnace. Returns zero if not a fuel." },
GetFurnaceRecipe = { Params = "{{cItem|InItem}}", Return = "{{cItem|OutItem}}, NumTicks, {{cItem|InItem}}", Notes = "(STATIC) Returns the furnace recipe for smelting the specified input. If a recipe is found, returns the smelted result, the number of ticks required for the smelting operation, and the input consumed (note that MCServer supports smelting M items into N items and different smelting rates). If no recipe is found, returns no value." },
GetPhysicalRAMUsage = { Params = "", Return = "number", Notes = "Returns the amount of physical RAM that the entire MCServer process is using, in KiB. Negative if the OS doesn't support this query." },
GetFurnaceRecipe = { Params = "{{cItem|InItem}}", Return = "{{cItem|OutItem}}, NumTicks, {{cItem|InItem}}", Notes = "(STATIC) Returns the furnace recipe for smelting the specified input. If a recipe is found, returns the smelted result, the number of ticks required for the smelting operation, and the input consumed (note that Cuberite supports smelting M items into N items and different smelting rates). If no recipe is found, returns no value." },
GetPhysicalRAMUsage = { Params = "", Return = "number", Notes = "Returns the amount of physical RAM that the entire Cuberite process is using, in KiB. Negative if the OS doesn't support this query." },
GetPluginManager = { Params = "", Return = "{{cPluginManager|cPluginManager}}", Notes = "Returns the cPluginManager object." },
GetPrimaryServerVersion = { Params = "", Return = "number", Notes = "Returns the servers primary server version." },
GetProtocolVersionTextFromInt = { Params = "Protocol Version", Return = "string", Notes = "Returns the Minecraft version from the given Protocol. If there is no version found, it returns 'Unknown protocol(Parameter)'" },
GetServer = { Params = "", Return = "{{cServer|cServer}}", Notes = "Returns the cServer object." },
GetServerUpTime = { Params = "", Return = "number", Notes = "Returns the uptime of the server in seconds." },
GetTotalChunkCount = { Params = "", Return = "number", Notes = "Returns the amount of loaded chunks." },
GetVirtualRAMUsage = { Params = "", Return = "number", Notes = "Returns the amount of virtual RAM that the entire MCServer process is using, in KiB. Negative if the OS doesn't support this query." },
GetVirtualRAMUsage = { Params = "", Return = "number", Notes = "Returns the amount of virtual RAM that the entire Cuberite process is using, in KiB. Negative if the OS doesn't support this query." },
GetWebAdmin = { Params = "", Return = "{{cWebAdmin|cWebAdmin}}", Notes = "Returns the cWebAdmin object." },
GetWorld = { Params = "WorldName", Return = "{{cWorld|cWorld}}", Notes = "Returns the cWorld object of the given world. It returns nil if there is no world with the given name." },
QueueExecuteConsoleCommand = { Params = "Message", Return = "", Notes = "Queues a console command for execution through the cServer class. The command will be executed in the tick thread. The command's output will be sent to console." },
@ -2277,7 +2277,7 @@ local CompressedString = cStringCompression.CompressStringGZIP("DataToCompress")
{
Desc = [[
cWorld is the game world. It is the hub of all the information managed by individual classes,
providing convenient access to them. MCServer supports multiple worlds in any combination of
providing convenient access to them. Cuberite supports multiple worlds in any combination of
world types. You can have two overworlds, three nethers etc. To enumerate all world the server
provides, use the {{cRoot}}:ForEachWorld() function.</p>
<p>
@ -2430,10 +2430,10 @@ local CompressedString = cStringCompression.CompressStringGZIP("DataToCompress")
QueueBlockForTick = { Params = "BlockX, BlockY, BlockZ, TicksToWait", Return = "", Notes = "Queues the specified block to be ticked after the specified number of gameticks." },
QueueSaveAllChunks = { Params = "", Return = "", Notes = "Queues all chunks to be saved in the world storage thread" },
QueueSetBlock = { Params = "BlockX, BlockY, BlockZ, BlockType, BlockMeta, TickDelay", Return = "", Notes = "Queues the block to be set to the specified blocktype and meta after the specified amount of game ticks. Uses SetBlock() for the actual setting, so simulators are woken up and block entities are handled correctly." },
QueueTask = { Params = "TaskFunction", Return = "", Notes = "Queues the specified function to be executed in the tick thread. This is the primary means of interaction with a cWorld from the WebAdmin page handlers (see {{WebWorldThreads}}). The function signature is <pre class=\"pretty-print lang-lua\">function()</pre>All return values from the function are ignored. Note that this function is actually called *after* the QueueTask() function returns. Note that it is unsafe to store references to MCServer objects, such as entities, across from the caller to the task handler function; store the EntityID instead." },
QueueTask = { Params = "TaskFunction", Return = "", Notes = "Queues the specified function to be executed in the tick thread. This is the primary means of interaction with a cWorld from the WebAdmin page handlers (see {{WebWorldThreads}}). The function signature is <pre class=\"pretty-print lang-lua\">function()</pre>All return values from the function are ignored. Note that this function is actually called *after* the QueueTask() function returns. Note that it is unsafe to store references to Cuberite objects, such as entities, across from the caller to the task handler function; store the EntityID instead." },
QueueUnloadUnusedChunks = { Params = "", Return = "", Notes = "Queues a cTask that unloads chunks that are no longer needed and are saved." },
RegenerateChunk = { Params = "ChunkX, ChunkZ", Return = "", Notes = "Queues the specified chunk to be re-generated, overwriting the current data. To queue a chunk for generating only if it doesn't exist, use the GenerateChunk() instead." },
ScheduleTask = { Params = "DelayTicks, TaskFunction", Return = "", Notes = "Queues the specified function to be executed in the world's tick thread after a the specified number of ticks. This enables operations to be queued for execution in the future. The function signature is <pre class=\"pretty-print lang-lua\">function({{cWorld|World}})</pre>All return values from the function are ignored. Note that it is unsafe to store references to MCServer objects, such as entities, across from the caller to the task handler function; store the EntityID instead." },
ScheduleTask = { Params = "DelayTicks, TaskFunction", Return = "", Notes = "Queues the specified function to be executed in the world's tick thread after a the specified number of ticks. This enables operations to be queued for execution in the future. The function signature is <pre class=\"pretty-print lang-lua\">function({{cWorld|World}})</pre>All return values from the function are ignored. Note that it is unsafe to store references to Cuberite objects, such as entities, across from the caller to the task handler function; store the EntityID instead." },
SendBlockTo = { Params = "BlockX, BlockY, BlockZ, {{cPlayer|Player}}", Return = "", Notes = "Sends the block at the specified coords to the specified player's client, as an UpdateBlock packet." },
SetAreaBiome = {
{ Params = "MinX, MaxX, MinZ, MaxZ, EMCSBiome", Return = "bool", Notes = "Sets the biome in the rectangular area specified. Returns true if successful, false if any of the chunks were unloaded." },
@ -2939,7 +2939,7 @@ end
{
Include = { "^eWeather_.*", "wSunny", "wRain", "wStorm", "wThunderstorm" },
TextBefore = [[
These constants represent the weather in the world. Note that unlike vanilla, MCServer allows
These constants represent the weather in the world. Note that unlike vanilla, Cuberite allows
different weathers even in non-overworld {{Globals#WorldDimension|dimensions}}.
]],
},
@ -3035,7 +3035,7 @@ end
ExtraPages =
{
-- No sorting is provided for these, they will be output in the same order as defined here
{ FileName = "Writing-a-MCServer-plugin.html", Title = "Writing a MCServer plugin" },
{ FileName = "Writing-a-MCServer-plugin.html", Title = "Writing a Cuberite plugin" },
{ FileName = "InfoFile.html", Title = "Using the Info.lua file" },
{ FileName = "SettingUpDecoda.html", Title = "Setting up the Decoda Lua IDE" },
{ FileName = "SettingUpZeroBrane.html", Title = "Setting up the ZeroBrane Studio Lua IDE" },

4
MCServer/Plugins/APIDump/Classes/Geometry.lua
View File

@ -123,10 +123,10 @@ various events. See below for further information.
{
Header = "Callbacks",
Contents = [[
The Callbacks in the Trace() function is a table that contains named functions. MCServer will call
The Callbacks in the Trace() function is a table that contains named functions. Cuberite will call
individual functions from that table for the events that occur on the line - hitting a block, going out of
valid world data etc. The following table lists all the available callbacks. If the callback function is
not defined, MCServer skips it. Each function can return a bool value, if it returns true, the tracing is
not defined, Cuberite skips it. Each function can return a bool value, if it returns true, the tracing is
aborted and Trace() returns false.</p>
<p>
<table><tr><th>Name</th><th>Parameters</th><th>Notes</th></tr>

2
MCServer/Plugins/APIDump/Classes/Plugins.lua
View File

@ -73,7 +73,7 @@ cPluginManager.AddHook(cPluginManager.HOOK_CHAT, OnChatMessage);
ForceExecuteCommand = { Params = "{{cPlayer|Player}}, CommandStr", Return = "{{cPluginManager#CommandResult|CommandResult}}", Notes = "Same as ExecuteCommand, but doesn't check permissions" },
ForEachCommand = { Params = "CallbackFn", Return = "bool", Notes = "Calls the CallbackFn function for each command that has been bound using BindCommand(). The CallbackFn has the following signature: <pre class=\"prettyprint lang-lua\">function(Command, Permission, HelpString)</pre> If the callback returns true, the enumeration is aborted and this API function returns false; if it returns false or no value, the enumeration continues with the next command, and the API function returns true." },
ForEachConsoleCommand = { Params = "CallbackFn", Return = "bool", Notes = "Calls the CallbackFn function for each command that has been bound using BindConsoleCommand(). The CallbackFn has the following signature: <pre class=\"prettyprint lang-lua\">function (Command, HelpString)</pre> If the callback returns true, the enumeration is aborted and this API function returns false; if it returns false or no value, the enumeration continues with the next command, and the API function returns true." },
ForEachPlugin = { Params = "CallbackFn", Return = "bool", Notes = "(STATIC) Calls the CallbackFn function for each plugin that is currently discovered by MCServer (including disabled, unloaded and errrored plugins). The CallbackFn has the following signature: <pre class=\"prettyprint lang-lua\">function ({{cPlugin|Plugin}})</pre> If the callback returns true, the enumeration is aborted and this API function returns false; if it returns false or no value, the enumeration continues with the next command, and the API function returns true." },
ForEachPlugin = { Params = "CallbackFn", Return = "bool", Notes = "(STATIC) Calls the CallbackFn function for each plugin that is currently discovered by Cuberite (including disabled, unloaded and errrored plugins). The CallbackFn has the following signature: <pre class=\"prettyprint lang-lua\">function ({{cPlugin|Plugin}})</pre> If the callback returns true, the enumeration is aborted and this API function returns false; if it returns false or no value, the enumeration continues with the next command, and the API function returns true." },
Get = { Params = "", Return = "cPluginManager", Notes = "(STATIC) Returns the single instance of the plugin manager" },
GetAllPlugins = { Params = "", Return = "table", Notes = "Returns a table (dictionary) of all plugins, [name => value], where value is a valid {{cPlugin}} if the plugin is loaded, or the bool value false if the plugin is not loaded." },
GetCommandPermission = { Params = "Command", Return = "Permission", Notes = "Returns the permission needed for executing the specified command" },

2
MCServer/Plugins/APIDump/Hooks/OnBlockSpread.lua
View File

@ -29,7 +29,7 @@ return
},
Returns = [[
If the function returns false or no value, the next plugin's callback is called, and finally
MCServer will process the spread. If the function
Cuberite will process the spread. If the function
returns true, no other callback is called for this event and the spread will not occur.
]],
}, -- HOOK_BLOCK_SPREAD

6
MCServer/Plugins/APIDump/Hooks/OnChunkGenerated.lua
View File

@ -21,10 +21,10 @@ return
{ 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 the plugin returns false or no value, Cuberite 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.
In either case, Cuberite will then store the data from ChunkDesc as the chunk's contents in the world.
]],
CodeExamples =
{
@ -34,7 +34,7 @@ return
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
-- This is actually similar to how Cuberite 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;

4
MCServer/Plugins/APIDump/Hooks/OnChunkUnloading.lua
View File

@ -5,8 +5,8 @@ return
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>
Cuberite calls this function when a chunk is about to be unloaded from the memory. A plugin may
force Cuberite 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.

2
MCServer/Plugins/APIDump/Hooks/OnCollectingPickup.lua
View File

@ -20,7 +20,7 @@ return
{ 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
If the function returns false or no value, Cuberite 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.
]],

4
MCServer/Plugins/APIDump/Hooks/OnCraftingNoRecipe.lua
View File

@ -6,7 +6,7 @@ return
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
Cuberite cannot find a built-in {{cCraftingRecipe|recipe}} for the combination. Plugins may provide
a recipe for the ingredients given.
]],
Params =
@ -17,7 +17,7 @@ return
},
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
other plugin will have their callback called for this event and Cuberite will use the crafting
recipe in Recipe.</p>
<p>
FIXME: To allow plugins give suggestions and overwrite other plugins' suggestions, we should change

2
MCServer/Plugins/APIDump/Hooks/OnDisconnect.lua
View File

@ -26,7 +26,7 @@ return
{ 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 false or no value, Cuberite calls other plugins' callbacks for this event.
If the function returns true, no other plugins are called for this event. In either case,
the client is disconnected.
]],

2
MCServer/Plugins/APIDump/Hooks/OnEntityAddEffect.lua
View File

@ -22,7 +22,7 @@ return
},
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
be called. If the plugin returns false, Cuberite calls all the remaining hook handlers and finally
the effect is added to the entity.
]],
}, -- HOOK_EXECUTE_COMMAND

2
MCServer/Plugins/APIDump/Hooks/OnExecuteCommand.lua
View File

@ -27,7 +27,7 @@ return
{ Name = "EntireCommand", Type = "string", Notes = "The entire command as a single string" },
},
Returns = [[
If the plugin returns false, MCServer calls all the remaining hook handlers and finally the command
If the plugin returns false, Cuberite calls all the remaining hook handlers and finally the command
will be executed. If the plugin returns true, the none of the remaining hook handlers will be called.
In this case the plugin can return a second value, specifying whether what the command result should
be set to, one of the {{cPluginManager#CommandResult|CommandResult}} constants. If not

2
MCServer/Plugins/APIDump/Hooks/OnExploding.lua
View File

@ -39,7 +39,7 @@ return
},
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
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.
]],
}, -- HOOK_EXPLODING

2
MCServer/Plugins/APIDump/Hooks/OnKilling.lua
View File

@ -16,7 +16,7 @@ return
{ Name = "TDI", Type = "{{TakeDamageInfo}}", Notes = "The damage type, cause and effects." },
},
Returns = [[
If the function returns false or no value, MCServer calls other plugins with this event. If the
If the function returns false or no value, Cuberite 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

2
MCServer/Plugins/APIDump/Hooks/OnLogin.lua
View File

@ -19,7 +19,7 @@ return
},
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
If the function returns false or no value, Cuberite 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.
]],

10
MCServer/Plugins/APIDump/Hooks/OnPlayerLeftClick.lua
View File

@ -5,15 +5,15 @@ return
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
This hook is called when Cuberite 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
Plugins may refuse the default processing for the packet, causing Cuberite 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
if a plugin refuses the processing, Cuberite 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>
@ -31,11 +31,11 @@ return
{ 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
If the function returns false or no value, Cuberite 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
block dig, Cuberite sends the block specified in the coords back to the client. The packet is
dropped.
]],
}, -- HOOK_PLAYER_LEFT_CLICK

2
MCServer/Plugins/APIDump/Hooks/OnPlayerPlacedBlock.lua
View File

@ -28,7 +28,7 @@ return
{ 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
If this function returns false or no value, Cuberite calls other plugins with the same event. If
this function returns true, no other plugin is called for this event.
]],
}, -- HOOK_PLAYER_PLACED_BLOCK

6
MCServer/Plugins/APIDump/Hooks/OnPlayerPlacingBlock.lua
View File

@ -10,7 +10,7 @@ return
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>
refuses the placement, Cuberite 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>
@ -31,9 +31,9 @@ return
{ 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
If this function returns false or no value, Cuberite 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
function returns true, no other plugin is called for this event, Cuberite sends the old block at
the specified coords to the client and drops the packet.
]],
}, -- HOOK_PLAYER_PLACING_BLOCK

6
MCServer/Plugins/APIDump/Hooks/OnPlayerRightClick.lua
View File

@ -5,12 +5,12 @@ return
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
This hook is called when Cuberite 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
Plugins may refuse the default processing for the packet, causing Cuberite 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.
]],
@ -26,7 +26,7 @@ return
{ Name = "CursorZ", Type = "number", Notes = "Z-coord of the mouse crosshair on the block" },
},
Returns = [[
If the function returns false or no value, MCServer calls other plugins' callbacks and finally sends
If the function returns false or no value, Cuberite 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.

2
MCServer/Plugins/APIDump/Hooks/OnPlayerRightClickingEntity.lua
View File

@ -14,7 +14,7 @@ return
{ 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
If the functino returns false or no value, Cuberite 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.
]],

2
MCServer/Plugins/APIDump/Hooks/OnPlayerShooting.lua
View File

@ -20,7 +20,7 @@ return
},
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
Cuberite creates the projectile. If the functino returns true, no other callback is called and no
projectile is created.
]],
}, -- HOOK_PLAYER_SHOOTING

2
MCServer/Plugins/APIDump/Hooks/OnPlayerTossingItem.lua
View File

@ -20,7 +20,7 @@ return
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}}:TossHeldItem, {{cPlayer}}:TossEquippedItem,
or {{cPlayer}}:TossPickup. If the function returns true, no other callbacks are called for this event
and MCServer doesn't toss the item.
and Cuberite doesn't toss the item.
]],
}, -- HOOK_PLAYER_TOSSING_ITEM
}

2
MCServer/Plugins/APIDump/Hooks/OnPlayerUsedBlock.lua
View File

@ -6,7 +6,7 @@ return
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
{{cChestEntity|chest}} or a lever. It is called after Cuberite 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>

2
MCServer/Plugins/APIDump/Hooks/OnPlayerUsedItem.lua
View File

@ -7,7 +7,7 @@ return
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).
hoe. It is called after Cuberite 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,

2
MCServer/Plugins/APIDump/Hooks/OnPlayerUsingBlock.lua
View File

@ -6,7 +6,7 @@ return
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
{{cChestEntity|chest}} or a lever. It is called before Cuberite 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,

2
MCServer/Plugins/APIDump/Hooks/OnPlayerUsingItem.lua
View File

@ -7,7 +7,7 @@ return
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).
hoe. It is called before Cuberite 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,

4
MCServer/Plugins/APIDump/Hooks/OnPostCrafting.lua
View File

@ -20,11 +20,11 @@ return
{
{ 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)" },
{ Name = "Recipe", Type = "{{cCraftingRecipe}}", Notes = "The recipe that Cuberite 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
returns true, no other callbacks are called for this event. In either case, Cuberite uses the value
of Recipe as the recipe to be presented to the player.
]],
}, -- HOOK_POST_CRAFTING

4
MCServer/Plugins/APIDump/Hooks/OnPreCrafting.lua
View File

@ -19,13 +19,13 @@ return
{
{ 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" },
{ Name = "Recipe", Type = "{{cCraftingRecipe}}", Notes = "The recipe that Cuberite 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
If the function returns true, no other callbacks are called for this event and Cuberite uses the
recipe stored in the Recipe output parameter.
]],
}, -- HOOK_PRE_CRAFTING

4
MCServer/Plugins/APIDump/InfoFile.html
View File

@ -1,7 +1,7 @@
<!DOCTYPE html>
<html>
<head>
<title>MCServer - Info.lua file</title>
<title>Cuberite - Info.lua file</title>
<link rel="stylesheet" type="text/css" href="main.css" />
<link rel="stylesheet" type="text/css" href="prettify.css" />
<script src="prettify.js"></script>
@ -27,7 +27,7 @@
<hr />
<a name="Introduction"><h2>Introduction</h2></a>
<p>For a long time MCServer plugins were plagued by poor documentation. The plugins worked, people who wrote them knew how to use them, but for anyone new to the plugin it was a terrible ordeal learning how to use it. Most of the times, the plugin authors only wrote what commands the plugin supported, sometimes not even that. Then, there was a call to action to put an end to this, to make documenting the plugins easy and at the same time centralized. Thus, the Info.lua file was born.</p>
<p>For a long time Cuberite plugins were plagued by poor documentation. The plugins worked, people who wrote them knew how to use them, but for anyone new to the plugin it was a terrible ordeal learning how to use it. Most of the times, the plugin authors only wrote what commands the plugin supported, sometimes not even that. Then, there was a call to action to put an end to this, to make documenting the plugins easy and at the same time centralized. Thus, the Info.lua file was born.</p>
<p>Most plugins have some parts that are the same across all the plugins. These are commands, console commands and their permissions. If a plugin implemented a command, it would practically copy &amp; paste the same code over and over again. So it makes sense to extract only unique information, centralize it and automate all the parts around it. This was another reason for the Info.lua file - it is a central hub of commands, console commands and their permissions.</p>

10
MCServer/Plugins/APIDump/SettingUpDecoda.html
View File

@ -2,7 +2,7 @@
<html>
<head>
<title>MCServer - Setting up Decoda</title>
<title>Cuberite - Setting up Decoda</title>
<link rel="stylesheet" type="text/css" href="main.css" />
<link rel="stylesheet" type="text/css" href="prettify.css" />
<script src="prettify.js"></script>
@ -13,7 +13,7 @@
<div id="content">
<h1>Setting up the Decoda IDE</h1>
<p>
This article will explain how to set up Decoda, an IDE for writing Lua code, so that you can develop MCServer plugins with the comfort of an IDE.</p>
This article will explain how to set up Decoda, an IDE for writing Lua code, so that you can develop Cuberite plugins with the comfort of an IDE.</p>
<h2><img src="Static/decoda_logo.png" /> About Decoda</h2>
@ -30,9 +30,9 @@
<p>In the debugging section, fill in the full path to MCServer.exe, or click the triple-dot button to browse for the file. Note that the Working directory will be automatically filled in for you with the folder where the executable is (until the last backslash). This is how it's supposed to work, don't change it; if it for some reason doesn't update, copy and paste the folder name from the Command edit box. All done, you can close this dialog now.</p>
<h2><img src="Static/decoda_logo.png" /> Debugging</h2>
<p>You are now ready to debug your code. Before doing that, though, don't forget to save your project file. If you haven't done so already, enable your plugin in the settings.ini file. If you want the program to break at a certain line, it is best to set the breakpoint before starting the program. Set the cursor on the line and hit F9 (or use menu Debug -> Toggle Breakpoint) to toggle a breakpoint on that line. Finally, hit F5, or select menu Debug -> Start to launch MCServer under the debugger. The MCServer window comes up and loads your plugin. If Decoda displays the Project Settings dialog instead, you haven't set up the executable to run, see the Project management section for instructions.</p>
<p>At this point you will see that Decoda starts adding new items to your project. All the files for all plugins are added temporarily. Don't worry, they are only temporary, they will be removed again once the debugging session finishes. You can tell the temporary files from the regular files by their icon, it's faded out. Decoda handles all the files that MCServer loads, so you can actually debug any of those faded files, too.</p>
<p>If there's an error in the code, the Decoda window will flash and a dialog box will come up, describing the error and taking you to the line where it occured. Note that the execution is paused in the thread executing the plugin, so until you select Debug -> Continue from the menu (F5), MCServer won't be fully running. You can fix the error and issue a "reload" command in MCServer console to reload the plugin code anew (MCServer doesn't detect changes in plugin code automatically).</p>
<p>You are now ready to debug your code. Before doing that, though, don't forget to save your project file. If you haven't done so already, enable your plugin in the settings.ini file. If you want the program to break at a certain line, it is best to set the breakpoint before starting the program. Set the cursor on the line and hit F9 (or use menu Debug -> Toggle Breakpoint) to toggle a breakpoint on that line. Finally, hit F5, or select menu Debug -> Start to launch Cuberite under the debugger. The Cuberite window comes up and loads your plugin. If Decoda displays the Project Settings dialog instead, you haven't set up the executable to run, see the Project management section for instructions.</p>
<p>At this point you will see that Decoda starts adding new items to your project. All the files for all plugins are added temporarily. Don't worry, they are only temporary, they will be removed again once the debugging session finishes. You can tell the temporary files from the regular files by their icon, it's faded out. Decoda handles all the files that Cuberite loads, so you can actually debug any of those faded files, too.</p>
<p>If there's an error in the code, the Decoda window will flash and a dialog box will come up, describing the error and taking you to the line where it occured. Note that the execution is paused in the thread executing the plugin, so until you select Debug -> Continue from the menu (F5), Cuberite won't be fully running. You can fix the error and issue a "reload" command in Cuberite console to reload the plugin code anew (Cuberite doesn't detect changes in plugin code automatically).</p>
<p>If the execution hits a breakpoint, the Decoda window will flash and a yellow arrow is displayed next to the line. You can step through the code using F10 and F11, just like in MSVS. You can also use the Watch window to inspect variable values, or simply hover your mouse over a variable to display its value in the tooltip.</p>
<h2><img src="Static/decoda_logo.png" /> Limitations</h2>

20
MCServer/Plugins/APIDump/SettingUpZeroBrane.html
View File

@ -2,7 +2,7 @@
<html>
<head>
<title>MCServer - Setting up ZeroBrane Studio</title>
<title>Cuberite - Setting up ZeroBrane Studio</title>
<link rel="stylesheet" type="text/css" href="main.css" />
<link rel="stylesheet" type="text/css" href="prettify.css" />
<script src="prettify.js"></script>
@ -13,7 +13,7 @@
<div id="content">
<h1>Setting up the ZeroBrane Studio IDE</h1>
<p>
This article will explain how to set up ZeroBrane Studio, an IDE for writing Lua code, so that you can develop MCServer plugins with the comfort of an IDE.</p>
This article will explain how to set up ZeroBrane Studio, an IDE for writing Lua code, so that you can develop Cuberite plugins with the comfort of an IDE.</p>
<h2><img src="Static/zbs_logo.png" /> About ZeroBrane Studio</h2>
@ -24,23 +24,23 @@
<p>ZBS is open-source, the sources are on GitHub: <a href="https://github.com/pkulchenko/ZeroBraneStudio">https://github.com/pkulchenko/ZeroBraneStudio</a>. The project's homepage is at <a href="http://studio.zerobrane.com/">http://studio.zerobrane.com/</a>.
<h2><img src="Static/zbs_logo.png" /> First-time setup</h2>
<p>Since ZBS is a universal Lua IDE, you need to first set it up so that it is ready for MCS plugin development. For that, you need to download one file, <a href="https://raw.githubusercontent.com/pkulchenko/ZeroBranePackage/master/mcserver.lua">mcserver.lua</a> from the <a href="https://github.com/pkulchenko/ZeroBranePackage">ZBS's plugin repository</a>. Place that file in the "packages" folder inside your ZBS's folder. Note that there are other useful plugins in the repository and you may want to have a look there later on to further customize your ZBS. To install them, simply save them into the same folder.</p>
<p>Next you should install the code-completion support specific for MCServer. You should repeat this step from time to time, because the API evolves in time so new functions and classes are added to it quite often. You should have an APIDump plugin in your MCServer installation. Enable the APIDump plugin in the server settings, it's very cheap to keep it enabled and it doesn't cost any performance during normal gameplay. To generate the code-completion support file, enter the <code style="background: #ddd; border: 1px solid #aaa">api</code> command into the server console. This will create a new file, "mcserver_api.lua", next to the MCS executable. Move that file into the "api/lua" subfolder inside your ZBS's folder.</p>
<p>After you download the mcserver.lua file and install the completion support, you need to restart ZBS in order for the plugin to load. If there are no errors, you should see two new items in the Project -> Lua Interpreter submenu: "MCServer - debug mode" and "MCServer - release mode". The only difference between the two is which filename they use to launch MCServer - mcserver_debug(.exe) for the debug option and "mcserver(.exe)" for the release option. If you built your own MCServer executable and you built it in debug mode, you should select the debug mode option. In all other cases, including if you downloaded the already-compiled MCServer executable from the internet, you should select the release mode option.</p>
<p>Since ZBS is a universal Lua IDE, you need to first set it up so that it is ready for Cuberite plugin development. For that, you need to download one file, <a href="https://raw.githubusercontent.com/pkulchenko/ZeroBranePackage/master/mcserver.lua">mcserver.lua</a> from the <a href="https://github.com/pkulchenko/ZeroBranePackage">ZBS's plugin repository</a>. Place that file in the "packages" folder inside your ZBS's folder. Note that there are other useful plugins in the repository and you may want to have a look there later on to further customize your ZBS. To install them, simply save them into the same folder.</p>
<p>Next you should install the code-completion support specific for MCServer. You should repeat this step from time to time, because the API evolves in time so new functions and classes are added to it quite often. You should have an APIDump plugin in your Cuberite installation. Enable the APIDump plugin in the server settings, it's very cheap to keep it enabled and it doesn't cost any performance during normal gameplay. To generate the code-completion support file, enter the <code style="background: #ddd; border: 1px solid #aaa">api</code> command into the server console. This will create a new file, "mcserver_api.lua", next to the Cuberite executable. Move that file into the "api/lua" subfolder inside your ZBS's folder.</p>
<p>After you download the mcserver.lua file and install the completion support, you need to restart ZBS in order for the plugin to load. If there are no errors, you should see two new items in the Project -> Lua Interpreter submenu: "Cuberite - debug mode" and "Cuberite - release mode". The only difference between the two is which filename they use to launch Cuberite - mcserver_debug(.exe) for the debug option and "mcserver(.exe)" for the release option. If you built your own Cuberite executable and you built it in debug mode, you should select the debug mode option. In all other cases, including if you downloaded the already-compiled Cuberite executable from the internet, you should select the release mode option.</p>
<p>For a first time user, it might be a bit overwhelming that there are no GUI settings in the ZBS, yet the IDE is very configurable. There are two files that you edit in order to change settings, either system-wide (all users of the computer share those settings) or user-wide (the settings are only for a specific user of the computer). Those files are regular Lua sources and you can quickly locate them and edit them from within the IDE itself, select Edit -> Preferences -> Settings: XYZ from the menu, with XYZ being either System or User.</p>
<p>There is a documentation on most of the settings on ZBS's webpage, have a look at <a href="http://studio.zerobrane.com/documentation.html">http://studio.zerobrane.com/documentation.html</a>, especially the Preferences section. Personally I recommend setting editor.usetabs to true and possibly adjusting the editor.tabwidth, turn off the editor.smartindent feature and for debugging the option debugger.alloweditting should be set to true unless you feel like punishing yourself.</p>
<h2><img src="Static/zbs_logo.png" /> Project management</h2>
<p>ZBS works with projects, it considers all files and subfolder in a specific folder to be a project. There's no need for a special project file nor for adding individual files to the workspace, all files are added automatically. To open a MCS plugin as the project, click the triple-dot button in the Project pane, or select Project -> Project directory -> Choose... from the menu. Browse and select the MCS plugin's folder. ZBS will load all the files in the plugin's folder and you can start editting code.</p>
<p>Note that although ZBS allows you to work with subfolders in your plugins (and you should, especially with larger plugins), the current mcserver ZBS plugin will not be able to start debugging unless you have a file open in the editor that is at the root level of the MCS plugin's folder.</p>
<p>ZBS works with projects, it considers all files and subfolder in a specific folder to be a project. There's no need for a special project file nor for adding individual files to the workspace, all files are added automatically. To open a Cuberite plugin as the project, click the triple-dot button in the Project pane, or select Project -> Project directory -> Choose... from the menu. Browse and select the Cuberite plugin's folder. ZBS will load all the files in the plugin's folder and you can start editting code.</p>
<p>Note that although ZBS allows you to work with subfolders in your plugins (and you should, especially with larger plugins), the current Cuberite ZBS plugin will not be able to start debugging unless you have a file open in the editor that is at the root level of the Cuberite plugin's folder.</p>
<h2><img src="Static/zbs_logo.png" /> Debugging</h2>
<p>You are now ready to debug your code. Before doing that, though, don't forget to save your project files. If you haven't done so already, enable your plugin in the settings.ini file. If you want the program to break at a certain line, it is best to set the breakpoint before starting the program. Set the cursor on the line and hit F9 (or use menu Project -> Toggle Breakpoint) to toggle a breakpoint on that line. Finally, hit F5, or select menu Project -> Start Debugging to launch MCServer under the debugger. The MCServer window comes up and loads your plugin. If the window doesn't come up, inspect the Output pane in ZBS, there are usually two reasons for failure:<ul>
<p>You are now ready to debug your code. Before doing that, though, don't forget to save your project files. If you haven't done so already, enable your plugin in the settings.ini file. If you want the program to break at a certain line, it is best to set the breakpoint before starting the program. Set the cursor on the line and hit F9 (or use menu Project -> Toggle Breakpoint) to toggle a breakpoint on that line. Finally, hit F5, or select menu Project -> Start Debugging to launch Cuberite under the debugger. The Cuberite window comes up and loads your plugin. If the window doesn't come up, inspect the Output pane in ZBS, there are usually two reasons for failure:<ul>
<li>Your code in the currently open file has a hard syntax error. These are reported as "Compilation error" in the Output pane, double-click the line to go to the error</li>
<li>ZBS cannot find the MCServer executable. Make sure you are editting a file two levels down the folder hierarchy from the MCS executable and that the MCS executable is named properly (mcserver[.exe] or mcserver_debug[.exe]). Also make sure you have selected the right Interpreter (menu Project -> Lua Interpreter).</li>
<li>ZBS cannot find the Cuberite executable. Make sure you are editting a file two levels down the folder hierarchy from the Cuberite executable and that the Cuberite executable is named properly (mcserver[.exe] or mcserver_debug[.exe]). Also make sure you have selected the right Interpreter (menu Project -> Lua Interpreter).</li>
</ul></p>
<p>Once running, if the execution hits a breakpoint, the ZBS window will come up and a green arrow is displayed next to the breakpoint line. You can step through the code using F10 (Step Into) and Shift+F10 (Step Over). You can also use the Watch window to inspect variable values, or simply hover your mouse over a variable to display its value in the tooltip. Use the Remote console pane to execute commands directly *inside* the MCServer's plugin context.</p>
<p>You can also use the Project -> Break menu item to break into the debugger as soon as possible. You can also set breakpoints while the MCS plugin is running. Note that due to the way in which the debugger is implemented, MCS may execute some more Lua code before the break / breakpoint comes into effect. If MCS is not executing any Lua code in your plugin, it will not break until the plugin code kicks in again. This may result in missed breakpoints and delays before the Break command becomes effective. Therefore it's best to set breakpoints before running the program, or while the program is waiting in another breakpoint.</p>
<p>You can also use the Project -> Break menu item to break into the debugger as soon as possible. You can also set breakpoints while the Cuberite plugin is running. Note that due to the way in which the debugger is implemented, Cuberite may execute some more Lua code before the break / breakpoint comes into effect. If Cuberite is not executing any Lua code in your plugin, it will not break until the plugin code kicks in again. This may result in missed breakpoints and delays before the Break command becomes effective. Therefore it's best to set breakpoints before running the program, or while the program is waiting in another breakpoint.</p>
</div>
</body>
</html>

2
MCServer/Plugins/APIDump/UsingChunkStays.html
View File

@ -1,7 +1,7 @@
<!DOCTYPE html>
<html>
<head>
<title>MCServer - Using ChunkStays</title>
<title>Cuberite - Using ChunkStays</title>
<link rel="stylesheet" type="text/css" href="main.css" />
<link rel="stylesheet" type="text/css" href="prettify.css" />
<script src="prettify.js"></script>

4
MCServer/Plugins/APIDump/WebWorldThreads.html
View File

@ -1,7 +1,7 @@
<!DOCTYPE html>
<html>
<head>
<title>MCServer - Webserver vs World threads</title>
<title>Cuberite - Webserver vs World threads</title>
<link rel="stylesheet" type="text/css" href="main.css" />
<link rel="stylesheet" type="text/css" href="prettify.css" />
<script src="prettify.js"></script>
@ -14,7 +14,7 @@
<p>
This article will explain the threading issues that arise between the webserver and world threads are of concern to plugin authors.</p>
<p>
Generally, plugins that provide webadmin pages should be quite careful about their interactions. Most operations on MCServer objects requires synchronization, that MCServer provides automatically and transparently to plugins - when a block is written, the chunkmap is locked, or when an entity is being manipulated, the entity list is locked. Each plugin also has a mutex lock, so that only one thread at a time may be executing plugin code.</p>
Generally, plugins that provide webadmin pages should be quite careful about their interactions. Most operations on Cuberite objects requires synchronization, that Cuberite provides automatically and transparently to plugins - when a block is written, the chunkmap is locked, or when an entity is being manipulated, the entity list is locked. Each plugin also has a mutex lock, so that only one thread at a time may be executing plugin code.</p>
<p>
This locking can be a source of deadlocks for plugins that are not written carefully.</p>

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

@ -2,7 +2,7 @@
<html>
<head>
<title>MCS Plugin Tutorial</title>
<title>Cuberite Plugin Tutorial</title>
<link rel="stylesheet" type="text/css" href="main.css" />
<link rel="stylesheet" type="text/css" href="prettify.css" />
<script src="prettify.js"></script>
@ -11,7 +11,7 @@
</head>
<body>
<div id="content">
<h1>Writing a MCServer plugin</h1>
<h1>Writing a Cuberite plugin</h1>
<p>
This article will explain how to write a basic plugin. It details basic requirements
for a plugin, explains how to register a hook and bind a command, and gives plugin
@ -20,12 +20,12 @@
<p>
Let us begin. In order to begin development, we must firstly obtain a compiled copy
of MCServer, and make sure that the Core plugin is within the Plugins folder, and activated.
Core handles much of the MCServer end-user experience and gameplay will be very bland without it.
Core handles much of the Cuberite end-user experience and gameplay will be very bland without it.
</p>
<h2>Creating the basic template</h2>
<p>
Plugins are written in Lua. Therefore, create a new Lua file. You can create as many files as you wish, with
any filename - MCServer bungs them all together at runtime, however, let us create a file called main.lua for now.
any filename - Cuberite bungs them all together at runtime, however, let us create a file called main.lua for now.
Format it like so:
</p>
<pre class="prettyprint lang-lua">
@ -60,12 +60,12 @@ end
This global variable is only needed if you want to know the plugin details (name, etc.) when shutting down.</li>
<li><b>function OnDisable</b> is called when the plugin is disabled, commonly when the server is shutting down. Perform cleanup and logging here.</li>
</ul>
Be sure to return true for this function, else MCS thinks you plugin had failed to initialise and prints a stacktrace with an error message.
Be sure to return true for this function, else Cuberite thinks you plugin had failed to initialise and prints a stacktrace with an error message.
</p>
<h2>Registering hooks</h2>
<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 Cuberite 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="index.html">the API documentation</a>.
</p>
<p>
@ -85,7 +85,7 @@ cPluginManager.AddHook(cPluginManager.HOOK_NAME_HERE, FunctionNameToBeCalled)
<ul>
<li><b>cPluginManager.AddHook</b> registers the hook. The hook name is the second parameter. See the previous API documentation link for a list of all hooks.</li>
</ul>
What about the third parameter, you ask? Well, it is the name of the function that MCServer calls when the hook fires. It is in this
What about the third parameter, you ask? Well, it is the name of the function that Cuberite calls when the hook fires. It is in this
function that you should handle or cancel the hook.
</p>
<p>
@ -140,11 +140,11 @@ cPluginManager.BindCommand("/commandname", "permissionnode", FunctionToCall, " ~
</p>
<h3>Parameters</h3>
<p>
What parameters are in the function MCServer calls when the command is executed? A 'Split' array and a 'Player' object.
What parameters are in the function Cuberite calls when the command is executed? A 'Split' array and a 'Player' object.
</p>
<h4>The Split Array</h4>
<p>
The Split array is an array of all text submitted to the server, including the actual command. MCServer automatically splits the text into the array,
The Split array is an array of all text submitted to the server, including the actual command. Cuberite automatically splits the text into the array,
so plugin authors do not need to worry about that. An example of a Split array passed for the command, "/derp zubby explode" would be:<br /><br />
&nbsp&nbsp /derp (Split[1])<br />
&nbsp&nbsp zubby (Split[2])<br />
@ -206,7 +206,7 @@ function Explode(Split, Player)
return true
end
-- Create a callback ExplodePlayer with parameter Explodee, which MCS calls for every player on the server
-- 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
@ -215,11 +215,11 @@ function Explode(Split, Player)
Player:GetWorld():DoExplosionAt(Explodee:GetPosX(), Explodee:GetPosY(), Explodee:GetPosZ(), false, esPlugin)
Player:SendMessageSuccess(Split[2] .. " was successfully exploded")
HasExploded = true;
return true -- Signalize to MCS that we do not need to call this callback for any more players
return true -- Signalize to Cuberite that we do not need to call this callback for any more players
end
end
-- Tell MCS to loop through all players and call the callback above with the Player object it has found
-- Tell Cuberite to loop through all players and call the callback above with the Player object it has found
cRoot:Get():FindAndDoWithPlayer(Split[2], ExplodePlayer)
if not(HasExploded) then
@ -239,7 +239,7 @@ function OnCollectingPickup(Player, Pickup) -- Again, see the API docs for param
end
</pre>
<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 Cuberite 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,
and finally, <a href="index.html">the API documentation</a> is your friend!
</p>

229
MCServer/Plugins/APIDump/main_APIDump.lua
View File

@ -20,7 +20,7 @@ local g_TrackedPages = {}
local function LoadAPIFiles(a_Folder, a_DstTable)
assert(type(a_Folder) == "string")
assert(type(a_DstTable) == "table")
local Folder = g_PluginFolder .. a_Folder;
for _, fnam in ipairs(cFile:GetFolderContents(Folder)) do
local FileName = Folder .. fnam;
@ -79,7 +79,7 @@ local function CreateAPITables()
},
...
},
cCuboid = {} -- Each array item also has the map item by its name
};
local Globals = {
@ -94,7 +94,7 @@ local function CreateAPITables()
local Globals = {Functions = {}, Constants = {}, Variables = {}, Descendants = {}};
local API = {};
local function Add(a_APIContainer, a_ObjName, a_ObjValue)
if (type(a_ObjValue) == "function") then
table.insert(a_APIContainer.Functions, {Name = a_ObjName});
@ -105,14 +105,14 @@ local function CreateAPITables()
table.insert(a_APIContainer.Constants, {Name = a_ObjName, Value = a_ObjValue});
end
end
local function ParseClass(a_ClassName, a_ClassObj)
local res = {Name = a_ClassName, Functions = {}, Constants = {}, Variables = {}, Descendants = {}};
-- Add functions and constants:
for i, v in pairs(a_ClassObj) do
Add(res, i, v);
end
-- Member variables:
local SetField = a_ClassObj[".set"] or {};
if ((a_ClassObj[".get"] ~= nil) and (type(a_ClassObj[".get"]) == "table")) then
@ -128,7 +128,7 @@ local function CreateAPITables()
end
return res;
end
for i, v in pairs(_G) do
if (
(v ~= _G) and -- don't want the global namespace
@ -145,7 +145,7 @@ local function CreateAPITables()
end
end
end
return API, Globals;
end
@ -196,14 +196,14 @@ end
local function LinkifyString(a_String, a_Referrer)
assert(a_Referrer ~= nil);
assert(a_Referrer ~= "");
--- Adds a page to the list of tracked pages (to be checked for existence at the end)
local function AddTrackedPage(a_PageName)
local Pg = (g_TrackedPages[a_PageName] or {});
table.insert(Pg, a_Referrer);
g_TrackedPages[a_PageName] = Pg;
end
--- Creates the HTML for the specified link and title
local function CreateLink(Link, Title)
if (Link:sub(1, 7) == "http://") then
@ -226,7 +226,7 @@ local function LinkifyString(a_String, a_Referrer)
AddTrackedPage(Link);
return "<a href=\"" .. Link .. ".html\">" .. Title .. "</a>";
end
-- Linkify the strings using the CreateLink() function:
local txt = a_String:gsub("{{([^|}]*)|([^}]*)}}", CreateLink) -- {{link|title}}
txt = txt:gsub("{{([^|}]*)}}", -- {{LinkAndTitle}}
@ -254,10 +254,10 @@ local function WriteHtmlHook(a_Hook, a_HookNav)
return;
end
local HookName = a_Hook.DefaultFnName;
f:write([[<!DOCTYPE html><html>
<head>
<title>MCServer API - ]], HookName, [[ Hook</title>
<title>Cuberite API - ]], HookName, [[ Hook</title>
<link rel="stylesheet" type="text/css" href="main.css" />
<link rel="stylesheet" type="text/css" href="prettify.css" />
<script src="prettify.js"></script>
@ -330,7 +330,7 @@ local function WriteHooks(f, a_Hooks, a_UndocumentedHooks, a_HookNav)
A plugin can decide whether it will let the event pass through to the rest of the plugins, or hide it
from them. This is determined by the return value from the hook callback function. If the function
returns false or no value, the event is propagated further. If the function returns true, the processing
is stopped, no other plugin receives the notification (and possibly MCServer disables the default
is stopped, no other plugin receives the notification (and possibly Cuberite disables the default
behavior for the event). See each hook's details to see the exact behavior.</p>
<table>
<tr>
@ -371,7 +371,7 @@ local function ReadDescriptions(a_API)
end
return false;
end
-- Returns true if the function is to be ignored
local function IsFunctionIgnored(a_ClassName, a_FnName)
if (g_APIDesc.IgnoreFunctions == nil) then
@ -389,7 +389,7 @@ local function ReadDescriptions(a_API)
end
return false;
end
-- Returns true if the constant (specified by its fully qualified name) is to be ignored
local function IsConstantIgnored(a_CnName)
if (g_APIDesc.IgnoreConstants == nil) then
@ -402,7 +402,7 @@ local function ReadDescriptions(a_API)
end
return false;
end
-- Returns true if the member variable (specified by its fully qualified name) is to be ignored
local function IsVariableIgnored(a_VarName)
if (g_APIDesc.IgnoreVariables == nil) then
@ -415,7 +415,7 @@ local function ReadDescriptions(a_API)
end
return false;
end
-- Remove ignored classes from a_API:
local APICopy = {};
for _, cls in ipairs(a_API) do
@ -433,7 +433,7 @@ local function ReadDescriptions(a_API)
cls.ConstantGroups = {};
cls.NumConstantsInGroups = 0;
cls.NumConstantsInGroupsForDescendants = 0;
-- Rename special functions:
for _, fn in ipairs(cls.Functions) do
if (fn.Name == ".call") then
@ -456,13 +456,13 @@ local function ReadDescriptions(a_API)
fn.Name = "<i>operator ==</i>";
end
end
local APIDesc = g_APIDesc.Classes[cls.Name];
if (APIDesc ~= nil) then
APIDesc.IsExported = true;
cls.Desc = APIDesc.Desc;
cls.AdditionalInfo = APIDesc.AdditionalInfo;
-- Process inheritance:
if (APIDesc.Inherits ~= nil) then
for _, icls in ipairs(a_API) do
@ -476,13 +476,13 @@ local function ReadDescriptions(a_API)
cls.UndocumentedFunctions = {}; -- This will contain names of all the functions that are not documented
cls.UndocumentedConstants = {}; -- This will contain names of all the constants that are not documented
cls.UndocumentedVariables = {}; -- This will contain names of all the variables that are not documented
local DoxyFunctions = {}; -- This will contain all the API functions together with their documentation
local function AddFunction(a_Name, a_Params, a_Return, a_Notes)
table.insert(DoxyFunctions, {Name = a_Name, Params = a_Params, Return = a_Return, Notes = a_Notes});
end
if (APIDesc.Functions ~= nil) then
-- Assign function descriptions:
for _, func in ipairs(cls.Functions) do
@ -508,7 +508,7 @@ local function ReadDescriptions(a_API)
FnDesc.IsExported = true;
end
end -- for j, func
-- Replace functions with their described and overload-expanded versions:
cls.Functions = DoxyFunctions;
else -- if (APIDesc.Functions ~= nil)
@ -519,7 +519,7 @@ local function ReadDescriptions(a_API)
end
end
end -- if (APIDesc.Functions ~= nil)
if (APIDesc.Constants ~= nil) then
-- Assign constant descriptions:
for _, cons in ipairs(cls.Constants) do
@ -541,7 +541,7 @@ local function ReadDescriptions(a_API)
end
end
end -- else if (APIDesc.Constants ~= nil)
-- Assign member variables' descriptions:
if (APIDesc.Variables ~= nil) then
for _, var in ipairs(cls.Variables) do
@ -565,7 +565,7 @@ local function ReadDescriptions(a_API)
end
end
end -- else if (APIDesc.Variables ~= nil)
if (APIDesc.ConstantGroups ~= nil) then
-- Create links between the constants and the groups:
local NumInGroups = 0;
@ -590,7 +590,7 @@ local function ReadDescriptions(a_API)
if (group.ShowInDescendants) then
NumInDescendantGroups = NumInDescendantGroups + NumInGroup;
end
-- Sort the constants:
table.sort(group.Constants,
function(c1, c2)
@ -601,7 +601,7 @@ local function ReadDescriptions(a_API)
cls.ConstantGroups = APIDesc.ConstantGroups;
cls.NumConstantsInGroups = NumInGroups;
cls.NumConstantsInGroupsForDescendants = NumInDescendantGroups;
-- Remove grouped constants from the normal list:
local NewConstants = {};
for _, cons in ipairs(cls.Constants) do
@ -611,9 +611,9 @@ local function ReadDescriptions(a_API)
end
cls.Constants = NewConstants;
end -- if (ConstantGroups ~= nil)
else -- if (APIDesc ~= nil)
-- Class is not documented at all, add all its members to Undocumented lists:
cls.UndocumentedFunctions = {};
cls.UndocumentedConstants = {};
@ -637,7 +637,7 @@ local function ReadDescriptions(a_API)
end
end -- for j, var - cls.Variables[]
end -- else if (APIDesc ~= nil)
-- Remove ignored functions:
local NewFunctions = {};
for _, fn in ipairs(cls.Functions) do
@ -660,7 +660,7 @@ local function ReadDescriptions(a_API)
return (f1.Name < f2.Name);
end
);
-- Remove ignored constants:
local NewConstants = {};
for _, cn in ipairs(cls.Constants) do
@ -669,14 +669,14 @@ local function ReadDescriptions(a_API)
end
end -- for j, cn
cls.Constants = NewConstants;
-- Sort the constants:
table.sort(cls.Constants,
function(c1, c2)
return (c1.Name < c2.Name);
end
);
-- Remove ignored member variables:
local NewVariables = {};
for _, var in ipairs(cls.Variables) do
@ -685,7 +685,7 @@ local function ReadDescriptions(a_API)
end
end -- for j, var
cls.Variables = NewVariables;
-- Sort the member variables:
table.sort(cls.Variables,
function(v1, v2)
@ -693,7 +693,7 @@ local function ReadDescriptions(a_API)
end
);
end -- for i, cls
-- Sort the descendants lists:
for _, cls in ipairs(a_API) do
table.sort(cls.Descendants,
@ -738,7 +738,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
LOGINFO("Cannot write HTML API for class " .. a_ClassAPI.Name .. ": " .. err)
return;
end
-- Writes a table containing all functions in the specified list, with an optional "inherited from" header when a_InheritedName is valid
local function WriteFunctions(a_Functions, a_InheritedName)
if (#a_Functions == 0) then
@ -757,7 +757,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
end
cf:write("</table>\n");
end
local function WriteConstantTable(a_Constants, a_Source)
cf:write("<table>\n<tr><th>Name</th><th>Value</th><th>Notes</th></tr>\n");
for _, cons in ipairs(a_Constants) do
@ -767,22 +767,22 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
end
cf:write("</table>\n\n");
end
local function WriteConstants(a_Constants, a_ConstantGroups, a_NumConstantGroups, a_InheritedName)
if ((#a_Constants == 0) and (a_NumConstantGroups == 0)) then
return;
end
local Source = a_ClassAPI.Name
if (a_InheritedName ~= nil) then
cf:write("<h2>Constants inherited from ", a_InheritedName, "</h2>\n");
Source = a_InheritedName;
end
if (#a_Constants > 0) then
WriteConstantTable(a_Constants, Source);
end
for _, group in pairs(a_ConstantGroups) do
if ((a_InheritedName == nil) or group.ShowInDescendants) then
cf:write("<a name='", group.Name, "'><p>");
@ -792,16 +792,16 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
end
end
end
local function WriteVariables(a_Variables, a_InheritedName)
if (#a_Variables == 0) then
return;
end
if (a_InheritedName ~= nil) then
cf:write("<h2>Member variables inherited from ", a_InheritedName, "</h2>\n");
end
cf:write("<table><tr><th>Name</th><th>Type</th><th>Notes</th></tr>\n");
for _, var in ipairs(a_Variables) do
cf:write("<tr><td>", var.Name, "</td>\n");
@ -810,7 +810,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
end
cf:write("</table>\n\n");
end
local function WriteDescendants(a_Descendants)
if (#a_Descendants == 0) then
return;
@ -823,7 +823,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
end
cf:write("</ul>\n");
end
local ClassName = a_ClassAPI.Name;
-- Build an array of inherited classes chain:
@ -833,10 +833,10 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
table.insert(InheritanceChain, CurrInheritance);
CurrInheritance = CurrInheritance.Inherits;
end
cf:write([[<!DOCTYPE html><html>
<head>
<title>MCServer API - ]], a_ClassAPI.Name, [[ Class</title>
<title>Cuberite API - ]], a_ClassAPI.Name, [[ Class</title>
<link rel="stylesheet" type="text/css" href="main.css" />
<link rel="stylesheet" type="text/css" href="prettify.css" />
<script src="prettify.js"></script>
@ -861,9 +861,9 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
</td><td style="vertical-align: top;"><h1>Contents</h1>
<p><ul>
]]);
local HasInheritance = ((#a_ClassAPI.Descendants > 0) or (a_ClassAPI.Inherits ~= nil));
local HasConstants = (#a_ClassAPI.Constants > 0) or (a_ClassAPI.NumConstantsInGroups > 0);
local HasFunctions = (#a_ClassAPI.Functions > 0);
local HasVariables = (#a_ClassAPI.Variables > 0);
@ -872,7 +872,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
HasFunctions = HasFunctions or (#cls.Functions > 0);
HasVariables = HasVariables or (#cls.Variables > 0);
end
-- Write the table of contents:
if (HasInheritance) then
cf:write("<li><a href=\"#inherits\">Inheritance</a></li>\n");
@ -892,7 +892,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
end
end
cf:write("</ul></p>\n");
-- Write the class description:
cf:write("<hr /><a name=\"desc\"><h1>", ClassName, " class</h1></a>\n");
if (a_ClassAPI.Desc ~= nil) then
@ -900,7 +900,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
cf:write(LinkifyString(a_ClassAPI.Desc, ClassName));
cf:write("</p>\n\n");
end;
-- Write the inheritance, if available:
if (HasInheritance) then
cf:write("<hr /><a name=\"inherits\"><h1>Inheritance</h1></a>\n");
@ -917,7 +917,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
cf:write("</p>\n\n");
end
end
-- Write the constants:
if (HasConstants) then
cf:write("<a name=\"constants\"><hr /><h1>Constants</h1></a>\n");
@ -927,7 +927,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
WriteConstants(cls.Constants, cls.ConstantGroups, cls.NumConstantsInGroupsForDescendants, cls.Name);
end;
end;
-- Write the member variables:
if (HasVariables) then
cf:write("<a name=\"variables\"><hr /><h1>Member variables</h1></a>\n");
@ -937,7 +937,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
WriteVariables(cls.Variables, cls.Name);
end;
end
-- Write the functions, including the inherited ones:
if (HasFunctions) then
cf:write("<a name=\"functions\"><hr /><h1>Functions</h1></a>\n");
@ -947,7 +947,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
WriteFunctions(cls.Functions, cls.Name);
end
end
-- Write the additional infos:
if (a_ClassAPI.AdditionalInfo ~= nil) then
for i, additional in ipairs(a_ClassAPI.AdditionalInfo) do
@ -969,7 +969,7 @@ end
local function WriteClasses(f, a_API, a_ClassMenu)
f:write([[
<a name="classes"><h2>Class index</h2></a>
<p>The following classes are available in the MCServer Lua scripting language:
<p>The following classes are available in the Cuberite Lua scripting language:
<ul>
]]);
for _, cls in ipairs(a_API) do
@ -1005,7 +1005,7 @@ local function ListUndocumentedObjects(API, UndocumentedHooks)
f:write("\t\t\tDesc = \"\"\n");
end
end
if (HasFunctions) then
f:write("\t\t\tFunctions =\n\t\t\t{\n");
table.sort(cls.UndocumentedFunctions);
@ -1014,7 +1014,7 @@ local function ListUndocumentedObjects(API, UndocumentedHooks)
end -- for j, fn - cls.UndocumentedFunctions[]
f:write("\t\t\t},\n\n");
end
if (HasConstants) then
f:write("\t\t\tConstants =\n\t\t\t{\n");
table.sort(cls.UndocumentedConstants);
@ -1023,7 +1023,7 @@ local function ListUndocumentedObjects(API, UndocumentedHooks)
end -- for j, fn - cls.UndocumentedConstants[]
f:write("\t\t\t},\n\n");
end
if (HasVariables) then
f:write("\t\t\tVariables =\n\t\t\t{\n");
table.sort(cls.UndocumentedVariables);
@ -1032,13 +1032,13 @@ local function ListUndocumentedObjects(API, UndocumentedHooks)
end -- for j, fn - cls.UndocumentedVariables[]
f:write("\t\t\t},\n\n");
end
if (HasFunctions or HasConstants or HasVariables) then
f:write("\t\t},\n\n");
end
end -- for i, cls - API[]
f:write("\t},\n");
if (#UndocumentedHooks > 0) then
f:write("\n\tHooks =\n\t{\n");
for i, hook in ipairs(UndocumentedHooks) do
@ -1118,19 +1118,19 @@ local function ListMissingPages()
end;
g_Stats.NumTrackedLinks = NumLinks;
g_TrackedPages = {};
if (#MissingPages == 0) then
-- No missing pages, congratulations!
return;
end
-- Sort the pages by name:
table.sort(MissingPages,
function (Page1, Page2)
return (Page1.Name < Page2.Name);
end
);
-- Output the pages:
local f, err = io.open("API/_missingPages.txt", "w");
if (f == nil) then
@ -1163,7 +1163,7 @@ local function WriteStats(f)
else
Color = "red";
end
local meter = {
"\n",
"<div style=\"background-color: black; padding: 1px; width: 100px\">\n",
@ -1177,7 +1177,7 @@ local function WriteStats(f)
};
return table.concat(meter, "");
end
f:write([[
<hr /><a name="docstats"><h2>Documentation statistics</h2></a>
<table><tr><th>Object</th><th>Total</th><th>Documented</th><th>Undocumented</th><th colspan="2">Documented %</th></tr>
@ -1205,13 +1205,13 @@ local function WriteStats(f)
f:write("</td><td>", g_Stats.NumUndocumentedConstants);
f:write("</td><td>", ExportMeter(100 * (g_Stats.NumTotalConstants - g_Stats.NumUndocumentedConstants) / g_Stats.NumTotalConstants));
f:write("</td></tr>\n");
f:write("<tr><td>Hooks</td><td>", g_Stats.NumTotalHooks);
f:write("</td><td>", g_Stats.NumTotalHooks - g_Stats.NumUndocumentedHooks);
f:write("</td><td>", g_Stats.NumUndocumentedHooks);
f:write("</td><td>", ExportMeter(100 * (g_Stats.NumTotalHooks - g_Stats.NumUndocumentedHooks) / g_Stats.NumTotalHooks));
f:write("</td></tr>\n");
f:write([[
</table>
<p>There are ]], g_Stats.NumTrackedLinks, " internal links, ", g_Stats.NumInvalidLinks, " of them are invalid.</p>"
@ -1224,7 +1224,7 @@ end
local function DumpAPIHtml(a_API)
LOG("Dumping all available functions and constants to API subfolder...");
-- Create the output folder
if not(cFile:IsFolder("API")) then
cFile:CreateFolder("API");
@ -1257,7 +1257,7 @@ local function DumpAPIHtml(a_API)
end
);
ReadHooks(Hooks);
-- Create a "class index" file, write each class as a link to that file,
-- then dump class contents into class-specific file
LOG("Writing HTML files...");
@ -1277,7 +1277,7 @@ local function DumpAPIHtml(a_API)
table.insert(ClassMenuTab, "</a><br />");
end
local ClassMenu = table.concat(ClassMenuTab, "");
-- Create a hook navigation menu that will be inserted into each hook file for faster navigation(#403)
local HookNavTab = {};
for _, hook in ipairs(Hooks) do
@ -1288,18 +1288,18 @@ local function DumpAPIHtml(a_API)
table.insert(HookNavTab, "</a><br />");
end
local HookNav = table.concat(HookNavTab, "");
-- Write the HTML file:
f:write([[<!DOCTYPE html>
<html>
<head>
<title>MCServer API - Index</title>
<title>Cuberite API - Index</title>
<link rel="stylesheet" type="text/css" href="main.css" />
</head>
<body>
<div id="content">
<header>
<h1>MCServer API - Index</h1>
<h1>Cuberite API - Index</h1>
<hr />
</header>
<p>The API reference is divided into the following sections:</p>
@ -1311,11 +1311,11 @@ local function DumpAPIHtml(a_API)
</ul>
<hr />
]]);
WriteArticles(f);
WriteClasses(f, a_API, ClassMenu);
WriteHooks(f, Hooks, UndocumentedHooks, HookNav);
-- Copy the static files to the output folder:
local StaticFiles =
{
@ -1328,7 +1328,7 @@ local function DumpAPIHtml(a_API)
cFile:Delete("API/" .. fnam);
cFile:Copy(g_Plugin:GetLocalFolder() .. "/" .. fnam, "API/" .. fnam);
end
-- List the documentation problems:
LOG("Listing leftovers...");
ListUndocumentedObjects(a_API, UndocumentedHooks);
@ -1336,12 +1336,12 @@ local function DumpAPIHtml(a_API)
ListMissingPages();
WriteStats(f);
f:write([[</ul></div>]])
f:write(GetHtmlTimestamp())
f:write([[</body></html>]])
f:close()
LOG("API subfolder written");
end
@ -1354,16 +1354,16 @@ local function CleanUpDescription(a_Desc)
-- Get rid of indent and newlines, normalize whitespace:
local res = a_Desc:gsub("[\n\t]", "")
res = a_Desc:gsub("%s%s+", " ")
-- Replace paragraph marks with newlines:
res = res:gsub("<p>", "\n")
res = res:gsub("</p>", "")
-- Replace list items with dashes:
res = res:gsub("</?ul>", "")
res = res:gsub("<li>", "\n - ")
res = res:gsub("</li>", "")
return res
end
@ -1405,21 +1405,21 @@ end
--- Writes one MCS class definition into the specified file in ZBS format
--- Writes one Cuberite class definition into the specified file in ZBS format
local function WriteZBSClass(f, a_Class)
assert(type(a_Class) == "table")
-- Write class header:
f:write("\t", a_Class.Name, " =\n\t{\n")
f:write("\t\ttype = \"class\",\n")
f:write("\t\tdescription = [[", CleanUpDescription(a_Class.Desc or ""), " ]],\n")
f:write("\t\tchilds =\n")
f:write("\t\t{\n")
-- Export methods and constants:
WriteZBSMethods(f, a_Class.Functions)
WriteZBSConstants(f, a_Class.Constants)
-- Finish the class definition:
f:write("\t\t},\n")
f:write("\t},\n\n")
@ -1437,12 +1437,12 @@ local function DumpAPIZBS(a_API)
LOG("Cannot open mcserver_lua.lua for writing, ZBS API will not be dumped. " .. err)
return
end
-- Write the file header:
f:write("-- This is a MCServer API file automatically generated by the APIDump plugin\n")
f:write("-- This is a Cuberite API file automatically generated by the APIDump plugin\n")
f:write("-- Note that any manual changes will be overwritten by the next dump\n\n")
f:write("return {\n")
-- Export each class except Globals, store those aside:
local Globals
for _, cls in ipairs(a_API) do
@ -1452,13 +1452,13 @@ local function DumpAPIZBS(a_API)
Globals = cls
end
end
-- Export the globals:
if (Globals) then
WriteZBSMethods(f, Globals.Functions)
WriteZBSConstants(f, Globals.Constants)
end
-- Finish the file:
f:write("}\n")
f:close()
@ -1480,21 +1480,21 @@ local function IsDeclaredDescendant(a_DescendantName, a_BaseName, a_API)
end
assert(type(a_API[a_BaseName]) == "table", "Not a class name: " .. a_BaseName)
assert(type(a_API[a_BaseName].Descendants) == "table")
-- Check direct inheritance:
for _, desc in ipairs(a_API[a_BaseName].Descendants) do
if (desc.Name == a_DescendantName) then
return true
end
end -- for desc - a_BaseName's descendants
-- Check indirect inheritance:
for _, desc in ipairs(a_API[a_BaseName].Descendants) do
if (IsDeclaredDescendant(a_DescendantName, desc.Name, a_API)) then
return true
end
end -- for desc - a_BaseName's descendants
return false
end
@ -1509,7 +1509,7 @@ local function CheckClassInheritance(a_Class, a_API, a_Report)
assert(type(a_Class) == "table")
assert(type(a_API) == "table")
assert(type(a_Report) == "table")
-- Check that the declared descendants are really descendants:
local registry = debug.getregistry()
for _, desc in ipairs(a_Class.Descendants or {}) do
@ -1519,7 +1519,7 @@ local function CheckClassInheritance(a_Class, a_API, a_Report)
table.insert(a_Report, desc.Name .. " is not a descendant of " .. a_Class.Name)
end
end -- for desc - a_Class.Descendants[]
-- Check that all inheritance is listed for the class:
local parents = registry["tolua_super"][_G[a_Class.Name]] -- map of "classname" -> true for each class that a_Class inherits
for clsName, isParent in pairs(parents or {}) do
@ -1544,7 +1544,7 @@ local function CheckAPIDescendants(a_API)
CheckClassInheritance(cls, a_API, report)
end
end
-- If there's anything to report, output it to a file:
if (report[1] ~= nil) then
LOG("There are inheritance errors in the API description:")
@ -1568,7 +1568,7 @@ end
local function DumpApi()
LOG("Dumping the API...")
-- Load the API descriptions from the Classes and Hooks subfolders:
-- This needs to be done each time the command is invoked because the export modifies the tables' contents
dofile(g_PluginFolder .. "/APIDesc.lua")
@ -1598,10 +1598,10 @@ local function DumpApi()
NumTrackedLinks = 0,
NumInvalidLinks = 0,
}
-- Create the API tables:
local API, Globals = CreateAPITables();
-- Sort the classes by name:
table.sort(API,
function (c1, c2)
@ -1609,24 +1609,24 @@ local function DumpApi()
end
);
g_Stats.NumTotalClasses = #API;
-- Add Globals into the API:
Globals.Name = "Globals";
table.insert(API, Globals);
-- Read in the descriptions:
LOG("Reading descriptions...");
ReadDescriptions(API);
-- Check that the API lists the inheritance properly, report any problems to a file:
CheckAPIDescendants(API)
-- Dump all available API objects in HTML format into a subfolder:
DumpAPIHtml(API);
-- Dump all available API objects in format used by ZeroBraneStudio API descriptions:
DumpAPIZBS(API)
LOG("APIDump finished");
return true
end
@ -1671,20 +1671,15 @@ end
function Initialize(Plugin)
g_Plugin = Plugin;
g_PluginFolder = Plugin:GetLocalFolder();
LOG("Initialising " .. Plugin:GetName() .. " v." .. Plugin:GetVersion())
-- Bind a console command to dump the API:
cPluginManager:BindConsoleCommand("api", HandleCmdApi, "Dumps the Lua API docs into the API/ subfolder")
cPluginManager:BindConsoleCommand("apishow", HandleCmdApiShow, "Runs the default browser to show the API docs")
-- Add a WebAdmin tab that has a Dump button
g_Plugin:AddWebTab("APIDump", HandleWebAdminDump)
return true
end