World effects and environment

These are members of the world object, next to the basics and the block calls of the world API. Faces are 0 to 5 or down, up, north, south, west, east.

Border, sound and particles#

world.border is a snapshot { center_x, center_z, size, target_size, lerp_ticks, damage_amount, damage_buffer, warning_distance, warning_time }. world:set_border(settings) takes any of those fields plus seconds for a moving size.

world:set_border({ size = 200, center_x = 0, center_z = 0, seconds = 30 })
world:sound("minecraft:block.bell.use", 0, 64, 0, 1, 1, "blocks")
world:particle({ type = "minecraft:flame", x = 0, y = 65, z = 0, count = 20, offset_x = 0.3, offset_y = 0.3,
                 offset_z = 0.3, speed = 0.01 })

data in a particle spec is read by the particle's own options in order: block state id; argb colour; argb and power; rgb and scale; two rgb and scale; target x y z, rgb and duration (trail); value; delay ticks; block count; target block x y z and arrival ticks (vibration).

Blocks#

Four helpers on worlds read block facts:

Chunks, weather and counts#

A hardcore world keeps its difficulty on hard, tells a logging-in client it is hardcore, and puts a respawning player in spectator. Setting hardcore to 1 also moves the difficulty to hard. It is saved with the world, and hardcore = false in worlds.toml [defaults] or a world's settings.toml is the starting value of a world that has none saved.

With loot_refill on, loot containers keep their table after the first opening and fill again later; loot_reloot_seconds is how long a player waits to loot a refilled container again. It is not vanilla, so it is off by default; see worlds.toml for the loot-refill* keys. A container keeps Paper.LootableData (lastFill, nextRefill, numRefills and lootedPlayers, in milliseconds of the real clock). Other block entity data a plugin can use through the NBT calls: a ringing bell keeps Basalt.BellShaking, Basalt.BellTicks, Basalt.BellResonating and Basalt.BellResonationTicks; a campfire takes Paper.StopCooking (four ints, 1 for a slot that does not cook); a sculk sensor takes Paper.ListenerRange; the trial spawner reads normal_config, ominous_config, target_cooldown_length and required_player_range; raids keep BukkitValues.

Players below the world floor minus 64 take 4 damage, creative players included. void_damage turns it off per world.

Planting trees#

world:place_tree(tree, x, y, z, apply?) plants a named tree feature as the world generator would, with no sapling needed. tree is oak, fancy_oak, swamp_oak, azalea, birch, super_birch, jungle_tree, jungle_bush, mega_jungle, spruce, pine, acacia, dark_oak, pale_oak, pale_oak_creaking, mega_spruce, mega_pine, mangrove, tall_mangrove or cherry. It returns { { x, y, z, before, after } }, or nil when the tree does not fit. With apply set to false nothing changes and the blocks it would set come back.

world:place_tree("oak", 10, 64, 10)

Structures, raids and points of interest#

for _, s in ipairs(world:structures(0, 0)) do
  log.info(s.structure .. " " .. s.bounds.minx)
end

Spawning rules#

world.spawn_rules is { limits, ticks_per, allow_monsters, allow_animals } and holds only what a plugin changed. world:set_spawn_rules{ ... } takes the same fields; a negative value restores vanilla. Categories are monster, creature, ambient, axolotls, underground_water_creature, water_creature, water_ambient and misc.

world:set_spawn_rules{ limits = { monster = 20 }, allow_animals = false }

Changing these departs from vanilla spawning for as long as the values are set.