LuaWML/Reorganization
This is a proposal to clean up and reorganize the existing set of Lua functions, helpers, tables, and proxy tables into a coherent, organized API, separated by category. The global wesnoth table would be the access point for the API categories, with subtables for each category within it from which the specific API item can be accessed (these subtables will essentially each represent a namespace). The idea would be to deprecate, but not immediately remove, the old access points, keeping them as valid aliases for a few versions to ensure backwards compatibility for developers and content creators and allowing them time to switch over.
The status of this document is currently an unapproved draft proposal pending discussion, consensus, and implementation. If and when these changes are implemented, LuaWML should be kept intact to (a) temporarily serve as documentation for the deprecated access points and (b) permanently describe the [lua] tag and its usage. The new "Lua API" should then be documented on its own page by the same name.
Some portions of the original proposal have already been implemented (though not always in precisely the proposed manner). These portions have been removed from this document; see the page history for more information on removed portions.
Most names will remain the same, but some will be changed for consistency (ex: anything previously referring to a "tile" now refers to a "hex"), accuracy (ex: "theme_items" has nothing to do with themes or items), or because their category makes part of their name redundant (ex: "wesnoth.get_unit" is now "wesnoth.units.get")
Note also that the metatable functions are planned to be modified to no longer require a table to be passed in for use, and simply return a proxy table for whatever kind of metatable is being created, and as such, their names will be radically changed in this proposal to reflect their primary purpose (to get a proxy table which behaves a certain way). This also raises the question of why exactly certain data need to have a proxy returned from some creation function (such as the proxy for working with WML variables), and certain others are available through direct access to proxy tables (such as sides, game config, current, etc.), and others yes are modified through getters and/or setters despite being heavily id-based and thus prime candidates for proxy table usage (such as traits and eras). There is also the question of missing functionality and providing access to data which should be available but is not. These topics can and should be discussed and fleshed out as well, but are beyond the current scope of this document, which is to perform a one-to-one reorganization of existing functionality.
In addition, the author of this proposal is very much aware that there are likely to be a great deal of differing opinions on how such a reorganization should take place, and therefore a discussion has been opened on the forum. Specific topics that are not set in stone are:
- Whether ALL API items should be within a category
- Whether the wesnoth table should, indeed, be the ONLY global table in the API
- Whether there should be a "misc" category for stuff that doesn't fit nicely anywhere else
- The specific names and categorizations of each specific API item
- Should the scope be expanded to drop functions and proxies which no longer make sense?
- Should the scope be expanded to modify the behavior of existing functions or proxies to make things more consistent?
- Pretty much anything and everything else about this proposal, indeed, all the way down to "should we even DO this at all?"
The categories and names being proposed are as follows:
Contents
string
APIs for manipulation of strings
| Old Access Point | New Access Point | Comments |
|---|---|---|
| wesnoth.textdomain | wesnoth.string.textdomain |
output
APIs for the output of text messages
| Old Access Point | New Access Point | Comments |
|---|---|---|
| wesnoth.message | wesnoth.output.message | |
| wesnoth.clear_messages | wesnoth.output.clear_messages | |
| wesnoth.log | wesnoth.output.log |
sound
APIs relating to sound
| Old Access Point | New Access Point | Comments |
|---|---|---|
| wesnoth.play_sound | wesnoth.sound.play | |
| wesnoth.set_music | wesnoth.sound.set_music | wesnoth.music.set or wesnoth.music.play? |
| wesnoth.add_sound_source | wesnoth.sound.add_source | |
| wesnoth.remove_sound_source | wesnoth.sound.remove_source | |
| wesnoth.get_sound_source | wesnoth.sound.get_source |
map
APIs for working with the game map
| Old Access Point | New Access Point | Comments |
|---|---|---|
| wesnoth.get_map_size | wesnoth.map.get_size | |
| wesnoth.get_terrain | wesnoth.map.get_terrain | |
| wesnoth.set_terrain | wesnoth.map.set_terrain | |
| wesnoth.get_locations | wesnoth.map.get_locations | |
| wesnoth.get_villages | wesnoth.map.get_villages | |
| wesnoth.get_village_owner | wesnoth.map.get_village_owner | |
| wesnoth.set_village_owner | wesnoth.map.set_village_owner | |
| wesnoth.match_location | wesnoth.map.location_matches | |
| wesnoth.add_fog | wesnoth.map.add_fog | |
| wesnoth.remove_fog | wesnoth.map.remove_fog | |
| wesnoth.get_time_of_day | wesnoth.map.get_time_of_day | |
| wesnoth.add_time_area | wesnoth.map.add_time_area | |
| wesnoth.remove_time_area | wesnoth.map.remove_time_area | |
| wesnoth.get_starting_location | wesnoth.map.get_side_starting_location | |
| wesnoth.find_path | wesnoth.map.find_path | |
| wesnoth.find_vacant_tile | wesnoth.map.find_vacant_hex | |
| wesnoth.find_reach | wesnoth.map.find_reach | |
| wesnoth.find_cost_map | wesnoth.map.find_cost_map | |
| helper.distance_between | wesnoth.map.distance_between | |
| helper.adjacent_tiles | wesnoth.map.adjacent_hex_iterator |
file
APIs for working with files
| Old Access Point | New Access Point | Comments |
|---|---|---|
| wesnoth.dofile | wesnoth.file.run | Should this remain as "dofile", which is the standard name used by lua? |
| wesnoth.require | wesnoth.file.require | |
| wesnoth.read_file | wesnoth.file.read | |
| wesnoth.get_image_size | wesnoth.file.image_size | |
| wesnoth.have_file | wesnoth.file.exists |
game
APIs for working with game states and data
| Old Access Point | New Access Point | Comments |
|---|---|---|
| wesnoth.game_config | wesnoth.game.config | |
| wesnoth.get_era | wesnoth.game.get_era | Should this be somewhere else? If so, where? |
| wesnoth.current | wesnoth.game.current | |
| wesnoth.synchronize_choice | wesnoth.game.synchronize | |
| wesnoth.set_next_scenario | wesnoth.game.set_next_scenario | Should this be somewhere else? If so, where? |
| wesnoth.name_generator | wesnoth.game.name_generator | Should this be somewhere else? If so, where? |
| wesnoth.compare_versions | wesnoth.game.compare_versions | Should this be somewhere else? If so, where? |
| wesnoth.get_time_stamp | wesnoth.game.get_time_stamp | Should this be somewhere else? If so, where? |
| wesnoth.get_terrain_info | wesnoth.game.get_terrain_info | Should this be in map? |
| wesnoth.simulate_combat | wesnoth.game.simulate_combat | Should this be in unit? |
| wesnoth.get_traits | wesnoth.game.get_traits | Should this be in unit? |
| wesnoth.races | wesnoth.game.races | Should this be somewhere else? If so, where? |
| wesnoth.game_events | wesnoth.game.events | Should this be somewhere else? If so, where? |
formula
APIs for working with Wesnoth Formula Language
| Old Access Point | New Access Point | Comments |
|---|---|---|
| wesnoth.eval_formula | wesnoth.formula.evaluate | |
| wesnoth.compile_formula | wesnoth.formula.compile |
math
Mathematical APIs
| Old Access Point | New Access Point | Comments |
|---|---|---|
| wesnoth.random | wesnoth.math.random | |
| helper.rand | wesnoth.math.randvar | |
| helper.round | wesnoth.math.round | |
| helper.shuffle | wesnoth.math.shuffle |
action
APIs for working with WML actions
| Old Access Point | New Access Point | Comments |
|---|---|---|
| wesnoth.fire | wesnoth.action.execute | |
| wesnoth.wml_actions | wesnoth.action.tags | |
| helper.set_wml_action_metatable | wesnoth.action.get_execution_table |
event
APIs for working with WML events
| Old Access Point | New Access Point | Comments |
|---|---|---|
| wesnoth.fire_event | wesnoth.event.fire | |
| wesnoth.fire_event_by_id | wesnoth.event.fire_by_id | |
| wesnoth.add_event_handler | wesnoth.event.add_handler | |
| wesnoth.remove_event_handler | wesnoth.event.remove_handler |
conditional
APIs for working with WML conditionals
| Old Access Point | New Access Point | Comments |
|---|---|---|
| wesnoth.wml_conditionals | wesnoth.conditional.tags | |
| wesnoth.eval_conditional | wesnoth.conditional.evaluate |
effect
APIs for working with WML effects
| Old Access Point | New Access Point | Comments |
|---|---|---|
| wesnoth.effects | wesnoth.effect.types |