LuaAPI/UpdatingFrom14

This page contains a summary of the major Lua API changes between 1.12 and 1.15, to help make updating older code simpler.

In general, when it says "renamed", the new function is a drop-in replacement for the old one. When it says "replaced", the new function probably has a different API (such as different arguments) or might not even be a function at all.

For some of these that are more than just a simple rename, an example is given where the old, pre-1.16 code is shown commented out and the new code is shown below it.

wesnoth.add_tile_overlay renamed to wesnoth.interface.add_hex_overlay
wesnoth.add_widget_definition renamed to gui.add_widget_definition
wesnoth.advance_unit renamed to wesnoth.units.advance
wesnoth.alert renamed to gui.alert
wesnoth.allow_end_turn renamed to wesnoth.interface.allow_end_turn
wesnoth.append_ai renamed to wesnoth.sides.append_ai
wesnoth.canonical_path renamed to filesystem.canonical_path
wesnoth.change_ai_component renamed to wesnoth.sides.change_ai_component
wesnoth.clear_messages renamed to wesnoth.interface.clear_chat_messages
wesnoth.color_adjust replaced with wesnoth.interface.color_adjust

wesnoth.compare_versions replaced with wesnoth.version, which creates a version object that can be compared with standard comparison operators

-- if wesnoth.compare_versions(wesnoth.game_config.version, '<=', '1.13') then
if wesnoth.current_version() <= wesnoth.version '1.13' then
    -- do version-specific stuff
end

wesnoth.confirm renamed to gui.confirm
wesnoth.copy_unit renamed to wesnoth.units.clone
wesnoth.create_animator renamed to wesnoth.units.create_animator
wesnoth.create_side renamed to wesnoth.sides.create
wesnoth.create_unit renamed to wesnoth.units.create
wesnoth.create_weapon renamed to wesnoth.units.create_weapon
wesnoth.debug_ai renamed to wesnoth.sides.debug_ai
wesnoth.debug renamed to wml.tostring; in addition, it now produces an output that is valid WML, meaning that wml.parse(wml.tostring(wml_table)) will output a clone of wml_table (though for this purpose there's a separate wml.clone function which is probably faster).
wesnoth.delay renamed to wesnoth.interface.delay
wesnoth.delete_ai_component renamed to wesnoth.sides.delete_ai_component
wesnoth.deselect_hex renamed to wesnoth.interface.deselect_hex
wesnoth.end_level replaced with assignable wesnoth.scenario.end_level_data
wesnoth.end_turn renamed to wesnoth.interface.end_turn
wesnoth.erase_unit renamed to wesnoth.units.erase
wesnoth.eval_conditional renamed to wml.eval_conditional
wesnoth.extract_unit renamed to wesnoth.units.extract
wesnoth.find_cost_map renamed to wesnoth.paths.find_cost_map
wesnoth.find_path renamed to wesnoth.paths.find_path
wesnoth.find_reach renamed to wesnoth.paths.find_reach
wesnoth.find_vacant_tile renamed to wesnoth.paths.find_vacant_hex
wesnoth.find_vision_range renamed to wesnoth.paths.find_vision_range
wesnoth.fire renamed to wml.fire
wesnoth.float_label renamed to wesnoth.interface.float_label
wesnoth.format_conjunct_list renamed to stringx.format_conjunct_list
wesnoth.format_disjunct_list renamed to stringx.format_disjunct_list
wesnoth.format renamed to stringx.vformat and can also be called directly on a string literal
wesnoth.gamestate_inspector renamed to gui.show_inspector
wesnoth.get_all_vars replaced with read-only variable wml.all_variables (but it should still be used sparingly)
wesnoth.get_displayed_unit renamed to wesnoth.interface.get_displayed_unit
wesnoth.get_end_level_data replaced with readable wesnoth.scenario.end_level_data
wesnoth.get_image_size renamed to filesystem.image_size
wesnoth.get_max_liminal_bonus replaced with read-only wesnoth.current.schedule.liminal_bonus
wesnoth.get_mouseover_tile renamed to wesnoth.interface.get_hovered_hex
wesnoth.get_recall_units renamed to wesnoth.units.find_on_recall
wesnoth.get_selected_tile renamed to wesnoth.interface.get_selected_hex

wesnoth.get_side_variable and wesnoth.set_side_variable replaced by variables member in side data (found in wesnoth.sides array). This otherwise works the same as wml.variables.

-- local old_value = wesnoth.get_side_variable(1, 'my_value')
local old_value = wesnoth.sides[1].variables['my_value'] -- or variables.myvalue
local new_value = old_value * 2
-- wesnoth.set_side_variable(1, 'my_value', new_value)
wesnoth.sides[1].variables['my_value'] = new_value

wesnoth.get_sides renamed to wesnoth.sides.find
wesnoth.get_sound_source replaced with wesnoth.audio.sources mapping (read key)
wesnoth.get_starting_location replaced by starting_location member in side data

wesnoth.get_time_of_day replaced with wesnoth.schedule.get_time_of_day and wesnoth.schedule.get_illumination as well as wesnoth.current.schedule.time_of_day

-- local global_tod = wesnoth.get_time_of_day(wesnoth.current.turn + 1)
local global_tod = wesnoth.schedule.get_time_of_day(nil, wesnoth.current.turn + 1)
-- local base_tod = wesnoth.get_time_of_day(wesnoth.current.turn + 1, {44, 23})
local base_tod = wesnoth.schedule.get_time_of_day({44, 23}, wesnoth.current.turn + 1)
-- local final_tod = wesnoth.get_time_of_day(wesnoth.current.turn + 1, {44, 23, true})
local final_tod = wesnoth.schedule.get_illumination({44, 24}, wesnoth.current.turn + 1)

wesnoth.get_time_stamp renamed to wesnoth.ms_since_init
wesnoth.get_traits replaced with wesnoth.game_config.global_traits, which is the table it formerly returned
wesnoth.get_unit renamed to wesnoth.units.get
wesnoth.get_units renamed to wesnoth.units.find_on_map

wesnoth.get_variable and wesnoth.set_variable are replaced by wml.variables which can be indexed with a variable path - set a variable by assigning to it

-- local old_value = wesnoth.get_variable('my_array[2].value')
local old_value = wml.variables['my_array[2].value']
local new_value = old_value * 2
-- wesnoth.set_variable('my_array[2].value', new_value)
wml.variables['my_array[2].value'] = new_value

wesnoth.have_file renamed to filesystem.have_file
wesnoth.highlight_hex renamed to wesnoth.interface.highlight_hex
wesnoth.invoke_synced_command renamed to wesnoth.sync.invoke_command
wesnoth.is_enemy renamed to wesnoth.sides.is_enemy
wesnoth.is_fogged renamed to wesnoth.sides.is_fogged
wesnoth.is_shrouded renamed to wesnoth.sides.is_shrouded
wesnoth.is_skipping_messages renamed to wesnoth.interface.is_skipping_messages
wesnoth.lock_view renamed to wesnoth.interface.lock
wesnoth.match_side renamed to wesnoth.sides.matches
wesnoth.match_unit renamed to wesnoth.units.matches
wesnoth.message renamed to wesnoth.interface.add_chat_message
wesnoth.music_list renamed to wesnoth.audio.music_list
wesnoth.open_help renamed to gui.show_help
wesnoth.place_shroud replaced with wesnoth.sides.place_shroud and wesnoth.sides.override_shroud
wesnoth.play_sound renamed to wesnoth.audio.play
wesnoth.put_recall_unit renamed to wesnoth.units.to_recall
wesnoth.put_unit replaced with wesnoth.units.to_map, which reordered the arguments, so that the unit info has now moved from the 3rd position to the first
wesnoth.random renamed to mathx.random
wesnoth.read_file renamed to filesystem.read_file
wesnoth.remove_modifications renamed to wesnoth.units.remove_modifications
wesnoth.remove_sound_source replaced with wesnoth.audio.sources mapping (assign nil to key)
wesnoth.remove_tile_overlay renamed to wesnoth.interface.remove_hex_overlay
wesnoth.replace_schedule renamed to wesnoth.schedule.replace
wesnoth.scroll_to_tile renamed to wesnoth.interface.scroll_to_hex
wesnoth.scroll renamed to wesnoth.interface.scroll
wesnoth.select_unit renamed to wesnoth.units.select (also available as wesnoth.interface.select_unit)
wesnoth.set_end_campaign_credits replaced with assignable wesnoth.scenario.show_credits
wesnoth.set_end_campaign_text replaced with assignable wesnoth.scenario.end_text and wesnoth.scenario.end_text_duration
wesnoth.set_next_scenario replaced with assignable wesnoth.scenario.next
wesnoth.set_side_id renamed to wesnoth.sides.set_id
wesnoth.set_time_of_day (which was undocumented and unofficial) replaced with assigning wesnoth.current.schedule.time_of_day, though that only covers part of the original functionality
wesnoth.show_lua_console renamed to gui.show_lua_console
wesnoth.show_menu renamed to gui.show_menu
wesnoth.show_message_box renamed to gui.show_prompt
wesnoth.show_message_dialog renamed to gui.show_narration
wesnoth.show_popup_dialog renamed to gui.show_popup
wesnoth.show_story renamed to gui.show_story
wesnoth.skip_messages renamed to wesnoth.interface.skip_messages
wesnoth.sound_volume replaced with read-write wesnoth.audio.volume
wesnoth.switch_ai renamed to wesnoth.sides.switch_ai
wesnoth.synchronize_choice renamed to wesnoth.sync.evaluate_single
wesnoth.synchronize_choices renamed to wesnoth.sync.evaluate_multiple
wesnoth.teleport renamed to wesnoth.units.teleport
wesnoth.theme_items renamed to wesnoth.interface.game_display - it's still a table with the same keys as before
wesnoth.tovconfig renamed to wml.tovconfig
wesnoth.transform_unit renamed to wesnoth.units.transform
wesnoth.unit_ability renamed to wesnoth.units.ability
wesnoth.unit_defense renamed to wesnoth.units.chance_to_be_hit - can use wesnoth.units.defense_on if you want the defense instead
wesnoth.unit_jamming_cost renamed to wesnoth.units.jamming_on
wesnoth.unit_movement_cost renamed to wesnoth.units.movement_on
wesnoth.unit_resistance replaced by wesnoth.units.resistance_against - new function returns (100 - old function)
wesnoth.unit_vision_cost renamed to wesnoth.units.vision_on
wesnoth.unsynced renamed to wesnoth.sync.run_unsynced
wesnoth.view_locked renamed to wesnoth.interface.is_locked
wesnoth.wml_matches_filter renamed to wml.matches_filter
wesnoth.zoom renamed to wesnoth.interface.zoom

wesnoth.tovconfig and related functions in plugins

The wesnoth.tovconfig function has been removed from the plugin context. This will have no effect on most people, as the plugin context is rarely used. A plugin context is any Lua script loaded using the --plugin command-line parameter, primarily intended for creating bots on the multiplayer server.

If you were calling wesnoth.tovconfig in a plugin, then you have several options for updating your code. If you simply needed to verify that a variable holds a valid WML table, you can use wml.valid instead. If you need to substitute variables into a WML table, you can also use wml.interpolate to replicate the behaviour of wml.tovconfig, supplying the variables themselves as an extra argument (another WML table).

In addition, the helper functions parsed, literal, shallow_parsed, and shallow_literal are not available in the plugin context.

GUI2 API

There has been a major rehaul of the GUI2 API for arbitrary custom dialogs. See LuaAPI/types/widget and LuaAPI/gui/widget for details; the changes are also summarized below.

wesnoth.add_dialog_tree_node renamed to gui.widget.add_item_of_type and now takes a reference to the widget instead of a path to it; use gui.widget.find to convert a path to a reference
wesnoth.get_dialog_value and wesnoth.set_dialog_value removed; instead access the appropriate member of the widget, such as selected_index or selected or text or value or percentage or selected_item_path or unfolded or unit or label. Some of these may be write-only.
wesnoth.remove_dialog_item renamed to gui.widget.remove_items_at and now takes a reference to the widget instead of a path to it; use gui.widget.find to convert a path to a reference.

wesnoth.set_dialog_active removed; instead assign the enabled member of a widget

-- local function preshow()
local function preshow(self)
    local var_a = true
    -- whatever you are doing to determine if button should be active
    -- wesnoth.set_dialog_active(var_a, "my_button_id")
    local widget_handle = self:find('my_button_id') -- or just self.my_button_id
    widget_handle.enabled = var_a
    -- ...
end

wesnoth.set_dialog_callback removed; instead simply assign to a widget's callback handler, eg my_widget.on_modified = function() end

-- local function preshow()
local function preshow(self)
    local function on_text_modified()
        -- Do whatever you need to do
    end
    -- This example shows an on_modified event; there's also on_left_click and on_button_click
    -- Use one of the click events if you were setting the callback on a button.
    -- wesnoth.set_dialog_callback(on_text_modified, "my_text_id")
    local widget_handle = self:find('my_text_id') -- or just self.my_text_id
    widget_handle.on_modified = set_dialog_callback
    -- Or you could have defined the function here like this:
    -- function widget_handle.on_modified()
    -- ...
end

wesnoth.set_dialog_canvas renamed to gui.widget.set_canvas and now takes a reference to the widget instead of a path to it; use gui.widget.find to convert a path to a reference

wesnoth.set_dialog_focus renamed to gui.widget.focus and now takes a reference to the widget instead of a path to it; use gui.widget.find to convert a path to a reference

-- local function preshow()
local function preshow(self)
    -- wesnoth.set_dialog_focus("my_text_id")
    local widget_handle = self:find('my_text_id') -- or just self.my_text_id
    widget_handle:focus()
    -- ...
end

wesnoth.set_dialog_markup removed; instead assign the use_markup member of a widget

wesnoth.set_dialog_tooltip removed; instead assign the tooltip member of a widget

-- local function preshow()
local function preshow(self)
    local var_a = 'Some explanation'
    -- whatever you are doing to determine the button's tooltip
    -- wesnoth.set_dialog_tooltip(var_a, "my_button_id")
    local widget_handle = self:find('my_button_id') -- or just self.my_button_id
    widget_handle.tooltip = var_a
    -- ...
end

wesnoth.set_dialog_visible removed; instead assign the visible member of a widget

-- local function preshow()
local function preshow(self)
    local var_a = true
    -- whatever you are doing to determine if button should be visible
    -- wesnoth.set_dialog_visible(var_a, "my_button_id")
    local widget_handle = self:find('my_button_id') -- or just self.my_button_id
    widget_handle.visible = var_a
    -- ...
end

wesnoth.show_dialog renamed to gui.show_dialog
The preshow and postshow functions passed to gui.show_dialog now take a single parameter, which is a reference to the dialog's root widget (a widget of type "window"). This can be passed to gui.widget.find to look up widgets by their path. You can also access direct child widgets by simply indexing the root widget.

Map API

Due to a major rehaul of the map API, many map functions are now methods on the map object, available as wesnoth.current.map (abbreviated in the below listing to just map).

wesnoth.add_time_area renamed to wesnoth.map.place_area
wesnoth.get_locations renamed to wesnoth.map.find

wesnoth.get_map_size replaced with map.playable_width, map.playable_height, and map.border_size

-- local width, height, border_size = wesnoth.get_map_size()
local width, height = wesnoth.current.map.playable_width, wesnoth.current.map.playable_height
local border_size = wesnoth.current.map.border_size
-- local width_with_border, height_with_border = width + border_size * 2, height + border_size * 2
local width_with_border, height_with_border = wesnoth.current.map.width and wesnoth.current.map.height

wesnoth.get_terrain_info replaced with wesnoth.terrain_types

-- local info = wesnoth.get_terrain_info('Gg')
local info = wesnoth.terrain_types['Gg']

wesnoth.get_terrain replaced with map[{x,y}]

-- local terrain = wesnoth.get_terrain(x, y)
local terrain = wesnoth.current.map[{x,y}]
-- local terrain_under_unit = wesnoth.get_terrain(unit.x, unit.y)
local terrain_under_unit = wesnoth.current.map[unit]

wesnoth.get_village_owner renamed to wesnoth.map.get_owner

wesnoth.get_villages replaced with wesnoth.map.find (with gives_income = true)

-- For example, get all villages in [time_area]id=shadowed
-- local villages = wesnoth.get_villages{area = 'shadowed'}
local villages = wesnoth.map.find{area = 'shadowed', gives_income = true}

wesnoth.label renamed to wesnoth.map.add_label
wesnoth.map.get_adjacent_tiles renamed to wesnoth.map.get_adjacent_hexes
wesnoth.match_location renamed to wesnoth.map.matches
wesnoth.remove_time_area renamed to wesnoth.map.remove_area

wesnoth.set_terrain replaced with assigning map[{x,y}] - helper functions in wesnoth.map expose the more advanced assignment operations (replace_overlay, replace_both, replace_if_failed) - just assign the result of one of these functions to the hex

-- wesnoth.set_terrain(x, y, 'Gg')
wesnoth.current.map[{x,y}] = 'Gg'
-- Or be explicit about layer:
wesnoth.current.map[{x,y}] = wesnoth.map.replace_both 'Gg'
-- wesnoth.set_terrain(x, y, 'Gg', 'base')
wesnoth.current.map[{x,y}] = wesnoth.map.replace_base 'Gg'
-- wesnoth.set_terrain(x, y, '^Vh', 'overlay')
wesnoth.current.map[{x,y}] = wesnoth.map.replace_overlay '^Vh'
-- wesnoth.set_terrain(x, y, 'Gg^Vh', 'overlay', true)
wesnoth.current.map[{x,y}] = wesnoth.map.replace_if_failed('Gg^Vh', 'overlay')

wesnoth.set_village_owner renamed to wesnoth.map.set_owner
wesnoth.special_locations renamed to map.special_locations (note: the length operator is no longer supported)
wesnoth.terrain_mask replaced with map:terrain_mask

The following functions are only available in map generation scripts:

wesnoth.create_filter renamed to wesnoth.map.filter
wesnoth.create_map renamed to wesnoth.map.create
wesnoth.default_generate_height_map renamed to wesnoth.map.generate_height_map
wesnoth.generate_default_map renamed to wesnoth.map.generate
map:get_locations renamed to map:find

map:get_tiles_radius replaced with map::find_in_radius (and the order of arguments changed)

-- This example assumes you have a variable f defined as in World Conquest (engine.lua)
-- local in_radius = map:get_tiles_radius(12, 22, f.terrain 'Gg', 5)
local in_radius = map:find_in_radius(12, 22, 5, f.terrain 'Gg')

helper module

The helper module is being phased out, so quite a lot of things have been moved out of it. This section is written under the assumption that you loaded it with local helper = wesnoth.require "helper" or the like, but many people call it H instead of helper, so keep that in mind.

helper.adjacent_tiles replaced by wesnoth.map.iter_adjacent, can be renamed to wesnoth.current.map:iter_adjacent
helper.child_array renamed to wml.child_array
helper.child_count renamed to wml.child_count
helper.child_range renamed to wml.child_range
helper.distance_between renamed to wesnoth.map.distance_between
helper.find_attack renamed to wesnoth.units.find_attack
helper.get_child renamed to wml.get_child
helper.get_nth_child renamed to wml.get_nth_child
helper.get_user_choice renamed to gui.get_user_choice
helper.get_variable_array renamed to wml.array_access.get
helper.get_variable_proxy_array renamed to wml.array_access.get_proxy
helper.literal renamed to wml.literal
helper.modify_unit renamed to wesnoth.units.modify
helper.move_unit_fake renamed to wesnoth.interface.move_unit_fake
helper.parsed renamed to wml.parsed
helper.rand renamed to mathx.random_choice
helper.round renamed to mathx.round
helper.set_variable_array renamed to wml.array_access.set
helper.set_wml_tag_metatable replaced with wml.tag, which is a table that works exactly the same as what this function would return
- ```
-- local T = helper.set_wml_tag_metatable{}
local T = wml.tag -- Or you can dispense with T and use wml.tag directly
```
helper.set_wml_var_metatable replaced with wml.variable.proxy, which is a table that works exactly the same as what this function would return
helper.set_wml_action_metatable replaced with wml.fire, which can be used as if it were the table that this function would return
helper.shallow_literal renamed to wml.shallow_literal
helper.shallow_parsed renamed to wml.shallow_parsed
helper.shuffle renamed to mathx.shuffle
helper.wml_error renamed to wml.error

items module

There were also a few things in an "items" module that have been moved into the main API.

items.place_halo renamed to wesnoth.interface.add_item_halo
items.place_image renamed to wesnoth.interface.add_item_image
items.remove renamed to wesnoth.interface.remove_item