---
title: "World handle"
---

> Documentation Index
> Fetch the complete documentation index at: https://aesthetic-docs.pages.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# World handle

Live handle over the loaded world. Every colon-call re-reads the game. `nil` while no
world is loaded.

```lua
if not world then return end
```

## Entities and players

| Method | Returns |
|--------|---------|
| `world:players()` | All players as [entity handles](/entity), including yourself |
| `world:player(name)` | One player by name (case-insensitive), or `nil` |
| `world:entities(type?)` | All entities; optional exact type id (`"minecraft:item"`) |
| `world:entity(id)` | Entity by numeric id, or `nil` |

```lua
for _, p in ipairs(world:players()) do
if not p:is_self() and p:distance() < 8 then
    print(p:name() .. " is close!")
end
end
```

## Blocks

| Method | Returns |
|--------|---------|
| `world:block(pos)` | Block id at a [vec3](/vec3), e.g. `"minecraft:air"` |
| `world:block_state(pos)` | Full [block state handle](/block-state) |
| `world:top_y(x, z, heightmap?)` | Surface y of a column. Heightmaps: `"motion_blocking"` (default), `"motion_blocking_no_leaves"`, `"world_surface"`, `"ocean_floor"` |

## Raycasts

| Method | What it does |
|--------|--------------|
| `world:raycast(from, to, fluids?)` | First [block hit](/raycast) between two [vec3](/vec3) points, or `nil`. Pass `true` to also hit fluids |
| `world:raycast_entity(from, to)` | Closest [entity hit](/raycast), or `nil`. Skips spectators and yourself |

Both need a local player — they return `nil` without one. For the crosshair ray use
`player:raycast(max_distance?)` (blocks and entities at once).

## Environment

| Method | Returns |
|--------|---------|
| `world:time()` | Time of day in ticks |
| `world:dimension()` | Dimension id, e.g. `"minecraft:overworld"` |
| `world:raining()`, `world:thundering()` | Weather flags |
| `world:rain_gradient()`, `world:thunder_gradient()` | Weather strength `[0, 1]` |
| `world:biome(pos)` | Biome id, e.g. `"minecraft:plains"` |
| `world:light(pos)` | Two returns: block light and sky light, both `0–15` |

```lua
local pos = player:position()
print(world:biome(pos), world:light(pos))
if world:raining() then
print("rain strength", world:rain_gradient())
end
```

Source: https://aesthetic-docs.pages.dev/world/index.md