LuaWML/Tiles

2017-09-14T22:28:33Z

Shrieker1: Correct the descriptions for get_direction and get_relative_dir that had documentation switched compared to implementation. Also a few extra details added about functions.

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 [[InterfaceActionsWML|[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''])'''

{{DevFeature1.13|5}} 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''])'''

{{DevFeature1.13|5}} 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'')'''

{{DevFeature1.13|5}} 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'')'''

{{DevFeature1.13|5}} Removes a sound source.

==== wesnoth.get_sound_source ====

* '''wesnoth.get_sound_source(''id'')'''

{{DevFeature1.13|5}} 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 ====
{{DevFeature1.13|8}}

* '''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 ====
{{DevFeature1.13|8}}

* '''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 ====
{{DevFeature1.13|8}}

* '''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 ====
{{DevFeature1.13|8}}

* '''wesnoth.map.get_adjacent_tiles(''loc'')'''

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

==== wesnoth.map.tiles_adjacent ====
{{DevFeature1.13|8}}

* '''wesnoth.map.tiles_adjacent(''loc1'', ''loc2'')'''

Tests if two hexes are adjacent.

==== wesnoth.map.distance_between ====
{{DevFeature1.13|8}}

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

[[Category: Lua Reference]]

The Battle for Wesnoth Wiki - User contributions [en]

LuaWML/Tiles