Campaigns¶

Custom campaigns: your own series of tracks inside the game's track selection. As soon as any plugin registers a campaign, the play page's sidebar gets a custom campaigns tab under the game's own (circuit, trials, hub, collabs). It is the game's own tab widget, so it hovers, highlights and sounds like them; with no campaign registered it isn't there. The tab lists every registered campaign as a card (picture, title, description). Choosing one opens that campaign's own screen in the same place: its title as the page header, a bar back to the list, an optional note, and its courses as numbered cards with a picture, a title, a line under the title and a text on the right (a best time, say). The game's back button and Escape go from a campaign's screen back to the list, and from the list back where the player came from.

The host draws these screens; your plugin supplies what's on them and decides what a course does. When the player chooses a course, Campaigns::Picked tells you which, and you open it (for example a saved map with Tracks::OpenLocalList). Pictures are PNG or JPG files in your plugin's folder ("images/banner.png", or a full path from Plugins::Folder()), or a game texture ("/Game/..."). A campaign goes away with the plugin that registered it. Requires host 0.26.0.

Register¶

int Campaigns::Register(const string &in title, const string &in image, const string &in description)

Registers a campaign and returns its id (above 0), which the other functions take. The first one registered makes the custom campaigns tab appear. Call it once, in Main.

Example

int campaign;

void Main()
{
    campaign = Campaigns::Register("Summer Series", "images/summer_series.png", "Four courses, one series: race each for your best time.");
    Campaigns::AddCourse(campaign, "Harbour Run", "images/harbour_run.png");
    Campaigns::AddCourse(campaign, "Cliff Loop", "images/cliff_loop.png");
}

Remove¶

bool Campaigns::Remove(int id)

Removes one of your campaigns. When the last campaign of every plugin is gone, so is the tab.

Example

Campaigns::Remove(campaign);

AddCourse¶

int Campaigns::AddCourse(int id, const string &in title, const string &in image)

Adds a course to the end of a campaign's screen and returns its index (0 for the first), or -1 for an id that isn't one of yours.

Example

for (uint i = 0; i < files.length(); i++)
    Campaigns::AddCourse(campaign, titles[i], "images/" + pictures[i]);

SetCourseInfo¶

bool Campaigns::SetCourseInfo(int id, int course, const string &in info)

The texts on a course's card: SetCourseInfo on the right (a best time, "no time yet"), SetCourseDetail on a line under its title (a record, a hint). Setting the text it already has costs nothing, so they can be called every time your numbers might have changed.

Example

Campaigns::SetCourseInfo(campaign, i, best < 0 ? "no time yet" : FormatTime(best));
Campaigns::SetCourseDetail(campaign, i, "world record 1:02.345");

SetCourseDetail¶

bool Campaigns::SetCourseDetail(int id, int course, const string &in detail)

The texts on a course's card: SetCourseInfo on the right (a best time, "no time yet"), SetCourseDetail on a line under its title (a record, a hint). Setting the text it already has costs nothing, so they can be called every time your numbers might have changed.

Example

Campaigns::SetCourseInfo(campaign, i, best < 0 ? "no time yet" : FormatTime(best));
Campaigns::SetCourseDetail(campaign, i, "world record 1:02.345");

SetTheme¶

bool Campaigns::SetTheme(int id, const string &in theme)

The campaign's colours, for its card on the list and the course cards on its own screen (without a theme they use the game's dark cards and its blue when hovered). A list of key=#RRGGBB (or #RRGGBBAA) pairs, separated by spaces; colours as in any paint program (sRGB). Keys:

key	what it colours	if not given
`card`	a card's background	the game's dark card
`hover`	a card under the mouse	the game's blue
`pressed`	a card held down	`hover`, darker
`text`	titles and the right-hand text	white
`body`	the description and the line under a course's title	light grey
`hovertext`	all of a card's text while it's hovered or held	`text` and `body`
`accent`	a rim around every card	no rim
`number`	the course numbers	`text`
`coursecard`, `coursehover`	the course cards only, if they should differ from the list card	`card`, `hover`

False (with the reason in the log) for an unknown key or a colour that isn't #RRGGBB / #RRGGBBAA; the theme it had stays. Each call replaces the whole theme; "" goes back to the game's colours. Pictures on the cards keep their proportions, fitted and centred in their box.

Example

// Deep teal cards, white lettering, an orange rim; orange with dark lettering under the mouse
Campaigns::SetTheme(campaign, "card=#0F4C5C hover=#F28C28 text=#FFFFFF body=#CFE3E8 hovertext=#1A1A1A accent=#F28C28 number=#F28C28");

SetNote¶

bool Campaigns::SetNote(int id, const string &in note)

A line under the campaign screen's back bar: a total, a status, or why a course couldn't be opened. "" for none.

Example

Campaigns::SetNote(campaign, "series total  " + FormatTime(total));

Opened¶

bool Campaigns::Opened(int id)

True once each time the player opens the campaign's screen (from the list, or by Campaigns::Show). A good moment to load your records and fill in the cards.

Example

if (Campaigns::Opened(campaign))
    RefreshCards();

Picked¶

int Campaigns::Picked(int id)

The course the player chose on the campaign's screen (its index), once; -1 when none was. Open it yourself.

Example

int course = Campaigns::Picked(campaign);
if (course >= 0)
    Tracks::OpenLocalList(files, course);

Show¶

bool Campaigns::Show(int id)

Opens the game's play page at the campaign's screen, from the main menu: for example when the player comes back from one of the campaign's races. False for an id that isn't one of yours.

Example

// Back at the main menu after one of our races: our screen again
if (raced && UI::MainMenuShown() && !Race::OnTrack())
{
    raced = false;
    Campaigns::Show(campaign);
}

Shown¶

bool Campaigns::Shown(int id)

Shown is true while the campaign's screen is on screen, ListShown while the list of campaigns is.

Example

if (Campaigns::Shown(campaign))
    RefreshOnlineRecords();

ListShown¶

bool Campaigns::ListShown()

Shown is true while the campaign's screen is on screen, ListShown while the list of campaigns is.

Example

if (Campaigns::Shown(campaign))
    RefreshOnlineRecords();