Difference between revisions of "LuaWML/Tiles"

From The Battle for Wesnoth Wiki
(Explicitly note how to call each function)
(wesnoth.map.get_adjacent_tiles)
 
(18 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 +
{{Template:LuaMove}}
 +
 
This page describes the [[LuaWML]] functions for handling terrains and tiles. The ''items'' library can be loaded by
 
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"
+
<syntaxhighlight lang=lua>
 +
items = wesnoth.require "lua/wml/items.lua"
 +
</syntaxhighlight>
  
 
==== wesnoth.get_map_size ====
 
==== wesnoth.get_map_size ====
Line 9: Line 13:
 
Returns the width, the height, and the border size of the map.
 
Returns the width, the height, and the border size of the map.
  
local w,h,b = wesnoth.get_map_size()
+
<syntaxhighlight lang=lua>
 +
local w,h,b = wesnoth.get_map_size()
 +
</syntaxhighlight>
  
 
==== wesnoth.get_terrain ====
 
==== wesnoth.get_terrain ====
Line 17: Line 23:
 
Returns the terrain code for the given location.
 
Returns the terrain code for the given location.
  
local is_grassland = wesnoth.get_terrain(12, 15) == "Gg"
+
<syntaxhighlight lang=lua>
 +
local is_grassland = wesnoth.get_terrain(12, 15) == "Gg"
 +
</syntaxhighlight>
  
 
==== wesnoth.set_terrain ====
 
==== wesnoth.set_terrain ====
Line 25: Line 33:
 
Modifies the terrain at the given location.
 
Modifies the terrain at the given location.
  
function create_village(x, y)
+
<syntaxhighlight lang=lua>
    wesnoth.set_terrain(x, y, "Gg^Vh")
+
function create_village(x, y)
end
+
    wesnoth.set_terrain(x, y, "Gg^Vh")
 +
end
 +
</syntaxhighlight>
 +
 
 
An optional 4th parameter can be passed (layer): overlay, base or both, default both: Change the specified layer only.
 
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.
 
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 ====
  
* '''wesnoth.get_info(''terrain_code'')'''
+
* '''wesnoth.get_terrain_info(''terrain_code'')'''
  
 
Returns the terrain details for the given terrain code.
 
Returns the terrain details for the given terrain code.
  
local is_keep = wesnoth.get_terrain_info(wesnoth.get_terrain(12, 15)).keep
+
<syntaxhighlight lang=lua>
 +
local is_keep = wesnoth.get_terrain_info(wesnoth.get_terrain(12, 15)).keep
 +
</syntaxhighlight>
  
 
Terrain info is a plain table with the following fields:
 
Terrain info is a plain table with the following fields:
Line 51: Line 65:
 
Returns the two coordinates of the currently selected tile. This is mostly useful for defining command-mode helpers.
 
Returns the two coordinates of the currently selected tile. This is mostly useful for defining command-mode helpers.
  
function chg_unit(attr, val)
+
<syntaxhighlight lang=lua>
    local x, y = wesnoth.get_selected_tile()
+
function chg_unit(attr, val)
    if not x then wesnoth.message("Error", "No unit selected."); return end
+
  local x, y = wesnoth.get_selected_tile()
    helper.modify_unit({ x = x, y = y }, { [attr] = val })
+
  if not x then wesnoth.message("Error", "No unit selected."); return end
end
+
  helper.modify_unit({ x = x, y = y }, { [attr] = val })
-- Function chg_unit can be used in command mode to modify unit attributes on the fly:
+
end
--  :lua chg_unit("status.poisoned", true)
+
-- Function chg_unit can be used in command mode to modify unit attributes on the fly:
 +
--  :lua chg_unit("status.poisoned", true)
 +
</syntaxhighlight>
  
 
==== wesnoth.get_locations ====
 
==== wesnoth.get_locations ====
  
 
* '''wesnoth.get_locations(''filter'')'''
 
* '''wesnoth.get_locations(''filter'')'''
 +
* {{DevFeature1.13|12}} '''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.
+
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
+
<syntaxhighlight lang=lua>
for i,loc in ipairs(wesnoth.get_locations { terrain = "Gg" }) do
+
-- replace all grass terrains by roads
    wesnoth.set_terrain(loc[1], loc[2], "Rr")
+
for i,loc in ipairs(wesnoth.get_locations { terrain = "Gg" }) do
end
+
    wesnoth.set_terrain(loc[1], loc[2], "Rr")
 +
end
 +
</syntaxhighlight>
  
 
==== wesnoth.get_villages ====
 
==== wesnoth.get_villages ====
Line 76: Line 95:
 
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.
 
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?
+
<syntaxhighlight lang=lua>
v = #wesnoth.get_villages()
+
-- How many villages do we have on our map?
 +
v = #wesnoth.get_villages()
 +
</syntaxhighlight>
  
 
==== wesnoth.match_location ====
 
==== wesnoth.match_location ====
  
 
* '''wesnoth.match_location(''x'', ''y'', ''filter'')'''
 
* '''wesnoth.match_location(''x'', ''y'', ''filter'')'''
 +
* {{DevFeature1.13|12}} '''wesnoth.match_location(''x'', ''y'', ''filter'' [, ''reference_unit''])'''
  
Returns true if the given location passes the filter.
+
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*" } })
+
<syntaxhighlight lang=lua>
 +
bool b = wesnoth.match_location(x, y, { terrain = "Ww", { "filter_adjacent_location", terrain = "Ds,*^Bw*" } })
 +
</syntaxhighlight>
  
 
==== wesnoth.add_tile_overlay ====
 
==== wesnoth.add_tile_overlay ====
Line 93: Line 117:
 
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.
 
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" })
+
<syntaxhighlight lang=lua>
 +
wesnoth.add_tile_overlay(17, 42, { image = "items/orcish-flag.png" })
 +
</syntaxhighlight>
  
 
==== wesnoth.remove_tile_overlay ====
 
==== wesnoth.remove_tile_overlay ====
Line 101: Line 127:
 
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.
 
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")
+
<syntaxhighlight lang=lua>
 +
wesnoth.remove_tile_overlay(17, 42, "items/orcish-flag.png")
 +
</syntaxhighlight>
 +
 
 +
==== 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.
 +
 
 +
<syntaxhighlight lang=lua>
 +
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
 +
</syntaxhighlight>
 +
 
 +
==== 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.
 +
 
 +
<syntaxhighlight lang=lua>
 +
local a, b, c, d, e, f = wesnoth.map.get_adjacent_tiles({3, 3})
 +
local a_x = a[1]
 +
local a_y = a[2]
 +
</syntaxhighlight>
 +
 
 +
See also [[LuaWML:Pathfinder#helper.adjacent_tiles|helper.adjacent_tiles]] if you want to iterate over the hexes.
 +
 
 +
==== 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.
 +
 
 +
<syntaxhighlight lang=lua>
 +
local my_distance = wesnoth.map.distance_between({10, 10}, {20, 20})
 +
</syntaxhighlight>
 +
 
 +
==== wesnoth.label====
 +
{{DevFeature1.13|0}}
 +
 
 +
* '''wesnoth.label(''cfg'')'''
 +
 
 +
Sets label of cfg.x, cfg.y to cfg.text. More supported keys https://wiki.wesnoth.org/InterfaceActionsWML#.5Blabel.5D
 +
 
 +
<syntaxhighlight lang=lua>
 +
wesnoth.label {x=10,y=10,text="a",color={255,255,255,255}}
 +
</syntaxhighlight>
 +
 
 +
==== wesnoth.special_locations ====
 +
 
 +
{{DevFeature1.13|12}}
 +
 
 +
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.)
 +
 
 +
<syntaxhighlight lang=lua>
 +
-- 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
 +
</syntaxhighlight>
  
 
==== items.place_image ====
 
==== items.place_image ====
Line 109: Line 252:
 
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.
 
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"
+
<syntaxhighlight lang=lua>
items.place_image(17, 42, "items/orcish-flag.png")
+
local items = wesnoth.require "lua/wml/items.lua"
 +
items.place_image(17, 42, "items/orcish-flag.png")
 +
</syntaxhighlight>
  
 
==== items.place_halo ====
 
==== items.place_halo ====
Line 124: Line 269:
 
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.
 
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")
+
<syntaxhighlight lang=lua>
 +
items.remove(17, 42, "items/orcish-flag.png")
 +
</syntaxhighlight>
  
 
[[Category: Lua Reference]]
 
[[Category: Lua Reference]]

Latest revision as of 20:50, 18 February 2021



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

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

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")
This page was last edited on 18 February 2021, at 20:50.