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.

Functions in wesnoth namespace

• The wesnoth.tovconfig function has been removed from the map generator context (or the plugin context). If you were calling it in a map generator, you will need to use wml.valid instead. You can also use wml.interpolate to replicate the behaviour of wml.tovconfig but supplying the variables as an extra argument. In addition, the helper functions parsed, literal, shallow_parsed, and shallow_literal are not available in the map generator context. All these functions still work the same as before in regular game Lua, but they are now in the wml module.

• wesnoth.add_ai_component renamed to wesnoth.sides.add_ai_component
• wesnoth.add_modification renamed to wesnoth.units.add_modification
• 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.append_ai renamed to wesnoth.sides.append_ai
• wesnoth.change_ai_component renamed to wesnoth.sides.change_ai_component
• wesnoth.confirm renamed to gui.confirm
• wesnoth.copy_unit renamed to wesnoth.units.clone
• wesnoth.create_unit renamed to wesnoth.units.create
• 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.erase_unit renamed to wesnoth.units.erase
• wesnoth.extract_unit renamed to wesnoth.units.extract
• 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_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.
• wesnoth.get_sides renamed to wesnoth.sides.find
• wesnoth.get_starting_location replaced by starting_location member in side data
• 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
• wesnoth.highlight_hex renamed to wesnoth.interface.highlight_hex
• wesnoth.is_enemy renamed to wesnoth.sides.is_enemy
• 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.put_recall_unit renamed to wesnoth.units.to_recall
• wesnoth.put_unit renamed to wesnoth.units.to_map
• wesnoth.remove_modifications renamed to wesnoth.units.remove_modifications
• wesnoth.remove_tile_overlay renamed to wesnoth.interface.remove_hex_overlay
• 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
• wesnoth.set_side_id renamed to wesnoth.sides.set_id
• 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.switch_ai renamed to wesnoth.sides.switch_ai
• 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
• wesnoth.unit_jamming_cost renamed to wesnoth.units.jamming_on
• wesnoth.unit_movement_cost renamed to wesnoth.units.movement_on
• wesnoth.unit_resistance renamed to wesnoth.units.resistance
• wesnoth.unit_vision_cost renamed to wesnoth.units.vision_on
• 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

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
• wesnoth.set_dialog_callback removed; instead simply assign to a widget's callback handler, eg my_widget.on_modified = function() 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
• 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
• wesnoth.set_dialog_visible removed; instead assign the visible member of a widget
• 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.

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.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.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
• 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.shallow_literal renamed to wml.shallow_literal
• helper.shallow_parsed renamed to wml.shallow_parsed
• 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