LuaWML/Tiles

This section has been moved. The information here remains accurate as of 1.14.0, but for 1.15.0 and later, LuaAPI is now the definitive source. See LuaAPI/UpdatingFrom14 for a summary of what's changed.

This page describes the LuaWML functions for handling terrains and tiles. The items library can be loaded by

items = wesnoth.require "lua/wml/items.lua"

wesnoth.get_map_size

• wesnoth.get_map_size()

Returns the width, the height, and the border size of the map.

local w,h,b = wesnoth.get_map_size()

wesnoth.get_terrain

• wesnoth.get_terrain(x, y)

Returns the terrain code for the given location.

local is_grassland = wesnoth.get_terrain(12, 15) == "Gg"

wesnoth.set_terrain

• wesnoth.set_terrain(x, y, terrain_code, [layer], [replace_if_failed])

Modifies the terrain at the given location.

function create_village(x, y)
    wesnoth.set_terrain(x, y, "Gg^Vh")
end

An optional 4th parameter can be passed (layer): overlay, base or both, default both: Change the specified layer only.

An optional 5th boolean parameter (replace_if_failed) can be passed, see the documentation of the [terrain] tag. To pass the 5th parameter but not the 4th, pass nil for the 4th.

wesnoth.get_terrain_info

• wesnoth.get_terrain_info(terrain_code)

Returns the terrain details for the given terrain code.

local is_keep = wesnoth.get_terrain_info(wesnoth.get_terrain(12, 15)).keep

Terrain info is a plain table with the following fields:

• id: string
• name, description, editor_name: translatable strings
• castle, keep, village: booleans
• healing: integer

wesnoth.get_selected_tile

• wesnoth.get_selected_tile()

Returns the two coordinates of the currently selected tile. This is mostly useful for defining command-mode helpers.

function chg_unit(attr, val)
   local x, y = wesnoth.get_selected_tile()
   if not x then wesnoth.message("Error", "No unit selected."); return end
   helper.modify_unit({ x = x, y = y }, { [attr] = val })
end
-- Function chg_unit can be used in command mode to modify unit attributes on the fly:
--   :lua chg_unit("status.poisoned", true)

wesnoth.get_locations

• wesnoth.get_locations(filter)
• (Version 1.13.12 and later only) wesnoth.get_locations(filter [, reference_unit])

Returns a table containing all the locations matching the given filter. Locations are stored as pairs: tables of two elements. See StandardLocationFilter for details about location filters. If a unit is passed, it can be referenced from the filter via the $teleport_unit variable, as well as in WFL formulas used in the filter.

-- replace all grass terrains by roads
for i,loc in ipairs(wesnoth.get_locations { terrain = "Gg" }) do
    wesnoth.set_terrain(loc[1], loc[2], "Rr")
end

wesnoth.get_villages

• wesnoth.get_villages([filter])

This function, when called without arguments, returns a table containing all the villages present on the map (as tables of two elements). If it's called with a WML table as argument, a table containing only the villages matching the supplied StandardLocationFilter is returned.

-- How many villages do we have on our map?
v = #wesnoth.get_villages()

wesnoth.match_location

• wesnoth.match_location(x, y, filter)
• (Version 1.13.12 and later only) wesnoth.match_location(x, y, filter [, reference_unit])

Returns true if the given location passes the filter. If a unit is passed, it can be referenced from the filter via the $teleport_unit variable, as well as in WFL formulas used in the filter.

bool b = wesnoth.match_location(x, y, { terrain = "Ww", { "filter_adjacent_location", terrain = "Ds,*^Bw*" } })

wesnoth.add_tile_overlay

• wesnoth.add_tile_overlay(x, y, item_wml)

Places a tile overlay (either an image or a halo) at a given location. The overlay is described by a table supporting the same fields as [item]. Note that the overlay is not kept over save/load cycles.

wesnoth.add_tile_overlay(17, 42, { image = "items/orcish-flag.png" })

wesnoth.remove_tile_overlay

• wesnoth.remove_tile_overlay(x, y, [filename])

Removes all the overlays at the given location. If a filename is passed as a third argument, only this overlay (either image or halo) is removed.

wesnoth.remove_tile_overlay(17, 42, "items/orcish-flag.png")

wesnoth.add_fog

• wesnoth.add_fog([sides], locations, [permanent])

(Version 1.13.5 and later only) Fogs over the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. The permanent argument defaults to false, causing temporary fog overrides to be cleared; if true, it affects the team's permanent fog as well.

wesnoth.remove_fog

• wesnoth.remove_fog([sides], locations, [permanent])

(Version 1.13.5 and later only) Unfogs the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. The permanent argument defaults to false, creating temporary fog overrides that disappear at the end of the turn; if true, it affects the team's permanent fog as well.

wesnoth.remove_fog(1, { {5, 5}, {5, 6} }) --removes fog on 5,5 and 5,6 for side 1
wesnoth.remove_fog(wesnoth.sides[1].side, { {5, 5} }) -- removes fog for first side on 5,5
wesnoth.remove_fog(1, wesnoth.get_locations{ x = 5, y = 5 }) --removes fog on 5,5

wesnoth.add_sound_source

• wesnoth.add_sound_source(cfg)

(Version 1.13.5 and later only) Adds a sound source. Input parameters are the same as for the [add_sound_source] tag. If a sound source with the same ID already exists, it is replaced.

wesnoth.remove_sound_source

• wesnoth.remove_sound_source(id)

(Version 1.13.5 and later only) Removes a sound source.

wesnoth.get_sound_source

• wesnoth.get_sound_source(id)

(Version 1.13.5 and later only) Retrieves the parameters of an existing sound source. The result of this function is suitable for feeding back to add_sound_source. The table returned by this function is a copy of the sound source's parameters, so if you change any of them, you must call add_sound_source to update the source.

wesnoth.map.get_direction

(Version 1.13.8 and later only)

• wesnoth.map.get_direction(from, dir, [count])

Calculates the hex reached by travelling in the specified direction, which should be a string such as "ne" or "s". The optional third parameter count is number of steps to travel to specified direction. Negative count is supported to travel opposite direction.

wesnoth.map.get_relative_dir

(Version 1.13.8 and later only)

• wesnoth.map.get_relative_dir(from, to)

Calculates the direction from one hex to another. Possible returns are strings "n", "ne", "nw", "s", "se", "sw" or "". The empty string means no direction which happens if from and to are same.

wesnoth.map.rotate_right_around_center

(Version 1.13.8 and later only)

• wesnoth.map.rotate_right_around_center(loc, center, angle)

Calculates the hex obtained from rotating the specified location around the specified center by the specified angle. The angle is an integer in the range 1..6.

wesnoth.map.get_adjacent_tiles

(Version 1.13.8 and later only)

• wesnoth.map.get_adjacent_tiles(loc)

Return all hexes adjacent to the specified hex, as six separate return values.

local a, b, c, d, e, f = wesnoth.map.get_adjacent_tiles({3, 3})
local a_x = a[1]
local a_y = a[2]

See also helper.adjacent_tiles if you want to iterate over the hexes.

wesnoth.map.tiles_adjacent

(Version 1.13.8 and later only)

• wesnoth.map.tiles_adjacent(loc1, loc2)

Tests if two hexes are adjacent.

wesnoth.map.distance_between

(Version 1.13.8 and later only)

• wesnoth.map.distance_between(loc1, loc2)

Calculates the distance between two hexes.

local my_distance = wesnoth.map.distance_between({10, 10}, {20, 20})

wesnoth.label

(Version 1.13.0 and later only)

• wesnoth.label(cfg)

Sets label of cfg.x, cfg.y to cfg.text. More supported keys https://wiki.wesnoth.org/InterfaceActionsWML#.5Blabel.5D

wesnoth.label {x=10,y=10,text="a",color={255,255,255,255}}

wesnoth.special_locations

(Version 1.13.12 and later only)

This is a table containing all the special locations set in the map data, including side starting locations, indexed by their key. (Side starting locations are indexed by the side number.)

-- Get the starting position of side 3
local enemy_start = wesnoth.special_locations[3]
-- Get a named location, "spire", from the map data
local destination = wesnoth.special_locations.spire

items.place_image

• items.place_image(x, y, filename)

Places an image at a given location and registers it as a WML [item] would do, so that it can be restored after save/load.

local items = wesnoth.require "lua/wml/items.lua"
items.place_image(17, 42, "items/orcish-flag.png")

items.place_halo

• items.place_halo(x, y, filename)

Behaves the same as #items.place_image but for halos.

items.remove

• items.remove(x, x, [filename])

Removes an overlay set by #items.place_image or #items.place_halo. If no filename is provided, all the overlays on a given tile are removed.

items.remove(17, 42, "items/orcish-flag.png")