EssentialsPE API - LegendOfMCPE/EssentialsPE GitHub Wiki

EssentialsPE has an incredible amount of features, but the main on what those features work is because of its easy to use API. EssentialsPE provides a custom API for external developers to make it easy to integrate this awesome plugin with other projects for PocketMine-MP.

Please visit the THIS LINK to see how does our developers like to access this API:

Here you have a cheat sheet of the different sections of the API, each one of them point to different type of uses; from AFK status, to Vanishing players on the server.

Section Usage
General Some functions that doesn't have a special category, but they're useful anyways
Sessions Manage player's session features like AFK, God or Vanish modes
AFK Manage the different features of the Aways of The Keyboard status
Back Let a player go back to the last position before any teleport
Economy EssentialsPE's basic economy functions
Entities EssentialsPE's special management of entities
God mode Makes a player invincible
Homes Manage custom private locations for a player
Kits Basic implementation of Kits in EssentialsPE
Mute Ban anyone from the chat
Nicks Manage custom display names for a player
PowerTool Manage custom commands or chat macros assigned to a specific item (per player)
Player vs Player (PvP) Let (or not) players fight with others
Teleport Requests Manage the different types of teleport requests between two players (or a list of players)
Unlimited mode Allow players to place unlimited blocks
Vanish mode Makes a player invisible to others
Warps Manage custom global locations for the server

=

General API

  • getPlayer($player) Let you search for a player by its name or nick.

    • Paramerers: Player name (string) A string containing the name/nick of the player to search for.
    • Return:
      • Boolean False if the player isn't found.
      • Player Object The player that was found.

  • colorMessage($message, $player = null) Replace color codes inside a message with a real colored message.

    • Parameters:
      • Message (string) The string to color.
      • Player name (string) [OPTIONAL] The player to test the permission essentials.colorchat.
    • Return:
      • Boolean If the player (if specified) doesn't has permission to use colored messages.
      • String The message with real color codes.

  • isReparable($item) Tell if an item can be repaired.

    • Parameters: Item Object The item to work over.
    • Return: Boolean True if the item specified is reparable, False if not.

  • getNearPlayers(Player $player, $radius = null) Show the nears player to the target one.

    • Parameters:
      • Player Object The player to work over.
      • Radius (integer) [OPTIONAL] The radius to scan.
    • Return:
      • Boolean False if the radius specified isn't an integer.
      • Array an array with all the players found... in Objects.

  • setPlayerTime($player, $time, $static = false) Sets the player time. (Dawn, day, noon, night, etc...)

    • Parameters:
      • Player Object The player to work over.
      • Time (integer) The time to set (in ticks).
      • Static (boolean) [OPTIONAL] If the time to set will be static or can flow.
    • Return: Boolean True if the packet was sent correctly, False if one of the arguments isn't valid.

  • getItem($item_name) Gets an item by name, and supports Metadata too!

    • Parameters:
      • Item Name (string) The item name to look for. You can also add metadata for this parameter, the function separates the Item ID/Name and the Metadata with a ':', for example, if I want to get a Granite block, I should assign the item name parameter has: '1:1' or 'stone:1'
    • Return:
      • Item Object/Block Item Object if the item was found.
      • Boolean False if the Item was not found.

=

Sessions API

  • sessionExists($player) Tells if a session exists for a specific player.

    • Parameters: Player Object The player to work over.
    • Return: Boolean True if the Session exists, False if doesn't.

  • createSession($player) Creates a new session for a player using the configuration needed.

    • Parameters: Player Object The player to work over.
    • Return: Void.

  • removeSession($player) Removes an existing session of a player.

    • Parameters: Player Object The player to work over.
    • Return: Void

=

AFK API

  • isAFK($player) Tells if a player is Away From the Keyboard.

    • Parameters: Player Object The player to work over.
    • Return: Boolean True if it's AFK, False if not.

  • setAFK($player, $state, $broadcast = true) Set the AFK status of a player.

    • Parameters:
      • Player Object The player to work over.
      • State (boolean) The state to set: True will activate it, False will deactivate it.
      • Broadcast (boolean) [OPTIONAL] Allow to broadcast (or not) the status change.
    • Return: Boolean True if successfully set AFK to the player, False if not.

  • switchAFKMode($player, $broadcast = true) Automatically switch the AFK status. Activate it if isn't activated and vice versa.

    • Parameters:
      • Player Object The player to work over.
      • Broadcast (boolean) [OPTIONAL] Allow to broadcast (or not) the status change.
    • Return: Void.

=

Back API

  • getLastPlayerPosition($player) Get the last player position. (Doesn't include Rotation)

    • Parameters: Player Object The player to work over.

  • getLastPlayerRotation($player) Get the last player rotation. (Obviously doesn't include Position :stuck_out_tongue_winking_eye:)

    • Parameters: Player Object The player to work over.

  • setLastPlayerPosition($player, $pos, $yaw, $pitch) Saves the last position and rotation of a player before teleporting.

    • Parameters:
      • Player Object The player to work over.
      • Position Object The position to save.
      • Yaw (integer) The X-axis rotation to save.
      • Pitch (integer) The Y-axis rotation to save.

  • removePlayerLastPosition($player) Removes the last know position of a player.

    • Parameters: Player Object The player to work over.

  • returnPlayerToLastKnownPosition($player) Teleports the player back to the last known spot.

    • Parameters: Player Object The player to work over.

=

Economy API

  • getDefaultBalance() Gets the default balance for new players.

    • Parameters: Null.
    • Return: Balance (integer) The default balance specified in the config file.

  • getMaxBalance() Gets the max balance that a player can own.

    • Parameters: Null.
    • Return: Balance (integer) The max balance specified in the config file.

  • getMinBalance() Gets the minimum balance that a player can own.

    • Parameters: Null.
    • Return: Balance (integer) The minium balance specified in the config file.

  • getCurrencySymbol() Return the currency symbol used for balances.

    • Parameters: Null.
    • Return: Symbol (string) The symbol to use for currency.

  • getPlayerBalance($player) Get the current balance of a player.

    • Parameters: Player $player The player to work over.
    • Return: Balance (integer) The player current balance.

  • setPlayerBalance($player, $balance) Modify a player's balance.

    • Parameters:
      • Player Object The player to work over.
      • Balance (integer) The new balance to set.
    • Return: Void.

  • addToPlayerBalance($player, $balance) Add a quantity to a player's balance (Support negative values too!)

    • Parameters:
      • Player Object The player to work over.
      • Balance (integer) The balance to add to player's actual balance; if you want to subtract, just specify a negative value :wink: .
    • Return Void.

  • getItemWorth($itemId) Get the worth of an item.

    • Parameters: ItemId (integer) The Item ID to work over.
    • Return:
      • Boolean False if the worth is not available.
      • Worth (integer) The item worth if found.

  • setItemWorth($itemId, $worth) Modify an Item's worth.

    • Parameters:
      • ItemId (integer) The Item ID to work over.
      • Worth (integer) The worth to set.
    • Return Void.

  • sellPlayerItem($player, $item, $amount = null) Takes an item from a player's inventory, sell it and add the corresponding worth to the player.

    • Parameters:
      • Player Object The player to work over.
      • Item Object The item to take.
      • Amount [OPTIONAL] The amount of items to take.
    • Return:
      • Boolean False If the player doesn't have the item, or the amount specified.
      • Worth (integer) The worth obtained from the item.
      • Array (Amount [integer], Worth [integer]) The amount of items sold and the worth obtained.

=

Entities API

  • nuke($player) Spawn a carpet of bomb around the specified player.

    • Parameters: Player Object The player to work over.
    • Return: Void.

  • antioch($player) Spawn a live TNT at the spot that the specified player is looking at.

    • Parameters: Player Object The player to work over.
    • Return: Void.

  • createTNT($pos) Spawn live TNT at the position specified.

    • Parameters: Position Object The position ot work over.
    • Return: Void.

=

God API

  • isGod($player) Tell if a player has its God mode active

    • Parameters: Player Object The player to work over.
    • Return: Boolean True if the player is in God mode, False if not.

  • setGodMode($player, $state) Set the God mode of a player.

    • Parameters:
      • Player Object The player to work over.
      • State (boolean) The mode to set: True will activate it, False will deactivate it.
    • Return: Boolean True if the mode was successfully updated, False if not.

  • switchGodMode($player) Automatically switch the God mode. Activate it if isn't activated and vice versa.

    • Parameters: Player Object The player to work over.
    • Return: `Void``.

=

Homes API

  • homeExists($player, $home) Tell if a player has a home with that name.

    • Parameters:
      • Player Object The player to work over.
      • Home (string) The home name to check.
    • Return: Boolean True if the player has a home with that name, False if not.

  • getHome($player, $home) Get a home's information.

    • Parameters:
      • Player Object The player to work over.
      • Home (string) The home to check.
    • Return:
      • Boolean False if the home doesn't exists or if the home level doesn't exists.
      • Array (Position Object, Yaw [integer], Pitch [integer]) The home information.

  • setHome($player, $home, $pos, $yaw = 0, $pitch = 0) Creates a new home or updates an existing one with the specified information.

    • Parameters:
      • Player Object The player to work over.
      • Home (string) The home name.
      • Position Object The XYZ coordinates and Level for the home.
      • Yaw (integer) [OPTIONAL] The X-Axis direction to set.
      • Pitch (integer) [OPTIONAL] The Y-Axis direction to set.

  • removeHome($player, $home) Removes a home.

    • Parameters:
      • Player Object The player to work over.
      • Home (string) The home to remove.
    • Return: Boolean True if the home successfully was removed, False if the home doesn't exists or wan't removed.

  • homeList($player, $inArray = false) Get a list of homes that a player has.

    • Parameters:
      • Player Object The player to work over.
      • InArray (boolean) Specify if you want the list as an Array or a String.
    • Return:
      • Home List (array) An array with the homes list.
      • Home List (string) A string with the homes list.

=

Kits API

  • kitExists($kit) Tell if a kit exists.

    • Parameters: Kit (string) The kit to check.
    • Return: Boolean True if the kit exists, False if not.

  • getKit($kit) Get kit's item list.

    • Parameters: Kit (string) The kit to get.
    • Return:
      • Boolean False if the it doesn't exists.
      • Item List (array) The list of items.

  • kitList($inArray = false) Get a list of all the available kits.

    • Parameters: InArray (boolean) Specify if you want to get the list as an Array or a String.
    • Return:
      • Kit List (array) An array with the kit list.
      • Kit List (string) A string with the kit list.

=

Mute API

  • isMuted($player) Tell if a player is Muted or not.

    • Parameters: Player Object The player to work over.

  • setMuted($player $state) Set the Mute state of a player.

    • Parameters:
      • Player Object The player to work over.
      • State (boolean) The state to set: True will mute the player, False will unmute.

  • switchMute($player) Automatically switch the Mute state of a player. Activate it if isn't activated and vice versa.

    • Parameters: Player Object The player to work over.

=

Nicks API

  • setNick($player, $nick, $save = true) Set's the DisplayName (aka Nick) for a player.

    • Parameters:
      • Player Object The player to work over.
      • Nick (string) The nick to set.
      • Save (boolean) [OPTIONAL] Saves the nick, or not.
    • Return: Boolean True if the nick was successfully changed, False if not.

  • removeNick($Player, $save = true) Removes the DisplayeName (aka Nick) of a player.

    • Parameters:
      • Player Object The player to work over.
      • Save (boolean) [OPTIONAL] Saves the new nick (in this case, it's removed).
    • Return: Boolean True if the nick was successfully removed, False if not.

  • getNick($player) Get the nick of a player.

    • Parameters: Player Object The player to work over.
    • Return: Nick/Name (string) The player nick (if available, if not, it will return the player name).

=

PvP API

  • isPvPEnabled($player) Tell if a player has PvP enabled.

    • Parameters: Player Object The player to work over.

  • setPvP($player, $state) Set the PvP state of a player.

    • Parameters:
      • Player Object The player to work over.
      • State (boolean) The state to set: True will enable PvP, False will disable it.

  • switchPvP($player) Automatically switch the Mute state of a player. Activate it if isn't activated and vice versa.

    • Parameters: Player Object The player to work over.

=

Unlimited API

  • isUnlimitedEnabled($player) Tell if the Unlimited placing of Blocks is enabled.

    • Parameters: Player Object The player to work over.

  • setUnlimited($player, $state) Set the state of the Unlimited mode.

    • Parameters:
      • Player Object The player to work over.
      • State (boolean) The state to set: True will enable it, False will disable it.

  • switchUnlimited($player) Automatically switch the Unlimited mode. Activate it if isn't activated and vice versa. Parameters: Player Object The player to work over.

=

Vanish API

  • isVanished($player) Tell if a player is vanished.

    • Parameters: Player Object The player to work over.

  • setVanish($player, $state) Vanish or unvanish a player.

    • Parameters:
      • Player Object The player to work over.
      • State (boolean) The state to set: True will vanish the player, False will unvanish.

=

Warps API

  • warpExists($warp) Tell if a warp exists.

    • Parameters: Warp (string) The warp to search for.
    • Return: Boolean True if the warp exists, False if not.

  • getWarp($warp) Get a warp information, if exists.

    • Parameters: Warp (string) The warp to search for.
    • Return:
      • Boolean: False if the warp does't exists.
      • Array (Position Object, Yaw [integer], Pitch [integer]) The warp information.

  • setWarp($warp, $pos, $yaw = 0, $pitch = 0) Creates or updates a warp.

    • Parameters:
      • Warp (string) The warp to create or update.
      • Position Object The desired position for the warp.
      • Yaw (integer) [OPTIONAL] The X-Axis direction to set.
      • Pitch (integer) [OPTIONAL] The Y-Axis direction to set.
    • Return: Boolean True if the warp was successfully created or updated, False if not.

  • removeWarp($warp) Removes a warp from the server.

    • Parameters: Warp (string) The warp to remove.
    • Return: Boolean True if the warp was successfully removed, False if not or the warp doesn't exists.

  • warpList($inArray = false) Get a list of all the available warps in the server.

    • Parameters: InArray (boolean) [OPTIONAL] Specify if yo want to get the list as an array or a string.
    • Return:
      • Warp List (array) An array with the warp list.
      • Warp List (string) A string with the warp list.