LuaWML/Tiles

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_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)

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.

-- 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)

Returns true if the given location passes 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.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, to)

Calculates the direction from one hex to another. Returns a string such as "ne" or "s".

wesnoth.map.get_relative_dir

(Version 1.13.8 and later only)

• wesnoth.map.get_relative_dir(from, dir)

Calculates the hex reached by travelling in the specified direction, which should be a string such as "ne" or "s".

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.

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.

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")