Workshop¶

The workshop's maps, searched and listed the ways Steam can: by text, with any of Steam's rankings, by tags, and a player's own lists (played, favourites, subscriptions, likes, published). Every map a query returns is kept, so the functions that take a map's id (Title, Author, Plays, ...) answer for any map a query has returned. Also who made a map and this player's progress on it. Queries run in the background: start one, then read State until it's "done". Everything here needs host 0.23.0.

Find¶

int Workshop::Find(const string &in text = "", const string &in sort = "top", int page = 1, int days = 7,

Starts a search of every map: text to match (in a title, description or tag; "" for every map), sort one of "relevance" (needs text), "top", "trending" (over the last days days), "new", "updated", "played", "subscribed", "liked" or "unrated", then page (1-based, 50 maps a page). withTags are tags a map needs (all of them, or any one with anyTag), withoutTags tags it mustn't have. Returns the query's number, or -1 (with a warning in the log) for an unknown sort or without Steam.

Example

int newest = Workshop::Find("", "new");
array<string> with = {"flow"}, without = {"troll"};
int flowMaps = Workshop::Find("", "top", 1, 7, with, without);

FindList¶

int Workshop::FindList(const string &in list, const string &in user = "", const string &in sort = "new", int page = 1)

Starts a query of one player's list: "published", "played", "favorited", "subscribed", "liked" or "disliked". user is a Steam id ("": you, and only your own lists other than published are public to you), sort one of "new", "old", "title", "updated", "top" or "subscribed", 50 maps a page.

Example

int theirs = Workshop::FindList("published", Workshop::Author(id));
int mine = Workshop::FindList("played");

FindIds¶

int Workshop::FindIds(const array<string>@ ids)

Starts a query for these maps by id (up to 50), to read about maps no other query has returned.

Example

array<string> ids = {"3412345678", "3423456789"};
int q = Workshop::FindIds(ids);

State¶

string Workshop::State(int)

"searching", "done" or "error: ..."; "" for a query that doesn't exist (or was forgotten).

Example

if (Workshop::State(query) == "done")
    ShowResults();

Count¶

int Workshop::Count(int)

How many maps a finished query returned (this page).

Example

for (int i = 0; i < Workshop::Count(query); i++)
    Log::Info(Workshop::Title(Workshop::Id(query, i)));

Total¶

int Workshop::Total(int)

How many maps match the query in all, over every page.

Example

int pages = (Workshop::Total(query) + 49) / 50;

Id¶

string Workshop::Id(int, int)

The id of a map a query returned, by its place in the results.

Example

string id = Workshop::Id(query, 0);

Forget¶

void Workshop::Forget(int)

Forgets a query's results (the maps themselves are still known by id). Queries past the 256 newest are forgotten by themselves.

Example

Workshop::Forget(query);

Title¶

string Workshop::Title(const string &in)

A map's title; "" if no query has returned it.

Example

titleText.text = Workshop::Title(id);

Author¶

string Workshop::Author(const string &in)

The Steam id of the player who made a map. Their name is Workshop::Name.

Example

string author = Workshop::Author(id);

Description¶

string Workshop::Description(const string &in)

A map's description, as its author wrote it on the workshop.

Example

descriptionArea.text = Workshop::Description(id);

Tags¶

string Workshop::Tags(const string &in)

A map's tags, separated by commas, as on Steam ("map,beginner,flow").

Example

bool flow = Workshop::Tags(id).findFirst("flow") >= 0;

Created¶

int64 Workshop::Created(const string &in)

When a map was published, in seconds since 1970 (UTC).

Example

int64 age = Workshop::Created(id);

Updated¶

int64 Workshop::Updated(const string &in)

When a map was last updated, in seconds since 1970 (UTC).

Example

bool updated = Workshop::Updated(id) > Workshop::Created(id);

VotesUp¶

int Workshop::VotesUp(const string &in)

How many players liked a map.

Example

Log::Info(Workshop::VotesUp(id) + " likes");

VotesDown¶

int Workshop::VotesDown(const string &in)

How many players disliked a map.

Example

Log::Info(Workshop::VotesDown(id) + " dislikes");

Score¶

float Workshop::Score(const string &in)

Steam's rating of a map, 0 to 1, from its likes and dislikes.

Example

float stars = Workshop::Score(id) * 5;

Plays¶

int64 Workshop::Plays(const string &in)

How many times a map has been played (Steam's count of play sessions, the number the game's hub shows).

Example

Log::Info(Workshop::Plays(id) + " plays");

Subscribers¶

int64 Workshop::Subscribers(const string &in)

How many players have subscribed to a map.

Example

Log::Info(Workshop::Subscribers(id) + " subscribers");

Favorites¶

int64 Workshop::Favorites(const string &in)

How many players have a map in their favourites.

Example

Log::Info(Workshop::Favorites(id) + " favourites");

Size¶

int64 Workshop::Size(const string &in)

The size of a map's file, in bytes.

Example

Log::Info((Workshop::Size(id) / 1024) + " KB");

Image¶

string Workshop::Image(const string &in)

A map's preview picture for Window.AddImage: the game's own cached copy, or one downloaded here. "" until there is one; asking starts the download, so ask again a moment later.

Example

string image = Workshop::Image(id);
if (image != "")
    picture.path = image;

Name¶

string Workshop::Name(const string &in)

A Steam player's name, by Steam id. "" while Steam is still being asked (asking starts it); ask again later.

Example

string name = Workshop::Name(Workshop::Author(id));
bylineText.text = name == "" ? "" : "by " + name;

Me¶

string Workshop::Me()

Your own Steam id.

Example

bool mine = Workshop::Author(id) == Workshop::Me();

MyBest¶

double Workshop::MyBest(const string &in)

Your best time on a map in seconds, from the game's save; 0 if you haven't finished it.

Example

double best = Workshop::MyBest(id);

MyMedal¶

int Workshop::MyMedal(const string &in)

Your medal on a map, from the game's save: -1 if you haven't finished it, else 0 none, 1 bronze, 2 silver, 3 gold, 4 author.

Example

bool needsGold = Workshop::MyMedal(id) < 3;

Finished¶

array<string>@ Workshop::Finished()

The ids of every workshop map the game's save has a time for.

Example

Log::Info(Workshop::Finished().length() + " workshop maps finished");

MyRank¶

int Workshop::MyRank(const string &in)

Your place on a map's leaderboard: -1 while it's being looked up (asking starts it, for a map a query has returned), 0 if you have no time on it, else your rank.

Example

int rank = Workshop::MyRank(id);
if (rank > 0)
    rankText.text = "#" + rank + " of " + Workshop::Players(id);

Players¶

int Workshop::Players(const string &in)

How many players have a time on a map's leaderboard; 0 until Workshop::MyRank has looked it up.

Example

int players = Workshop::Players(id);