The Battle for Wesnoth  1.17.23+dev
Go to the documentation of this file.
1 /*
2  Copyright (C) 2009 - 2023
3  by Guillaume Melquiond <>
4  Part of the Battle for Wesnoth Project
6  This program is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 2 of the License, or
9  (at your option) any later version.
10  This program is distributed in the hope that it will be useful,
13  See the COPYING file for more details.
14 */
16 #pragma once
18 #include "scripting/lua_kernel_base.hpp" // for lua_kernel_base
20 #include "game_events/action_wml.hpp" // for wml_action, etc
22 #include <stack>
23 #include <string> // for string
25 class config;
26 class game_config_view;
27 class unit;
28 class vconfig;
29 namespace ai { class engine_lua; }
30 namespace ai { class lua_ai_action_handler; }
31 namespace ai { class lua_ai_context; }
32 namespace game_events { struct queued_event; }
34 class game_display;
35 class game_state;
36 class game_board;
37 class unit_map;
38 class gamemap;
39 class team;
40 class game_data;
41 class tod_manager;
42 class play_controller;
43 class reports;
45 struct map_location;
46 typedef int (*lua_CFunction) (lua_State *L);
49 {
55  // Private functions to ease access to parts of game_state
56  unit_map & units();
57  game_data & gamedata();
58  tod_manager & tod_man();
62  bool has_preloaded_ = false;
64  std::stack<game_events::queued_event const * > queued_events_;
69  static std::vector<config> preload_scripts;
72  friend class game_config_manager; // to allow it to call extract_preload_scripts
74  // Private lua callbacks
75  int intf_allow_end_turn(lua_State *);
76  int intf_allow_undo(lua_State *);
77  int intf_cancel_action(lua_State *);
78  int intf_add_time_area(lua_State *);
79  int intf_remove_time_area(lua_State *);
80  int intf_get_time_area(lua_State *);
81  int intf_animate_unit(lua_State *);
82  int intf_gamestate_inspector(lua_State *);
83  int impl_run_animation(lua_State *);
84  int intf_create_animator(lua_State *);
85  int intf_get_unit(lua_State *);
86  int intf_get_units(lua_State *);
87  int intf_get_displayed_unit(lua_State*);
88  int intf_match_unit(lua_State *L);
89  int intf_get_recall_units(lua_State *L);
90  int intf_get_variable(lua_State *L);
91  int intf_set_variable(lua_State *L);
92  int intf_highlight_hex(lua_State *L);
93  int intf_is_enemy(lua_State *L);
94  int intf_unit_ability(lua_State *L);
95  int intf_view_locked(lua_State *L);
96  int intf_lock_view(lua_State *L);
97  int impl_get_terrain_info(lua_State *L);
98  template<bool consider_illuminates>
99  int intf_get_time_of_day(lua_State *L);
100  int impl_schedule_get(lua_State *L);
101  int impl_schedule_len(lua_State *L);
102  void luaW_push_schedule(lua_State* L, int area_index);
103  int intf_get_village_owner(lua_State *L);
104  int intf_set_village_owner(lua_State *L);
105  int intf_get_mouseover_tile(lua_State *L);
106  int intf_get_selected_tile(lua_State *L);
107  int impl_game_config_get(lua_State *L) override;
108  int impl_game_config_set(lua_State *L) override;
109  int impl_scenario_get(lua_State *L);
110  int impl_scenario_set(lua_State *L);
111  int impl_current_get(lua_State *L);
112  int intf_clear_messages(lua_State*);
113  int impl_end_level_data_set(lua_State*);
114  int intf_end_turn(lua_State*);
115  int intf_find_cost_map(lua_State *L);
116  int intf_find_path(lua_State *L);
117  int intf_find_reach(lua_State *L);
118  int intf_find_vision_range(lua_State *L);
119  int intf_heal_unit(lua_State *L);
120  int intf_message(lua_State *L);
121  int intf_play_sound(lua_State *L);
122  int intf_set_achievement(lua_State *L);
123  int intf_has_achievement(lua_State *L);
124  int intf_has_sub_achievement(lua_State *L);
125  int intf_get_achievement(lua_State *L);
126  int intf_progress_achievement(lua_State *L);
127  int intf_set_sub_achievement(lua_State *L);
128  int intf_set_floating_label(lua_State* L, bool spawn);
129  int intf_remove_floating_label(lua_State* L);
130  int intf_move_floating_label(lua_State* L);
131  void put_unit_helper(const map_location& loc);
132  int intf_put_unit(lua_State *L);
133  int intf_erase_unit(lua_State *L);
134  int intf_put_recall_unit(lua_State *L);
135  int intf_extract_unit(lua_State *L);
136  int intf_find_vacant_tile(lua_State *L);
137  int intf_float_label(lua_State *L);
138  int intf_set_end_campaign_credits(lua_State *L);
139  int intf_set_end_campaign_text(lua_State *L);
140  int intf_clear_menu_item(lua_State *L);
141  int intf_create_side(lua_State *L);
142  int intf_set_menu_item(lua_State *L);
143  int intf_toggle_shroud(lua_State *L, bool place_shroud);
144  int intf_override_shroud(lua_State *L);
145  int intf_simulate_combat(lua_State *L);
146  int intf_scroll_to_tile(lua_State *L);
147  int intf_select_unit(lua_State *L);
148  int intf_deselect_hex(lua_State *L);
149  int intf_is_skipping_messages(lua_State *L);
150  int intf_skip_messages(lua_State *L);
151  int intf_get_locations(lua_State *L);
152  int intf_match_location(lua_State *L);
153  int intf_match_side(lua_State *L);
154  int intf_set_side_id(lua_State *L);
155  int intf_modify_ai_wml(lua_State *L);
156  int intf_get_sides(lua_State* L);
157  int intf_get_side(lua_State* L);
158  int intf_add_tile_overlay(lua_State *L);
159  int intf_remove_tile_overlay(lua_State *L);
160  template<bool is_menu_item>
161  int intf_add_event_simple(lua_State* L);
162  int intf_add_event_wml(lua_State* L);
163  int intf_add_event(lua_State *L);
164  int intf_add_undo_actions(lua_State *L);
165  int cfun_undoable_event(lua_State *L);
166  int intf_remove_event(lua_State *L);
167  int intf_color_adjust(lua_State *L);
168  int intf_get_color_adjust(lua_State *L);
169  int intf_screen_fade(lua_State *L);
170  int intf_delay(lua_State *L);
171  int intf_add_label(lua_State *L);
172  int intf_remove_label(lua_State *L);
173  int intf_get_label(lua_State* L);
174  int intf_redraw(lua_State *L);
175  int intf_replace_schedule(lua_State *l);
176  int impl_schedule_set(lua_State *L);
177  int intf_scroll(lua_State *L);
178  int intf_get_all_vars(lua_State *L);
179  int impl_theme_item(lua_State *L, std::string name);
180  int impl_theme_items_get(lua_State *L);
181  int impl_theme_items_set(lua_State *L);
182  int cfun_builtin_effect(lua_State *L);
183  int cfun_wml_action(lua_State *L);
184  int intf_fire_event(lua_State *L, const bool by_id);
185  int intf_fire_wml_menu_item(lua_State *L);
186  int intf_teleport(lua_State *L);
187  int intf_log(lua_State *L);
188  int intf_toggle_fog(lua_State *L, const bool clear);
189  int intf_get_fog_or_shroud(lua_State *L, bool fog);
190  int intf_log_replay(lua_State* L);
191  int intf_zoom(lua_State* L);
193  //private helpers
194  std::string synced_state();
195  void lua_chat(const std::string& caption, const std::string& msg);
196  std::vector<int> get_sides_vector(const vconfig& cfg);
198 public:
199  game_board & board();
200  std::vector<team> & teams();
201  const gamemap & map() const;
202  game_display * get_display() const { return game_display_; }
203  /**
204  A value != 0 means that the shouldn't remove any units from the map, usually because
205  we are currently operating on a unit& and removing it might cause memory corruptions
206  note that we don't check for the dtor of lua owned units because we assume that
207  we operate on such a unit that the lua function that invoked the operation on that unit
208  (like wesnoth.units.add_modification, wesnoth.units.matches ..) have a local copy of that
209  lua_unit* userdata in its stack that prevents it from being collected.
210  */
214  void set_game_display(game_display * gd);
216  virtual std::string my_name() override { return "Game Lua Kernel"; }
218  std::string apply_effect(const std::string& name, unit& u, const config& cfg, bool need_apply);
219  void initialize(const config& level);
220  void save_game(config & level);
221  void load_game(const config& level);
223  void custom_command(const std::string&, const config&);
224  void push_builtin_effect();
225  void set_wml_action(const std::string&, game_events::wml_action::handler);
226  void set_wml_condition(const std::string&, bool(*)(const vconfig&));
227  bool run_wml_action(const std::string&, const vconfig&,
229  bool run_filter(char const *name, const unit& u);
230  bool run_filter(char const *name, const map_location& l);
231  bool run_filter(char const *name, const team& t);
232  bool run_filter(char const *name, int nArgs);
233  bool run_wml_conditional(const std::string&, const vconfig&);
234  /**
235  * Store a WML event in the Lua registry, as a function.
236  * Uses a default function that interprets ActionWML.
237  * @return A unique index into the EVENT_TABLE within the Lua registry
238  */
239  int save_wml_event();
240  /**
241  * Store a WML event in the Lua registry, as a function.
242  * Compiles the function from the given code.
243  * @param name The event name, used to generate a chunk name for the compiled function
244  * @param id The event id, used to generate a chunk name for the compiled function
245  * @param code The actual code of the function
246  * @return A unique index into the EVENT_TABLE within the Lua registry
247  */
248  int save_wml_event(const std::string& name, const std::string& id, const std::string& code);
249  /**
250  * Store a WML event in the Lua registry, as a function.
251  * Uses the function at the specified Lua stack index.
252  * @param idx The Lua stack index of the function to store
253  * @return A unique index into the EVENT_TABLE within the Lua registry
254  */
255  int save_wml_event(int idx);
256  /**
257  * Clear a WML event store in the Lua registry.
258  * @param ref The unique index into the EVENT_TABLE within the Lua registry
259  */
260  void clear_wml_event(int ref);
261  /**
262  * Run a WML stored in the Lua registry.
263  * @param ref The unique index into the EVENT_TABLE within the Lua registry
264  * @param args Arguments to pass to the event function, as a config
265  * @param ev The event data for the event being fired
266  * @param out If non-null, receives the result of the called function (provided it is a boolean value)
267  * @return Whether the function was successfully called; could be false if @a ref was invalid or if the function raised an error
268  */
269  bool run_wml_event(int ref, const vconfig& args, const game_events::queued_event& ev, bool* out = nullptr);
271  virtual void log_error(char const* msg, char const* context = "Lua error") override;
273  ai::lua_ai_context* create_lua_ai_context(char const *code, ai::engine_lua *engine);
276  void mouse_over_hex_callback(const map_location& loc);
277  bool mouse_button_callback(const map_location& loc, const std::string &button, const std::string &event);
278  void select_hex_callback(const map_location& loc);
280 };
Define actions for the game's events mechanism.
double t
Definition: astarsearch.cpp:65
Proxy class for calling AI action handlers defined in Lua.
Definition: core.hpp:71
Proxy table for the AI context.
Definition: core.hpp:34
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:161
Game board class.
Definition: game_board.hpp:53
A class grating read only view to a vector of config objects, viewed as one config with all children ...
void(* handler)(const queued_event &, const vconfig &)
Definition: action_wml.hpp:50
int intf_get_mouseover_tile(lua_State *L)
Returns the currently overed tile.
void custom_command(const std::string &, const config &)
int intf_put_unit(lua_State *L)
Places a unit on the map.
int intf_get_label(lua_State *L)
int intf_cancel_action(lua_State *)
int intf_set_floating_label(lua_State *L, bool spawn)
Arg 1: text - string Arg 2: options table.
int intf_replace_schedule(lua_State *l)
Replacing the current time of day schedule.
int intf_select_unit(lua_State *L)
Selects and highlights the given location on the map.
int intf_deselect_hex(lua_State *L)
Deselects any highlighted hex on the map.
std::stack< game_events::queued_event const * > queued_events_
int intf_get_all_vars(lua_State *L)
Gets all the WML variables currently set.
int intf_remove_tile_overlay(lua_State *L)
Removes an overlay from a tile.
int intf_screen_fade(lua_State *L)
int intf_set_end_campaign_credits(lua_State *L)
int intf_erase_unit(lua_State *L)
Erases a unit from the map.
int intf_get_fog_or_shroud(lua_State *L, bool fog)
int intf_override_shroud(lua_State *L)
Overrides the shroud entirely.
int intf_get_variable(lua_State *L)
Gets a WML variable.
int intf_scroll(lua_State *L)
game_lua_kernel(game_state &, play_controller &, reports &)
int intf_set_sub_achievement(lua_State *L)
Marks a single sub-achievement as completed.
int intf_lock_view(lua_State *L)
Sets whether gamemap scrolling is disabled for the user.
void put_unit_helper(const map_location &loc)
int intf_toggle_shroud(lua_State *L, bool place_shroud)
Toggle shroud on some locations Arg 1: Side number Arg 2: List of locations on which to place/remove ...
int intf_match_side(lua_State *L)
Matches a side against the given filter.
int intf_get_selected_tile(lua_State *L)
Returns the currently selected tile.
int cfun_wml_action(lua_State *L)
Executes its upvalue as a wml action.
virtual void log_error(char const *msg, char const *context="Lua error") override
Error reporting mechanisms, used by virtual methods protected_call and load_string.
int cfun_builtin_effect(lua_State *L)
Applies its upvalue as an effect Arg 1: The unit to apply to Arg 3: The [effect] tag contents Arg 3: ...
ai::lua_ai_context * create_lua_ai_context(char const *code, ai::engine_lua *engine)
int intf_has_achievement(lua_State *L)
Returns whether an achievement has been completed.
int intf_gamestate_inspector(lua_State *)
int intf_float_label(lua_State *L)
Floats some text on the map.
tod_manager & tod_man()
int intf_find_reach(lua_State *L)
Finds all the locations reachable by a unit.
bool run_event(const game_events::queued_event &)
Executes the game_events.on_event function.
int intf_end_turn(lua_State *)
int save_wml_event()
Store a WML event in the Lua registry, as a function.
int intf_set_achievement(lua_State *L)
Sets an achievement as being completed.
int intf_get_units(lua_State *)
Gets all the units matching a given filter.
int intf_color_adjust(lua_State *L)
int intf_redraw(lua_State *L)
int intf_set_village_owner(lua_State *L)
Sets the owner of a village.
static config preload_config
int intf_find_cost_map(lua_State *L)
Is called with one or more units and builds a cost map.
int intf_get_time_area(lua_State *)
int intf_highlight_hex(lua_State *L)
Highlights the given location on the map.
bool run_wml_event(int ref, const vconfig &args, const game_events::queued_event &ev, bool *out=nullptr)
Run a WML stored in the Lua registry.
int intf_scroll_to_tile(lua_State *L)
Scrolls to given tile.
int intf_get_side(lua_State *L)
int intf_remove_event(lua_State *L)
int intf_is_enemy(lua_State *L)
Returns whether the first side is an enemy of the second one.
static void extract_preload_scripts(const game_config_view &game_config)
int impl_get_terrain_info(lua_State *L)
Gets details about a terrain.
virtual std::string my_name() override
User-visible name of the lua kernel that they are talking to.
int intf_remove_label(lua_State *L)
bool run_wml_action(const std::string &, const vconfig &, const game_events::queued_event &)
Runs a command from an event handler.
int intf_move_floating_label(lua_State *L)
int intf_match_unit(lua_State *L)
Matches a unit against the given filter.
int intf_add_time_area(lua_State *)
Adding new time_areas dynamically with Standard Location Filters.
int intf_set_end_campaign_text(lua_State *L)
void clear_wml_event(int ref)
Clear a WML event store in the Lua registry.
int intf_create_animator(lua_State *)
int intf_add_event_wml(lua_State *L)
Add a new event handler Arg: A full event specification as a WML config.
int impl_scenario_set(lua_State *L)
Sets some scenario data (__newindex metamethod).
int intf_message(lua_State *L)
Displays a message in the chat window and in the logs.
int intf_set_side_id(lua_State *L)
int intf_view_locked(lua_State *L)
Gets whether gamemap scrolling is disabled for the user.
int intf_get_displayed_unit(lua_State *)
Gets the unit displayed in the sidebar.
bool run_wml_conditional(const std::string &, const vconfig &)
Evaluates a WML conidition.
int intf_get_recall_units(lua_State *L)
Gets the numeric ids of all the units matching a given filter on the recall lists.
int intf_add_label(lua_State *L)
int intf_zoom(lua_State *L)
int intf_log_replay(lua_State *L)
const game_events::queued_event & get_event_info()
int intf_unit_ability(lua_State *L)
Returns true if the unit has the given ability enabled.
void push_builtin_effect()
Registers a function for use as an effect handler.
int impl_run_animation(lua_State *)
std::string apply_effect(const std::string &name, unit &u, const config &cfg, bool need_apply)
game_board & board()
int intf_fire_wml_menu_item(lua_State *L)
Fires a wml menu item.
int intf_clear_menu_item(lua_State *L)
void mouse_over_hex_callback(const map_location &loc)
int impl_theme_items_get(lua_State *L)
Creates a field of the theme_items table and returns it (__index metamethod).
int intf_find_vacant_tile(lua_State *L)
Finds a vacant tile.
play_controller & play_controller_
const gamemap & map() const
int map_locked_
A value != 0 means that the shouldn't remove any units from the map, usually because we are currently...
static std::vector< config > preload_scripts
int intf_get_unit(lua_State *)
Gets the unit at the given location or with the given id.
int impl_current_get(lua_State *L)
Gets some data about current point of game (__index metamethod).
int impl_schedule_set(lua_State *L)
void select_hex_callback(const map_location &loc)
void set_wml_condition(const std::string &, bool(*)(const vconfig &))
Registers a function for use as a conditional handler.
game_state & game_state_
int impl_end_level_data_set(lua_State *)
std::string synced_state()
converts synced_context::get_synced_state() to a string.
int intf_find_path(lua_State *L)
Finds a path between two locations.
int intf_remove_floating_label(lua_State *L)
int intf_animate_unit(lua_State *)
void set_wml_action(const std::string &, game_events::wml_action::handler)
Registers a function for use as an action handler.
int intf_put_recall_unit(lua_State *L)
Puts a unit on a recall list.
int intf_teleport(lua_State *L)
Teeleports a unit to a location.
void luaW_push_schedule(lua_State *L, int area_index)
int intf_add_tile_overlay(lua_State *L)
Adds an overlay on a tile.
int intf_play_sound(lua_State *L)
Plays a sound, possibly repeated.
void lua_chat(const std::string &caption, const std::string &msg)
int intf_allow_end_turn(lua_State *)
Allow undo sets the flag saying whether the event has mutated the game to false.
int intf_get_village_owner(lua_State *L)
Gets the side of a village owner.
int intf_heal_unit(lua_State *L)
int intf_get_sides(lua_State *L)
Returns a proxy table array for all sides matching the given SSF.
int intf_has_sub_achievement(lua_State *L)
Returns whether an achievement has been completed.
int intf_create_side(lua_State *L)
void initialize(const config &level)
int intf_add_undo_actions(lua_State *L)
Add undo actions for the current active event Arg 1: Either a table of ActionWML or a function to cal...
int impl_game_config_set(lua_State *L) override
Sets some game_config data (__newindex metamethod).
void save_game(config &level)
Executes the game_events.on_save function and adds to cfg the returned tags.
int impl_scenario_get(lua_State *L)
Gets some scenario data (__index metamethod).
int intf_remove_time_area(lua_State *)
Removing new time_areas dynamically with Standard Location Filters.
int impl_schedule_len(lua_State *L)
int intf_get_locations(lua_State *L)
Gets all the locations matching a given filter.
int intf_add_event(lua_State *L)
Add a new event handler Arg 1: Table of options.
int intf_simulate_combat(lua_State *L)
Simulates a combat between two units.
std::vector< team > & teams()
int intf_progress_achievement(lua_State *L)
Progresses the provided achievement.
int intf_match_location(lua_State *L)
Matches a location against the given filter.
int intf_toggle_fog(lua_State *L, const bool clear)
Implements the lifting and resetting of fog via WML.
int intf_extract_unit(lua_State *L)
Extracts a unit from the map or a recall list and gives it to Lua.
int intf_log(lua_State *L)
Logs a message Arg 1: (optional) Logger; "wml" for WML errors or deprecations Arg 2: Message Arg 3: W...
int intf_clear_messages(lua_State *)
Removes all messages from the chat window.
int intf_modify_ai_wml(lua_State *L)
int intf_allow_undo(lua_State *)
Allow undo sets the flag saying whether the event has mutated the game to false.
int impl_schedule_get(lua_State *L)
int intf_set_variable(lua_State *L)
Sets a WML variable.
int impl_theme_items_set(lua_State *L)
Sets a field of the theme_items table (__newindex metamethod).
void set_game_display(game_display *gd)
int intf_set_menu_item(lua_State *L)
game_display * get_display() const
ai::lua_ai_action_handler * create_lua_ai_action_handler(char const *code, ai::lua_ai_context &context)
int impl_theme_item(lua_State *L, std::string name)
Executes its upvalue as a theme item generator.
bool mouse_button_callback(const map_location &loc, const std::string &button, const std::string &event)
int intf_get_achievement(lua_State *L)
Returns information on a single achievement, or no data if the achievement is not found.
std::vector< int > get_sides_vector(const vconfig &cfg)
Gets a vector of sides from side= attribute in a given config node.
int intf_fire_event(lua_State *L, const bool by_id)
Fires an event.
int intf_delay(lua_State *L)
Delays engine for a while.
int intf_add_event_simple(lua_State *L)
Add a new event handler Arg 1: Event to handle, as a string or list of strings; or menu item ID if th...
bool run_filter(char const *name, const unit &u)
Runs a script from a unit filter.
int intf_find_vision_range(lua_State *L)
Finds all the locations for which a given unit would remove the fog (if there was fog on the map).
int intf_skip_messages(lua_State *L)
Set whether to skip messages Arg 1 (optional) - boolean.
int impl_game_config_get(lua_State *L) override
Gets some game_config data (__index metamethod).
game_display * game_display_
int cfun_undoable_event(lua_State *L)
Upvalue 1: The event function Upvalue 2: The undo function Arg 1: The event content.
void load_game(const config &level)
Executes the game_events.on_load function and passes to it all the scenario tags not yet handled.
int intf_get_time_of_day(lua_State *L)
Gets time of day information.
game_data & gamedata()
int intf_get_color_adjust(lua_State *L)
int intf_is_skipping_messages(lua_State *L)
Return true if a replay is in progress but the player has chosen to skip it.
Encapsulates the map of the game.
Definition: map.hpp:172
This class stores all the data for a single 'side' (in game nomenclature).
Definition: team.hpp:76
Container associating units to locations.
Definition: map.hpp:99
This class represents a single unit of a specific type.
Definition: unit.hpp:135
A variable-expanding proxy for the config class.
Definition: variable.hpp:45
int(* lua_CFunction)(lua_State *L)
A small explanation about what's going on here: Each action has access to two game_info objects First...
Definition: actions.cpp:61
void clear()
Clear the current render target.
Definition: draw.cpp:41
Game configuration data as global variables.
Definition: build_info.cpp:63
Domain specific events.
bool fog()
Definition: game.cpp:525
Unit and team statistics.
static void msg(const char *act, debug_info &i, const char *to="", const char *result="")
Definition: debugger.cpp:110
Encapsulates the map of the game.
Definition: location.hpp:38