diff --git a/Doxyfile b/Doxyfile index bd0e4f48e9..6eb9d1232b 100644 --- a/Doxyfile +++ b/Doxyfile @@ -5,7 +5,6 @@ PROJECT_NAME = openttd OUTPUT_DIRECTORY = docs/source/ CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English -USE_WINDOWS_ENCODING = NO BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES ABBREVIATE_BRIEF = "The $name class" \ @@ -186,13 +185,13 @@ PERLMOD_MAKEVAR_PREFIX = # Configuration options related to the preprocessor #--------------------------------------------------------------------------- ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = NO -EXPAND_ONLY_PREDEF = NO +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES SEARCH_INCLUDES = YES INCLUDE_PATH = INCLUDE_FILE_PATTERNS = PREDEFINED = -EXPAND_AS_DEFINED = +EXPAND_AS_DEFINED = DEF_COMMAND SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- # Configuration::additions related to external references @@ -221,8 +220,6 @@ DIRECTORY_GRAPH = YES DOT_IMAGE_FORMAT = png DOT_PATH = DOTFILE_DIRS = -MAX_DOT_GRAPH_WIDTH = 1024 -MAX_DOT_GRAPH_HEIGHT = 1024 MAX_DOT_GRAPH_DEPTH = 1000 DOT_TRANSPARENT = NO DOT_MULTI_TARGETS = NO diff --git a/src/command.cpp b/src/command.cpp index 6d26279e22..ca7f950cf1 100644 --- a/src/command.cpp +++ b/src/command.cpp @@ -16,8 +16,17 @@ #include "variables.h" #include "genworld.h" -const char* _cmd_text = NULL; - +const char *_cmd_text = NULL; + +/** + * Helper macro to define the header of all command handler macros. + * + * This macro create the function header for a given command handler function, as + * all command handler functions got the parameters from the #CommandProc callback + * type. + * + * @param yyyy The desired function name of the new command handler function. + */ #define DEF_COMMAND(yyyy) CommandCost yyyy(TileIndex tile, uint32 flags, uint32 p1, uint32 p2) DEF_COMMAND(CmdBuildRailroadTrack); @@ -181,166 +190,178 @@ DEF_COMMAND(CmdMoveOrder); DEF_COMMAND(CmdChangeTimetable); DEF_COMMAND(CmdSetVehicleOnTime); DEF_COMMAND(CmdAutofillTimetable); - -/* The master command table */ +#undef DEF_COMMAND + +/** + * The master command table + * + * This table contains all possible CommandProc functions with + * the flags which belongs to it. The indizes are the same + * as the value from the CMD_* enums. + */ static const Command _command_proc_table[] = { - {CmdBuildRailroadTrack, CMD_AUTO}, /* 0 */ - {CmdRemoveRailroadTrack, CMD_AUTO}, /* 1 */ - {CmdBuildSingleRail, CMD_AUTO}, /* 2 */ - {CmdRemoveSingleRail, CMD_AUTO}, /* 3 */ - {CmdLandscapeClear, 0}, /* 4 */ - {CmdBuildBridge, CMD_AUTO}, /* 5 */ - {CmdBuildRailroadStation, CMD_AUTO}, /* 6 */ - {CmdBuildTrainDepot, CMD_AUTO}, /* 7 */ - {CmdBuildSingleSignal, CMD_AUTO}, /* 8 */ - {CmdRemoveSingleSignal, CMD_AUTO}, /* 9 */ - {CmdTerraformLand, CMD_AUTO}, /* 10 */ - {CmdPurchaseLandArea, CMD_AUTO}, /* 11 */ - {CmdSellLandArea, 0}, /* 12 */ - {CmdBuildTunnel, CMD_AUTO}, /* 13 */ - {CmdRemoveFromRailroadStation, 0}, /* 14 */ - {CmdConvertRail, 0}, /* 15 */ - {CmdBuildTrainWaypoint, 0}, /* 16 */ - {CmdRenameWaypoint, 0}, /* 17 */ - {CmdRemoveTrainWaypoint, 0}, /* 18 */ - {NULL, 0}, /* 19 */ - {NULL, 0}, /* 20 */ - {CmdBuildRoadStop, CMD_AUTO}, /* 21 */ - {CmdRemoveRoadStop, 0}, /* 22 */ - {CmdBuildLongRoad, CMD_AUTO}, /* 23 */ - {CmdRemoveLongRoad, CMD_AUTO}, /* 24 */ - {CmdBuildRoad, 0}, /* 25 */ - {CmdRemoveRoad, 0}, /* 26 */ - {CmdBuildRoadDepot, CMD_AUTO}, /* 27 */ - {NULL, 0}, /* 28 */ - {CmdBuildAirport, CMD_AUTO}, /* 29 */ - {CmdBuildDock, CMD_AUTO}, /* 30 */ - {CmdBuildShipDepot, CMD_AUTO}, /* 31 */ - {CmdBuildBuoy, CMD_AUTO}, /* 32 */ - {CmdPlantTree, CMD_AUTO}, /* 33 */ - {CmdBuildRailVehicle, 0}, /* 34 */ - {CmdMoveRailVehicle, 0}, /* 35 */ - {CmdStartStopTrain, 0}, /* 36 */ - {NULL, 0}, /* 37 */ - {CmdSellRailWagon, 0}, /* 38 */ - {CmdSendTrainToDepot, 0}, /* 39 */ - {CmdForceTrainProceed, 0}, /* 40 */ - {CmdReverseTrainDirection, 0}, /* 41 */ - - {CmdModifyOrder, 0}, /* 42 */ - {CmdSkipToOrder, 0}, /* 43 */ - {CmdDeleteOrder, 0}, /* 44 */ - {CmdInsertOrder, 0}, /* 45 */ - - {CmdChangeServiceInt, 0}, /* 46 */ - - {CmdBuildIndustry, 0}, /* 47 */ - {CmdBuildCompanyHQ, CMD_AUTO}, /* 48 */ - {CmdSetPlayerFace, 0}, /* 49 */ - {CmdSetPlayerColor, 0}, /* 50 */ - - {CmdIncreaseLoan, 0}, /* 51 */ - {CmdDecreaseLoan, 0}, /* 52 */ - - {CmdWantEnginePreview, 0}, /* 53 */ - - {CmdNameVehicle, 0}, /* 54 */ - {CmdRenameEngine, 0}, /* 55 */ - - {CmdChangeCompanyName, 0}, /* 56 */ - {CmdChangePresidentName, 0}, /* 57 */ - - {CmdRenameStation, 0}, /* 58 */ - - {CmdSellAircraft, 0}, /* 59 */ - {CmdStartStopAircraft, 0}, /* 60 */ - - {CmdBuildAircraft, 0}, /* 61 */ - {CmdSendAircraftToHangar, 0}, /* 62 */ - {NULL, 0}, /* 63 */ - {CmdRefitAircraft, 0}, /* 64 */ - - {CmdPlaceSign, 0}, /* 65 */ - {CmdRenameSign, 0}, /* 66 */ - - {CmdBuildRoadVeh, 0}, /* 67 */ - {CmdStartStopRoadVeh, 0}, /* 68 */ - {CmdSellRoadVeh, 0}, /* 69 */ - {CmdSendRoadVehToDepot, 0}, /* 70 */ - {CmdTurnRoadVeh, 0}, /* 71 */ - {CmdRefitRoadVeh, 0}, /* 72 */ - - {CmdPause, CMD_SERVER}, /* 73 */ - - {CmdBuyShareInCompany, 0}, /* 74 */ - {CmdSellShareInCompany, 0}, /* 75 */ - {CmdBuyCompany, 0}, /* 76 */ - - {CmdBuildTown, CMD_OFFLINE}, /* 77 */ - {NULL, 0}, /* 78 */ - {NULL, 0}, /* 79 */ - {CmdRenameTown, CMD_SERVER}, /* 80 */ - {CmdDoTownAction, 0}, /* 81 */ - - {CmdSetRoadDriveSide, CMD_SERVER}, /* 82 */ - {NULL, 0}, /* 83 */ - {NULL, 0}, /* 84 */ - {CmdChangeDifficultyLevel, CMD_SERVER}, /* 85 */ - - {CmdStartStopShip, 0}, /* 86 */ - {CmdSellShip, 0}, /* 87 */ - {CmdBuildShip, 0}, /* 88 */ - {CmdSendShipToDepot, 0}, /* 89 */ - {NULL, 0}, /* 90 */ - {CmdRefitShip, 0}, /* 91 */ - - {NULL, 0}, /* 92 */ - {NULL, 0}, /* 93 */ - {NULL, 0}, /* 94 */ - {NULL, 0}, /* 95 */ - {NULL, 0}, /* 96 */ - {NULL, 0}, /* 97 */ - - {CmdOrderRefit, 0}, /* 98 */ - {CmdCloneOrder, 0}, /* 99 */ - - {CmdClearArea, 0}, /* 100 */ - {NULL, 0}, /* 101 */ - - {CmdMoneyCheat, CMD_OFFLINE}, /* 102 */ - {CmdBuildCanal, CMD_AUTO}, /* 103 */ - {CmdPlayerCtrl, 0}, /* 104 */ - - {CmdLevelLand, CMD_AUTO}, /* 105 */ - - {CmdRefitRailVehicle, 0}, /* 106 */ - {CmdRestoreOrderIndex, 0}, /* 107 */ - {CmdBuildLock, CMD_AUTO}, /* 108 */ - {NULL, 0}, /* 109 */ - {CmdBuildSignalTrack, CMD_AUTO}, /* 110 */ - {CmdRemoveSignalTrack, CMD_AUTO}, /* 111 */ - {NULL, 0}, /* 112 */ - {CmdGiveMoney, 0}, /* 113 */ - {CmdChangePatchSetting, CMD_SERVER}, /* 114 */ - {CmdSetAutoReplace, 0}, /* 115 */ - {CmdCloneVehicle, 0}, /* 116 */ - {CmdMassStartStopVehicle, 0}, /* 117 */ - {CmdDepotSellAllVehicles, 0}, /* 118 */ - {CmdDepotMassAutoReplace, 0}, /* 119 */ - {CmdCreateGroup, 0}, /* 120 */ - {CmdDeleteGroup, 0}, /* 121 */ - {CmdRenameGroup, 0}, /* 122 */ - {CmdAddVehicleGroup, 0}, /* 123 */ - {CmdAddSharedVehicleGroup, 0}, /* 124 */ - {CmdRemoveAllVehiclesGroup, 0}, /* 125 */ - {CmdSetGroupReplaceProtection, 0}, /* 126 */ - {CmdMoveOrder, 0}, /* 127 */ - {CmdChangeTimetable, 0}, /* 128 */ - {CmdSetVehicleOnTime, 0}, /* 129 */ - {CmdAutofillTimetable, 0}, /* 130 */ + {CmdBuildRailroadTrack, CMD_AUTO}, /* 0, CMD_BUILD_RAILROAD_TRACK */ + {CmdRemoveRailroadTrack, CMD_AUTO}, /* 1, CMD_REMOVE_RAILROAD_TRACK */ + {CmdBuildSingleRail, CMD_AUTO}, /* 2, CMD_BUILD_SINGLE_RAIL */ + {CmdRemoveSingleRail, CMD_AUTO}, /* 3, CMD_REMOVE_SINGLE_RAIL */ + {CmdLandscapeClear, 0}, /* 4, CMD_LANDSCAPE_CLEAR */ + {CmdBuildBridge, CMD_AUTO}, /* 5, CMD_BUILD_BRIDGE */ + {CmdBuildRailroadStation, CMD_AUTO}, /* 6, CMD_BUILD_RAILROAD_STATION */ + {CmdBuildTrainDepot, CMD_AUTO}, /* 7, CMD_BUILD_TRAIN_DEPOT */ + {CmdBuildSingleSignal, CMD_AUTO}, /* 8, CMD_BUILD_SIGNALS */ + {CmdRemoveSingleSignal, CMD_AUTO}, /* 9, CMD_REMOVE_SIGNALS */ + {CmdTerraformLand, CMD_AUTO}, /* 10, CMD_TERRAFORM_LAND */ + {CmdPurchaseLandArea, CMD_AUTO}, /* 11, CMD_PURCHASE_LAND_AREA */ + {CmdSellLandArea, 0}, /* 12, CMD_SELL_LAND_AREA */ + {CmdBuildTunnel, CMD_AUTO}, /* 13, CMD_BUILD_TUNNEL */ + {CmdRemoveFromRailroadStation, 0}, /* 14, CMD_REMOVE_FROM_RAILROAD_STATION */ + {CmdConvertRail, 0}, /* 15, CMD_CONVERT_RAILD */ + {CmdBuildTrainWaypoint, 0}, /* 16, CMD_BUILD_TRAIN_WAYPOINT */ + {CmdRenameWaypoint, 0}, /* 17, CMD_RENAME_WAYPOINT */ + {CmdRemoveTrainWaypoint, 0}, /* 18, CMD_REMOVE_TRAIN_WAYPOINT */ + {NULL, 0}, /* 19, unused */ + {NULL, 0}, /* 20, unused */ + {CmdBuildRoadStop, CMD_AUTO}, /* 21, CMD_BUILD_ROAD_STOP */ + {CmdRemoveRoadStop, 0}, /* 22, CMD_REMOVE_ROAD_STOP */ + {CmdBuildLongRoad, CMD_AUTO}, /* 23, CMD_BUILD_LONG_ROAD */ + {CmdRemoveLongRoad, CMD_AUTO}, /* 24, CMD_REMOVE_LONG_ROAD */ + {CmdBuildRoad, 0}, /* 25, CMD_BUILD_ROAD */ + {CmdRemoveRoad, 0}, /* 26, CMD_REMOVE_ROAD */ + {CmdBuildRoadDepot, CMD_AUTO}, /* 27, CMD_BUILD_ROAD_DEPOT */ + {NULL, 0}, /* 28, unused */ + {CmdBuildAirport, CMD_AUTO}, /* 29, CMD_BUILD_AIRPORT */ + {CmdBuildDock, CMD_AUTO}, /* 30, CMD_BUILD_DOCK */ + {CmdBuildShipDepot, CMD_AUTO}, /* 31, CMD_BUILD_SHIP_DEPOT */ + {CmdBuildBuoy, CMD_AUTO}, /* 32, CMD_BUILD_BUOY */ + {CmdPlantTree, CMD_AUTO}, /* 33, CMD_PLANT_TREE */ + {CmdBuildRailVehicle, 0}, /* 34, CMD_BUILD_RAIL_VEHICLE */ + {CmdMoveRailVehicle, 0}, /* 35, CMD_MOVE_RAIL_VEHICLE */ + {CmdStartStopTrain, 0}, /* 36, CMD_START_STOP_TRAIN */ + {NULL, 0}, /* 37, unused */ + {CmdSellRailWagon, 0}, /* 38, CMD_SELL_RAIL_WAGON */ + {CmdSendTrainToDepot, 0}, /* 39, CMD_SEND_TRAIN_TO_DEPOT */ + {CmdForceTrainProceed, 0}, /* 40, CMD_FORCE_TRAIN_PROCEED */ + {CmdReverseTrainDirection, 0}, /* 41, CMD_REVERSE_TRAIN_DIRECTION */ + + {CmdModifyOrder, 0}, /* 42, CMD_MODIFY_ORDER */ + {CmdSkipToOrder, 0}, /* 43, CMD_SKIP_TO_ORDER */ + {CmdDeleteOrder, 0}, /* 44, CMD_DELETE_ORDER */ + {CmdInsertOrder, 0}, /* 45, CMD_INSERT_ORDER */ + + {CmdChangeServiceInt, 0}, /* 46, CMD_CHANGE_SERVICE_INT */ + + {CmdBuildIndustry, 0}, /* 47, CMD_BUILD_INDUSTRY */ + {CmdBuildCompanyHQ, CMD_AUTO}, /* 48, CMD_BUILD_COMPANY_HQ */ + {CmdSetPlayerFace, 0}, /* 49, CMD_SET_PLAYER_FACE */ + {CmdSetPlayerColor, 0}, /* 50, CMD_SET_PLAYER_COLOR */ + + {CmdIncreaseLoan, 0}, /* 51, CMD_INCREASE_LOAN */ + {CmdDecreaseLoan, 0}, /* 52, CMD_DECREASE_LOAN */ + + {CmdWantEnginePreview, 0}, /* 53, CMD_WANT_ENGINE_PREVIEW */ + + {CmdNameVehicle, 0}, /* 54, CMD_NAME_VEHICLE */ + {CmdRenameEngine, 0}, /* 55, CMD_RENAME_ENGINE */ + + {CmdChangeCompanyName, 0}, /* 56, CMD_CHANGE_COMPANY_NAME */ + {CmdChangePresidentName, 0}, /* 57, CMD_CHANGE_PRESIDENT_NAME */ + + {CmdRenameStation, 0}, /* 58, CMD_RENAME_STATION */ + + {CmdSellAircraft, 0}, /* 59, CMD_SELL_AIRCRAFT */ + {CmdStartStopAircraft, 0}, /* 60, CMD_START_STOP_AIRCRAFT */ + + {CmdBuildAircraft, 0}, /* 61, CMD_BUILD_AIRCRAFT */ + {CmdSendAircraftToHangar, 0}, /* 62, CMD_SEND_AIRCRAFT_TO_HANGAR */ + {NULL, 0}, /* 63, unused */ + {CmdRefitAircraft, 0}, /* 64, CMD_REFIT_AIRCRAFT */ + + {CmdPlaceSign, 0}, /* 65, CMD_PLACE_SIGN */ + {CmdRenameSign, 0}, /* 66, CMD_RENAME_SIGN */ + + {CmdBuildRoadVeh, 0}, /* 67, CMD_BUILD_ROAD_VEH */ + {CmdStartStopRoadVeh, 0}, /* 68, CMD_START_STOP_ROADVEH */ + {CmdSellRoadVeh, 0}, /* 69, CMD_SELL_ROAD_VEH */ + {CmdSendRoadVehToDepot, 0}, /* 70, CMD_SEND_ROADVEH_TO_DEPOT */ + {CmdTurnRoadVeh, 0}, /* 71, CMD_TURN_ROADVEH */ + {CmdRefitRoadVeh, 0}, /* 72, CMD_REFIT_ROAD_VEH */ + + {CmdPause, CMD_SERVER}, /* 73, CMD_PAUSE */ + + {CmdBuyShareInCompany, 0}, /* 74, CMD_BUY_SHARE_IN_COMPANY */ + {CmdSellShareInCompany, 0}, /* 75, CMD_SELL_SHARE_IN_COMPANY */ + {CmdBuyCompany, 0}, /* 76, CMD_BUY_COMANY */ + + {CmdBuildTown, CMD_OFFLINE}, /* 77, CMD_BUILD_TOWN */ + {NULL, 0}, /* 78, unused */ + {NULL, 0}, /* 79, unused */ + {CmdRenameTown, CMD_SERVER}, /* 80, CMD_RENAME_TOWN */ + {CmdDoTownAction, 0}, /* 81, CMD_DO_TOWN_ACTION */ + + {CmdSetRoadDriveSide, CMD_SERVER}, /* 82, CMD_SET_ROAD_DRIVE_SIDE */ + {NULL, 0}, /* 83, unused */ + {NULL, 0}, /* 84, unused */ + {CmdChangeDifficultyLevel, CMD_SERVER}, /* 85, CMD_CHANGE_DIFFICULTY_LEVEL */ + + {CmdStartStopShip, 0}, /* 86, CMD_START_STOP_SHIP */ + {CmdSellShip, 0}, /* 87, CMD_SELL_SHIP */ + {CmdBuildShip, 0}, /* 88, CMD_BUILD_SHIP */ + {CmdSendShipToDepot, 0}, /* 89, CMD_SEND_SHIP_TO_DEPOT */ + {NULL, 0}, /* 90, unused */ + {CmdRefitShip, 0}, /* 91, CMD_REFIT_SHIP */ + + {NULL, 0}, /* 92, unused */ + {NULL, 0}, /* 93, unused */ + {NULL, 0}, /* 94, unused */ + {NULL, 0}, /* 95, unused */ + {NULL, 0}, /* 96, unused */ + {NULL, 0}, /* 97, unused */ + + {CmdOrderRefit, 0}, /* 98, CMD_ORDER_REFIT */ + {CmdCloneOrder, 0}, /* 99, CMD_CLONE_ORDER */ + + {CmdClearArea, 0}, /* 100, CMD_CLEAR_AREA */ + {NULL, 0}, /* 101, unused */ + + {CmdMoneyCheat, CMD_OFFLINE}, /* 102, CMD_MONEY_CHEAT */ + {CmdBuildCanal, CMD_AUTO}, /* 103, CMD_BUILD_CANAL */ + {CmdPlayerCtrl, 0}, /* 104, CMD_PLAYER_CTRL */ + + {CmdLevelLand, CMD_AUTO}, /* 105, CMD_LEVEL_LAND */ + + {CmdRefitRailVehicle, 0}, /* 106, CMD_REFIT_RAIL_VEHICLE */ + {CmdRestoreOrderIndex, 0}, /* 107, CMD_RESTORE_ORDER_INDEX */ + {CmdBuildLock, CMD_AUTO}, /* 108, CMD_BUILD_LOCK */ + {NULL, 0}, /* 109, unused */ + {CmdBuildSignalTrack, CMD_AUTO}, /* 110, CMD_BUILD_SIGNAL_TRACK */ + {CmdRemoveSignalTrack, CMD_AUTO}, /* 111, CMD_REMOVE_SIGNAL_TRACK */ + {NULL, 0}, /* 112, unused */ + {CmdGiveMoney, 0}, /* 113, CMD_GIVE_MONEY */ + {CmdChangePatchSetting, CMD_SERVER}, /* 114, CMD_CHANGE_PATCH_SETTING */ + {CmdSetAutoReplace, 0}, /* 115, CMD_SET_AUTOREPLACE */ + {CmdCloneVehicle, 0}, /* 116, CMD_CLONE_VEHICLE */ + {CmdMassStartStopVehicle, 0}, /* 117, CMD_MASS_START_STOP */ + {CmdDepotSellAllVehicles, 0}, /* 118, CMD_DEPOT_SELL_ALL_VEHICLES */ + {CmdDepotMassAutoReplace, 0}, /* 119, CMD_DEPOT_MASS_AUTOREPLACE */ + {CmdCreateGroup, 0}, /* 120, CMD_CREATE_GROUP */ + {CmdDeleteGroup, 0}, /* 121, CMD_DELETE_GROUP */ + {CmdRenameGroup, 0}, /* 122, CMD_RENAME_GROUP */ + {CmdAddVehicleGroup, 0}, /* 123, CMD_ADD_VEHICLE_GROUP */ + {CmdAddSharedVehicleGroup, 0}, /* 124, CMD_ADD_SHARE_VEHICLE_GROUP */ + {CmdRemoveAllVehiclesGroup, 0}, /* 125, CMD_REMOVE_ALL_VEHICLES_GROUP */ + {CmdSetGroupReplaceProtection, 0}, /* 126, CMD_SET_GROUP_REPLACE_PROTECTION */ + {CmdMoveOrder, 0}, /* 127, CMD_MOVE_ORDER */ + {CmdChangeTimetable, 0}, /* 128, CMD_CHANGE_TIMETABLE */ + {CmdSetVehicleOnTime, 0}, /* 129, CMD_SET_VEHICLE_ON_TIME */ + {CmdAutofillTimetable, 0}, /* 130, CMD_AUTOFILL_TIMETABLE */ }; -/* This function range-checks a cmd, and checks if the cmd is not NULL */ +/*! + * This function range-checks a cmd, and checks if the cmd is not NULL + * + * @param cmd The integervalue of a command + * @return true if the command is valid (and got a CommandProc function) + */ bool IsValidCommand(uint cmd) { cmd &= 0xFF; @@ -350,14 +371,34 @@ bool IsValidCommand(uint cmd) _command_proc_table[cmd].proc != NULL; } +/*! + * This function mask the parameter with 0xFF and returns + * the flags which belongs to the given command. + * + * @param cmd The integer value of the command + * @return The flags for this command + * @bug integervalues which are less equals 0xFF and greater than the + * size of _command_proc_table can result in an index out of bounce + * error (which doesn't happend anyway). Check function #IsValidCommand(). (Progman) + */ byte GetCommandFlags(uint cmd) { return _command_proc_table[cmd & 0xFF].flags; } - static int _docommand_recursive; +/*! + * This function executes a given command with the parameters from the #CommandProc parameter list. + * Depending on the flags parameter it execute or test a command. + * + * @param tile The tile to apply the command on (for the #CommandProc) + * @param p1 Additional data for the command (for the #CommandProc) + * @param p2 Additional data for the command (for the #CommandProc) + * @param flags Flags for the command and how to execute the command + * @param procc The command-id to execute (a value of the CMD_* enums) + * @see CommandProc + */ CommandCost DoCommand(TileIndex tile, uint32 p1, uint32 p2, uint32 flags, uint procc) { CommandCost res; @@ -421,6 +462,13 @@ error: return res; } +/*! + * This functions returns the money which can be used to execute a command. + * This is either the money of the current player or INT64_MAX if there + * is no such a player "at the moment" like the server itself. + * + * @return The available money of a player or INT64_MAX + */ Money GetAvailableMoneyForCommand() { PlayerID pid = _current_player; @@ -428,8 +476,20 @@ Money GetAvailableMoneyForCommand() return GetPlayer(pid)->player_money; } -/* toplevel network safe docommand function for the current player. must not be called recursively. - * the callback is called when the command succeeded or failed. */ +/*! + * Toplevel network safe docommand function for the current player. Must not be called recursively. + * The callback is called when the command succeeded or failed. The parameters + * tile, p1 and p2 are from the #CommandProc function. The paramater cmd is the command to execute. + * The parameter my_cmd is used to indicate if the command is from a player or the server. + * + * @param tile The tile to perform a command on (see #CommandProc) + * @param p1 Additional data for the command (see #CommandProc) + * @param p2 Additional data for the command (see #CommandProc) + * @param callback A callback function to call after the command is finished + * @param cmd The command to execute (a CMD_* value) + * @param my_cmd indicator if the command is from a player or server (to display error messages for a user) + * @return true if the command succeeded, else false + */ bool DoCommandP(TileIndex tile, uint32 p1, uint32 p2, CommandCallback *callback, uint32 cmd, bool my_cmd) { CommandCost res, res2; diff --git a/src/command.h b/src/command.h index 2ae5661723..8a020ca13d 100644 --- a/src/command.h +++ b/src/command.h @@ -5,161 +5,176 @@ #ifndef COMMAND_H #define COMMAND_H +/** + * List of commands. + * + * This enum defines all possible commands which can be executed to the game + * engine. Observing the game like the query-tool or checking the profit of a + * vehicle don't result in a command which should be executed in the engine + * nor send to the server in a network game. + * + * @see _command_proc_table + */ enum { - CMD_BUILD_RAILROAD_TRACK = 0, - CMD_REMOVE_RAILROAD_TRACK = 1, - CMD_BUILD_SINGLE_RAIL = 2, - CMD_REMOVE_SINGLE_RAIL = 3, - CMD_LANDSCAPE_CLEAR = 4, - CMD_BUILD_BRIDGE = 5, - CMD_BUILD_RAILROAD_STATION = 6, - CMD_BUILD_TRAIN_DEPOT = 7, - CMD_BUILD_SIGNALS = 8, - CMD_REMOVE_SIGNALS = 9, - CMD_TERRAFORM_LAND = 10, - CMD_PURCHASE_LAND_AREA = 11, - CMD_SELL_LAND_AREA = 12, - CMD_BUILD_TUNNEL = 13, + CMD_BUILD_RAILROAD_TRACK = 0, ///< build a rail track + CMD_REMOVE_RAILROAD_TRACK = 1, ///< remove a rail track + CMD_BUILD_SINGLE_RAIL = 2, ///< build a single rail track + CMD_REMOVE_SINGLE_RAIL = 3, ///< remove a single rail track + CMD_LANDSCAPE_CLEAR = 4, ///< demolish a tile + CMD_BUILD_BRIDGE = 5, ///< build a bridge + CMD_BUILD_RAILROAD_STATION = 6, ///< build a railroad station + CMD_BUILD_TRAIN_DEPOT = 7, ///< build a train depot + CMD_BUILD_SIGNALS = 8, ///< build a signal + CMD_REMOVE_SIGNALS = 9, ///< remove a signal + CMD_TERRAFORM_LAND = 10, ///< terraform a tile + CMD_PURCHASE_LAND_AREA = 11, ///< purchase a tile + CMD_SELL_LAND_AREA = 12, ///< sell a bought tile before + CMD_BUILD_TUNNEL = 13, ///< build a tunnel - CMD_REMOVE_FROM_RAILROAD_STATION = 14, - CMD_CONVERT_RAIL = 15, + CMD_REMOVE_FROM_RAILROAD_STATION = 14, ///< remove a tile station + CMD_CONVERT_RAIL = 15, ///< convert a rail type - CMD_BUILD_TRAIN_WAYPOINT = 16, - CMD_RENAME_WAYPOINT = 17, - CMD_REMOVE_TRAIN_WAYPOINT = 18, + CMD_BUILD_TRAIN_WAYPOINT = 16, ///< build a waypoint + CMD_RENAME_WAYPOINT = 17, ///< rename a waypoint + CMD_REMOVE_TRAIN_WAYPOINT = 18, ///< remove a waypoint - CMD_BUILD_ROAD_STOP = 21, - CMD_REMOVE_ROAD_STOP = 22, - CMD_BUILD_LONG_ROAD = 23, - CMD_REMOVE_LONG_ROAD = 24, - CMD_BUILD_ROAD = 25, - CMD_REMOVE_ROAD = 26, - CMD_BUILD_ROAD_DEPOT = 27, + CMD_BUILD_ROAD_STOP = 21, ///< build a road stop + CMD_REMOVE_ROAD_STOP = 22, ///< remove a road stop + CMD_BUILD_LONG_ROAD = 23, ///< build a complete road (not a "half" one) + CMD_REMOVE_LONG_ROAD = 24, ///< remove a complete road (not a "half" one) + CMD_BUILD_ROAD = 25, ///< build a "half" road + CMD_REMOVE_ROAD = 26, ///< remove a "half" road + CMD_BUILD_ROAD_DEPOT = 27, ///< build a road depot - CMD_BUILD_AIRPORT = 29, + CMD_BUILD_AIRPORT = 29, ///< build an airport - CMD_BUILD_DOCK = 30, + CMD_BUILD_DOCK = 30, ///< build a dock - CMD_BUILD_SHIP_DEPOT = 31, - CMD_BUILD_BUOY = 32, + CMD_BUILD_SHIP_DEPOT = 31, ///< build a ship depot + CMD_BUILD_BUOY = 32, ///< build a buoy - CMD_PLANT_TREE = 33, + CMD_PLANT_TREE = 33, ///< plant a tree - CMD_BUILD_RAIL_VEHICLE = 34, - CMD_MOVE_RAIL_VEHICLE = 35, + CMD_BUILD_RAIL_VEHICLE = 34, ///< build a rail vehicle + CMD_MOVE_RAIL_VEHICLE = 35, ///< move a rail vehicle (in the depot) - CMD_START_STOP_TRAIN = 36, + CMD_START_STOP_TRAIN = 36, ///< start or stop a train - CMD_SELL_RAIL_WAGON = 38, + CMD_SELL_RAIL_WAGON = 38, ///< sell a rail wagon - CMD_SEND_TRAIN_TO_DEPOT = 39, - CMD_FORCE_TRAIN_PROCEED = 40, - CMD_REVERSE_TRAIN_DIRECTION = 41, + CMD_SEND_TRAIN_TO_DEPOT = 39, ///< send a train to a depot + CMD_FORCE_TRAIN_PROCEED = 40, ///< proceed a train to pass a red signal + CMD_REVERSE_TRAIN_DIRECTION = 41, ///< turn a train around - CMD_MODIFY_ORDER = 42, - CMD_SKIP_TO_ORDER = 43, - CMD_DELETE_ORDER = 44, - CMD_INSERT_ORDER = 45, + CMD_MODIFY_ORDER = 42, ///< modify an order (like set full-load) + CMD_SKIP_TO_ORDER = 43, ///< skip an order to the next of specific one + CMD_DELETE_ORDER = 44, ///< delete an order + CMD_INSERT_ORDER = 45, ///< insert a new order - CMD_CHANGE_SERVICE_INT = 46, + CMD_CHANGE_SERVICE_INT = 46, ///< change the server interval of a vehicle - CMD_BUILD_INDUSTRY = 47, + CMD_BUILD_INDUSTRY = 47, ///< build a new industry - CMD_BUILD_COMPANY_HQ = 48, - CMD_SET_PLAYER_FACE = 49, - CMD_SET_PLAYER_COLOR = 50, + CMD_BUILD_COMPANY_HQ = 48, ///< build the company headquarter + CMD_SET_PLAYER_FACE = 49, ///< set the face of the player/company + CMD_SET_PLAYER_COLOR = 50, ///< set the color of the player/company - CMD_INCREASE_LOAN = 51, - CMD_DECREASE_LOAN = 52, + CMD_INCREASE_LOAN = 51, ///< increase the loan from the bank + CMD_DECREASE_LOAN = 52, ///< decrease the loan from the bank - CMD_WANT_ENGINE_PREVIEW = 53, + CMD_WANT_ENGINE_PREVIEW = 53, ///< confirm the preview of an engine - CMD_NAME_VEHICLE = 54, - CMD_RENAME_ENGINE = 55, - CMD_CHANGE_COMPANY_NAME = 56, - CMD_CHANGE_PRESIDENT_NAME = 57, - CMD_RENAME_STATION = 58, + CMD_NAME_VEHICLE = 54, ///< rename a whole vehicle + CMD_RENAME_ENGINE = 55, ///< rename a engine (in the engine list) + CMD_CHANGE_COMPANY_NAME = 56, ///< change the company name + CMD_CHANGE_PRESIDENT_NAME = 57, ///< change the president name + CMD_RENAME_STATION = 58, ///< rename a station - CMD_SELL_AIRCRAFT = 59, - CMD_START_STOP_AIRCRAFT = 60, - CMD_BUILD_AIRCRAFT = 61, - CMD_SEND_AIRCRAFT_TO_HANGAR = 62, - CMD_REFIT_AIRCRAFT = 64, + CMD_SELL_AIRCRAFT = 59, ///< sell an aircraft + CMD_START_STOP_AIRCRAFT = 60, ///< start/stop an aircraft + CMD_BUILD_AIRCRAFT = 61, ///< build an aircraft + CMD_SEND_AIRCRAFT_TO_HANGAR = 62, ///< send an aircraft to a hanger + CMD_REFIT_AIRCRAFT = 64, ///< refit the cargo space of an aircraft - CMD_PLACE_SIGN = 65, - CMD_RENAME_SIGN = 66, + CMD_PLACE_SIGN = 65, ///< place a sign + CMD_RENAME_SIGN = 66, ///< rename a sign - CMD_BUILD_ROAD_VEH = 67, - CMD_START_STOP_ROADVEH = 68, - CMD_SELL_ROAD_VEH = 69, - CMD_SEND_ROADVEH_TO_DEPOT = 70, - CMD_TURN_ROADVEH = 71, - CMD_REFIT_ROAD_VEH = 72, + CMD_BUILD_ROAD_VEH = 67, ///< build a road vehicle + CMD_START_STOP_ROADVEH = 68, ///< start/stop a road vehicle + CMD_SELL_ROAD_VEH = 69, ///< sell a road vehicle + CMD_SEND_ROADVEH_TO_DEPOT = 70, ///< send a road vehicle to the depot + CMD_TURN_ROADVEH = 71, ///< turn a road vehicle around + CMD_REFIT_ROAD_VEH = 72, ///< refit the cargo space of a road vehicle - CMD_PAUSE = 73, + CMD_PAUSE = 73, ///< pause the game - CMD_BUY_SHARE_IN_COMPANY = 74, - CMD_SELL_SHARE_IN_COMPANY = 75, - CMD_BUY_COMPANY = 76, + CMD_BUY_SHARE_IN_COMPANY = 74, ///< buy a share from a company + CMD_SELL_SHARE_IN_COMPANY = 75, ///< sell a share from a company + CMD_BUY_COMPANY = 76, ///< buy a company which is bankrupt - CMD_BUILD_TOWN = 77, + CMD_BUILD_TOWN = 77, ///< build a town - CMD_RENAME_TOWN = 80, - CMD_DO_TOWN_ACTION = 81, + CMD_RENAME_TOWN = 80, ///< rename a town + CMD_DO_TOWN_ACTION = 81, ///< do a action from the town detail window (like advertises or bribe) - CMD_SET_ROAD_DRIVE_SIDE = 82, + CMD_SET_ROAD_DRIVE_SIDE = 82, ///< set the side where the road vehicles drive - CMD_CHANGE_DIFFICULTY_LEVEL = 85, + CMD_CHANGE_DIFFICULTY_LEVEL = 85, ///< change the difficult of a game (each setting for it own) - CMD_START_STOP_SHIP = 86, - CMD_SELL_SHIP = 87, - CMD_BUILD_SHIP = 88, - CMD_SEND_SHIP_TO_DEPOT = 89, - CMD_REFIT_SHIP = 91, + CMD_START_STOP_SHIP = 86, ///< start/stop a ship + CMD_SELL_SHIP = 87, ///< sell a ship + CMD_BUILD_SHIP = 88, ///< build a new ship + CMD_SEND_SHIP_TO_DEPOT = 89, ///< send a ship to a depot + CMD_REFIT_SHIP = 91, ///< refit the cargo space of a ship - CMD_ORDER_REFIT = 98, - CMD_CLONE_ORDER = 99, - CMD_CLEAR_AREA = 100, + CMD_ORDER_REFIT = 98, ///< change the refit informaction of an order (for "goto depot" ) + CMD_CLONE_ORDER = 99, ///< clone (and share) an order + CMD_CLEAR_AREA = 100, ///< clear an area - CMD_MONEY_CHEAT = 102, - CMD_BUILD_CANAL = 103, + CMD_MONEY_CHEAT = 102, ///< do the money cheat + CMD_BUILD_CANAL = 103, ///< build a canal CMD_PLAYER_CTRL = 104, ///< used in multiplayer to create a new player etc. CMD_LEVEL_LAND = 105, ///< level land - CMD_REFIT_RAIL_VEHICLE = 106, - CMD_RESTORE_ORDER_INDEX = 107, - CMD_BUILD_LOCK = 108, + CMD_REFIT_RAIL_VEHICLE = 106, ///< refit the cargo space of a train + CMD_RESTORE_ORDER_INDEX = 107, ///< restore vehicle order-index and service interval + CMD_BUILD_LOCK = 108, ///< build a lock - CMD_BUILD_SIGNAL_TRACK = 110, - CMD_REMOVE_SIGNAL_TRACK = 111, + CMD_BUILD_SIGNAL_TRACK = 110, ///< add signals along a track (by dragging) + CMD_REMOVE_SIGNAL_TRACK = 111, ///< remove signals along a track (by dragging) - CMD_GIVE_MONEY = 113, - CMD_CHANGE_PATCH_SETTING = 114, + CMD_GIVE_MONEY = 113, ///< give money to an other player + CMD_CHANGE_PATCH_SETTING = 114, ///< change a patch setting - CMD_SET_AUTOREPLACE = 115, + CMD_SET_AUTOREPLACE = 115, ///< set an autoreplace entry - CMD_CLONE_VEHICLE = 116, - CMD_MASS_START_STOP = 117, - CMD_DEPOT_SELL_ALL_VEHICLES = 118, - CMD_DEPOT_MASS_AUTOREPLACE = 119, + CMD_CLONE_VEHICLE = 116, ///< clone a vehicle + CMD_MASS_START_STOP = 117, ///< start/stop all vehicles (in a depot) + CMD_DEPOT_SELL_ALL_VEHICLES = 118, ///< sell all vehicles which are in a given depot + CMD_DEPOT_MASS_AUTOREPLACE = 119, ///< force the autoreplace to take action in a given depot - CMD_CREATE_GROUP = 120, - CMD_DELETE_GROUP = 121, - CMD_RENAME_GROUP = 122, - CMD_ADD_VEHICLE_GROUP = 123, - CMD_ADD_SHARED_VEHICLE_GROUP = 124, - CMD_REMOVE_ALL_VEHICLES_GROUP = 125, - CMD_SET_GROUP_REPLACE_PROTECTION = 126, + CMD_CREATE_GROUP = 120, ///< create a new group + CMD_DELETE_GROUP = 121, ///< delete a group + CMD_RENAME_GROUP = 122, ///< rename a group + CMD_ADD_VEHICLE_GROUP = 123, ///< add a vehicle to a group + CMD_ADD_SHARED_VEHICLE_GROUP = 124, ///< add all other shared vehicles to a group which are missing + CMD_REMOVE_ALL_VEHICLES_GROUP = 125, ///< remove all vehicles from a group + CMD_SET_GROUP_REPLACE_PROTECTION = 126, ///< set the autoreplace-protection for a group - CMD_MOVE_ORDER = 127, - CMD_CHANGE_TIMETABLE = 128, - CMD_SET_VEHICLE_ON_TIME = 129, - CMD_AUTOFILL_TIMETABLE = 130, + CMD_MOVE_ORDER = 127, ///< move an order + CMD_CHANGE_TIMETABLE = 128, ///< change the timetable for a vehicle + CMD_SET_VEHICLE_ON_TIME = 129, ///< set the vehicle on time feature (timetable) + CMD_AUTOFILL_TIMETABLE = 130, ///< autofill the timetable }; +/** + * List of flags for a command. + * + * This enums defines some flags which can be used for the commands. + */ enum { - DC_EXEC = 0x01, + DC_EXEC = 0x01, ///< execute the given command DC_AUTO = 0x02, ///< don't allow building on structures DC_QUERY_COST = 0x04, ///< query cost only, don't build. DC_NO_WATER = 0x08, ///< don't allow building on water @@ -169,50 +184,167 @@ enum { DC_FORCETEST = 0x80, ///< force test too. }; +/** + * Used to combine a StringID with the command. + * + * This macro can be used to add a StringID (the error message to show) on a command-id + * (CMD_xxx). Use the binary or-operator "|" to combine the command with the result from + * this macro. + * + * @param x The StringID to combine with a command-id + */ #define CMD_MSG(x) ((x) << 16) +/** + * Defines some flags. + * + * This enumeration defines some flags which are binary-or'ed on a command. + */ enum { - CMD_NO_WATER = 0x0400, + CMD_NO_WATER = 0x0400, ///< dont build on water CMD_NETWORK_COMMAND = 0x0800, ///< execute the command without sending it on the network CMD_NO_TEST_IF_IN_NETWORK = 0x1000, ///< When enabled, the command will bypass the no-DC_EXEC round if in network - CMD_SHOW_NO_ERROR = 0x2000, + CMD_SHOW_NO_ERROR = 0x2000, ///< do not show the error message }; -/** Command flags for the command table _command_proc_table */ +/** + * Command flags for the command table _command_proc_table. + * + * This enumeration defines flags for the _command_proc_table. + */ enum { CMD_SERVER = 0x1, ///< the command can only be initiated by the server CMD_OFFLINE = 0x2, ///< the command cannot be executed in a multiplayer game; single-player only CMD_AUTO = 0x4, ///< set the DC_AUTO flag on this command }; +/** + * Defines the callback type for all command handler functions. + * + * This type defines the function header for all functions which handles a CMD_* command. + * A command handler use the parameters to act according to the meaning of the command. + * The tile parameter defines the tile to perform an action on. + * The flag parameter is filled with flags from the DC_* enumeration. The parameters + * p1 and p2 are filled with parameters for the command like "which road type", "which + * order" or "direction". Each function should mentioned in there doxygen comments + * the usage of these parameters. + * + * @param tile The tile to apply a command on + * @param flags Flags for the command, from the DC_* enumeration + * @param p1 Additional data for the command + * @param p2 Additional data for the command + * @return The CommandCost of the command, which can be succeeded or failed. + */ typedef CommandCost CommandProc(TileIndex tile, uint32 flags, uint32 p1, uint32 p2); +/** + * Define a command with the flags which belongs to it. + * + * This struct connect a command handler function with the flags created with + * the #CMD_AUTO, #CMD_OFFLINE and #CMD_SERVER values. + */ struct Command { CommandProc *proc; byte flags; }; +/** + * Checks if a command failes. + * + * As you see the parameter is not a command but the return value of a command, + * the CommandCost class. This function checks if the command executed by + * the CommandProc function failed and returns true if it does. + * + * @param cost The return value of a CommandProc call + * @return true if the command failes + * @see CmdSucceded + */ static inline bool CmdFailed(CommandCost cost) { return cost.Failed(); } + +/** + * Checks if a command succeeded. + * + * As #CmdFailed this function checks if a command succeeded + * + * @param cost The return value of a CommandProc call + * @return true if the command succeeded + * @see CmdSucceeded + */ static inline bool CmdSucceeded(CommandCost cost) { return cost.Succeeded(); } +/** + * Define a default return value for a failed command. + * + * This variable contains a CommandCost object with is declared as "failed". + * Other functions just need to return this error if there is an error, + * which doesn't need to specific by a StringID. + */ static const CommandCost CMD_ERROR = CommandCost(INVALID_STRING_ID); -#define return_cmd_error(errcode) do { return CommandCost(errcode); } while (0) +/** + * Returns from a function with a specific StringID as error. + * + * This macro is used to return from a function. The parameter contains the + * StringID which will be returned. + * + * @param errcode The StringID to return + */ +#define return_cmd_error(errcode) return CommandCost(errcode); /* command.cpp */ +/** + * Define a callback function for the client, after the command is finished. + * + * Functions of this type are called after the command is finished. The parameters + * are from the #CommandProc callback type. The boolean parameter indicates if the + * command succeeded or failed. + * + * @param success If the command succeeded or not. + * @param tile The tile of the command action + * @param p1 Additional data of the command + * @param p1 Additional data of the command + * @see CommandProc + */ typedef void CommandCallback(bool success, TileIndex tile, uint32 p1, uint32 p2); + +/** + * Execute a command + */ CommandCost DoCommand(TileIndex tile, uint32 p1, uint32 p2, uint32 flags, uint procc); + +/** + * Execute a network safe DoCommand function + */ bool DoCommandP(TileIndex tile, uint32 p1, uint32 p2, CommandCallback *callback, uint32 cmd, bool my_cmd = true); #ifdef ENABLE_NETWORK +/** + * Send a command over the network + */ void NetworkSend_Command(TileIndex tile, uint32 p1, uint32 p2, uint32 cmd, CommandCallback *callback); #endif /* ENABLE_NETWORK */ -extern const char* _cmd_text; ///< Text, which gets sent with a command - +/** + * Text, which gets sent with a command + * + * This variable contains a string (be specific a pointer of the first + * char of this string) which will be send with a command. This is + * used for user input data like names or chat messages. + */ +extern const char *_cmd_text; + +/** + * Checks if a integer value belongs to a command. + */ bool IsValidCommand(uint cmd); +/** + * Returns the flags from a given command. + */ byte GetCommandFlags(uint cmd); +/** + * Returns the current money available which can be used for a command. + */ Money GetAvailableMoneyForCommand(); #endif /* COMMAND_H */