entity

you get an entity value from Katton.world().entities, or as the return value of Katton.world().spawnEntity(...). players are not included here, they're exposed separately via player values (see player) and Katton.world().players


properties

entity.uuid //"8667ba71-b85a-4004-af54-457a9734eed7" as a string
entity.type //"zombie"
entity.is_valid //true / false. an entity can stop existing at any point, whether it dies, despawns, etc. once that happens, every method below (other than the properties) throws a runtime error so check first if the `entity` value still exists
entity.location //{ x: 12.5, y: 64.0, z: -3.0, yaw: 90.0, pitch: 0.0 }
entity.health //20.0, living entities only
entity.max_health //20.0, living entities only
entity.tags //a list of scoreboard tag strings
entity.vehicle //a `entity` value for whatever they are riding
entity.yaw //living entities only
entity.pitch //living entities only

methods

entity.setHealth(health)
entity.setDisplayName(text)
display.setSkin(username)
entity.teleport(location)
entity.setGlowing(glowing = true)
entity.addTag(tag)
entity.removeTag(tag)
entity.hasTag(tag)
entity.setMovementSpeed(speed)
entity.resetMovementSpeed()
entity.setJumpStrength(strength)
entity.resetJumpStrength()
display.setScale(x, y, z) or entity.setScale(scale)
entity.resetScale()
display.setText(text)
display.setBackgroundColor(r, g, b, a)
display.resetBackground()
display.setDefaultBackground(enabled)
display.setTextOpacity(opacity)
display.setAlignment(alignment)
display.setLineWidth(width)
display.setSeeThrough(seeThrough)
display.setShadowed(shadowed)
display.setBillboard(billboard)
display.setItem(item)
display.setBlock(material)
display.setOffset(x, y, z)
display.setRotation(yaw, pitch, roll)
display.setTeleportDuration(ticks)
display.setInterpolationDuration(ticks)
display.setInterpolationDelay(ticks)
entity.giveEffect(potion_effect)
entity.removeEffect(potion_effect)
entity.removeAllEffects()
thisEntity.mount(entity)
thisEntity.dismount()
entity.kill()

setHealth

sets the entity's current health

entity.setHealth(health)
parameter default description
health default=20.0 target health value

example

val zombie = Katton.world().spawnEntity("zombie", player.location)
zombie.setHealth(5)

setDisplayName

sets the custom name tag displayed above the entity

entity.setDisplayName(text)
parameter default description
text default="" custom display text, supports & color codes

example

zombie.setDisplayName("&c&lBOSS ZOMBIE")

setSkin

sets the entity's skin if the entity is a mannequin

display.setSkin(username)
parameter default description
username required changes the skin of a mannequin to this username

example

mannequin.setSkin("yayAmelia")

teleport

teleports the entity to a target location object

entity.teleport(location)
parameter default description
location required location object { x, y, z, yaw, pitch }

example

zombie.teleport({ "x": 0, "y": 70, "z": 0, "yaw": 0, "pitch": 0 })

setGlowing

enables or disables the vanilla outline glowing effect around the entity

entity.setGlowing(glowing = true)
parameter default description
glowing default=true whether the glowing effect should be active

example

zombie.setGlowing(true)
zombie.setGlowing(false)

addTag

adds a scoreboard tag to the entity

entity.addTag(tag)
parameter default description
tag default="" scoreboard tag string

example

val zombie = Katton.world().spawnEntity("zombie", player.location)
zombie.addTag("boss_fight_mob")
for (e in Katton.world().entities) {
    if (e.hasTag("boss_fight_mob")) {
        e.setGlowing(true)
    }
}

removeTag

removes a scoreboard tag from the entity

entity.removeTag(tag)
parameter default description
tag default="" scoreboard tag string

hasTag

checks if the entity has a scoreboard tag

entity.hasTag(tag)
parameter default description
tag default="" scoreboard tag string

setMovementSpeed

modifies movement speed attribute base values

entity.setMovementSpeed(speed)
parameter default description
speed default=0.1 movement speed attribute base value (vanilla default is 0.1)

example

zombie.setMovementSpeed(0.3)

resetMovementSpeed

resets movement speed attribute base values to default

entity.resetMovementSpeed()

setJumpStrength

modifies jump height attribute base values

entity.setJumpStrength(strength)
parameter default description
strength default=0.42 jump strength attribute base value (vanilla default is 0.42)

example

zombie.setJumpStrength(0.6)

resetJumpStrength

resets jump height attribute base values to default

entity.resetJumpStrength()

setScale

resizes the display entity along each coordinate axis or modifies the living entity's scale attribute

display.setScale(x, y, z) or entity.setScale(scale)
parameter default description
scale default=1.0 scale value multiplier
x default=1 horizontal scale factor (width)
y default=1 vertical scale factor (height)
z default=1 depth scale factor (length)

example

val display = Katton.world().spawnEntity("block_display", player.location)
display.setBlock("stone")
display.setScale(1, 3, 1)

resetScale

resets the scale configuration back to default

entity.resetScale()

setText

sets the text content displayed by a text display entity

display.setText(text)
parameter default description
text default="" text content string, automatically filtered and styled

example

val display = Katton.world().spawnEntity("text_display", player.location)
display.setText("hello world")

setBackgroundColor

changes the background color of a text display entity

display.setBackgroundColor(r, g, b, a)
parameter default description
r default=0 red color channel (0 to 255)
g default=0 green color channel (0 to 255)
b default=0 blue color channel (0 to 255)
a default=255 alpha transparency channel (0 to 255)

example

display.setBackgroundColor(255, 0, 0, 128)

resetBackground

resets the background color of a text display entity

display.resetBackground()

example

display.resetBackground()

setDefaultBackground

configures whether the default background is enabled for a text display entity

display.setDefaultBackground(enabled)
parameter default description
enabled default=true whether the default background is enabled

example

display.setDefaultBackground(false)

setTextOpacity

sets the opacity of the text on a text display entity

display.setTextOpacity(opacity)
parameter default description
opacity default=255 text opacity value (0 to 255)

example

display.setTextOpacity(128)

setAlignment

sets the text alignment on a text display entity

display.setAlignment(alignment)
parameter default description
alignment default="center" alignment string, must be one of: left, center, right

example

display.setAlignment("left")

setLineWidth

sets the maximum line width for wrapping text on a text display entity

display.setLineWidth(width)
parameter default description
width default=200 maximum width (clamped between 1 and 1000)

example

display.setLineWidth(300)

setSeeThrough

enables or disables whether the text display is visible through blocks

display.setSeeThrough(seeThrough)
parameter default description
seeThrough default=true whether text renders through obstacles

example

display.setSeeThrough(true)

setShadowed

enables or disables the text shadow effect on a text display entity

display.setShadowed(shadowed)
parameter default description
shadowed default=true whether text has a shadow

example

display.setShadowed(true)

setBillboard

sets the billboard setting of the text display entity

display.setBillboard(billboard)
parameter default description
billboard default=center the billboard setting

example

display.setBillboard("fixed")

setItem

sets the item stack displayed by an item display entity

display.setItem(item)
parameter default description
item required a Katton.item(...) value

example

val display = Katton.world().spawnEntity("item_display", player.location)
display.setItem(Katton.item("diamond_sword"))

setBlock

sets the block material displayed by a block display entity

display.setBlock(material)
parameter default description
material required block material name string (e.g. "stone")

example

val display = Katton.world().spawnEntity("block_display", player.location)
display.setBlock("stone")

setOffset

shifts the display entity relative to the entity's actual pivot point without moving the entity itself

display.setOffset(x, y, z)
parameter default description
x default=0 horizontal translation offset (left / right)
y default=0 vertical translation offset (up / down)
z default=0 forward / backward translation offset

example

val display = Katton.world().spawnEntity("block_display", player.location)
display.setBlock("stone")
display.setOffset(0, 2, 0)

setRotation

rotates the display model using degrees

display.setRotation(yaw, pitch, roll)
parameter default description
yaw default=0 horizontal rotation around the vertical Y axis (left / right)
pitch default=0 vertical tilt around the X axis (up / down)
roll default=0 sideways tilt around the Z axis

example

val display = Katton.world().spawnEntity("item_display", player.location)
display.setItem(Katton.item("diamond_sword"))
display.setRotation(0, 45, 90)

setTeleportDuration

sets the teleport tick duration for position changes to transition smoothly instead of snapping immediately

display.setTeleportDuration(ticks)
parameter default description
ticks default=0 transition duration in ticks (clamped between 0 and 59)

example

display.setTeleportDuration(20)

setInterpolationDuration

sets the interpolation duration

display.setInterpolationDuration(ticks)
parameter default description
ticks default=0 interpolation duration in ticks

setInterpolationDelay

sets the interpolation delay

display.setInterpolationDelay(ticks)
parameter default description
ticks default=0 interpolation delay in ticks

giveEffect

gives the entity a potion effect

entity.giveEffect(potion_effect)
parameter default description
effect required a potion effect value

removeEffect

removes a specific potion effect from the entity

entity.removeEffect(potion_effect)
parameter default description
effect required the potion effect to remove

removeAllEffects

removes all active potion effects from the entity

entity.removeAllEffects()

mount

makes the entity mount an entity

thisEntity.mount(entity)
parameter default description
vehicle required the entity the entity rides

dismount

makes the entity stop riding whatever they are currently riding

thisEntity.dismount()

kill

removes the entity immediately from the world

entity.kill()

example

zombie.kill()