OpenTTD GameScript API  20240526-master-gd11823df36
Public Types | Static Public Member Functions
GSStoryPage Class Reference

Class that handles story page related functions. More...

Inheritance diagram for GSStoryPage:

Public Types

enum  StoryPageID { STORY_PAGE_INVALID }
 The story page IDs. More...
 
enum  StoryPageElementID { STORY_PAGE_ELEMENT_INVALID }
 The story page element IDs. More...
 
enum  StoryPageElementType : int {
  SPET_TEXT,
  SPET_LOCATION,
  SPET_GOAL,
  SPET_BUTTON_PUSH,
  SPET_BUTTON_TILE,
  SPET_BUTTON_VEHICLE
}
 Story page element types. More...
 
enum  StoryPageButtonFlags : int {
  SPBF_NONE,
  SPBF_FLOAT_LEFT,
  SPBF_FLOAT_RIGHT
}
 Formatting and layout flags for story page buttons. More...
 
enum  StoryPageButtonCursor : int {
  SPBC_MOUSE,
  SPBC_ZZZ,
  SPBC_BUOY,
  SPBC_QUERY,
  SPBC_HQ,
  SPBC_SHIP_DEPOT,
  SPBC_SIGN,
  SPBC_TREE,
  SPBC_BUY_LAND,
  SPBC_LEVEL_LAND,
  SPBC_TOWN,
  SPBC_INDUSTRY,
  SPBC_ROCKY_AREA,
  SPBC_DESERT,
  SPBC_TRANSMITTER,
  SPBC_AIRPORT,
  SPBC_DOCK,
  SPBC_CANAL,
  SPBC_LOCK,
  SPBC_RIVER,
  SPBC_AQUEDUCT,
  SPBC_BRIDGE,
  SPBC_RAIL_STATION,
  SPBC_TUNNEL_RAIL,
  SPBC_TUNNEL_ELRAIL,
  SPBC_TUNNEL_MONO,
  SPBC_TUNNEL_MAGLEV,
  SPBC_AUTORAIL,
  SPBC_AUTOELRAIL,
  SPBC_AUTOMONO,
  SPBC_AUTOMAGLEV,
  SPBC_WAYPOINT,
  SPBC_RAIL_DEPOT,
  SPBC_ELRAIL_DEPOT,
  SPBC_MONO_DEPOT,
  SPBC_MAGLEV_DEPOT,
  SPBC_CONVERT_RAIL,
  SPBC_CONVERT_ELRAIL,
  SPBC_CONVERT_MONO,
  SPBC_CONVERT_MAGLEV,
  SPBC_AUTOROAD,
  SPBC_AUTOTRAM,
  SPBC_ROAD_DEPOT,
  SPBC_BUS_STATION,
  SPBC_TRUCK_STATION,
  SPBC_ROAD_TUNNEL,
  SPBC_CLONE_TRAIN,
  SPBC_CLONE_ROADVEH,
  SPBC_CLONE_SHIP,
  SPBC_CLONE_AIRPLANE,
  SPBC_DEMOLISH,
  SPBC_LOWERLAND,
  SPBC_RAISELAND,
  SPBC_PICKSTATION,
  SPBC_BUILDSIGNALS
}
 Mouse cursors usable by story page buttons.
 
enum  StoryPageButtonColour : int {
  SPBC_DARK_BLUE,
  SPBC_PALE_GREEN,
  SPBC_PINK,
  SPBC_YELLOW,
  SPBC_RED,
  SPBC_LIGHT_BLUE,
  SPBC_GREEN,
  SPBC_DARK_GREEN,
  SPBC_BLUE,
  SPBC_CREAM,
  SPBC_MAUVE,
  SPBC_PURPLE,
  SPBC_ORANGE,
  SPBC_BROWN,
  SPBC_GREY,
  SPBC_WHITE
}
 Colour codes usable for story page button elements. More...
 

Static Public Member Functions

static bool IsValidStoryPage (StoryPageID story_page_id)
 Check whether this is a valid story page ID. More...
 
static bool IsValidStoryPageElement (StoryPageElementID story_page_element_id)
 Check whether this is a valid story page element ID. More...
 
static bool IsValidStoryPageElementType (StoryPageElementType type)
 Check whether this is a valid story page element type. More...
 
static StoryPageID New (GSCompany::CompanyID company, Text *title)
 Create a new story page. More...
 
static StoryPageElementID NewElement (StoryPageID story_page_id, StoryPageElementType type, int reference, Text *text)
 Create a new story page element. More...
 
static bool UpdateElement (StoryPageElementID story_page_element_id, int reference, Text *text)
 Update the content of a page element. More...
 
static int GetPageSortValue (StoryPageID story_page_id)
 Get story page sort value. More...
 
static int GetPageElementSortValue (StoryPageElementID story_page_element_id)
 Get story page element sort value. More...
 
static GSCompany::CompanyID GetCompany (StoryPageID story_page_id)
 Get the company which the page belongs to. More...
 
static GSDate::Date GetDate (StoryPageID story_page_id)
 Get the page date which is displayed at the top of each page. More...
 
static bool SetDate (StoryPageID story_page_id, GSDate::Date date)
 Update date of a story page. More...
 
static bool SetTitle (StoryPageID story_page_id, Text *title)
 Update title of a story page. More...
 
static bool Show (StoryPageID story_page_id)
 Opens the Story Book if not yet open and selects the given page. More...
 
static bool Remove (StoryPageID story_page_id)
 Remove a story page and all the page elements associated with it. More...
 
static bool RemoveElement (StoryPageElementID story_page_element_id)
 Removes a story page element. More...
 
static bool IsValidStoryPageButtonColour (StoryPageButtonColour colour)
 Check whether this is a valid story page button colour. More...
 
static bool IsValidStoryPageButtonFlags (StoryPageButtonFlags flags)
 Check whether this is a valid story page button flag. More...
 
static bool IsValidStoryPageButtonCursor (StoryPageButtonCursor cursor)
 Check whether this is a valid story page button cursor. More...
 
static StoryPageButtonFormatting MakePushButtonReference (StoryPageButtonColour colour, StoryPageButtonFlags flags)
 Create a reference value for SPET_BUTTON_PUSH element parameters. More...
 
static StoryPageButtonFormatting MakeTileButtonReference (StoryPageButtonColour colour, StoryPageButtonFlags flags, StoryPageButtonCursor cursor)
 Create a reference value for SPET_BUTTON_TILE element parameters. More...
 
static StoryPageButtonFormatting MakeVehicleButtonReference (StoryPageButtonColour colour, StoryPageButtonFlags flags, StoryPageButtonCursor cursor, GSVehicle::VehicleType vehtype)
 Create a reference value for SPET_BUTTON_VEHICLE element parameters. More...
 

Detailed Description

Class that handles story page related functions.

To create a page:

  1. Create the page
  2. Create page elements that will be appended to the page in the order which they are created.

Pages can be either global or company specific. It is possible to mix, but the only mixed solution that will work is to have all global pages first. Once you create the first company specific page, it is not recommended to add additional global pages unless you clear up all pages first.

Page elements are stacked vertically on a page. If goal elements are used, the element will become empty if the goal is removed while the page still exist. Instead of removing the goal, you can mark it as complete and the Story Book will show that the goal is completed.

Mind that users might want to go back to old pages later on. Thus do not remove pages in the story book unless you really need to.

Member Enumeration Documentation

◆ StoryPageButtonColour

Colour codes usable for story page button elements.

Place a colour value in the lowest 8 bits of the reference parameter to the button.

◆ StoryPageButtonFlags

Formatting and layout flags for story page buttons.

The SPBF_FLOAT_LEFT and SPBF_FLOAT_RIGHT flags can not be combined.

Enumerator
SPBF_NONE 

No special formatting for button.

SPBF_FLOAT_LEFT 

Button is placed to the left of the following paragraph.

SPBF_FLOAT_RIGHT 

Button is placed to the right of the following paragraph.

◆ StoryPageElementID

The story page element IDs.

Enumerator
STORY_PAGE_ELEMENT_INVALID 

An invalid story page element id.

◆ StoryPageElementType

Story page element types.

Enumerator
SPET_TEXT 

An element that displays a block of text.

SPET_LOCATION 

An element that displays a single line of text along with a button to view the referenced location.

SPET_GOAL 

An element that displays a goal.

SPET_BUTTON_PUSH 

A push button that triggers an immediate event.

SPET_BUTTON_TILE 

A button that allows the player to select a tile, and triggers an event with the tile.

SPET_BUTTON_VEHICLE 

A button that allows the player to select a vehicle, and triggers an event wih the vehicle.

◆ StoryPageID

The story page IDs.

Enumerator
STORY_PAGE_INVALID 

An invalid story page id.

Member Function Documentation

◆ GetCompany()

static GSCompany::CompanyID GSStoryPage::GetCompany ( StoryPageID  story_page_id)
static

Get the company which the page belongs to.

If the page is global, GSCompany::COMPANY_INVALID is returned.

Parameters
story_page_idThe story page to get the company for.
Returns
owner company or GSCompany::COMPANY_INVALID
Precondition
IsValidStoryPage(story_page_id).

◆ GetDate()

static GSDate::Date GSStoryPage::GetDate ( StoryPageID  story_page_id)
static

Get the page date which is displayed at the top of each page.

Parameters
story_page_idThe story page to get the date of.
Returns
The calendar-date
Precondition
IsValidStoryPage(story_page_id).
See also
GSCalendarTime

◆ GetPageElementSortValue()

static int GSStoryPage::GetPageElementSortValue ( StoryPageElementID  story_page_element_id)
static

Get story page element sort value.

Each page element has a sort value that is internally assigned and used to sort the page elements within a page of the story book. OpenTTD maintains this number so that the sort order is perceived. This API exist only so that you can sort GSStoryPageList the same order as in GUI. You should not use this number for anything else.

Parameters
story_page_element_idThe story page element to get the sort value of.
Returns
Page element sort value.

◆ GetPageSortValue()

static int GSStoryPage::GetPageSortValue ( StoryPageID  story_page_id)
static

Get story page sort value.

Each page has a sort value that is internally assigned and used to sort the pages in the story book. OpenTTD maintains this number so that the sort order is perceived. This API exist only so that you can sort GSStoryPageList the same order as in GUI. You should not use this number for anything else.

Parameters
story_page_idThe story page to get the sort value of.
Returns
Page sort value.

◆ IsValidStoryPage()

static bool GSStoryPage::IsValidStoryPage ( StoryPageID  story_page_id)
static

Check whether this is a valid story page ID.

Parameters
story_page_idThe StoryPageID to check.
Returns
True if and only if this story page is valid.

◆ IsValidStoryPageButtonColour()

static bool GSStoryPage::IsValidStoryPageButtonColour ( StoryPageButtonColour  colour)
static

Check whether this is a valid story page button colour.

Parameters
colourThe StoryPageButtonColour to check.
Returns
True if and only if this story page button colour is valid.

◆ IsValidStoryPageButtonCursor()

static bool GSStoryPage::IsValidStoryPageButtonCursor ( StoryPageButtonCursor  cursor)
static

Check whether this is a valid story page button cursor.

Parameters
cursorThe StoryPageButtonCursor to check.
Returns
True if and only if this story page button cursor is valid.

◆ IsValidStoryPageButtonFlags()

static bool GSStoryPage::IsValidStoryPageButtonFlags ( StoryPageButtonFlags  flags)
static

Check whether this is a valid story page button flag.

Parameters
flagsThe StoryPageButtonFlags to check.
Returns
True if and only if this story page button flag is valid.

◆ IsValidStoryPageElement()

static bool GSStoryPage::IsValidStoryPageElement ( StoryPageElementID  story_page_element_id)
static

Check whether this is a valid story page element ID.

Parameters
story_page_element_idThe StoryPageElementID to check.
Returns
True if and only if this story page element is valid.

◆ IsValidStoryPageElementType()

static bool GSStoryPage::IsValidStoryPageElementType ( StoryPageElementType  type)
static

Check whether this is a valid story page element type.

Parameters
typeThe StoryPageElementType to check.
Returns
True if and only if this story page element type is valid.

◆ MakePushButtonReference()

static StoryPageButtonFormatting GSStoryPage::MakePushButtonReference ( StoryPageButtonColour  colour,
StoryPageButtonFlags  flags 
)
static

Create a reference value for SPET_BUTTON_PUSH element parameters.

Parameters
colourThe colour for the face of the button.
flagsThe formatting and layout flags for the button.
Returns
A reference value usable with the NewElement and UpdateElement functions.
Precondition
IsValidStoryPageButtonColour(colour).
IsValidStoryPageButtonFlags(flags).

◆ MakeTileButtonReference()

static StoryPageButtonFormatting GSStoryPage::MakeTileButtonReference ( StoryPageButtonColour  colour,
StoryPageButtonFlags  flags,
StoryPageButtonCursor  cursor 
)
static

Create a reference value for SPET_BUTTON_TILE element parameters.

Parameters
colourThe colour for the face of the button.
flagsThe formatting and layout flags for the button.
cursorThe mouse cursor to use when the player clicks the button and the game is ready for the player to select a tile.
Returns
A reference value usable with the NewElement and UpdateElement functions.
Precondition
IsValidStoryPageButtonColour(colour).
IsValidStoryPageButtonFlags(flags).
IsValidStoryPageButtonCursor(cursor).

◆ MakeVehicleButtonReference()

static StoryPageButtonFormatting GSStoryPage::MakeVehicleButtonReference ( StoryPageButtonColour  colour,
StoryPageButtonFlags  flags,
StoryPageButtonCursor  cursor,
GSVehicle::VehicleType  vehtype 
)
static

Create a reference value for SPET_BUTTON_VEHICLE element parameters.

Parameters
colourThe colour for the face of the button.
flagsThe formatting and layout flags for the button.
cursorThe mouse cursor to use when the player clicks the button and the game is ready for the player to select a vehicle.
vehtypeThe type of vehicle that will be selectable, or VT_INVALID to allow all types.
Returns
A reference value usable with the NewElement and UpdateElement functions.
Precondition
IsValidStoryPageButtonColour(colour).
IsValidStoryPageButtonFlags(flags).
IsValidStoryPageButtonCursor(cursor).
vehtype == GSVehicle::VT_INVALID || vehtype == GSVehicle::VT_RAIL || vehtype == GSVehicle::VT_ROAD || vehtype == GSVehicle::VT_WATER || vehtype == GSVehicle::VT_AIR.

◆ New()

static StoryPageID GSStoryPage::New ( GSCompany::CompanyID  company,
Text *  title 
)
static

Create a new story page.

Parameters
companyThe company to create the story page for, or GSCompany::COMPANY_INVALID for all.
titlePage title (can be either a raw string, a GSText object, or null).
Returns
The new StoryPageID, or STORY_PAGE_INVALID if it failed.
Precondition
GSCompanyMode::IsDeity().
company == COMPANY_INVALID || ResolveCompanyID(company) != COMPANY_INVALID.

◆ NewElement()

static StoryPageElementID GSStoryPage::NewElement ( StoryPageID  story_page_id,
StoryPageElementType  type,
int  reference,
Text *  text 
)
static

Create a new story page element.

Parameters
story_page_idThe page id of the story page which the page element should be appended to.
typeWhich page element type to create.
referenceA reference value to the object that is referred to by some page element types. When type is SPET_GOAL, this is the goal ID. When type is SPET_LOCATION, this is the TileIndex. When type is a button, this is the ID returned by MakePushButtonReference, MakeTileButtonReference, or MakeVehicleButtonReference.
textThe body text of page elements that allow custom text. (SPET_TEXT and SPET_LOCATION)
Returns
The new StoryPageElementID, or STORY_PAGE_ELEMENT_INVALID if it failed.
Precondition
GSCompanyMode::IsDeity().
IsValidStoryPage(story_page).
IsValidStoryPageElementType(type).
(type != SPET_TEXT && type != SPET_LOCATION) || (text != null && len(text) != 0).
type != SPET_LOCATION || GSMap::IsValidTile(reference).
type != SPET_GOAL || GSGoal::IsValidGoal(reference).
if type is SPET_GOAL and story_page is a global page, then referenced goal must be global.

◆ Remove()

static bool GSStoryPage::Remove ( StoryPageID  story_page_id)
static

Remove a story page and all the page elements associated with it.

Parameters
story_page_idThe story page to remove.
Returns
True if the action succeeded.
Precondition
GSCompanyMode::IsDeity().
IsValidStoryPage(story_page_id).

◆ RemoveElement()

static bool GSStoryPage::RemoveElement ( StoryPageElementID  story_page_element_id)
static

Removes a story page element.

Parameters
story_page_element_idThe story page element to remove.
Returns
True if the action succeeded.
Precondition
GSCompanyMode::IsDeity().
IsValidStoryPageElement(story_page_element_id).

◆ SetDate()

static bool GSStoryPage::SetDate ( StoryPageID  story_page_id,
GSDate::Date  date 
)
static

Update date of a story page.

The date is shown in the top left of the page

Parameters
story_page_idThe story page to set the date for.
dateCalendar-date to display at the top of story page or GSDate::DATE_INVALID to disable showing date on this page. (also,
See also
GSDate)
Returns
True if the action succeeded.
Precondition
GSCompanyMode::IsDeity().
IsValidStoryPage(story_page_id).
See also
GSCalendarTime

◆ SetTitle()

static bool GSStoryPage::SetTitle ( StoryPageID  story_page_id,
Text *  title 
)
static

Update title of a story page.

The title is shown in the page selector drop down.

Parameters
story_page_idThe story page to update.
titlePage title (can be either a raw string, a GSText object, or null).
Returns
True if the action succeeded.
Precondition
GSCompanyMode::IsDeity().
IsValidStoryPage(story_page_id).

◆ Show()

static bool GSStoryPage::Show ( StoryPageID  story_page_id)
static

Opens the Story Book if not yet open and selects the given page.

Parameters
story_page_idThe story page to update. If it is a global page, clients of all companies are affecetd. Otherwise only the clients of the company which the page belongs to are affected.
Returns
True if the action succeeded.
Precondition
GSCompanyMode::IsDeity().
IsValidStoryPage(story_page_id).

◆ UpdateElement()

static bool GSStoryPage::UpdateElement ( StoryPageElementID  story_page_element_id,
int  reference,
Text *  text 
)
static

Update the content of a page element.

Parameters
story_page_element_idThe page id of the story page which the page element should be appended to.
referenceA reference value to the object that is referred to by some page element types. See also NewElement.
textThe body text of page elements that allow custom text. See also NewElement.
Returns
True if the action succeeded.
Precondition
GSCompanyMode::IsDeity().
IsValidStoryPage(story_page).
(type != SPET_TEXT && type != SPET_LOCATION) || (text != null && len(text) != 0).
type != SPET_LOCATION || GSMap::IsValidTile(reference).
type != SPET_GOAL || GSGoal::IsValidGoal(reference).
if type is SPET_GOAL and story_page is a global page, then referenced goal must be global.