cPluginManager

Index:
Articles
Classes
Hooks

Quick navigation:
BannerPattern
BossBarColor
BossBarDivisionType
cArrowEntity
cBeaconEntity
cBedEntity
cBlockArea
cBlockEntity
cBlockEntityWithItems
cBlockInfo
cBoat
cBoundingBox
cBrewingstandEntity
cChatColor
cChestEntity
cChunkDesc
cClientHandle
cColor
cCommandBlockEntity
cCompositeChat
cCraftingGrid
cCraftingRecipe
cCryptoHash
cCuboid
cDispenserEntity
cDropperEntity
cDropSpenserEntity
cEnchantments
cEnderCrystal
cEntity
cEntityEffect
cExpBottleEntity
cExpOrb
cFallingBlock
cFile
cFireChargeEntity
cFireworkEntity
cFloater
cFlowerPotEntity
cFurnaceEntity
cGhastFireballEntity
cHangingEntity
cHopperEntity
cIniFile
cInventory
cItem
cItemFrame
cItemGrid
cItems
cJson
cJukeboxEntity
cLeashKnot
cLineBlockTracer
cLuaWindow
cMap
cMapManager
cMobHeadEntity
cMobSpawnerEntity
cMojangAPI
cMonster
cNetwork
cNoteEntity
cObjective
cPainting
cPawn
cPickup
cPlayer
cPlugin
cPluginLua
cPluginManager
cProjectileEntity
cRankManager
cRoot
cScoreboard
cServer
cServerHandle
cSignEntity
cSplashPotionEntity
cStringCompression
cTCPLink
cTeam
cThrownEggEntity
cThrownEnderPearlEntity
cThrownSnowballEntity
cTNTEntity
cUDPEndpoint
cUrlClient
cUrlParser
CustomStatistic
cUUID
cWebAdmin
cWindow
cWitherSkullEntity
cWorld
EffectID
HTTPFormData
HTTPRequest
HTTPTemplateRequest
ItemCategory
lxp
SmokeDirection
sqlite3
StatisticsManager
TakeDamageInfo
tolua
Vector3d
Vector3f
Vector3i
Globals

Constants
Functions

cPluginManager class

This class is used for generic plugin-related functionality. The plugin manager has a list of all plugins, can enable or disable plugins, manages hooks and in-game console commands.

Plugins can be identified by either the PluginFolder or PluginName. Note that these two can differ, refer to the forum for detailed discussion.

There is one instance of cPluginManager in Cuberite, to get it, call either cRoot:Get():GetPluginManager() or cPluginManager:Get() function.

Note that some functions are "static", that means that they are called using a dot operator instead of the colon operator. For example:

cPluginManager.AddHook(cPluginManager.HOOK_CHAT, OnChatMessage);

Constants

These constants identify individual hooks. To register the plugin to receive notifications on hooks, use the cPluginManager:AddHook() function. For detailed description of each hook, see the hooks reference.

Name	Value	Notes
HOOK_BLOCK_SPREAD	0	Called when a block spreads based on world conditions
HOOK_BLOCK_TO_PICKUPS	1	Called when a block has been dug and is being converted to pickups. The server has provided the default pickups and the plugins may modify them.
HOOK_BREWING_COMPLETED	3	Called when a brewing stand completed a brewing process.
HOOK_BREWING_COMPLETING	2	Called before a brewing stand completes a brewing process.
HOOK_CHAT	4	Called when a client sends a chat message that is not a command. The plugin may modify the chat message
HOOK_CHUNK_AVAILABLE	5	Called when a chunk is loaded or generated and becomes available in the world.
HOOK_CHUNK_GENERATED	6	Called after a chunk is generated. A plugin may do last modifications on the generated chunk before it is handed of to the world.
HOOK_CHUNK_GENERATING	7	Called before a chunk is generated. A plugin may override some parts of the generation algorithm.
HOOK_CHUNK_UNLOADED	8	Called after a chunk has been unloaded from a world.
HOOK_CHUNK_UNLOADING	9	Called before a chunk is unloaded from a world. The chunk has already been saved.
HOOK_COLLECTING_PICKUP	10	Called when a player is about to collect a pickup.
HOOK_CRAFTING_NO_RECIPE	11	Called when a player has items in the crafting slots and the server cannot locate any recipe. Plugin may provide a recipe.
HOOK_DISCONNECT	12	Called after the player has disconnected.
HOOK_DROPSPENSE	23	Called when a DropSpenser is dropspensing an item.
HOOK_ENTITY_ADD_EFFECT	14	Called when an effect is being added to an entity. Plugin may refuse the effect.
HOOK_ENTITY_CHANGED_WORLD	16	Called after a entity has changed the world.
HOOK_ENTITY_CHANGING_WORLD	15	Called before a entity has changed the world. Plugin may disallow a entity to change the world.
HOOK_ENTITY_TELEPORT	46	Called when an entity is being teleported. Plugin may refuse the teleportation.
HOOK_EXECUTE_COMMAND	17	Called when a client sends a chat message that is recognized as a command, before handing that command to the regular command handler. A plugin may stop the command from being handled. This hook is called even when the player doesn't have permissions for the command.
HOOK_EXPLODED	18	Called after an explosion has been processed in a world.
HOOK_EXPLODING	19	Called before an explosion is processed in a world. A plugin may alter the explosion parameters or cancel the explosion altogether.
HOOK_HANDSHAKE	20	Called when a Handshake packet is received from a client.
HOOK_HOPPER_PULLING_ITEM	21	Called when a hopper is pulling an item from the container above it.
HOOK_HOPPER_PUSHING_ITEM	22	Called when a hopper is pushing an item into the container it is aimed at.
HOOK_KILLED	24	Called when an entity has been killed.
HOOK_KILLING	25	Called when an entity has just been killed. A plugin may resurrect the entity by setting its health to above zero.
HOOK_LOGIN	26	Called when a Login packet is sent to the client, before the client is queued for authentication.
HOOK_LOGIN_FORGE	27	Called when a Forge client has sent its ModList to the server, during the login handshake.
HOOK_PLAYER_ANIMATION	13	Called when a client send the Animation packet.
HOOK_PLAYER_BREAKING_BLOCK	28	Called when a player is about to break a block. A plugin may cancel the event.
HOOK_PLAYER_BROKEN_BLOCK	29	Called after a player has broken a block.
HOOK_PLAYER_CROUCHED	41	Called when a player crouches.
HOOK_PLAYER_DESTROYED	30	Called when the cPlayer object is destroyed - a player has disconnected.
HOOK_PLAYER_EATING	31	Called when the player starts eating a held item. Plugins may abort the eating.
HOOK_PLAYER_FISHED	32	Called when the player reels the fishing rod back in, after the server decides the player's fishing reward and the experience to grant.
HOOK_PLAYER_FISHING	33	Called when the player reels the fishing rod back in, plugins may alter the fishing reward and the experience granted to the player.
HOOK_PLAYER_FOOD_LEVEL_CHANGE	34	Called when the player's food level is changing. Plugins may refuse the change.
HOOK_PLAYER_JOINED	35	Called when the player entity has been created. It has not yet been fully initialized.
HOOK_PLAYER_LEFT_CLICK	36	Called when the client sends the LeftClick packet.
HOOK_PLAYER_MOVING	37	Called when the player has moved and the movement is now being applied.
HOOK_PLAYER_OPENING_WINDOW	38	Called when the player is about to open a window. The plugin can return true to cancel the window opening.
HOOK_PLAYER_PLACED_BLOCK	39	Called when the player has just placed a block
HOOK_PLAYER_PLACING_BLOCK	40	Called when the player is about to place a block. A plugin may cancel the event.
HOOK_PLAYER_RIGHT_CLICK	42	Called when the client sends the RightClick packet.
HOOK_PLAYER_RIGHT_CLICKING_ENTITY	43	Called when the client sends the UseEntity packet.
HOOK_PLAYER_SHOOTING	44	Called when the player releases the mouse button to fire their bow.
HOOK_PLAYER_SPAWNED	45	Called after the player entity has been created. The entity is fully initialized and is spawning in the world.
HOOK_PLAYER_TOSSING_ITEM	47	Called when the player is tossing the held item (keypress Q)
HOOK_PLAYER_USED_BLOCK	48	Called after the player has right-clicked a block
HOOK_PLAYER_USED_ITEM	49	Called after the player has right-clicked with a usable item in their hand.
HOOK_PLAYER_USING_BLOCK	50	Called when the player is about to use (right-click) a block
HOOK_PLAYER_USING_ITEM	51	Called when the player is about to right-click with a usable item in their hand.
HOOK_PLUGINS_LOADED	53	Called after all plugins have loaded.
HOOK_PLUGIN_MESSAGE	52	Called when a PluginMessage packet is received from a client.
HOOK_POST_CRAFTING	54	Called after a valid recipe has been chosen for the current contents of the crafting grid. Plugins may modify the recipe.
HOOK_PRE_CRAFTING	55	Called before a recipe is searched for the current contents of the crafting grid. Plugins may provide a recipe and cancel the built-in search.
HOOK_PROJECTILE_HIT_BLOCK	56	Called when a projectile hits a block.
HOOK_PROJECTILE_HIT_ENTITY	57	Called when a projectile hits an entity.
HOOK_SERVER_PING	58	Called when a client pings the server from the server list. Plugins may change the favicon, server description, players online and maximum players values.
HOOK_SPAWNED_ENTITY	59	Called after an entity is spawned in a world. The entity is already part of the world.
HOOK_SPAWNED_MONSTER	60	Called after a mob is spawned in a world. The mob is already part of the world.
HOOK_SPAWNING_ENTITY	61	Called just before an entity is spawned in a world.
HOOK_SPAWNING_MONSTER	62	Called just before a mob is spawned in a world.
HOOK_TAKE_DAMAGE	63	Called when an entity is taking any kind of damage. Plugins may modify the damage value, effects, source or cancel the damage.
HOOK_TICK	64	Called when the main server thread ticks - 20 times a second.
HOOK_UPDATED_SIGN	65	Called after a sign text has been updated, either by a player or by any external means.
HOOK_UPDATING_SIGN	66	Called before a sign text is updated, either by a player or by any external means.
HOOK_WEATHER_CHANGED	67	Called after the weather has changed.
HOOK_WEATHER_CHANGING	68	Called just before the weather changes
HOOK_WORLD_STARTED	69	Called when a world has been started.
HOOK_WORLD_TICK	70	Called in each world's tick thread when the game logic is about to tick (20 times a second).

These constants are used to report status of individual plugins. Use cPlugin:GetStatus() to query the status of a plugin; use cPluginManager::ForEachPlugin() to iterate over plugins.

Name	Value	Notes
psDisabled	1	The plugin is not enabled in settings.ini
psError	3	The plugin is enabled in settings.ini, but it has run into an error while loading. Use cPlugin:GetLoadError() to identify the error.
psLoaded	0	The plugin is enabled and loaded.
psNotFound	4	The plugin has been loaded, but is no longer present on disk.
psUnloaded	2	The plugin is enabled in settings.ini, but it has been unloaded (by a command).

Results that the (Force)ExecuteCommand functions return. This gives information whether the command was executed or not, and the reason.

Name	Value	Notes
crBlocked	3	When a plugin stopped the command using the OnExecuteCommand hook
crError	2	When the command handler for the given command results in an error
crExecuted	0	When the command is successfully executed.
crNoPermission	4	When the player doesn't have permission to execute the given command.
crUnknownCommand	1	When the given command doesn't exist.

Functions

Name

Parameters

Return value

Notes

AddHook

HookType	PluginHook
Callback	function

(STATIC) Informs the plugin manager that it should call the specified function when the specified hook event occurs. If a function is not specified, a default global function name is looked up, based on the hook type

BindCommand

Command	string
Permission	string
Callback	function
HelpString	string

boolean

Binds an in-game command with the specified callback function, permission and help string. By common convention, providing an empty string for HelpString will hide the command from the /help display. Returns true if successful, logs to console and returns no value on error. The callback uses the following signature:

function(Split, Player)

The Split parameter contains an array-table of the words that the player has sent, Player is the cPlayer object representing the player who sent the command. If the callback returns true, the command is assumed to have executed successfully; in all other cases the server sends a warning to the player that the command is unknown (this is so that subcommands can be implemented).

BindCommand

Command	string
Permission	string
Callback	function
HelpString	string

boolean

(STATIC) Binds an in-game command with the specified callback function, permission and help string. By common convention, providing an empty string for HelpString will hide the command from the /help display. Returns true if successful, logs to console and returns no value on error. The callback uses the following signature:

function(Split, Player)

BindConsoleCommand

Command	string
Callback	function
HelpString	string

boolean

(STATIC) Binds a console command with the specified callback function and help string. By common convention, providing an empty string for HelpString will hide the command from the "help" console command. Returns true if successful, logs to console and returns no value on error. The callback uses the following signature:

function(Split)

The Split parameter contains an array-table of the words that the admin has typed. If the callback returns true, the command is assumed to have executed successfully; in all other cases the server issues a warning to the console that the command is unknown (this is so that subcommands can be implemented).

BindConsoleCommand

Command	string
Callback	function
HelpString	string

boolean

Binds a console command with the specified callback function and help string. By common convention, providing an empty string for HelpString will hide the command from the "help" console command. Returns true if successful, logs to console and returns no value on error. The callback uses the following signature:

function(Split)

CallPlugin

PluginName	string
FunctionName	string
FunctionArgs...	...

FunctionRets

...

(STATIC) Calls the specified function in the specified plugin, passing all the given arguments to it. If it succeeds, it returns all the values returned by that function. If it fails, returns no value at all. Note that only strings, numbers, bools, nils, API classes and simple tables can be used for parameters and return values; functions cannot be copied across plugins.

DoWithPlugin

PluginName	string
CallbackFn	function

boolean

(STATIC) Calls the CallbackFn for the specified plugin, if found. A plugin can be found even if it is currently unloaded, disabled or errored, the callback should check the plugin status. If the plugin is not found, this function returns false, otherwise it returns the bool value that the callback has returned. The CallbackFn has the following signature:

function (Plugin)

ExecuteCommand

Player	cPlayer
CommandStr	string

CommandResult

CommandResult

Executes the command as if given by the specified Player. Checks permissions.

ExecuteConsoleCommand

CommandStr

string

	boolean
	string

Executes the console command as if given by the admin on the console. If the command is successfully executed, returns true and the text that would be output to the console normally. On error it returns false and an error message.

FindPlugins

OBSOLETE, use RefreshPluginList() instead

ForEachCommand

CallbackFn

function

boolean

Calls the CallbackFn function for each command that has been bound using BindCommand(). The CallbackFn has the following signature:

function(Command, Permission, HelpString)

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

CallbackFn

function

boolean

Calls the CallbackFn function for each command that has been bound using BindConsoleCommand(). The CallbackFn has the following signature:

function (Command, HelpString)

ForEachPlugin

CallbackFn

function

boolean

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:

function (Plugin)

ForEachPlugin

CallbackFn

function

boolean

(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:

function (Plugin)

ForceExecuteCommand

Player	cPlayer
CommandStr	string

CommandResult

CommandResult

Same as ExecuteCommand, but doesn't check permissions

Get

cPluginManager

(STATIC) Returns the single instance of the plugin manager

GetAllPlugins

table

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

Command

string

Permission

string

Returns the permission needed for executing the specified command

GetCurrentPlugin

cPlugin

Returns the cPlugin object for the calling plugin. This is the same object that the Initialize function receives as the argument.

GetNumLoadedPlugins

number

Returns the number of loaded plugins (psLoaded only)

GetNumPlugins

number

Returns the number of plugins, including the disabled, errored, unloaded and not-found ones

GetPlugin

PluginName

string

cPlugin

(DEPRECATED, UNSAFE) Returns a plugin handle of the specified plugin, or nil if such plugin is not loaded. Note thatdue to multithreading the handle is not guaranteed to be safe for use when stored - a single-plugin reload may have been triggered in the mean time for the requested plugin.

GetPluginFolderName

PluginName

string

Returns the name of the folder from which the plugin was loaded (without the "Plugins" part). Used as a plugin's display name.

GetPluginsPath

string

(STATIC) Returns the path where the individual plugin folders are located. Doesn't include the path separator at the end of the returned string.

IsCommandBound

Command

string

boolean

Returns true if in-game Command is already bound (by any plugin)

IsConsoleCommandBound

Command

string

boolean

Returns true if console Command is already bound (by any plugin)

IsPluginLoaded

PluginName

string

Returns true if the specified plugin is loaded.

LoadPlugin

PluginFolder

string

(DEPRECATED) Loads a plugin from the specified folder. NOTE: Loading plugins may be an unsafe operation and may result in a deadlock or a crash. This API is deprecated and might be removed.

LogStackTrace

(STATIC) Logs a current stack trace of the Lua engine to the server console log. Same format as is used when the plugin fails.

RefreshPluginList

Refreshes the list of plugins to include all folders inside the Plugins folder (potentially new disabled plugins)

ReloadPlugin

PluginName

string

Queues the specified plugin to be reloaded. To avoid deadlocks, the reloading happens in the main tick thread asynchronously.

ReloadPlugins

Reloads all active plugins

UnloadPlugin

PluginName

string

Queues the specified plugin to be unloaded. To avoid deadlocks, the unloading happens in the main tick thread asynchronously.

Contents

cPluginManager class

Constants

Functions