Player

The player API inherits functions from the living entity API

The player API is accessed through the player global. Like so: player:isGliding()

warning

This page is a WIP. It contains all the information in Figura's documentation but we're working on adding more helpful descriptions.

Player information that isn't synced between clients is kept in the host API. Examples of unsynced data are: Creative flying, status effects, and remaining air amount.

note

There are times during a script's functioning where the script will run, but the player global will be empty. This will cause the "Tried to access the EntityAPI before its initialization" error. To solve this, move the player API call into a protected event, like tick. If you wish to initialize a check during the initialization phase of a script (outside of any other event) you can use the entity_init event.

All provided examples assume you're using a tick event.

To reiterate:

player:isGliding() -- will error
function events.entity_init()
    player:isGliding() -- will not error, but will only play once
end

player:isGliding() -- will error
function events.tick()
    player:isGliding() -- won't error, and will update once a tick
end

player:isGliding() -- will error

---

Player Transformations

getPos()

Gets the position of the entity in the world

If delta is passed in, then it will be used to linearly interpolate the position of the entity between the previous tick and the current tick

The default value of delta is 1

Overload 1

getPos()

Returns:

Type	Description
Vector3	-

Overload 2

getPos(delta)

Parameters:

Name	Type	Description	Default
delta	Number	-	-

Returns:

Type	Description
Vector3	-

Example:

player:getPos()

---

getRot()

Gets the rotation of the entity in degrees

If delta is passed in, then it will be used to linearly interpolate the rotation of the entity between the previous tick and the current tick

The default value of delta is 1

Overload 1

getRot()

Returns:

Type	Description
Vector2	-

Overload 2

getRot(delta)

Parameters:

Name	Type	Description	Default
delta	Number	-	-

Returns:

Type	Description
Vector2	-

Example:

player:getRot()

---

getBodyYaw()

Gets the yaw of this entity's body in degrees

If delta is passed in, then it will be used to linearly interpolate the rotation of the body between the previous tick and the current tick

The default value of delta is 1

Overload 1

getBodyYaw()

Returns:

Type	Description
Number	-

Overload 2

getBodyYaw(delta)

Parameters:

Name	Type	Description	Default
delta	Number	-	-

Returns:

Type	Description
Number	-

Example:

player:getBodyYaw()

---

getLookDir()

Returns a unit vector pointing in the direction that this entity is looking

See the blue line in the F3+B screen for an example

getLookDir()

Returns:

Type	Description
Vector3	-

Example:

player:getLookDir()

---

getVelocity()

Gets the current velocity of this entity in world coordinates, calculated as its position this tick minus its position last tick

getVelocity()

Returns:

Type	Description
Vector3	-

Example:

player:getVelocity()

---

Player Actions

getPose()

Returns the current pose of the player

This can be one of: "STANDING", "FALL_FLYING", "SLEEPING", "SWIMMING", "SPIN_ATTACK", "CROUCHING", "LONG_JUMPING", or "DYING"

getPose()

Returns:

Type	Description
String	-

Example:

player:getPose() == "CROUCHING"

---

isCrouching()

Returns true if this entity is visually sneaking

isCrouching()

Returns:

Type	Description
Boolean	-

Example:

player:isCrouching()

---

isGliding()

Returns if this entity is gliding with an elytra

isGliding()

Returns:

Type	Description
Boolean	-

Example:

player:isGliding() -- will error
function events.entity_init()
    player:isGliding() -- will not error, but will only play once
end

player:isGliding() -- will error
function events.tick()
    player:isGliding() -- won't error, and will update once a tick
end

player:isGliding() -- will error

---

isFishing()

Returns if the player is currently fishing

isFishing()

Returns:

Type	Description
Boolean	-

Example:

player:isFishing()

---

isBlocking()

Return if this entity is blocking with a shield

isBlocking()

Returns:

Type	Description
Boolean	-

Example:

player:isBlocking()

---

isVisuallySwimming()

Returns if this entity has the swimming pose

isVisuallySwimming()

Returns:

Type	Description
Boolean	-

Example:

player:isVisuallySwimming()

---

isClimbing()

Returns true if the entity is currently using a climbable block, like a ladder or vine

isClimbing()

Returns:

Type	Description
Boolean	-

Example:

player:isClimbing()

---

isSneaking()

Returns true if this entity is logically sneaking (can't fall from blocks edges, can't see nameplate behind walls, etc)

isSneaking()

Returns:

Type	Description
Boolean	-

Example:

player:isSneaking()

---

isSprinting()

Returns true if this entity is currently sprinting

isSprinting()

Returns:

Type	Description
Boolean	-

Example:

player:isSprinting()

---

riptideSpinning()

Returns if this entity is riptide spinning

riptideSpinning()

Returns:

Type	Description
Boolean	-

Example:

player:riptideSpinning()

---

Player Data

isLoaded()

Checks if this entity object is still being updated and loaded

A non-loaded entity would be someone or something which is in another dimension or out of the render distance for example

isLoaded()

Returns:

Type	Description
Boolean	-

Example:

player:isLoaded()

---

getNbt()

Gets a table containing the NBT of this entity

Please note that not all values in the entity's NBT may be synced, as some are handled only on the server side

getNbt()

Returns:

Type	Description
Table	-

Example:

player:getNbt()

---

getChargedAttackDelay()

Returns the delay (in ticks) of charged attacks

getChargedAttackDelay()

Returns:

Type	Description
Number	-

Example:

player:getChargedAttackDelay()

---

getExperienceProgress()

Gets the progress of the way towards the player's next level, as a value from 0 to 1

getExperienceProgress()

Returns:

Type	Description
Number	-

Example:

player:getExperienceProgress()

---

getExperienceLevel()

Gets the player's current level

getExperienceLevel()

Returns:

Type	Description
Integer	-

Example:

player:getExperienceLevel()

---

getShoulderEntity()

Returns a table of the nbt of this entity left or right shoulder entity

Overload 1

getShoulderEntity()

Returns:

Type	Description
Table	-

Overload 2

getShoulderEntity(right)

Parameters:

Name	Type	Description	Default
right	Boolean	-	-

Returns:

Type	Description
Table	-

Example:

player:getShoulderEntity()

---

getTeamInfo()

Returns a table with information about the team of this player

Returns nil if the player doesn't have a team

getTeamInfo()

Returns:

Type	Description
Table	-

Example:

player:getTeamInfo()

---

getFood()

Gets the current food level of the player, from 0 to 20

getFood()

Returns:

Type	Description
Integer	-

Example:

player:getFood()

---

getGamemode()

Returns "SURVIVAL", "CREATIVE", "ADVENTURE", or "SPECTATOR" depending on the player's gamemode

If the gamemode is unknown, returns nil

getGamemode()

Returns:

Type	Description
String	-

Example:

player:getGamemode()

---

getSaturation()

Gets the current saturation level of the player

getSaturation()

Returns:

Type	Description
Number	-

Example:

player:getSaturation()

---

getExhaustion()

Gets the current exhaustion level of the player

getExhaustion()

Returns:

Type	Description
Number	-

Example:

player:getExhaustion()

---

getAbsorptionAmount()

Returns the amount of this entity's absorption (yellow hearts)

getAbsorptionAmount()

Returns:

Type	Description
Number	-

Example:

player:getAbsorptionAmount()

---

getArmor()

Returns the amount of armor points this entity has

getArmor()

Returns:

Type	Description
Number	-

Example:

player:getArmor()

---

getMaxHealth()

Returns the maximum amount of health this entity can have

getMaxHealth()

Returns:

Type	Description
Number	-

Example:

player:getMaxHealth()

---

getHealth()

Returns the amount of health this entity has remaining

getHealth()

Returns:

Type	Description
Number	-

Example:

player:getHealth()

---

getDeathTime()

Returns the number of ticks this entity has been dead for

getDeathTime()

Returns:

Type	Description
Number	-

Example:

player:getDeathTime()

---

getStingerCount()

Returns the number of bee stingers sticking out of this entity

getStingerCount()

Returns:

Type	Description
Integer	-

Example:

player:getStingerCount()

---

getArrowCount()

Returns the number of arrows sticking out of this entity

getArrowCount()

Returns:

Type	Description
Integer	-

Example:

player:getArrowCount()

---

getEntityCategory()

Returns the category of this entity

The categories are: "ARTHROPOD", "UNDEAD", "WATER", "ILLAGER" and by default, "UNDEFINED"

getEntityCategory()

Returns:

Type	Description
String	-

Example:

player:getEntityCategory() == "UNDEAD"

---

isSensitiveToWater()

Returns if this entity takes damage to water

isSensitiveToWater()

Returns:

Type	Description
Boolean	-

Example:

player:isSensitiveToWater()

---

getName()

Gets the name of this entity, if it has a custom name

If it doesn't, returns a translated form of getType()

getName()

Returns:

Type	Description
String	-

Example:

player:getName()

---

isAlive()

Returns whether this entity is alive or not

isAlive()

Returns:

Type	Description
Boolean	-

Example:

player:isAlive()

---

getType()

Gets the Minecraft identifier of this entity

For instance, "minecraft:pig"

getType()

Returns:

Type	Description
String	-

Example:

player:getType()

---

getControlledVehicle()

Return the vehicle that this entity is controlling

getControlledVehicle()

Returns:

Type	Description
EntityAPI	-

Example:

player:getControlledVehicle()

---

getControllingPassenger()

Returns the entity that is controlling this entity

getControllingPassenger()

Returns:

Type	Description
EntityAPI	-

Example:

player:getControllingPassenger()

---

getPassengers()

Returns a List of entities of all passengers this entity has

getPassengers()

Returns:

Type	Description
Table	-

Example:

player:getPassengers()

---

getFrozenTicks()

Gets the number of ticks this entity has been freezing in powder snow for

getFrozenTicks()

Returns:

Type	Description
Integer	-

Example:

player:getFrozenTicks()

---

getMaxAir()

Gets the maximum amount of air this entity can have

getMaxAir()

Returns:

Type	Description
Integer	-

Example:

player:getMaxAir()

---

getDimensionName()

Gets the Minecraft identifier of the dimension this entity is in

getDimensionName()

Returns:

Type	Description
String	-

Example:

player:getDimensionName()

---

isUnderwater()

Returns true if this entity's eyes are touching water

isUnderwater()

Returns:

Type	Description
Boolean	-

Example:

player:isUnderwater()

---

isInWater()

Returns true if this entity is currently in a water block, including waterlogging

isInWater()

Returns:

Type	Description
Boolean	-

Example:

player:isInWater()

---

isInRain()

Returns true if this entity is currently standing in rain

isInRain()

Returns:

Type	Description
Boolean	-

Example:

player:isInRain()

---

isWet()

Returns true in any of three conditions: if the entity is in water, if the entity is in rain, or if the entity is in a bubble column

Otherwise, returns false

isWet()

Returns:

Type	Description
Boolean	-

Example:

player:isWet()

---

isInLava()

Returns true if this entity is currently in lava

isInLava()

Returns:

Type	Description
Boolean	-

Example:

player:isInLava()

---

isOnFire()

Returns true if this entity is currently on fire

isOnFire()

Returns:

Type	Description
Boolean	-

Example:

player:isOnFire()

---

isInvisible()

Returns true if this entity is invisible, for one reason or another

isInvisible()

Returns:

Type	Description
Boolean	-

Example:

player:isInvisible()

---

getVehicle()

Returns a proxy for the entity that this player is currently riding

If the player isn't riding anything, returns nil

getVehicle()

Returns:

Type	Description
EntityAPI	-

Example:

local vehicle = player:getVehicle()
-- We make sure `vehicle` isn't nil so we can safely call `getType()`
if vehicle and vehicle:getType() == "minecraft:pig" then
    log("You're riding a pig")
end

---

isSilent()

Returns true if this entity is silent

isSilent()

Returns:

Type	Description
Boolean	-

Example:

player:isSilent()

---

isGlowing()

Returns true if this entity is currently glowing

isGlowing()

Returns:

Type	Description
Boolean	-

Example:

player:isGlowing()

---

getBoundingBox()

Returns the size of this entity's bounding box as a Vector3

{x, y, z} are the width, height, and width

Minecraft entity hitboxes always have square bases

getBoundingBox()

Returns:

Type	Description
Vector3	-

Example:

player:getBoundingBox()

---

isOnGround()

caution

Due to a glitch in Minecraft's code this function is unreliable, and will misfire in multiple situations such as being underwater, standing on a boat, or standing on a slime block.

Work Around:

-- check the blockstate of the block directly underneath the player
world.getBlockState(player:getPos():add(0, -0.1, 0)):isSolidBlock()

Returns whether or not this entity is currently on the ground

isOnGround()

Returns:

Type	Description
Boolean	-

Example:

player:isOnGround()

---

getEyeY()

Returns the Y level of this entity's eyes

Not to be confused with getEyeHeight, this function also takes the entity itself's Y position into account

getEyeY()

Returns:

Type	Description
Number	-

Example:

player:getEyeY()

---

getEyeHeight()

Returns the current eye height of this entity

getEyeHeight()

Returns:

Type	Description
Number	-

Example:

player:getEyeHeight()

---

getTargetedEntity()

Returns a proxy for your currently targeted Entity

This Entity appears on the F3 screen

Maximum and Default distance is 20, Minimum is 0

Overload 1

getTargetedEntity()

Returns:

Type	Description
Entity	Targeted entity
Vector3	Hit position

Overload 2

getTargetedEntity(distance)

Parameters:

Name	Type	Description	Default
distance	Number	-	-

Returns:

Type	Description
Entity	Targeted entity
Vector3	Hit position

Example:

local entity, pos = player:getTargetedEntity(host:getReachDistance() or 4.5) -- host is not synced
if entity and entity:getType() == "minecraft:creeper" then
    log("You're looking at a creeper")
end

---

getTargetedBlock()

Returns a proxy for your currently targeted BlockState

This BlockState appears on the F3 screen

The maximum (and default) distance is 20, minimum is -20

Returns the block, the hit position, and the targeted block face as three separate values

Overload 1

getTargetedBlock()

Returns:

Type	Description
BlockState	Targeted block
Vector3	Hit position
String	Targeted block face

Overload 2

getTargetedBlock(ignoreLiquids)

Parameters:

Name	Type	Description	Default
ignoreLiquids	Boolean	-	-

Returns:

Type	Description
BlockState	Targeted block
Vector3	Hit position
String	Targeted block face

Overload 3

getTargetedBlock(ignoreLiquids, distance)

Parameters:

Name	Type	Description	Default
ignoreLiquids	Boolean	-	-
distance	Number	-	-

Returns:

Type	Description
BlockState	Targeted block
Vector3	Hit position
String	Targeted block face

Example:

local block, hitPos, side = player:getTargetedBlock(true, 4.5)
if block.id == "minecraft:grass_block" then
    log("You're looking at grass")
end

---

hasInventory()

Checks if the entity has an inventory (Horses, Camels, LLamas, …)

hasInventory()

Returns:

Type	Description
Boolean	-

Example:

player:hasInventory()

---

hasContainer()

Checks if the entity has a container (Chest Boats, Minecarts with Chests, …)

hasContainer()

Returns:

Type	Description
Boolean	-

Example:

player:hasContainer()

---

isLiving()

Gets if this entity is a Living Entity

isLiving()

Returns:

Type	Description
Boolean	-

Example:

player:isLiving()

---

isPlayer()

Gets if this entity is a Player Entity

isPlayer()

Returns:

Type	Description
Boolean	-

Example:

player:isPlayer()

---

getPermissionLevel()

Returns the permission level number of this entity

Server Operators, by default, have the permission level of 4

getPermissionLevel()

Returns:

Type	Description
Integer	-

Example:

player:getPermissionLevel()

---

Vanilla Settings

getModelType()

Returns "SLIM" or "DEFAULT", depending on the player's model type

getModelType()

Returns:

Type	Description
String	-

Example:

player:getModelType() == "DEFAULT"

---

hasCape()

Returns whether the player has a cape loaded

hasCape()

Returns:

Type	Description
Boolean	-

Example:

player:hasCape()

---

hasSkin()

Returns whether the player has a custom skin loaded

hasSkin()

Returns:

Type	Description
Boolean	-

Example:

player:hasSkin()

---

isSkinLayerVisible()

Returns whether the specified skin layer, from the Skin Customizations settings, is currently visible

isSkinLayerVisible(part)

Parameters:

Name	Type	Description	Default
part	String	-	-

Returns:

Type	Description
Boolean	-

Example:

player:isSkinLayerVisible("HAT")

---

Item Functions

getItem()

Gets an ItemStack for the item in the given slot

For the player, slots are indexed with 1 as the main hand, 2 as the off hand, and 3,4,5,6 as the 4 armor slots from the boots to the helmet

If an invalid slot number is given, this will return nil

getItem(index)

Parameters:

Name	Type	Description	Default
index	Integer	-	-

Returns:

Type	Description
ItemStack	-

Example:

if player:getItem(5).id == "minecraft:elytra" then
    log("You're wearing an elytra")
end

---

getHeldItem()

Returns an ItemStack representing the item in this entity's main hand

If true is passed in for "offhand", then it will instead look at the item in the entity's offhand

If the entity isn't holding an item in that hand, returns air

Overload 1

getHeldItem()

Returns:

Type	Description
ItemStack	-

Overload 2

getHeldItem(offhand)

Parameters:

Name	Type	Description	Default
offhand	Boolean	-	-

Returns:

Type	Description
ItemStack	-

Example:

if player:getHeldItem(false).id ~= "minecraft:air" then
    log("Item in mainhand")
end
if player:getHeldItem(true).id ~= "minecraft:air" then
    log("Item in offhand")
end

---

isUsingItem()

Returns true if the entity is currently using an item

isUsingItem()

Returns:

Type	Description
Boolean	-

Example:

player:isUsingItem()

---

getActiveItem()

Returns an ItemStack representing the item the entity is currently using

If they're not using any item, returns air

getActiveItem()

Returns:

Type	Description
ItemStack	-

Example:

player:getActiveItem()

---

getActiveItemTime()

Returns the ticks this entity's active item has been used for

getActiveItemTime()

Returns:

Type	Description
Integer	-

Example:

player:getActiveItemTime()

---

getCooldownPercent()

Returns the whether a given ItemStack has an active cool down as a percent from 0.0 to 1.0

If it has none, it returns 0.0

Takes two parameters stack, and delta, delta offsets the cooldown's tick count by it, used for smoother animation.

getCooldownPercent(stack, delta)

Parameters:

Name	Type	Description	Default
stack	ItemStack	-	-
delta	Number	-	-

Returns:

Type	Description
Number	-

Example:

local function bar(percent)
    local progress = math.ceil(percent * 20)
    local remaining = 20 - progress
    return string.rep("▆", progress) .. string.rep("▁", remaining)
end

function events.tick()
    local heldItem = player:getHeldItem()
    if heldItem:getID() ~= "minecraft:ender_pearl" then
        host:setActionbar("")
        return
    end
    local cooldown = player:getCooldownPercent(heldItem)
    host:setActionbar(bar(1 - cooldown))
end

---

Hand Functions

isLeftHanded()

Returns true if the entity's main hand is its left

isLeftHanded()

Returns:

Type	Description
Boolean	-

Example:

player:isLeftHanded()

---

isSwingingArm()

Returns true if the entity is currently swinging its arm

isSwingingArm()

Returns:

Type	Description
Boolean	-

Example:

player:isSwingingArm()

---

getSwingDuration()

Returns the number of ticks this entity will have while swinging its arms

getSwingDuration()

Returns:

Type	Description
Integer	-

Example:

player:getSwingDuration()

---

getSwingTime()

Returns the number of ticks this entity has the arm swinging

getSwingTime()

Returns:

Type	Description
Integer	-

Example:

player:getSwingTime()

---

getActiveHand()

Returns "OFF_HAND" or "MAIN_HAND", depending on which hand this entity uses an item with

getActiveHand()

Returns:

Type	Description
String	-

Example:

player:getActiveHand() == "MAIN_HAND"

---

getSwingArm()

Returns "OFF_HAND" or "MAIN_HAND", based on the arm this entity is currently swinging

getSwingArm()

Returns:

Type	Description
String	-

Example:

player:getSwingArm() == "OFF_HAND"

---

Miscellaneous

getUUID()

Gets the UUID of the proxied entity

getUUID()

Returns:

Type	Description
String	-

Example:

player:getUUID()

---

getVariable()

Gets the value of a variable this entity stored in themselves using the Avatar API's store() function

Overload 1

getVariable()

Returns:

Type	Description
AnyType	-

Overload 2

getVariable(key)

Parameters:

Name	Type	Description	Default
key	String	-	-

Returns:

Type	Description
AnyType	-

Example:

player:getVariable()

---

hasAvatar()

Returns true if Figura has an avatar loaded for this entity

hasAvatar()

Returns:

Type	Description
Boolean	-

Example:

player:hasAvatar()

---