world

Asks about the world: who stands where, whether a place is guarded, what time it is, the moons.

Source: src/Moongate.Server.Ultima/Modules/WorldModule.cs

Functions

broadcast

world.broadcast(text) -> boolean

Sends a system message (cut to 128 characters) to every player in the world; false for a blank text.

Parameter	Type	Default
text	string

Returns boolean.

can_fit

world.can_fit(map, x, y, z, except?, mobiles?) -> boolean

Whether a mobile fits at the place x, y, z of the map: no other mobile than the one named (0 for none) stands there at that height (not asked when mobiles is false), and no impassable or surface item on the ground fills the space above z. Statics are not asked (see world.standing_z).

Whether a mobile fits at a place, as Teleport asks: no other mobile stands there and no impassable item, a shut door among them, lies on the ground. The fifth argument names a mobile that does not count (the caster); a false sixth leaves mobiles out of the question:

local z = world.standing_z(map, x, y, user_z)

if not z or not world.can_fit(map, x, y, z, caster) then
    return 501942 -- That location is blocked.
end

Parameter	Type	Default
map	MapType | string
x	integer
y	integer
z	integer
except (optional)	integer	0
mobiles (optional)	boolean	true

Returns boolean.

carries

world.carries(mobile, key, value) -> boolean

Whether the mobile wears or carries, in its containers at any depth, an item whose prop key is value.

Whether the mobile carries the key of a door:

world.carries(user, "key.value", 1234)

Parameter	Type	Default
mobile	integer
key	string
value	any

Returns boolean.

clear_global_light

world.clear_global_light() -> boolean

Makes the light follow the time of day again, whatever world.set_global_light or .globallight set. It does not check who calls it: a script for the staff checks world.is_staff first. Call it on the game loop, as a script does.

Makes the light follow the time of day again:

world.clear_global_light()

Returns boolean.

clear_season

world.clear_season(player) -> boolean

Gives the map where the player stands back its own season: the one of maps.toml, rotated when season_rotation is on, instead of the one a script or .season set. False for an NPC or a player not in the world. It does not check who calls it: a script for the staff checks world.is_staff first.

Gives that map back the season of maps.toml:

world.clear_season(user)

Parameter	Type	Default
player	integer

Returns boolean.

distance

world.distance(first, second) -> integer?

The tiles between two mobiles or items on the ground, the larger of the two coordinate differences, as the view range counts them; nil when either is unknown, is not in the world (an item in a container) or the two are on different maps.

The tiles between an NPC and a player, as the view range counts them; nil when one of them is gone, in a container or on another map:

local tiles = world.distance(npc_serial, user)
if tiles and tiles <= 2 then
    npc.say(npc_serial, "Come closer, friend.")
end

Parameter	Type	Default
first	integer
second	integer

Returns integer?.

get_prop

world.get_prop(key) -> any?

A value the whole shard keeps across restarts: a string, a number or a bool; nil when there is none.

Parameter	Type	Default
key	string

Returns any?.

global_light

world.global_light() -> integer?

The level every player is given instead of the clock's, set by world.set_global_light or .globallight, from 0 to 31; nil when the light follows the time of day.

The level every player was given with .globallight or world.set_global_light, nil when the light follows the time of day:

if world.global_light() == nil then
    mobile.message(user, "The light follows the clock.")
end

Returns integer?.

in_region

world.in_region(map, x, y, z, name) -> boolean

Whether the place x, y, z of the map is part of the region called name (case apart): the region that applies there is that one or has it among its parents, as ModernUO's IsPartOf. false outside every region, for an empty name or for a z outside -128 to 127.

Parameter	Type	Default
map	MapType | string
x	integer
y	integer
z	integer
name	string

Returns boolean.

is_administrator

world.is_administrator(player) -> boolean

Whether the player is an administrator; false for an NPC or a player not in the world, and for a game master.

Parameter	Type	Default
player	integer

Returns boolean.

is_guarded

world.is_guarded(map, x, y, z) -> boolean

Whether the region of the place x, y, z of the map is guarded; false outside every region or for a z outside -128 to 127.

Whether guards protect the region of the place, such as a town:

world.is_guarded(MapType.Trammel, 1496, 1628, 10)

Parameter	Type	Default
map	MapType | string
x	integer
y	integer
z	integer

Returns boolean.

is_occupied

world.is_occupied(map, x, y) -> boolean

Whether a player or an NPC stands on the tile x, y of the map, at any height, such as a door's doorway.

Parameter	Type	Default
map	MapType | string
x	integer
y	integer

Returns boolean.

is_staff

world.is_staff(player) -> boolean

Whether the player is a game master or an administrator; false for an NPC or a player not in the world.

Parameter	Type	Default
player	integer

Returns boolean.

is_water

world.is_water(map, x, y) -> boolean

Whether the cell x, y of the map is water a creature could swim on: water land or a wet static with room above, not blood, a trough or the water under a dock. False outside the map.

Whether a creature could swim on a cell, as a fishing pole asks of the place a player picked:

world.is_water(MapType.Trammel, 1496, 1640)

Parameter	Type	Default
map	MapType | string
x	integer
y	integer

Returns boolean.

items_in_range

world.items_in_range(map, x, y, range) -> table

The serials of the items on the ground within range tiles (0 to 32) of x, y on the map, at any height, as a list.

Parameter	Type	Default
map	MapType | string
x	integer
y	integer
range	integer

Returns table.

light_here

world.light_here(player) -> integer?

The light level where the player stands, from 0 (brightest) to 31 (darkest): the global light when one is set, else the dungeon or jail level of its region, else the time of day's. Nil for an NPC, a player not in the world or when the light is not running.

The light level where a player stands, from 0 (brightest) to 31 (darkest):

local level = world.light_here(user)

Parameter	Type	Default
player	integer

Returns integer?.

line_of_sight

world.line_of_sight(map, x1, y1, z1, x2, y2, z2) -> boolean

Whether the place x2, y2, z2 is in sight of x1, y1, z1 on the map, as for a spell or an arrow; false beyond the range a line of sight is checked at, on a map that is not loaded or for a z outside -128 to 127.

Parameter	Type	Default
map	MapType | string
x1	integer
y1	integer
z1	integer
x2	integer
y2	integer
z2	integer

Returns boolean.

mobiles_in_range

world.mobiles_in_range(map, x, y, range) -> table

The serials of the players and NPCs within range tiles (0 to 32) of x, y on the map, at any height, as a list.

Parameter	Type	Default
map	MapType | string
x	integer
y	integer
range	integer

Returns table.

moon

world.moon(moon, x) -> MoonPhaseType

The phase of the moon (MapType.Trammel or MapType.Felucca) seen from the column x, a MoonPhaseType; Felucca turns every 10 game minutes, Trammel every 30.

world.moon(MapType.Trammel, x) == MoonPhaseType.FullMoon

Parameter	Type	Default
moon	MapType | string
x	integer

Returns MoonPhaseType.

now

world.now() -> integer

The real time as whole seconds since 1970 (UTC): keep world.now() + 3600 in a prop to do something an hour from now, also after a restart.

Returns integer.

play_sound

world.play_sound(map, x, y, z, sound) -> boolean

Plays a sound id (0 to 65535) at x, y, z of the map, for the players within 15 cells of the place; false outside the map, for a z outside -128 to 127 or a sound out of range.

A splash on the water, heard by the players around the place:

world.play_sound(MapType.Trammel, 1496, 1640, -5, 0x364)

Parameter	Type	Default
map	MapType | string
x	integer
y	integer
z	integer
sound	integer

Returns boolean.

players

world.players() -> table

The serials of the players' characters in the world, as a list.

Returns table.

region

world.region(map, x, y, z) -> string?

The name of the region of the place x, y, z of the map; nil outside every region or for a z outside -128 to 127.

Parameter	Type	Default
map	MapType | string
x	integer
y	integer
z	integer

Returns string?.

rune_place

world.rune_place(map, x, y, z) -> string?

The place a recall rune marked at x, y, z of the map is called after: the rune name of its region, else the name of the region, else the name of the map. nil for a z outside -128 to 127.

The name a recall rune takes when it is marked at a place: the rune name of its region, else its name, else the map:

item.set_name(rune, "a recall rune for " .. world.rune_place(here.map, here.x, here.y, here.z))

Parameter	Type	Default
map	MapType | string
x	integer
y	integer
z	integer

Returns string?.

season

world.season(map) -> SeasonType?

The season of the map, a SeasonType; nil when the seasons are not running.

Parameter	Type	Default
map	MapType | string

Returns SeasonType?.

season_here

world.season_here(player) -> SeasonType?

The season the client of the player shows where it stands (its region's, else its map's), a SeasonType; nil for an NPC, a player not in the world or when the seasons are not running.

The season the client of a player shows where it stands, the region’s else the map’s:

if world.season_here(user) == SeasonType.Winter then
    mobile.message(user, "Brr.")
end

Parameter	Type	Default
player	integer

Returns SeasonType?.

set_global_light

world.set_global_light(level) -> boolean

Gives every player in the world the same light, from 0 (brightest) to 31 (darkest), at once, until world.clear_global_light or a restart. False for a level out of 0 to 31. It does not check who calls it: a script for the staff checks world.is_staff first. Call it on the game loop, as a script does.

Gives every player the same light, as .globallight does:

world.set_global_light(26)

Parameter	Type	Default
level	integer

Returns boolean.

set_prop

world.set_prop(key, value?) -> boolean

Keeps a string, a number or a bool for the whole shard across restarts, saved with the world; nil removes it. False for a table, a function or a blank key.

world.set_prop("event.day", 12)

Parameter	Type	Default
key	string
value (optional)	any	nil

Returns boolean.

set_season

world.set_season(player, season) -> boolean

Sets the season of the map where the player stands, a SeasonType, until the restart, and sends it at once to the players of the map except those in a region with a season of its own. False for an NPC or a player not in the world; a season that does not exist is a script error. It does not check who calls it: a script for the staff checks world.is_staff first. Call it on the game loop, as a script does.

Sets the season of the map where the player stands until the restart, as .season does:

world.set_season(user, SeasonType.Winter)

Parameter	Type	Default
player	integer
season	SeasonType | string

Returns boolean.

set_weather

world.set_weather(player, kind) -> boolean

Forces a WeatherKindType (None, Rain, Snow or Storm) on the profile where the player stands, which every region using that profile gets, until the next game hour. False for an NPC or a player not in the world; a kind that does not exist is a script error. It does not check who calls it: a script for the staff checks world.is_staff first.

Forces a kind of weather on that profile until the next game hour, as .weather does:

world.set_weather(user, WeatherKindType.Storm)

Parameter	Type	Default
player	integer
kind	WeatherKindType | string

Returns boolean.

spot_beside

world.spot_beside(map, x, y, z) -> table?

A tile one step from x, y, z of the map that a walking mobile standing there could step onto, so not one behind a wall, with nobody on it, as { map, x, y, z }: where to appear beside someone instead of on it. The first found going round from a random direction; nil when none is free, the spot is outside the map or the map is not loaded.

Parameter	Type	Default
map	MapType | string
x	integer
y	integer
z	integer

Returns table?.

standing_z

world.standing_z(map, x, y, z) -> integer?

The height a mobile can stand at on the cell x, y of the map, at or below z, such as before teleporting someone there; nil when nothing there can be stood on.

Parameter	Type	Default
map	MapType | string
x	integer
y	integer
z	integer

Returns integer?.

statics

world.statics(map, x, y, range) -> table

The statics of the map files within range tiles (0 to 18) of x, y on the map, at any height, as an array of { graphic, x, y, z }: what the map itself holds, such as the anvils, forges and trees of a place; ground items are world.items_in_range. Empty outside the map, for a range outside 0 to 18 or a map that is not loaded.

Whether a player stands within 2 tiles of an anvil that is part of the map:

local function near_an_anvil(user)
    local here = mobile.location(user)

    if not here then
        return false
    end

    for _, static in ipairs(world.statics(here.map, here.x, here.y, 2)) do
        if static.graphic == 0x0FAF or static.graphic == 0x0FB0 then
            return true
        end
    end

    return false
end

Parameter	Type	Default
map	MapType | string
x	integer
y	integer
range	integer

Returns table.

time

world.time(map, x) -> table

The time of day on the map at the column x, as a table { hours, minutes }; see the setting ultima.world.seconds_per_uo_minute.

world.time(MapType.Trammel, 1600).hours

Parameter	Type	Default
map	MapType | string
x	integer

Returns table.

travel_allowed

world.travel_allowed(map, x, y, z, rule) -> boolean

Whether the travel rule ('recall_in', 'recall_out', 'gate_in', 'gate_out', 'mark', 'teleport_in' or 'teleport_out') lets a mobile through the place x, y, z of the map: false when any region covering the place switches it off, true outside every region. False also for an unknown rule or a z outside -128 to 127.

Whether the regions of a place let a recall in: false when any region covering it says no:

if not world.travel_allowed(map, x, y, z, "recall_in") then
    mobile.message_cliloc(user, 1019004) -- You are not allowed to travel there.
end

Parameter	Type	Default
map	MapType | string
x	integer
y	integer
z	integer
rule	string

Returns boolean.

weather

world.weather(player) -> table?

The weather where the player stands, as a table { kind (a WeatherKindType), density, temperature }; nil for an NPC or a player not in the world.

Parameter	Type	Default
player	integer

Returns table?.

weather_profile

world.weather_profile(player) -> string?

The name of the weather profile where the player stands (its region's, else its map's), as data/weather.toml names it; nil for an NPC or a player not in the world.

The name of the weather profile where the player stands:

local profile = world.weather_profile(user)

Parameter	Type	Default
player	integer

Returns string?.