World and blocks
world is game.world(). Every call throws ScriptStateException when there is no world loaded; a block read is a snapshot taken at call time.
on<ClientTickEvent> {
whenInGame {
val under = world.block(player.x().toInt(), player.y().toInt() - 1, player.z().toInt())
val fluid = under.fluid()
val nearby = world.entitiesNear(player.position(), 8.0, filters.attackable())
chat.print("${under.id()} ${fluid?.id() ?: "dry"} ${nearby.size}")
}
}The world itself
| Method | Type | Description |
|---|---|---|
world.dimension() |
String |
dimension registry key, e.g. minecraft:overworld |
world.timeTicks() |
long |
total world age in ticks |
world.dayTimeTicks() |
long |
time of day in ticks, cycle length 24000 |
world.raining() |
boolean |
rain active in this world |
world.thundering() |
boolean |
thunderstorm active in this world |
world.rainGradient() |
float |
rain strength 0..1 |
world.thunderGradient() |
float |
thunder strength 0..1 |
world.biome(position) |
String? |
biome registry id at the floored position |
world.respawnAnchorWorks(x, y, z) |
boolean |
a respawn anchor sets spawn here instead of exploding (API 6) |
world.topY(x, z) |
int |
y above the highest non-air block, bottom y when unloaded |
Reading a block
| Method | Type | Description |
|---|---|---|
world.block(x, y, z) |
Block |
block state snapshot, void_air outside world limits |
world.block(position) |
Block |
same, Vec coordinates floored |
world.blockPending(x, y, z) |
boolean |
the block there is your own prediction the server has not acknowledged yet (API 7) |
block.id() |
String |
block registry id, e.g. minecraft:stone |
block.name() |
String |
localized block name |
block.x() |
int |
block x coordinate |
block.y() |
int |
block y coordinate |
block.z() |
int |
block z coordinate |
block.position() |
Vec |
block corner coordinates |
block.box() |
Box |
the 1×1×1 cube at this position, not the block shape |
Vec and Box are documented on Vectors, boxes, angles.
Block state
| Method | Type | Description |
|---|---|---|
block.air() |
boolean |
state is air |
block.solid() |
boolean |
state is solid |
block.liquid() |
boolean |
state is a liquid block |
block.opaque() |
boolean |
state is opaque |
block.blocksMovement() |
boolean |
state blocks movement |
block.replaceable() |
boolean |
a placed block can replace this state |
block.fullCube() |
boolean |
state is a full cube at this position |
block.hasCollision() |
boolean |
collision shape at this position is non-empty |
block.collisionBoxes() |
List<Box> |
collision shape parts in world coordinates, empty when none (API 3) |
block.outlineBoxes() |
List<Box> |
outline shape parts in world coordinates, empty when none (API 3) |
block.luminance() |
int |
emitted light 0..15 |
block.opacity() |
int |
light attenuation 0..15 |
block.hardness() |
float |
breaking hardness at this position, -1 for unbreakable |
block.blastResistance() |
float |
explosion resistance |
block.slipperiness() |
float |
friction factor, 0.6 default, 0.98 for ice |
block.velocityMultiplier() |
float |
horizontal movement multiplier |
block.jumpVelocityMultiplier() |
float |
jump velocity multiplier |
block.emitsRedstone() |
boolean |
state emits redstone power |
block.toolRequired() |
boolean |
correct tool required for drops |
block.burnable() |
boolean |
state is burnable |
block.randomTicks() |
boolean |
state receives random ticks |
block.pistonBehavior() |
String |
lowercase: normal, destroy, block, ignore, push_only |
block.mapColor() |
int |
map colour as ARGB, alpha forced to 0xFF |
Properties and tags
| Method | Type | Description |
|---|---|---|
block.properties() |
Map<String, String> |
every state property as name -> value, unmodifiable, insertion-ordered |
block.property(name) |
String? |
one property value by case-insensitive name |
block.tags() |
List<String> |
block tag ids |
block.hasTag(tagId) |
boolean |
block is in that tag, leading # and namespace optional (throws ScriptException when tagId is blank or unparsable) |
Block entities
| Method | Type | Description |
|---|---|---|
block.hasBlockEntity() |
boolean |
state declares a block entity |
block.blockEntity() |
BlockEntity? |
block entity at this position (main thread only) |
world.blockEntitiesIn(box) |
List<BlockEntity> |
block entities whose block centre is inside the box, immutable list (main thread only) (throws ScriptException when the box spans more than 32×32 chunks) |
blockEntity.type() |
String |
block entity type registry id, e.g. minecraft:vault |
blockEntity.x() |
int |
block x coordinate |
blockEntity.y() |
int |
block y coordinate |
blockEntity.z() |
int |
block z coordinate |
blockEntity.position() |
Vec |
block coordinates |
blockEntity.displayItem() |
Item? |
vault display item or brushable block item, null otherwise |
blockEntity.nbt() |
String |
client-side nbt as a string, empty without a world |
A block entity carries only what the server already sent: a vault's display item is there, a closed chest's contents are not.
displayItem() returns an ordinary item.
Fluids
| Method | Type | Description |
|---|---|---|
block.fluid() |
Fluid? |
fluid state at this position, waterlogging included, null when dry |
fluid.id() |
String |
fluid registry id, e.g. minecraft:water |
fluid.level() |
int |
fluid level 1..8, 8 for a source block |
fluid.still() |
boolean |
source block rather than flowing |
fluid.height() |
float |
rendered fluid height 0..1 |
Light
| Method | Type | Description |
|---|---|---|
world.lightLevel(x, y, z) |
int |
rendered light level 0..15, ambient darkness applied |
world.blockLight(x, y, z) |
int |
block-source light 0..15 |
world.skyLight(x, y, z) |
int |
sky-source light 0..15, no time-of-day adjustment |
Entities in the world
| Method | Type | Description |
|---|---|---|
world.entityCount() |
int |
number of loaded entities |
world.entities() |
List<Entity> |
every loaded entity, own player included, fresh mutable list |
world.entities(filter) |
List<Entity> |
loaded entities passing the filter, null filter keeps all |
world.entitiesIn(box) |
List<Entity> |
entities whose hitbox intersects the box |
world.entitiesIn(box, filter) |
List<Entity> |
same, filtered, null filter keeps all |
world.entitiesNear(origin, radiusBlocks, filter) |
List<Entity> |
entities within a spherical radius in blocks (throws ScriptException when radiusBlocks <= 0) |
world.players() |
List<PlayerEntity> |
loaded players, immutable list |
world.players(filter) |
List<PlayerEntity> |
loaded players passing the filter, immutable list |
world.entityByName(name) |
Entity? |
first entity whose display name matches, case-insensitive |
world.entityById(entityId) |
Entity? |
entity with that network id |
world.entityByUuid(uuid) |
Entity? |
linear scan for that uuid (throws ScriptException when the string is not a uuid) |
world.nearestEntity(origin, radiusBlocks, filter) |
Entity? |
closest matching entity within the radius (throws ScriptException when radiusBlocks <= 0) |
Entity members and the ready-made filters are on Entities and filters.
Collisions
| Method | Type | Description |
|---|---|---|
world.collisionsIn(box) |
List<Box> |
boxes of hard-colliding entities in the box, block collisions excluded |
world.blockCollisionsIn(box) |
List<Box> |
block collision shape parts intersecting the box, entities excluded (API 3) |
world.isFree(box) |
boolean |
no colliding entity intersects the box, block collisions not checked |
world.canPlace(itemId, x, y, z) |
boolean |
cell replaceable and no entity in the way, support not checked (API 6) (throws ScriptException when the item is not a block) |
world.isBlockSpaceFree(box) |
boolean |
no block collision intersects the box, entities not checked (API 3) |
A partial block reports one box per shape part: a fence gives the post and every connected arm, a slab one half-height box.
These are the same shapes raycast.blocks(...) clips against; block.box() stays the plain 1×1×1 cube.
Removing and hiding
| Method | Type | Description |
|---|---|---|
world.removeEntity(entity) |
boolean |
client-side removal by wrapper, false when null (main thread only) |
world.removeEntity(entityId) |
boolean |
client-side removal by network id, false for own player (main thread only) |
world.unhideEntities() |
void |
clears the hidden flag on every loaded entity |
world.hideEntity(entity) |
void |
stops drawing the entity: model, armour, nametag, shadow, glow (API 10) (main thread only) (throws ScriptStateException when entity is not a world entity) |
world.showEntity(entity) |
void |
undoes this script's own hideEntity (API 10) (main thread only) (throws ScriptStateException when entity is not a world entity) |
world.entityHidden(entity) |
boolean |
this script is hiding the entity with hideEntity (API 10) (main thread only) (throws ScriptStateException when entity is not a world entity) |
Removal is local: the server keeps the entity and resends it on a chunk reload, and each removal fires EntityRemoveEvent.
hideEntity belongs to the script that called it: switching the script off or unloading it shows the entity again, unhideEntities() does not touch it, an entity two scripts hide stays hidden until both show it, and one that unloads and comes back is visible again.
Entity models
| Method | Type | Description |
|---|---|---|
world.captureModel(entity) |
EntityModel? |
model pose drawn this frame, null for non-living entities (API 10) (main thread only) (throws ScriptStateException when entity is not a world entity) |
model.entity() |
Entity |
entity the model was captured from (API 10) |
model.cuboids() |
List<ModelCuboid> |
every visible cuboid of the model, immutable list (API 10) |
cuboid.part() |
String |
model part path, e.g. head or right_arm/right_sleeve, empty for the root (API 10) |
cuboid.index() |
int |
cuboid index inside its part, from 0 (API 10) |
cuboid.corners() |
List<Vec> |
8 corners in world blocks, 0..3 one face, 4..7 the opposite one (API 10) |
cuboid.center() |
Vec |
cuboid centre in world blocks (API 10) |
The pose is the one Minecraft draws this frame, animation, sneaking, sleeping and baby models included; armour, held items, capes and other layers are not in it.
Corners i and i + 4 share an edge, and 0-1-2-3 and 4-5-6-7 each run around one face; a hidden entity can still be captured.
Sounds and particles
| Method | Type | Description |
|---|---|---|
world.spawnParticle(particleId, position, velocity) |
void |
client-only particle, null velocity means zero (throws ScriptException on an unknown particle) |
world.playSound(soundId, position, volume, pitch) |
void |
client-only sound at a position, category PLAYERS (throws ScriptException on an unknown sound) |
world.playSound(soundId, volume, pitch) |
void |
client-only sound at the listener, category PLAYERS (throws ScriptException on an unknown sound) |
Last updated