From The Battle for Wesnoth Wiki

(Version 1.15.x (please read the template documentation to set the correct version number) and later only) The page describes the api available for lua map generators that is differnt from the ingame lua api.


  • wesnoth.find_path(src, dst, cost_function, mapsize_x, mapsize_y, include_border)

Behaves slightly differntly than in the ingame lua api with the same name in particular it no longer accepts unit arguments and explicitly nees the map size.


  • wesnoth.create_map (map_data)
  • wesnoth.find_path(width, height, terrain)

Creates a gamemap object, which has the following functions and properties

  • get_terrain(loc)
  • set_terrain(loc, terrain)
  • get_locations(filter, locs_to_check)
  • get_tiles_radius(locations, filter_radius)
  • terrain_mask(x_offset, y_offset, data, optional_argeument_table)
  • width number
  • height number
  • data string

The filters about use custom lua filter objects that can be constructed via wesnoth.create_filter


creates a lua filter object from a table describing a lua terrainfilter, this is similar but not the same as wml filters, compiling these into lua objects makes it much faster. A lua filtertable is a table which at index 1 has the type of the filter and the rest depends on the type of the filter, for example wesnoth.create_filter { "terrain", "K*"} " will create a filter that matches keeps. THe follwing types of theilter are known:

  • { "terrain", terraincode } matches for terrain terraincode
  • { "all", <filter1>, <filter2>, <filter3>, ... } matches when all the subfilters match
  • { "any", <filter1>, <filter2>, <filter3>, ... } matches when any the subfilters match
  • { "none", <filter1>, <filter2>, <filter3>, ... } matches when none the subfilters match
  • { "notall", <filter1>, <filter2>, <filter3>, ... } matches when not all the subfilters match
  • { "adjacent", <subfilter>, [count = <count>], [adjacent = <adjacent>]} matches when count adjacent tiles matchthe subfilter ('adjacent=' defaults to 'n,nw,sw,s,se,ne')
  • { "radius", <radius>, <subfilter>, filter_radius = <filter_radius> } radius: number, filter_radius: subfilter.

It is reccomended to create a helper function for filter construction for example:

f = {
	terrain =  function(terrain)
		return { "terrain", terrain }
	all =  function(...)
		return { "all", ... }
	any =  function(...)
		return { "any", ... }
	none =  function(...)
		return { "none", ... }
	adjacent =  function(f, ad, count)
		return { "adjacent",  f, adjacent = ad, count = count }
	radius =  function(r, f, f_r)
		return { "radius", r, f, filter_radius = f_r}

    f.radius(4, f.terrain("^V*"))

for a filter that matches keepos that are at most distance 4 to a village


wesnoth.generate_default_map(width, height, cfg) cfg is a wml table similar to the default map generators argument it supports the wml subtables as the defautl map generator and the following attributes:

  • nplayers the number of players-
  • nvillages the prefered number of villgaes on the map, unlike the default mapgen this is not 'per thousand'
  • iterations like the [generator] attribute the with same name, note that unliek the original value this is not divided by 10 for island maps.
  • hill_size like the [generator] attribute the with same name.
  • castle_size like the [generator] attribute the with same name.
  • island_size The size of the island usually up to half the width of the map.
  • island_off_center offset to place the island, used in particular for coastal maps.
  • max_lakes like the [generator] attribute the with same name, note that unliek the original value this is not divided by 10 for island maps.
  • link_castles whether to connect castles by roads
  • show_labels whether to generate labels.
  • seed the random seed.
This page was last edited on 12 December 2018, at 01:06.