Difference between revisions of "LuaWML/Reorganization"

From The Battle for Wesnoth Wiki
(action: no idea how that lost its prefix)
(analogous to namespaces)
Line 1: Line 1:
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. 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.
+
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.
 
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.

Revision as of 01:40, 6 November 2016

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.

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.unit.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
  • 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:

variable

APIs for dealing with WML variables

Old Access Point New Access Point Comments
wesnoth.get_variable wesnoth.variable.get
wesnoth.set_variable wesnoth.variable.set
wesnoth.get_all_vars wesnoth.variable.get_all
helper.set_wml_var_metatable wesnoth.variable.get_proxy
helper.get_variable_array wesnoth.variable.get_array
helper.set_variable_array wesnoth.variable.set_array
helper.get_variable_proxy_array wesnoth.variable.get_proxy_array

wml

APIs for dealing with wml tables and vconfigs

Old Access Point New Access Point Comments
helper.get_child wesnoth.wml.get_child
helper.get_nth_child wesnoth.wml.get_nth_child
helper.child_count wesnoth.wml.child_count
helper.child_range wesnoth.wml.child_range
helper.child_array wesnoth.wml.child_array
wesnoth.tovconfig wesnoth.wml.tovconfig
helper.literal wesnoth.wml.literal
helper.parsed wesnoth.wml.parsed
helper.shallow_literal wesnoth.wml.shallow_literal
helper.shallow_parsed wesnoth.wml.shallow_parsed
wesnoth.debug wesnoth.wml.debug
helper.set_wml_tag_metatable wesnoth.wml.get_tag_creator

interface

APIs for dealing with the main game interface

Old Access Point New Access Point Comments
wesnoth.delay wesnoth.interface.delay
wesnoth.float_label wesnoth.interface.float_label
wesnoth.select_hex wesnoth.interface.select_hex
wesnoth.select_unit wesnoth.interface.select_unit
wesnoth.highlight_hex wesnoth.interface.highlight_hex
wesnoth.deselect_hex wesnoth.interface.deselect_hex
wesnoth.get_selected_tile wesnoth.map.get_selected_hex
wesnoth.scroll_to_tile wesnoth.interface.scroll_to_hex
wesnoth.lock_view wesnoth.interface.lock
wesnoth.view_locked wesnoth.interface.is_locked
wesnoth.is_skipping_messages wesnoth.interface.is_skipping_messages
wesnoth.skip_messages wesnoth.interface.skip_messages
wesnoth.add_tile_overlay wesnoth.interface.add_hex_overlay
wesnoth.remove_tile_overlay wesnoth.interface.remove_hex_overlay
items.place_image wesnoth.interface.add_item_image
items.place_halo wesnoth.interface.add_item_halo
items.remove wesnoth.interface.remove_item
wesnoth.theme_items wesnoth.interface.game_display
helper.move_unit_fake wesnoth.interface.move_unit_fake

dialog

GUI2 APIs

Old Access Point New Access Point Comments
wesnoth.show_message_dialog wesnoth.dialog.show_message
wesnoth.show_popup_dialog wesnoth.dialog.show_popup
wesnoth.show_dialog wesnoth.dialog.show
wesnoth.set_dialog_value wesnoth.dialog.set_value
wesnoth.get_dialog_value wesnoth.dialog.get_value
wesnoth.set_dialog_active wesnoth.dialog.set_active
wesnoth.set_dialog_callback wesnoth.dialog.set_callback
wesnoth.set_dialog_markup wesnoth.dialog.set_markup
wesnoth.set_dialog_focus wesnoth.dialog.set_focus
wesnoth.set_dialog_visible wesnoth.dialog.set_visible
wesnoth.set_dialog_canvas wesnoth.dialog.set_canvas
wesnoth.add_dialog_tree_node wesnoth.dialog.add_tree_node
wesnoth.remove_dialog_item wesnoth.dialog.remove_item
wesnoth.get_displayed_unit wesnoth.dialog.get_displayed_unit
helper.get_user_choice wesnoth.dialog.get_user_choice

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
helper.wml_error wesnoth.output.wml_error
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.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

unit

APIs for working with unit data

Old Access Point New Access Point Comments
wesnoth.get_units wesnoth.unit.get_array
wesnoth.get_unit wesnoth.unit.get
wesnoth.match_unit wesnoth.unit.matches
wesnoth.put_unit wesnoth.unit.put
wesnoth.erase_unit wesnoth.unit.erase
wesnoth.get_recall_units wesnoth.unit.get_recall
wesnoth.put_recall_unit wesnoth.unit.put_recall
wesnoth.create_unit wesnoth.unit.create
wesnoth.copy_unit wesnoth.unit.copy
wesnoth.extract_unit wesnoth.unit.extract
wesnoth.advance_unit wesnoth.unit.advance
wesnoth.add_modification wesnoth.unit.add_modification
wesnoth.unit_resistance wesnoth.unit.resistance
wesnoth.unit_defense wesnoth.unit.defense
wesnoth.unit_movement_cost wesnoth.unit.movement_cost
wesnoth.unit_vision_cost wesnoth.unit.vision_cost
wesnoth.unit_jamming_cost wesnoth.unit.jamming_cost
wesnoth.unit_ability wesnoth.unit.ability
wesnoth.unit_types wesnoth.unit.types
wesnoth.transform_unit wesnoth.unit.transform
helper.modify_unit wesnoth.unit.modify_unit

side

APIs for working with sides

Old Access Point New Access Point Comments
wesnoth.sides wesnoth.side.proxy
wesnoth.get_sides wesnoth.side.get
wesnoth.is_enemy wesnoth.side.is_enemy
wesnoth.match_side wesnoth.side.matches
helper.all_teams wesnoth.side.iterator

file

APIs for working with files

Old Access Point New Access Point Comments
wesnoth.dofile wesnoth.file.run
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

location_set

Class for working with sets of locations

Since this is already nicely compartmentalized, the only proposed change is to move it to wesnoth.location_set rather than being global.

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