Host

A global API dedicated to specifically the host of the avatar

warning

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

For other viewers, these do nothing

Functions in the host API aren't synced, meaning to be useful in multiplayer their information will need to be synced via pings

`isHost()`

Returns true if this instance of the script is running on host

isHost()

Returns:

Type	Description
`Boolean`	-

Example:

host:isHost()

Player Data

`isContainerOpen()`

Checks if the host has a container screen opened

isContainerOpen()

Returns:

Type	Description
`Boolean`	-

Example:

host:isContainerOpen()

`isFlying()`

Checks if the player is currently flying

isFlying()

Returns:

Type	Description
`Boolean`	-

Example:

host:isFlying()

`isJumping()`

Checks if the player is jumping

Note this is only true during the first tick the player started jumping

isJumping()

Returns:

Type	Description
`Boolean`	-

Example:

host:isJumping()

`getAir()`

Gets the remaining amount of air of the player

getAir()

Returns:

Type	Description
`Integer`	-

Example:

host:getAir()

`setSlot()`

Sets a slot with an ItemStack

The slot is either their numerical id (0 indexed) or the slot string, as used in the /item command

Slot -1 uses the first available slot

Only runs for creative mode

Overload 1
Overload 2
Overload 3
Overload 4

setSlot(slot)

Parameters:

Name	Type	Description	Default
slot	`String`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

setSlot(slot)

Parameters:

Name	Type	Description	Default
slot	`Integer`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

setSlot(slot, item)

Parameters:

Name	Type	Description	Default
slot	`String`	-	-
item	`String`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

setSlot(slot, item)

Parameters:

Name	Type	Description	Default
slot	`Integer`	-	-
item	`ItemStack`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:setSlot(0, "apple")
-- setSlot also accepts an ItemStack retrieved from an actual item or world:newItem()

`getSlot()`

Gets an ItemStack for the item in the given slot

The slot is either their numerical id (0 indexed) or the slot string, as used in the /item command

Overload 1
Overload 2

getSlot(slot)

Parameters:

Name	Type	Description	Default
slot	`String`	-	-

Returns:

Type	Description
`ItemStack`	-

getSlot(slot)

Parameters:

Name	Type	Description	Default
slot	`Integer`	-	-

Returns:

Type	Description
`ItemStack`	-

Example:

host:getSlot(0)

`getScreenSlot()`

Gets the item in a screen slot

The slot is either their numerical id (0 indexed) or the slot string, as used in the /item command

If the player is not currently in a screen, the screen has no slots, or the slot index is greater than the maximum, returns nil

Overload 1
Overload 2

getScreenSlot(slot)

Parameters:

Name	Type	Description	Default
slot	`String`	-	-

Returns:

Type	Description
`ItemStack`	-

getScreenSlot(slot)

Parameters:

Name	Type	Description	Default
slot	`Integer`	-	-

Returns:

Type	Description
`ItemStack`	-

Example:

host:getScreenSlot(0)

`getScreenSlotCount()`

Gets the number of slots in the screen the player is currently in

If the player is not currently in a screen or the screen has no slots, returns nil

getScreenSlotCount()

Returns:

Type	Description
`Integer`	-

Example:

host:getScreenSlotCount()

`getScreen()`

Gets the class name of the screen the player is currently on

If the player is not currently in a screen, returns nil

getScreen()

Returns:

Type	Description
`String`	-

Example:

host:getScreen()

`getStatusEffects()`

Returns a table of all of the player's status effects

The table contains sub-tables, each of which contains the name, amplifier, duration, and particle visibility of each status effect

getStatusEffects()

Returns:

Type	Description
`Table`	-

Example:

for _, effect in pairs(host:getStatusEffects()) do
    logTable(effect) -- prints all the effect information into chat
    log(effect.name) -- gets the effect's name and prints it into chat
end

`getAttackCharge()`

Returns a fraction (0 to 1) of the charge of the player attack

If less than 1, every attack will result in a weak attack

getAttackCharge()

Returns:

Type	Description
`Number`	-

Example:

host:getAttackCharge()

`getReachDistance()`

Returns the current reach distance of the player

getReachDistance()

Returns:

Type	Description
`Number`	-

Example:

host:getReachDistance()

`getPickBlock()`

Returns the current targeted block set by the client

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

getPickBlock()

Returns:

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

Example:

local block, hitPos, side = host:getPickBlock()

`getPickEntity()`

Returns the currently targeted entity set by the client

getPickEntity()

Returns:

Type	Description
`EntityAPI`	-

Example:

host:getPickEntity()

Chat

`isChatOpen()`

Checks if the host has the chat screen opened

isChatOpen()

Returns:

Type	Description
`Boolean`	-

Example:

host:isChatOpen()

`isChatVerified()`

figura.docs.host.is_chat_verified

isChatVerified()

Returns:

Type	Description
`Boolean`	-

Example:

host:isChatVerified()

`sendChatCommand()`

caution

In order to use this function you must turn the Chat Messages setting on in Figura's settings

Sends the given command in the chat

sendChatCommand(command)

Parameters:

Name	Type	Description	Default
command	`String`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:sendChatCommand("kill @a")

`sendChatMessage()`

caution

In order to you this function you must turn the Chat Messages setting on in Figura's settings

Sends the given message in the chat

sendChatMessage(message)

Parameters:

Name	Type	Description	Default
message	`String`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:sendChatMessage("Hello World")

`setChatColor()`

Aliases: chatColor()

Sets the color of the text that is currently being typed into the chat window

Overload 1
Overload 2

setChatColor(color)

Parameters:

Name	Type	Description	Default
color	`Vector3`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

setChatColor(r, g, b)

Parameters:

Name	Type	Description	Default
r	`Number`	-	-
g	`Number`	-	-
b	`Number`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:setChatColor(0, 0, 1)

`getChatColor()`

Gets the chat window text color

getChatColor()

Returns:

Type	Description
`Integer`	-

Example:

host:getChatColor()

`setChatMessage()`

Modifies a chat message with the given text

Takes an index, were 1 means the last message on chat

Setting the message to nil will effectively remove it from the chat

Overload 1
Overload 2
Overload 3

setChatMessage(index)

Parameters:

Name	Type	Description	Default
index	`Integer`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

setChatMessage(index, newMessage)

Parameters:

Name	Type	Description	Default
index	`Integer`	-	-
newMessage	`String`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

setChatMessage(index, newMessage, backgroundColor)

Parameters:

Name	Type	Description	Default
index	`Integer`	-	-
newMessage	`String`	-	-
backgroundColor	`Vector3`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:setChatMessage(1, "Hi?", vec(1, 0, 0))

`getChatMessage()`

Returns a table with information about a chat message

Takes an index, where 1 means the last message on chat

getChatMessage(index)

Parameters:

Name	Type	Description	Default
index	`Integer`	-	-

Returns:

Type	Description
`Table`	-

Example:

host:getChatMessage(1)

`setChatText()`

Aliases: chatText()

caution

In order to use this function you must turn the Chat Messages setting on in Figura's settings

Sets the text currently being typed in the chat window to the given string

setChatText(text)

Parameters:

Name	Type	Description	Default
text	`String`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:setChatText("Hello World")

`getChatText()`

Gets the text that is currently being typed into the chat window

getChatText()

Returns:

Type	Description
`String`	-

Example:

host:getChatText() == "Hello World"

`appendChatHistory()`

Appends the message on the recent chat history

appendChatHistory(message)

Parameters:

Name	Type	Description	Default
message	`String`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:appendChatHistory("Hello World")

Other

`setActionbar()`

Aliases: actionbar()

Sets the action bar message to the given text

The boolean parameter defaults to false

Overload 1
Overload 2

setActionbar(text)

Parameters:

Name	Type	Description	Default
text	`String`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

setActionbar(text, animated)

Parameters:

Name	Type	Description	Default
text	`String`	-	-
animated	`Boolean`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:setActionbar("Hello World")

`setClipboard()`

Aliases: clipboard()

Sets the clipboard text

setClipboard(text)

Parameters:

Name	Type	Description	Default
text	`String`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:setClipboard("Hello World")

`getClipboard()`

Gets the text from the clipboard

getClipboard()

Returns:

Type	Description
`String`	-

Example:

host:getClipboard()

`setSubtitle()`

Aliases: subtitle()

Sets the current subtitle to the given text

The text is given as a JSON string

setSubtitle(text)

Parameters:

Name	Type	Description	Default
text	`String`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:setSubtitle("Hello World")

`setTitle()`

Aliases: title()

Sets the current title to the given text

The text is given as json

setTitle(text)

Parameters:

Name	Type	Description	Default
text	`String`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:setTitle("Hello World")

`setTitleTimes()`

Aliases: titleTimes()

Sets the duration of the title on the screen, also its fade-in and fade-out durations

Overload 1
Overload 2

setTitleTimes(timesData)

Parameters:

Name	Type	Description	Default
timesData	`Vector3`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

setTitleTimes(fadeInTime, stayTime, fadeOutTime)

Parameters:

Name	Type	Description	Default
fadeInTime	`Integer`	-	-
stayTime	`Integer`	-	-
fadeOutTime	`Integer`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:setTitleTimes(5, 5, 5)

`setUnlockCursor()`

Toggles locking of your cursor, letting you move it freely on the screen instead of it controlling your player's rotation

setUnlockCursor(boolean)

Parameters:

Name	Type	Description	Default
boolean	`Boolean`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:setUnlockCursor(true)

`clearTitle()`

Clears the current title from the GUI

clearTitle()

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:clearTitle()

`isAvatarUploaded()`

Checks if this avatar is currently uploaded

isAvatarUploaded()

Returns:

Type	Description
`Boolean`	-

Example:

host:isAvatarUploaded()

`isCursorUnlocked()`

Checks if the cursor is currently unlocked

Only responds to your own changes in your script, not anything done by Minecraft itself

isCursorUnlocked()

Returns:

Type	Description
`Boolean`	-

Example:

host:isCursorUnlocked()

`screenshot()`

Takes a screenshot from the current screen and returns a Texture of it

screenshot(name)

Parameters:

Name	Type	Description	Default
name	`String`	-	-

Returns:

Type	Description
`Texture`	-

Example:

host:screenshot()

`swingArm()`

Animates swinging the player's arm

If the boolean is true, then the offhand is the one that swings

Overload 1
Overload 2

swingArm()

Returns:

Type	Description
`HostAPI`	Returns self for chaining

swingArm(offhand)

Parameters:

Name	Type	Description	Default
offhand	`Boolean`	-	-

Returns:

Type	Description
`HostAPI`	Returns self for chaining

Example:

host:swingArm()

Fields

`unlockCursor`

Setting this value to true will unlock your cursor, letting you move it freely on the screen instead of it controlling your player's rotation

See setUnlockCursor for an example of how to set it.

isHost()​

Player Data​

isContainerOpen()​

isFlying()​

isJumping()​

getAir()​

setSlot()​

getSlot()​

getScreenSlot()​

getScreenSlotCount()​

getScreen()​

getStatusEffects()​

getAttackCharge()​

getReachDistance()​

getPickBlock()​

getPickEntity()​

Chat​

isChatOpen()​

isChatVerified()​

sendChatCommand()​

sendChatMessage()​

setChatColor()​

getChatColor()​

setChatMessage()​

getChatMessage()​

setChatText()​

getChatText()​

appendChatHistory()​

Other​

setActionbar()​

setClipboard()​

getClipboard()​

setSubtitle()​

setTitle()​

setTitleTimes()​

setUnlockCursor()​

clearTitle()​

isAvatarUploaded()​

isCursorUnlocked()​

screenshot()​

swingArm()​

Fields​

unlockCursor​

`isHost()`

Player Data

`isContainerOpen()`

`isFlying()`

`isJumping()`

`getAir()`

`setSlot()`

`getSlot()`

`getScreenSlot()`

`getScreenSlotCount()`

`getScreen()`

`getStatusEffects()`

`getAttackCharge()`

`getReachDistance()`

`getPickBlock()`

`getPickEntity()`

Chat

`isChatOpen()`

`isChatVerified()`

`sendChatCommand()`

`sendChatMessage()`

`setChatColor()`

`getChatColor()`

`setChatMessage()`

`getChatMessage()`

`setChatText()`

`getChatText()`

`appendChatHistory()`

Other

`setActionbar()`

`setClipboard()`

`getClipboard()`

`setSubtitle()`

`setTitle()`

`setTitleTimes()`

`setUnlockCursor()`

`clearTitle()`

`isAvatarUploaded()`

`isCursorUnlocked()`

`screenshot()`

`swingArm()`

Fields

`unlockCursor`