src/script/api/script_goal.hpp

   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 script_goal.hpp Everything to manipulate the current running goal. */
   9
  10 #ifndef SCRIPT_GOAL_HPP
  11 #define SCRIPT_GOAL_HPP
  12
  13 #include "script_client.hpp"
  14 #include "script_company.hpp"
  15 #include "../../goal_type.h"
  16
  17 /**
  18  * Class that handles some goal related functions.
  19  *
  20  * Goals are saved and loaded. Upon bankruptcy or company takeover, all company
  21  * specific goals are removed for that company. You can also remove individual
  22  * goals using #Remove.
  23  *
  24  * @api game
  25  */
  26 class ScriptGoal : public ScriptObject {
  27 public:
  28         /**
  29          * The goal IDs.
  30          */
  31         enum GoalID : uint16_t {
  32                 /* Note: these values represent part of the in-game GoalID enum */
  33                 GOAL_INVALID = ::INVALID_GOAL, ///< An invalid goal id.
  34         };
  35
  36         /**
  37          * Goal types that can be given to a goal.
  38          */
  39         enum GoalType : uint8_t {
  40                 /* Note: these values represent part of the in-game GoalType enum */
  41                 GT_NONE     = ::GT_NONE,     ///< Destination is not linked.
  42                 GT_TILE     = ::GT_TILE,     ///< Destination is a tile.
  43                 GT_INDUSTRY = ::GT_INDUSTRY, ///< Destination is an industry.
  44                 GT_TOWN     = ::GT_TOWN,     ///< Destination is a town.
  45                 GT_COMPANY  = ::GT_COMPANY,  ///< Destination is a company.
  46                 GT_STORY_PAGE = ::GT_STORY_PAGE ///< Destination is a story page.
  47         };
  48
  49         /**
  50          * Types of queries we could do to the user.
  51          * Basically the title of the question window.
  52          */
  53         enum QuestionType {
  54                 QT_QUESTION,    ///< Asking a simple question; title: Question.
  55                 QT_INFORMATION, ///< Showing an informational message; title: Information.
  56                 QT_WARNING,     ///< Showing a warning; title: Warning.
  57                 QT_ERROR,       ///< Showing an error; title: Error.
  58         };
  59
  60         /**
  61          * Types of buttons that can be in the question window.
  62          */
  63         enum QuestionButton {
  64                 /* Note: these values represent part of the string list starting with STR_GOAL_QUESTION_BUTTON_CANCEL */
  65                 BUTTON_CANCEL    = (1 << 0),  ///< Cancel button.
  66                 BUTTON_OK        = (1 << 1),  ///< OK button.
  67                 BUTTON_NO        = (1 << 2),  ///< No button.
  68                 BUTTON_YES       = (1 << 3),  ///< Yes button.
  69                 BUTTON_DECLINE   = (1 << 4),  ///< Decline button.
  70                 BUTTON_ACCEPT    = (1 << 5),  ///< Accept button.
  71                 BUTTON_IGNORE    = (1 << 6),  ///< Ignore button.
  72                 BUTTON_RETRY     = (1 << 7),  ///< Retry button.
  73                 BUTTON_PREVIOUS  = (1 << 8),  ///< Previous button.
  74                 BUTTON_NEXT      = (1 << 9),  ///< Next button.
  75                 BUTTON_STOP      = (1 << 10), ///< Stop button.
  76                 BUTTON_START     = (1 << 11), ///< Start button.
  77                 BUTTON_GO        = (1 << 12), ///< Go button.
  78                 BUTTON_CONTINUE  = (1 << 13), ///< Continue button.
  79                 BUTTON_RESTART   = (1 << 14), ///< Restart button.
  80                 BUTTON_POSTPONE  = (1 << 15), ///< Postpone button.
  81                 BUTTON_SURRENDER = (1 << 16), ///< Surrender button.
  82                 BUTTON_CLOSE     = (1 << 17), ///< Close button.
  83         };
  84
  85         /**
  86          * Check whether this is a valid goalID.
  87          * @param goal_id The GoalID to check.
  88          * @return True if and only if this goal is valid.
  89          */
  90         static bool IsValidGoal(GoalID goal_id);
  91
  92         /**
  93          * Check whether this is a valid goal destination.
  94          * @param company The relevant company if a story page is the destination.
  95          * @param type The type of the goal.
  96          * @param destination The destination of the \a type type.
  97          * @return True if and only if this goal destination is valid.
  98          */
  99         static bool IsValidGoalDestination(ScriptCompany::CompanyID company, GoalType type, SQInteger destination);
 100
 101         /**
 102          * Create a new goal.
 103          * @param company The company to create the goal for, or ScriptCompany::COMPANY_INVALID for all.
 104          * @param goal The goal to add to the GUI (can be either a raw string, or a ScriptText object).
 105          * @param type The type of the goal.
 106          * @param destination The destination of the \a type type.
 107          * @return The new GoalID, or GOAL_INVALID if it failed.
 108          * @pre ScriptCompanyMode::IsDeity().
 109          * @pre goal != null && len(goal) != 0.
 110          * @pre company == COMPANY_INVALID || ResolveCompanyID(company) != COMPANY_INVALID.
 111          * @pre if type is GT_STORY_PAGE, the company of the goal and the company of the story page need to match:
 112          *       \li Global goals can only reference global story pages.
 113          *       \li Company specific goals can reference global story pages and story pages of the same company.
 114          */
 115         static GoalID New(ScriptCompany::CompanyID company, Text *goal, GoalType type, SQInteger destination);
 116
 117         /**
 118          * Remove a goal from the list.
 119          * @param goal_id The goal to remove.
 120          * @return True if the action succeeded.
 121          * @pre ScriptCompanyMode::IsDeity().
 122          * @pre IsValidGoal(goal_id).
 123          */
 124         static bool Remove(GoalID goal_id);
 125
 126         /**
 127          * Update goal destination of a goal.
 128          * @param goal_id The goal to update.
 129          * @param type The type of the goal.
 130          * @param destination The destination of the \a type type.
 131          * @return True if the action succeeded.
 132          * @pre ScriptCompanyMode::IsDeity().
 133          * @pre IsValidGoal(goal_id).
 134          * @pre IsValidGoalDestination(g->company, type, destination).
 135          */
 136         static bool SetDestination(GoalID goal_id, GoalType type, SQInteger destination);
 137
 138         /**
 139          * Update goal text of a goal.
 140          * @param goal_id The goal to update.
 141          * @param goal The new goal text (can be either a raw string, or a ScriptText object).
 142          * @return True if the action succeeded.
 143          * @pre ScriptCompanyMode::IsDeity().
 144          * @pre goal != null && len(goal) != 0.
 145          * @pre IsValidGoal(goal_id).
 146          */
 147         static bool SetText(GoalID goal_id, Text *goal);
 148
 149         /**
 150          * Update the progress text of a goal. The progress text is a text that
 151          * is shown adjacent to the goal but in a separate column. Try to keep
 152          * the progress string short.
 153          * @param goal_id The goal to update.
 154          * @param progress The new progress text for the goal (can be either a raw string,
 155          * or a ScriptText object). To clear the progress string you can pass null or an
 156          * empty string.
 157          * @return True if the action succeeded.
 158          * @pre ScriptCompanyMode::IsDeity().
 159          * @pre IsValidGoal(goal_id).
 160          */
 161         static bool SetProgress(GoalID goal_id, Text *progress);
 162
 163         /**
 164          * Update completed status of goal
 165          * @param goal_id The goal to update.
 166          * @param complete The new goal completed status.
 167          * @return True if the action succeeded.
 168          * @pre ScriptCompanyMode::IsDeity().
 169          * @pre IsValidGoal(goal_id).
 170          */
 171         static bool SetCompleted(GoalID goal_id, bool complete);
 172
 173         /**
 174          * Checks if a given goal have been marked as completed.
 175          * @param goal_id The goal to check complete status.
 176          * @return True if the goal is completed, otherwise false.
 177          * @pre ScriptCompanyMode::IsDeity().
 178          * @pre IsValidGoal(goal_id).
 179          */
 180         static bool IsCompleted(GoalID goal_id);
 181
 182         /**
 183          * Ask a question of all players in a company.
 184          * @param uniqueid Your unique id to distinguish results of multiple questions in the returning event.
 185          * @param company The company to ask the question, or ScriptCompany::COMPANY_INVALID for all.
 186          * @param question The question to ask (can be either a raw string, or a ScriptText object).
 187          * @param type The type of question that is being asked.
 188          * @param buttons Any combinations (at least 1, up to 3) of buttons defined in QuestionButton. Like BUTTON_YES + BUTTON_NO.
 189          * @return True if the action succeeded.
 190          * @pre ScriptCompanyMode::IsDeity().
 191          * @pre question != null && len(question) != 0.
 192          * @pre company == COMPANY_INVALID || ResolveCompanyID(company) != COMPANY_INVALID.
 193          * @pre CountBits(buttons) >= 1 && CountBits(buttons) <= 3.
 194          * @pre uniqueid >= 0 && uniqueid <= MAX(uint16_t)
 195          * @note Replies to the question are given by you via the event ScriptEventGoalQuestionAnswer.
 196          * @note There is no guarantee you ever get a reply on your question.
 197          */
 198         static bool Question(SQInteger uniqueid, ScriptCompany::CompanyID company, Text *question, QuestionType type, SQInteger buttons);
 199
 200         /**
 201          * Ask client a question.
 202          * @param uniqueid Your unique id to distinguish results of multiple questions in the returning event.
 203          * @param client The client to ask the question.
 204          * @param question The question to ask (can be either a raw string, or a ScriptText object).
 205          * @param type The type of question that is being asked.
 206          * @param buttons Any combinations (at least 1, up to 3) of buttons defined in QuestionButton. Like BUTTON_YES + BUTTON_NO.
 207          * @return True if the action succeeded.
 208          * @pre ScriptCompanyMode::IsDeity().
 209          * @pre ScriptGame::IsMultiplayer()
 210          * @pre question != null && len(question) != 0.
 211          * @pre ResolveClientID(client) != CLIENT_INVALID.
 212          * @pre CountBits(buttons) >= 1 && CountBits(buttons) <= 3.
 213          * @pre uniqueid >= 0 && uniqueid <= MAX(uint16_t)
 214          * @note Replies to the question are given by you via the event ScriptEventGoalQuestionAnswer.
 215          * @note There is no guarantee you ever get a reply on your question.
 216          */
 217         static bool QuestionClient(SQInteger uniqueid, ScriptClient::ClientID client, Text *question, QuestionType type, SQInteger buttons);
 218
 219         /**
 220          * Close the question on all clients.
 221          * @param uniqueid The uniqueid of the question you want to close.
 222          * @return True if the action succeeded.
 223          * @pre ScriptCompanyMode::IsDeity().
 224          * @pre uniqueid >= 0 && uniqueid <= MAX(uint16_t)
 225          * @note If you send a question to a single company, and get a reply for them,
 226          *   the question is already closed on all clients. Only use this function if
 227          *   you want to timeout a question, or if you send the question to all
 228          *   companies, but you are only interested in the reply of the first.
 229          */
 230         static bool CloseQuestion(SQInteger uniqueid);
 231
 232 protected:
 233         /**
 234          * Does common checks and asks the question.
 235          */
 236         static bool DoQuestion(SQInteger uniqueid, uint32_t target, bool is_client, Text *question, QuestionType type, SQInteger buttons);
 237 };
 238
 239 #endif /* SCRIPT_GOAL_HPP */