# world

you interact with the world using `Katton.world()`

---

## properties

```csharp
Katton.world().players //a list of `player` values in the game
Katton.world().entities //every nonplayer entity currently in the world, as a list of entity values. use `world.players` instead if you want the players
```

## methods

```csharp
Katton.world().spawnEntity(type, location)
Katton.world().setBlock(location, material)
Katton.world().getBlock(location)
Katton.world().fillBlocks(from, to, material)
Katton.world().playSound(sound, location, volume = 1, pitch = 1)
Katton.world().spawnParticle(particle, location, ...)
```

---

### `spawnEntity`

spawns a new entity into the world

```csharp
Katton.world().spawnEntity(type, location)
```

| parameter | default | description |
| --- | --- | --- |
| `type` | *required* | case insensitive entity type name string |
| `location` | *required* | location object where the entity spawns |

#### example

```csharp
Katton.world().spawnEntity("zombie", player.location)
function spawnWave(count, location) {
    for (i in 1..count) {
        Katton.world().spawnEntity("zombie", location)
    }
}
```

---

### `setBlock`

sets a block at a target location to a material

```csharp
Katton.world().setBlock(location, material)
```

| parameter | default | description |
| --- | --- | --- |
| `location` | *required* | target location object |
| `material` | *required* | case insensitive vanilla block material name |

> [!note]
> nonblock materials like `"diamond_sword"` cause a runtime error

#### example

```csharp
Katton.world().setBlock(player.location, "glass")
```

---

### `getBlock`

gets the block material name at a target location

```csharp
Katton.world().getBlock(location)
```

| parameter | default | description |
| --- | --- | --- |
| `location` | *required* | target location object |

#### example

```csharp
val currentBlock = Katton.world().getBlock(player.location) // "glass"
```

---

### `fillBlocks`

fills a 3D rectangular region between two corner locations with a block material

```csharp
Katton.world().fillBlocks(from, to, material)
```

| parameter | default | description |
| --- | --- | --- |
| `from` | *required* | starting corner location object or coordinates |
| `to` | *required* | ending corner location object or coordinates |
| `material` | *required* | block material name string |

#### example

```csharp
Katton.world().fillBlocks({ "x": 0, "y": 60, "z": 0 }, { "x": 10, "y": 65, "z": 10 }, "stone")
function fillLargeArea(from, to, material) {
    // split into smaller boxes yourself and call fillBlocks per chunk
}
```

---

### `playSound`

plays a sound effect at a world location visible/audible to everyone around it

```csharp
Katton.world().playSound(sound, location, volume = 1, pitch = 1)
```

| parameter | default | description |
| --- | --- | --- |
| `sound` | *required* | sound name string |
| `location` | *required* | fixed location object where the sound plays |
| `volume` | default=1 | sound volume multiplier |
| `pitch` | default=1 | sound pitch multiplier |

> [!note]
> plays at a fixed location and everyone is able to hear it, unlike `player.playSound` which plays specifically to one player

#### example

```csharp
Katton.world().playSound("entity_wither_spawn", player.location)
Katton.world().playSound("entity_wither_spawn", player.location, volume = 2.0, pitch = 0.8)
```

---

### `spawnParticle`

spawns particles into the world visible to all players

```csharp
Katton.world().spawnParticle(particle, location, ...)
```

| parameter | default | description |
| --- | --- | --- |
| `particle` | *required* | case insensitive vanilla particle name string |
| `location` | *required* | target location object |
| `count` | default=1 | how many particles to spawn (ignored if `direction` is used) |
| `offset` | default={"x": | 0, "y": 0, "z": 0} spread range across axes (capped at +/-16 blocks) |
| `speed` | default=0 | particle motion speed (0 to 10) |
| `direction` | default=null | single particle motion vector |
| `color` | default=null | hex string, map, or RGB list for dust/transition particles |
| `to_color` | default=null | end color for dust transition particles |
| `size` | default=1.0 | dust particle size (0.1 to 4.0) |
| `material` | default=null | block or item material name for block/item particles |

> [!note]
> visible to all players

#### example

```csharp
Katton.world().spawnParticle("flame", player.location)
Katton.world().spawnParticle("dust", player.location, count = 20, offset = {"x": 1, "y": 1, "z": 1}, color = "#ff55aa", size = 1.5)
Katton.world().spawnParticle("dust_color_transition", player.location, count = 10, color = "#ff0000", to_color = "#0000ff", size = 2)
Katton.world().spawnParticle("block", player.location, count = 30, material = "diamond_block")
Katton.world().spawnParticle("flame", player.location, direction = {"x": 0, "y": 1, "z": 0}, speed = 0.5)
```

---
