OpenTTD GameScript API: GSGoal Class Reference

OpenTTD GameScript API 1.11.1

Public Types | Static Public Member Functions
GSGoal Class Reference

Class that handles some goal related functions. More...

Inheritance diagram for GSGoal:

## Public Types
enum | GoalID { GOAL_INVALID }
| The goal IDs. More...
enum | GoalType : byte { GT_NONE, GT_TILE, GT_INDUSTRY, GT_TOWN, GT_COMPANY, GT_STORY_PAGE = ::GT_STORY_PAGE }
| Goal types that can be given to a goal. More...
enum | QuestionType { QT_QUESTION, QT_INFORMATION, QT_WARNING, QT_ERROR }
| Types of queries we could do to the user. More...
enum | QuestionButton { BUTTON_CANCEL, BUTTON_OK, BUTTON_NO, BUTTON_YES, BUTTON_DECLINE, BUTTON_ACCEPT, BUTTON_IGNORE, BUTTON_RETRY, BUTTON_PREVIOUS, BUTTON_NEXT, BUTTON_STOP, BUTTON_START, BUTTON_GO, BUTTON_CONTINUE, BUTTON_RESTART, BUTTON_POSTPONE, BUTTON_SURRENDER, BUTTON_CLOSE }
| Types of buttons that can be in the question window. More...

## Static Public Member Functions
static bool | IsValidGoal (GoalID goal_id)
| Check whether this is a valid goalID. More...
static GoalID | New (GSCompany::CompanyID company, Text *goal, GoalType type, uint32 destination)
| Create a new goal. More...
static bool | Remove (GoalID goal_id)
| Remove a goal from the list. More...
static bool | SetText (GoalID goal_id, Text *goal)
| Update goal text of a goal. More...
static bool | SetProgress (GoalID goal_id, Text *progress)
| Update the progress text of a goal. More...
static bool | SetCompleted (GoalID goal_id, bool complete)
| Update completed status of goal. More...
static bool | IsCompleted (GoalID goal_id)
| Checks if a given goal have been marked as completed. More...
static bool | Question (uint16 uniqueid, GSCompany::CompanyID company, Text *question, QuestionType type, int buttons)
| Ask a question of all players in a company. More...
static bool | QuestionClient (uint16 uniqueid, GSClient::ClientID client, Text *question, QuestionType type, int buttons)
| Ask client a question. More...
static bool | CloseQuestion (uint16 uniqueid)
| Close the question on all clients. More...

## Detailed Description

Class that handles some goal related functions.

Goals are saved and loaded. Upon bankruptcy or company takeover, all company specific goals are removed for that company. You can also remove individual goals using Remove.

## Member Enumeration Documentation

## ◆ GoalID

enum GSGoal::GoalID

The goal IDs.

Enumerator
GOAL_INVALID | An invalid goal id.

## ◆ GoalType

enum GSGoal::GoalType : byte

Goal types that can be given to a goal.

Enumerator
GT_NONE | Destination is not linked.
GT_TILE | Destination is a tile.
GT_INDUSTRY | Destination is an industry.
GT_TOWN | Destination is a town.
GT_COMPANY | Destination is a company.
GT_STORY_PAGE | Destination is a story page.

## ◆ QuestionButton

enum GSGoal::QuestionButton

Types of buttons that can be in the question window.

Enumerator
BUTTON_CANCEL | Cancel button.
BUTTON_OK | OK button.
BUTTON_NO | No button.
BUTTON_YES | Yes button.
BUTTON_DECLINE | Decline button.
BUTTON_ACCEPT | Accept button.
BUTTON_IGNORE | Ignore button.
BUTTON_RETRY | Retry button.
BUTTON_PREVIOUS | Previous button.
BUTTON_NEXT | Next button.
BUTTON_STOP | Stop button.
BUTTON_START | Start button.
BUTTON_GO | Go button.
BUTTON_CONTINUE | Continue button.
BUTTON_RESTART | Restart button.
BUTTON_POSTPONE | Postpone button.
BUTTON_SURRENDER | Surrender button.
BUTTON_CLOSE | Close button.

## ◆ QuestionType

enum GSGoal::QuestionType

Types of queries we could do to the user.

Basically the title of the question window.

Enumerator
QT_QUESTION | Asking a simple question; title: Question.
QT_INFORMATION | Showing an informational message; title: Information.
QT_WARNING | Showing a warning; title: Warning.
QT_ERROR | Showing an error; title: Error.

## Member Function Documentation

## ◆ CloseQuestion()

static bool GSGoal::CloseQuestion | ( | uint16 | uniqueid | ) |
| static

Close the question on all clients.

Parameters

  uniqueid | The uniqueid of the question you want to close.

Returns
  True if the action succeeded.

Precondition
  No GSCompanyMode may be in scope.

Note
  If you send a question to a single company, and get a reply for them, the question is already closed on all clients. Only use this function if you want to timeout a question, or if you send the question to all companies, but you are only interested in the reply of the first.

## ◆ IsCompleted()

static bool GSGoal::IsCompleted | ( | GoalID | goal_id | ) |
| static

Checks if a given goal have been marked as completed.

Parameters

  goal_id | The goal to check complete status.

Returns
  True if the goal is completed, otherwise false.

Precondition
  No GSCompanyMode may be in scope.
  IsValidGoal(goal_id).

## ◆ IsValidGoal()

static bool GSGoal::IsValidGoal | ( | GoalID | goal_id | ) |
| static

Check whether this is a valid goalID.

Parameters

  goal_id | The GoalID to check.

Returns
  True if and only if this goal is valid.

## ◆ New()

static GoalID GSGoal::New | ( | GSCompany::CompanyID | company,
|  | Text * | goal,
|  | GoalType | type,
|  | uint32 | destination
| ) |  |
| static

Create a new goal.

Parameters

  company | The company to create the goal for, or GSCompany::COMPANY_INVALID for all.
  goal | The goal to add to the GUI (can be either a raw string, or a GSText object).
  type | The type of the goal.
  destination | The destination of the type type.

Returns
  The new GoalID, or GOAL_INVALID if it failed.

Precondition
  No GSCompanyMode may be in scope.
  goal != nullptr && len(goal) != 0.
  company == COMPANY_INVALID || ResolveCompanyID(company) != COMPANY_INVALID.
  if type is GT_STORY_PAGE, the company of the goal and the company of the story page need to match:
  - Global goals can only reference global story pages.
  - Company specific goals can reference global story pages and story pages of the same company.

## ◆ Question()

static bool GSGoal::Question | ( | uint16 | uniqueid,
|  | GSCompany::CompanyID | company,
|  | Text * | question,
|  | QuestionType | type,
|  | int | buttons
| ) |  |
| static

Ask a question of all players in a company.

Parameters

  uniqueid | Your unique id to distinguish results of multiple questions in the returning event.
  company | The company to ask the question, or GSCompany::COMPANY_INVALID for all.
  question | The question to ask (can be either a raw string, or a GSText object).
  type | The type of question that is being asked.
  buttons | Any combinations (at least 1, up to 3) of buttons defined in QuestionButton. Like BUTTON_YES + BUTTON_NO.

Returns
  True if the action succeeded.

Precondition
  No GSCompanyMode may be in scope.
  question != nullptr && len(question) != 0.
  company == COMPANY_INVALID || ResolveCompanyID(company) != COMPANY_INVALID.
  CountBits(buttons) >= 1 && CountBits(buttons) <= 3.

Note
  Replies to the question are given by you via the event GSEvent_GoalQuestionAnswer.
  There is no guarantee you ever get a reply on your question.

## ◆ QuestionClient()

static bool GSGoal::QuestionClient | ( | uint16 | uniqueid,
|  | GSClient::ClientID | client,
|  | Text * | question,
|  | QuestionType | type,
|  | int | buttons
| ) |  |
| static

Ask client a question.

Parameters

  uniqueid | Your unique id to distinguish results of multiple questions in the returning event.
  client | The client to ask the question.
  question | The question to ask (can be either a raw string, or a GSText object).
  type | The type of question that is being asked.
  buttons | Any combinations (at least 1, up to 3) of buttons defined in QuestionButton. Like BUTTON_YES + BUTTON_NO.

Returns
  True if the action succeeded.

Precondition
  No GSCompanyMode may be in scope.
  GSGame::IsMultiplayer()
  question != nullptr && len(question) != 0.
  ResolveClientID(client) != CLIENT_INVALID.
  CountBits(buttons) >= 1 && CountBits(buttons) <= 3.

Note
  Replies to the question are given by you via the event GSEvent_GoalQuestionAnswer.
  There is no guarantee you ever get a reply on your question.

## ◆ Remove()

static bool GSGoal::Remove | ( | GoalID | goal_id | ) |
| static

Remove a goal from the list.

Parameters

  goal_id | The goal to remove.

Returns
  True if the action succeeded.

Precondition
  No GSCompanyMode may be in scope.
  IsValidGoal(goal_id).

## ◆ SetCompleted()

static bool GSGoal::SetCompleted | ( | GoalID | goal_id,
|  | bool | complete
| ) |  |
| static

Update completed status of goal.

Parameters

  goal_id | The goal to update.
  complete | The new goal completed status.

Returns
  True if the action succeeded.

Precondition
  No GSCompanyMode may be in scope.
  IsValidGoal(goal_id).

## ◆ SetProgress()

static bool GSGoal::SetProgress | ( | GoalID | goal_id,
|  | Text * | progress
| ) |  |
| static

Update the progress text of a goal.

The progress text is a text that is shown adjacent to the goal but in a separate column. Try to keep the progress string short.

Parameters

  goal_id | The goal to update.
  progress | The new progress text for the goal (can be either a raw string, or a GSText object). To clear the progress string you can pass nullptr or an empty string.

Returns
  True if the action succeeded.

Precondition
  No GSCompanyMode may be in scope.
  IsValidGoal(goal_id).

## ◆ SetText()

static bool GSGoal::SetText | ( | GoalID | goal_id,
|  | Text * | goal
| ) |  |
| static

Update goal text of a goal.

Parameters

  goal_id | The goal to update.
  goal | The new goal text (can be either a raw string, or a GSText object).

Returns
  True if the action succeeded.

Precondition
  No GSCompanyMode may be in scope.
  goal != nullptr && len(goal) != 0.
  IsValidGoal(goal_id).