World API

import { World } from 'yeow-api';

Static Methods

Default is async (Promise), synchronous version adds Sync suffix.

Method	Return	Description
World.get(name)	Promise<World | null>	Get world by name
World.getAll()	Promise<World[]>	All loaded worlds

Properties

Property	Type	Read/Write	Description
name	string	Read-only	World name
time	number	Read/Write	Game time 0-24000 tick
storm	boolean	Read/Write	Raining
thundering	boolean	Read/Write	Thundering
difficulty	string	Read/Write	PEACEFUL / EASY / NORMAL / HARD
spawnLocation	Location | null	Read/Write	World spawn point

Difficulty values (difficulty) see Value Domain Appendix · Directly Maintained Enumeration List; Game rule keys see Value Domain Appendix · Version Change Domain.

Methods

Default is async (Promise), synchronous version adds Sync suffix.

Game Rules

world.getGameRule(rule)             // Promise<string | null>
world.setGameRule(rule, value)      // Promise

Rule names are R3 camelCase format (value domain appendix, e.g., keepInventory, doDaylightCycle), case-insensitive (input lenient; output strict camelCase).

World Info & WorldBorder

// World info
world.seed                        // number — World seed
world.environment                 // string — NORMAL / NETHER / THE_END
world.worldType                   // string | null
world.gameRules                   // string[] — All game rule names
await world.getSeed(); await world.getEnvironment(); ...

// WorldBorder (server world boundary)
const border = await world.getBorder();  // { centerX, centerZ, size, damageAmount, damageBuffer, warningDistance, warningTime }
await world.setBorderCenter(x, z);
await world.setBorderSize(size);
await world.setBorderDamage(amount?, buffer?);
await world.setBorderWarning(distance?, time?);
await world.setBorderMoving(from, to, seconds);   // Smooth movement

Player-side client boundary player.setBorder has been removed — only server world boundary retained (world.setBorder*, affects all players).

Blocks

world.getBlock(x, y, z)             // Promise<Block | null> (includes type, state and location)
world.setBlock(x, y, z, blockType)  // Promise (blockType is string, compatible, no state)
world.setBlock(x, y, z, block)      // Promise (block is Block descriptor, can have state; ignores its location)

Methods on Block object:

block.isSolid(): Promise<boolean>        // Material-level static judgment (delegated to Material)
block.isAir(): Promise<boolean>          // Whether it's air
block.breakNaturally(tool?): Promise<boolean>   // Natural break (includes drops; requires location)

Block unifiedly represents blocks: type/state/location are all snapshots at acquisition time (need latest state, re-call world.getBlock); getBlock returned Block has location (yaw/pitch always 0), Block.of() constructed ones don't. isSolid etc. are material-level static judgments, don't query world. See Block API for details.

tool is optional ItemStack (data snapshot, simulates tool properties, doesn't consume real item durability), used to simulate specific tool mining effects (e.g., { type: 'minecraft:diamond_pickaxe', meta: { enchantments: { fortune: 3 } } }). See ItemStack for details.

Biome & Lighting

world.getBiome(x, y, z)             // Promise<string> e.g., "minecraft:plains"
world.getHighestBlockY(x, z)        // Promise<number>
world.getBlockLightLevel(x, y, z)   // Promise<number> (0-15)
world.getSkyLightLevel(x, y, z)     // Promise<number> (0-15)

Chunks

world.getChunkAt(x, z)              // Promise<Chunk> (gets chunk, may trigger loading; includes x/z/world)
world.isChunkLoaded(x, z)           // Promise<boolean>
world.isChunkGenerated(x, z)        // Promise<boolean> (chunk generated, not loaded/not generated returns false)
world.loadChunk(x, z)               // Promise<boolean> (force load)
world.unloadChunk(x, z)             // Promise<boolean>

Chunk object block data snapshot (batch read, advanced scenarios) see Chunk API.

Entity Queries

world.getEntities()                       // Promise<string[]>
world.getPlayers()                        // Promise<string[]>
world.getNearbyEntities(x, y, z, radius)  // Promise<string[]>

World Operations

world.dropItem(x, y, z, item, amount?)               // Promise — item is ItemStack or material name string (string + amount compatible with legacy)
world.strikeLightning(x, y, z)                       // Promise
world.strikeLightningEffect(x, y, z)                 // Promise (effect only)
world.createExplosion(x, y, z, power?, fire?, breaks?)   // Promise

Entity Spawning

world.spawnEntity(type, x, y, z)       // Promise<string | null> — Returns entity UUID

type is minecraft registration key (e.g., minecraft:zombie, minecraft:creeper — consistent with entity.type); compatible with legacy Bukkit enumeration names (e.g., ZOMBIE).

Sound & Particle

world.playSound(sound, x, y, z, volume?, pitch?)         // Promise

World-level sound. sound is Paper series Sound enumeration name (e.g., block.note_block.pling).

Particle effect API see Particle documentation.

Read-only snapshot (snap())

Fetches the world's common state in a single round trip and returns a frozen WorldSnapshot. Use it instead of N × await getXxx() when reading several fields.

const s = await world.snap();
log.info(`time=${s.time}/${s.fullTime} rain=${s.isRaining()} border=${s.border.size}`);
const keepInv = s.gameRule('keepInventory');

Field	Type	Description
name	string	World name
time / fullTime	number	Day time / absolute time
storm / thundering	boolean	Storm / thundering
difficulty	string	peaceful | easy | normal | hard
spawnLocation	Location	Spawn point (locally built, frozen)
seed	number	Seed
environment	string	Dimension (NORMAL / NETHER / THE_END)
worldType	string | null	World type
gameRules	Record<string, string>	camelCase rule name → string value (read in one go)
border	WorldBorderInfo	Border (same shape as getBorder())

Helpers (local, zero round trips):

• gameRule(name) — rule value (lenient name: keepInventory / KEEP_INVENTORY); null if unknown
• isRaining() — storm || thundering
• toObject() / toJSON()

No player/entity lists: those vary by platform and runtime and their cost is not constant (they require iterating chunks). A snapshot is a copy at one point in time.

Example

const w = await World.get('world');
if (w) {
    await w.setTime(6000);                    // Noon
    await w.setStorm(true);
    await w.setBlock(0, 65, 0, 'minecraft:diamond_block');
    await w.createExplosion(10, 64, 10, 5);
}