src/command_func.h

   1 /*
   2  * This file is part of OpenTTD.
   3  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   4  * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   5  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   6  */
   7
   8 /** @file command_func.h Functions related to commands. */
   9
  10 #ifndef COMMAND_FUNC_H
  11 #define COMMAND_FUNC_H
  12
  13 #include "command_type.h"
  14 #include "network/network_type.h"
  15 #include "company_type.h"
  16 #include "company_func.h"
  17 #include "core/backup_type.hpp"
  18 #include "misc/endian_buffer.hpp"
  19 #include "tile_map.h"
  20
  21 /**
  22  * Define a default return value for a failed command.
  23  *
  24  * This variable contains a CommandCost object with is declared as "failed".
  25  * Other functions just need to return this error if there is an error,
  26  * which doesn't need to specific by a StringID.
  27  */
  28 static const CommandCost CMD_ERROR = CommandCost(INVALID_STRING_ID);
  29
  30 /**
  31  * Returns from a function with a specific StringID as error.
  32  *
  33  * This macro is used to return from a function. The parameter contains the
  34  * StringID which will be returned.
  35  *
  36  * @param errcode The StringID to return
  37  */
  38 #define return_cmd_error(errcode) return CommandCost(errcode);
  39
  40 void NetworkSendCommand(Commands cmd, StringID err_message, CommandCallback *callback, CompanyID company, TileIndex location, const CommandDataBuffer &cmd_data);
  41
  42 extern Money _additional_cash_required;
  43
  44 bool IsValidCommand(Commands cmd);
  45 CommandFlags GetCommandFlags(Commands cmd);
  46 const char *GetCommandName(Commands cmd);
  47 Money GetAvailableMoneyForCommand();
  48 bool IsCommandAllowedWhilePaused(Commands cmd);
  49
  50 template <Commands Tcmd>
  51 constexpr CommandFlags GetCommandFlags()
  52 {
  53         return CommandTraits<Tcmd>::flags;
  54 }
  55
  56 /**
  57  * Extracts the DC flags needed for DoCommand from the flags returned by GetCommandFlags
  58  * @param cmd_flags Flags from GetCommandFlags
  59  * @return flags for DoCommand
  60  */
  61 static constexpr inline DoCommandFlag CommandFlagsToDCFlags(CommandFlags cmd_flags)
  62 {
  63         DoCommandFlag flags = DC_NONE;
  64         if (cmd_flags & CMD_NO_WATER) flags |= DC_NO_WATER;
  65         if (cmd_flags & CMD_AUTO) flags |= DC_AUTO;
  66         if (cmd_flags & CMD_ALL_TILES) flags |= DC_ALL_TILES;
  67         return flags;
  68 }
  69
  70 /** Helper class to keep track of command nesting level. */
  71 struct RecursiveCommandCounter {
  72         RecursiveCommandCounter() noexcept { _counter++; }
  73         ~RecursiveCommandCounter() noexcept { _counter--; }
  74
  75         /** Are we in the top-level command execution? */
  76         bool IsTopLevel() const { return _counter == 1; }
  77 private:
  78         static int _counter;
  79 };
  80
  81
  82 template<Commands TCmd, typename T> struct CommandHelper;
  83
  84 class CommandHelperBase {
  85 protected:
  86         static void InternalDoBefore(bool top_level, bool test);
  87         static void InternalDoAfter(CommandCost &res, DoCommandFlag flags, bool top_level, bool test);
  88         static std::tuple<bool, bool, bool> InternalPostBefore(Commands cmd, CommandFlags flags, TileIndex tile, StringID err_message, bool network_command);
  89         static void InternalPostResult(const CommandCost &res, TileIndex tile, bool estimate_only, bool only_sending, StringID err_message, bool my_cmd);
  90         static bool InternalExecutePrepTest(CommandFlags cmd_flags, TileIndex tile, Backup<CompanyID> &cur_company);
  91         static std::tuple<bool, bool, bool> InternalExecuteValidateTestAndPrepExec(CommandCost &res, CommandFlags cmd_flags, bool estimate_only, bool network_command, Backup<CompanyID> &cur_company);
  92         static CommandCost InternalExecuteProcessResult(Commands cmd, CommandFlags cmd_flags, const CommandCost &res_test, const CommandCost &res_exec, TileIndex tile, Backup<CompanyID> &cur_company);
  93         static void LogCommandExecution(Commands cmd, StringID err_message, TileIndex tile, const CommandDataBuffer &args, bool failed);
  94 };
  95
  96 /**
  97  * Templated wrapper that exposes the command parameter arguments
  98  * for the various Command::Do/Post calls.
  99  * @tparam Tcmd The command-id to execute.
 100  * @tparam Targs The command parameter types.
 101  */
 102 template <Commands Tcmd, typename... Targs>
 103 struct CommandHelper<Tcmd, CommandCost(*)(DoCommandFlag, Targs...)> : protected CommandHelperBase {
 104 public:
 105         /**
 106          * This function executes a given command with the parameters from the #CommandProc parameter list.
 107          * Depending on the flags parameter it executes or tests a command.
 108          *
 109          * @note This function is to be called from the StateGameLoop or from within the execution of a Command.
 110          * This function must not be called from the context of a "player" (real person, AI, game script).
 111          * Use ::Post for commands directly triggered by "players".
 112          *
 113          * @param flags Flags for the command and how to execute the command
 114          * @param args Parameters for the command
 115          * @see CommandProc
 116          * @return the cost
 117          */
 118         static CommandCost Do(DoCommandFlag flags, Targs... args)
 119         {
 120                 if constexpr (std::is_same_v<TileIndex, std::tuple_element_t<0, std::tuple<Targs...>>>) {
 121                         /* Do not even think about executing out-of-bounds tile-commands. */
 122                         TileIndex tile = std::get<0>(std::make_tuple(args...));
 123                         if (tile != 0 && (tile >= MapSize() || (!IsValidTile(tile) && (flags & DC_ALL_TILES) == 0))) return CMD_ERROR;
 124                 }
 125
 126                 RecursiveCommandCounter counter{};
 127
 128                 /* Only execute the test call if it's toplevel, or we're not execing. */
 129                 if (counter.IsTopLevel() || !(flags & DC_EXEC)) {
 130                         InternalDoBefore(counter.IsTopLevel(), true);
 131                         CommandCost res = CommandTraits<Tcmd>::proc(flags & ~DC_EXEC, args...);
 132                         InternalDoAfter(res, flags, counter.IsTopLevel(), true); // Can modify res.
 133
 134                         if (res.Failed() || !(flags & DC_EXEC)) return res;
 135                 }
 136
 137                 /* Execute the command here. All cost-relevant functions set the expenses type
 138                  * themselves to the cost object at some point. */
 139                 InternalDoBefore(counter.IsTopLevel(), false);
 140                 CommandCost res = CommandTraits<Tcmd>::proc(flags, args...);
 141                 InternalDoAfter(res, flags, counter.IsTopLevel(), false);
 142
 143                 return res;
 144         }
 145
 146         /**
 147          * Shortcut for the long Post when not using a callback.
 148          * @param err_message Message prefix to show on error
 149          * @param args Parameters for the command
 150          */
 151         static inline bool Post(StringID err_message, Targs... args) { return Post(err_message, nullptr, std::forward<Targs>(args)...); }
 152         /**
 153          * Shortcut for the long Post when not using an error message.
 154          * @param callback A callback function to call after the command is finished
 155          * @param args Parameters for the command
 156          */
 157         static inline bool Post(CommandCallback *callback, Targs... args) { return Post((StringID)0, callback, std::forward<Targs>(args)...); }
 158         /**
 159          * Shortcut for the long Post when not using a callback or an error message.
 160          * @param args Parameters for the command
 161          */
 162         static inline bool Post(Targs... args) { return Post((StringID)0, nullptr, std::forward<Targs>(args)...); }
 163
 164         /**
 165          * Top-level network safe command execution for the current company.
 166          * Must not be called recursively. The callback is called when the
 167          * command succeeded or failed.
 168          *
 169          * @param err_message Message prefix to show on error
 170          * @param callback A callback function to call after the command is finished
 171          * @param args Parameters for the command
 172          * @return \c true if the command succeeded, else \c false.
 173          */
 174         static bool Post(StringID err_message, CommandCallback *callback, Targs... args)
 175         {
 176                 return InternalPost(err_message, callback, true, false, std::forward_as_tuple(args...));
 177         }
 178
 179         /**
 180          * Execute a command coming from the network.
 181          * @param err_message Message prefix to show on error
 182          * @param callback A callback function to call after the command is finished
 183          * @param my_cmd indicator if the command is from a company or server (to display error messages for a user)
 184          * @param location Tile location for user feedback.
 185          * @param args Parameters for the command
 186          * @return \c true if the command succeeded, else \c false.
 187          */
 188         static bool PostFromNet(StringID err_message, CommandCallback *callback, bool my_cmd, TileIndex location, std::tuple<Targs...> args)
 189         {
 190                 return InternalPost(err_message, callback, my_cmd, true, location, std::move(args));
 191         }
 192
 193         /**
 194          * Prepare a command to be send over the network
 195          * @param cmd The command to execute (a CMD_* value)
 196          * @param err_message Message prefix to show on error
 197          * @param callback A callback function to call after the command is finished
 198          * @param company The company that wants to send the command
 199          * @param args Parameters for the command
 200          */
 201         static void SendNet(StringID err_message, CommandCallback *callback, CompanyID company, Targs... args)
 202         {
 203                 auto args_tuple = std::forward_as_tuple(args...);
 204
 205                 TileIndex tile{};
 206                 if constexpr (std::is_same_v<TileIndex, std::tuple_element_t<0, decltype(args_tuple)>>) {
 207                         tile = std::get<0>(args_tuple);
 208                 }
 209
 210                 ::NetworkSendCommand(Tcmd, err_message, callback, _current_company, tile, EndianBufferWriter<CommandDataBuffer>::FromValue(args_tuple));
 211         }
 212
 213         /**
 214          * Top-level network safe command execution without safety checks.
 215          * @param err_message Message prefix to show on error
 216          * @param callback A callback function to call after the command is finished
 217          * @param my_cmd indicator if the command is from a company or server (to display error messages for a user)
 218          * @param estimate_only whether to give only the estimate or also execute the command
 219          * @param location Tile location for user feedback.
 220          * @param args Parameters for the command
 221          * @return the command cost of this function.
 222          */
 223         static CommandCost Unsafe(StringID err_message, CommandCallback *callback, bool my_cmd, bool estimate_only, TileIndex location, std::tuple<Targs...> args)
 224         {
 225                 return Execute(err_message, callback, my_cmd, estimate_only, false, location, std::move(args));
 226         }
 227
 228 protected:
 229         /** Helper to process a single ClientID argument. */
 230         template <class T>
 231         static inline void SetClientIdHelper(T &data)
 232         {
 233                 if constexpr (std::is_same_v<ClientID, T>) {
 234                         if (data == INVALID_CLIENT_ID) data = CLIENT_ID_SERVER;
 235                 }
 236         }
 237
 238         /** Set all invalid ClientID's to the proper value. */
 239         template<class Ttuple, size_t... Tindices>
 240         static inline void SetClientIds(Ttuple &values, std::index_sequence<Tindices...>)
 241         {
 242                 ((SetClientIdHelper(std::get<Tindices>(values))), ...);
 243         }
 244
 245         static bool InternalPost(StringID err_message, CommandCallback *callback, bool my_cmd, bool network_command, std::tuple<Targs...> args)
 246         {
 247                 /* Where to show the message? */
 248                 TileIndex tile{};
 249                 if constexpr (std::is_same_v<TileIndex, std::tuple_element_t<0, decltype(args)>>) {
 250                         tile = std::get<0>(args);
 251                 }
 252
 253                 return InternalPost(err_message, callback, my_cmd, network_command, tile, std::move(args));
 254         }
 255
 256         static bool InternalPost(StringID err_message, CommandCallback *callback, bool my_cmd, bool network_command, TileIndex tile, std::tuple<Targs...> args)
 257         {
 258                 auto [err, estimate_only, only_sending] = InternalPostBefore(Tcmd, GetCommandFlags<Tcmd>(), tile, err_message, network_command);
 259                 if (err) return false;
 260
 261                 /* Only set client IDs when the command does not come from the network. */
 262                 if (!network_command && GetCommandFlags<Tcmd>() & CMD_CLIENT_ID) SetClientIds(args, std::index_sequence_for<Targs...>{});
 263
 264                 CommandCost res = Execute(err_message, callback, my_cmd, estimate_only, network_command, tile, args);
 265                 InternalPostResult(res, tile, estimate_only, only_sending, err_message, my_cmd);
 266
 267                 if (!estimate_only && !only_sending && callback != nullptr) {
 268                         callback(Tcmd, res, tile, EndianBufferWriter<CommandDataBuffer>::FromValue(args));
 269                 }
 270
 271                 return res.Succeeded();
 272         }
 273
 274         /** Helper to process a single ClientID argument. */
 275         template <class T>
 276         static inline bool ClientIdIsSet(T &data)
 277         {
 278                 if constexpr (std::is_same_v<ClientID, T>) {
 279                         return data != INVALID_CLIENT_ID;
 280                 } else {
 281                         return true;
 282                 }
 283         }
 284
 285         /** Check if all ClientID arguments are set to valid values. */
 286         template<class Ttuple, size_t... Tindices>
 287         static inline bool AllClientIdsSet(Ttuple &values, std::index_sequence<Tindices...>)
 288         {
 289                 return (ClientIdIsSet(std::get<Tindices>(values)) && ...);
 290         }
 291
 292         static CommandCost Execute(StringID err_message, CommandCallback *callback, bool my_cmd, bool estimate_only, bool network_command, TileIndex tile, std::tuple<Targs...> args)
 293         {
 294                 /* Prevent recursion; it gives a mess over the network */
 295                 RecursiveCommandCounter counter{};
 296                 assert(counter.IsTopLevel());
 297
 298                 /* Command flags are used internally */
 299                 constexpr CommandFlags cmd_flags = GetCommandFlags<Tcmd>();
 300
 301                 if constexpr ((cmd_flags & CMD_CLIENT_ID) != 0) {
 302                         /* Make sure arguments are properly set to a ClientID also when processing external commands. */
 303                         assert(AllClientIdsSet(args, std::index_sequence_for<Targs...>{}));
 304                 }
 305
 306                 Backup<CompanyID> cur_company(_current_company, FILE_LINE);
 307                 if (!InternalExecutePrepTest(cmd_flags, tile, cur_company)) {
 308                         cur_company.Trash();
 309                         return CMD_ERROR;
 310                 }
 311
 312                 /* Test the command. */
 313                 DoCommandFlag flags = CommandFlagsToDCFlags(cmd_flags);
 314                 CommandCost res = std::apply(CommandTraits<Tcmd>::proc, std::tuple_cat(std::make_tuple(flags), args));
 315
 316                 auto [exit_test, desync_log, send_net] = InternalExecuteValidateTestAndPrepExec(res, cmd_flags, estimate_only, network_command, cur_company);
 317                 if (exit_test) {
 318                         if (desync_log) LogCommandExecution(Tcmd, err_message, tile, EndianBufferWriter<CommandDataBuffer>::FromValue(args), true);
 319                         cur_company.Restore();
 320                         return res;
 321                 }
 322
 323                 /* If we are in network, and the command is not from the network
 324                  * send it to the command-queue and abort execution. */
 325                 if (send_net) {
 326                         ::NetworkSendCommand(Tcmd, err_message, callback, _current_company, tile, EndianBufferWriter<CommandDataBuffer>::FromValue(args));
 327                         cur_company.Restore();
 328
 329                         /* Don't return anything special here; no error, no costs.
 330                          * This way it's not handled by DoCommand and only the
 331                          * actual execution of the command causes messages. Also
 332                          * reset the storages as we've not executed the command. */
 333                         return CommandCost();
 334                 }
 335
 336                 if (desync_log) LogCommandExecution(Tcmd, err_message, tile, EndianBufferWriter<CommandDataBuffer>::FromValue(args), false);
 337
 338                 /* Actually try and execute the command. */
 339                 CommandCost res2 = std::apply(CommandTraits<Tcmd>::proc, std::tuple_cat(std::make_tuple(flags | DC_EXEC), args));
 340
 341                 return InternalExecuteProcessResult(Tcmd, cmd_flags, res, res2, tile, cur_company);
 342         }
 343 };
 344
 345 template <Commands Tcmd>
 346 using Command = CommandHelper<Tcmd, typename CommandTraits<Tcmd>::ProcType>;
 347
 348 #endif /* COMMAND_FUNC_H */