Difference between revisions of "LuaWML/Tiles"

From The Battle for Wesnoth Wiki
(wesnoth.label)
(Syntax highlighting)
Line 1: Line 1:
 
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 11:
 
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 21:
 
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 31:
 
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.
  
Line 37: Line 47:
 
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 63:
 
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 ====
Line 65: Line 79:
 
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.
  
-- 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 92:
 
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 ====
Line 85: Line 103:
 
Returns true if the given location passes the 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*" } })
+
<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 113:
 
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 123:
 
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 ====
Line 115: Line 139:
 
{{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.
 
{{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.remove_fog(1, { {5, 5}, {5, 6} }) --removes fog on 5,5 and 5,6 for side 1
+
<syntaxhighlight lang=lua>
wesnoth.remove_fog(wesnoth.sides[1].side, { {5, 5} }) -- removes fog for first side on 5,5
+
wesnoth.remove_fog(1, { {5, 5}, {5, 6} }) --removes fog on 5,5 and 5,6 for side 1
wesnoth.remove_fog(1, wesnoth.get_locations{ x = 5, y = 5 }) --removes fog on 5,5
+
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 ====
Line 184: Line 210:
  
 
* '''wesnoth.label(''cfg'')'''
 
* '''wesnoth.label(''cfg'')'''
wesnoth.label {x=10,y=10,text="a",color={255,255,255,255}}
 
  
 
Sets label of cfg.x, cfg.y to cfg.text. More supported keys https://wiki.wesnoth.org/InterfaceActionsWML#.5Blabel.5D
 
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>
  
 
==== items.place_image ====
 
==== items.place_image ====
Line 194: Line 223:
 
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 209: Line 240:
 
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]]

Revision as of 04:35, 12 April 2018

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

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.

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

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