LuaAPI/UpdatingFrom14

From The Battle for Wesnoth Wiki
Revision as of 12:51, 16 October 2020 by Celtic Minstrel (talk | contribs) (Add deprecations from the helper and items module)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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

  • 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.wml_matches_filter renamed to wml.matches_filter
  • 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.get_all_vars replaced with read-only variable wml.all_variables (but it should still be used sparingly)
  • wesnoth.delay renamed to wesnoth.interface.delay
  • wesnoth.float_label renamed to wesnoth.interface.float_label
  • wesnoth.highlight_hex renamed to wesnoth.interface.highlight_hex
  • wesnoth.deselect_hex renamed to wesnoth.interface.deselect_hex
  • wesnoth.get_selected_tile renamed to wesnoth.interface.get_selected_hex
  • wesnoth.get_mouseover_tile renamed to wesnoth.interface.get_hovered_hex
  • wesnoth.scroll_to_tile renamed to wesnoth.interface.scroll_to_hex
  • wesnoth.scroll renamed to wesnoth.interface.scroll
  • wesnoth.lock_view renamed to wesnoth.interface.lock
  • wesnoth.view_locked renamed to wesnoth.interface.is_locked
  • wesnoth.is_skipping_messages renamed to wesnoth.interface.is_skipping_messages
  • wesnoth.skip_messages renamed to wesnoth.interface.skip_messages
  • wesnoth.add_tile_overlay renamed to wesnoth.interface.add_hex_overlay
  • wesnoth.remove_tile_overlay renamed to wesnoth.interface.remove_hex_overlay
  • wesnoth.theme_items renamed to wesnoth.interface.game_display - it's still a table with the same keys as before
  • wesnoth.get_displayed_unit renamed to wesnoth.interface.get_displayed_unit
  • wesnoth.zoom renamed to wesnoth.interface.zoom
  • wesnoth.gamestate_inspector renamed to gui.show_inspector
  • 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.erase_unit renamed to wesnoth.units.erase
  • wesnoth.copy_unit renamed to wesnoth.units.clone
  • wesnoth.extract_unit renamed to wesnoth.units.extract
  • wesnoth.advance_unit renamed to wesnoth.units.advance
  • wesnoth.add_modification renamed to wesnoth.units.add_modification
  • wesnoth.remove_modifications renamed to wesnoth.units.remove_modifications
  • wesnoth.unit_resistance renamed to wesnoth.units.resistance
  • wesnoth.unit_defense renamed to wesnoth.units.chance_to_be_hit
  • wesnoth.unit_movement_cost renamed to wesnoth.units.movement_on
  • wesnoth.unit_vision_cost renamed to wesnoth.units.vision_on
  • wesnoth.unit_jamming_cost renamed to wesnoth.units.jamming_on
  • wesnoth.unit_ability renamed to wesnoth.units.ability
  • wesnoth.transform_unit renamed to wesnoth.units.transform
  • wesnoth.select_unit renamed to wesnoth.units.select
  • wesnoth.create_unit renamed to wesnoth.units.create
  • wesnoth.get_unit renamed to wesnoth.units.get
  • wesnoth.get_units renamed to wesnoth.units.find_on_map
  • wesnoth.get_recall_units renamed to wesnoth.units.find_on_recall
  • 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_starting_location replaced by starting_location member in side data
  • wesnoth.is_enemy renamed to wesnoth.sides.is_enemy
  • wesnoth.match_side renamed to wesnoth.sides.matches
  • wesnoth.set_side_id renamed to wesnoth.sides.set_id
  • wesnoth.append_ai renamed to wesnoth.sides.append_ai
  • wesnoth.debug_ai renamed to wesnoth.sides.debug_ai
  • wesnoth.switch_ai renamed to wesnoth.sides.switch_ai
  • wesnoth.add_ai_component renamed to wesnoth.sides.add_ai_component
  • wesnoth.delete_ai_component renamed to wesnoth.sides.delete_ai_component
  • wesnoth.change_ai_component renamed to wesnoth.sides.change_ai_component
  • wesnoth.get_sides renamed to wesnoth.sides.find
  • wesnoth.tovconfig renamed to wml.tovconfig
  • 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.show_menu renamed to gui.show_menu
  • 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.show_message_box renamed to gui.show_prompt
  • wesnoth.alert renamed to gui.alert
  • wesnoth.confirm renamed to gui.confirm
  • wesnoth.show_lua_console renamed to gui.show_lua_console
  • wesnoth.add_widget_definition renamed to gui.add_widget_definition
  • wesnoth.format renamed to stringx.vformat and can also be called directly on a string literal
  • wesnoth.format_conjunct_list renamed to stringx.format_conjunct_list
  • wesnoth.format_disjunct_list renamed to stringx.format_disjunct_list


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


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.distance_between renamed to wesnoth.map.distance_between
  • helper.get_child renamed to wml.get_child
  • helper.get_nth_child renamed to wml.get_nth_child
  • helper.child_count renamed to wml.child_count
  • helper.child_range renamed to wml.child_range
  • helper.child_array renamed to wml.child_array
  • helper.get_variable_array renamed to wml.array_access.get
  • helper.set_variable_array renamed to wml.array_access.set
  • helper.get_variable_proxy_array renamed to wml.array_access.get_proxy
  • helper.wml_error renamed to wml.error
  • helper.move_unit_fake renamed to wesnoth.interface.move_unit_fake
  • helper.modify_unit renamed to wesnoth.units.modify
  • helper.find_attack renamed to wesnoth.units.find_attack
  • helper.literal renamed to wml.literal
  • helper.parsed renamed to wml.parsed
  • helper.shallow_literal renamed to wml.shallow_literal
  • helper.shallow_parsed renamed to wml.shallow_parsed
  • 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_tag_metatable replaced with wml.tag, which is a table that works exactly the same as what this function would return
  • helper.get_user_choice renamed to gui.get_user_choice

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

  • items.remove renamed to wesnoth.interface.remove_item
  • items.place_image renamed to wesnoth.interface.add_item_image
  • items.place_halo renamed to wesnoth.interface.add_item_halo
This page was last edited on 16 October 2020, at 12:51.