Plugins¶

The plugins currently loaded, in load order. Index i runs from 0 to Count() - 1. Installing, removing and updating the host are only allowed for the plugin manager. For any other plugin the call does nothing and a warning is logged.

Count¶

uint Plugins::Count()

How many plugins are loaded.

Example

// List every loaded plugin in the log
for (uint i = 0; i < Plugins::Count(); i++)
    Log::Info(Plugins::Name(i) + " " + Plugins::Version(i));

Id¶

string Plugins::Id(uint)

The plugin's id: its folder name under plugins\.

Example

// Find where another plugin sits in the list
int IndexOf(const string &in id)
{
    for (uint i = 0; i < Plugins::Count(); i++)
        if (Plugins::Id(i) == id)
            return int(i);
    return -1;
}

Name¶

string Plugins::Name(uint)

The plugin's display name, name in its info.toml.

Example

// "Grind Timer"
string title = Plugins::Name(i);

Version¶

string Plugins::Version(uint)

The plugin's version, version in its info.toml.

Example

// "Grind Timer   0.2.1"
string row = Plugins::Name(i) + "   " + Plugins::Version(i);

Status¶

string Plugins::Status(uint)

The plugin's status: "running", or why it stopped, for example "stopped: exceeded its 30 ms budget" or "exception: Null pointer access in void Update(float) line 10".

Example

// Flag plugins that have stopped
if (Plugins::Status(i) != "running")
    Log::Warn(Plugins::Name(i) + ": " + Plugins::Status(i));

Author¶

string Plugins::Author(uint)

The plugin's author, author in its info.toml.

Example

string byline = "by " + Plugins::Author(i);

Description¶

string Plugins::Description(uint)

The plugin's one-line description, description in its info.toml.

Example

// Name on one line, description under it
panel.AddLine(Plugins::Name(i));
panel.AddLine(Plugins::Description(i));

NetDomains¶

array<string>@ Plugins::NetDomains(uint)

The hosts a plugin may reach with Net:: ([net] domains in its info.toml, public host names only); empty for none. The plugin manager shows them on the plugin's card. Requires host 0.26.0.

Example

array<string>@ hosts = Plugins::NetDomains(i);

Icon¶

string Plugins::Icon(uint)

The full path of the plugin's icon image, or "" if it has none. It can be passed straight to AddImage.

Example

// The plugin's icon, or the default one
string icon = Plugins::Icon(i) != "" ? Plugins::Icon(i) : Plugins::DefaultIcon();
window.AddImage(icon, 48, 48);

Essential¶

bool Plugins::Essential(uint)

Whether the plugin is essential (essential = true in [meta]). Essential plugins are part of the host's own setup, like the plugin manager, and can't be removed.

Example

// No remove button for essential plugins
removeButton.visible = !Plugins::Essential(i);

Enabled¶

bool Plugins::Enabled(uint)

Whether the player has the plugin turned on. A plugin turned off stays installed and listed (its status is off) but doesn't run, and the plugins that depend on it wait for it.

Example

string state = Plugins::Enabled(i) ? "on" : "off";

SetEnabled¶

void Plugins::SetEnabled(const string &in id, bool)

Plugin manager only. Turns a plugin off or back on, straight away and for later launches. Its settings and saved data are kept. The plugin manager itself can't be turned off.

Example

Plugins::SetEnabled("grind-timer", false);

IsInstalled¶

bool Plugins::IsInstalled(const string &in id)

Whether a plugin with this id is loaded.

Example

// Only offer the replay extras if the Replay Manager is there too
bool haveReplayManager = Plugins::IsInstalled("replay-manager");

InstalledVersion¶

string Plugins::InstalledVersion(const string &in id)

The version of the loaded plugin with this id, or "" if there isn't one.

Example

// Compare with the registry's version to offer an update
bool outdated = Plugins::IsInstalled(id) && Plugins::InstalledVersion(id) != Registry::Version(i);

Install¶

void Plugins::Install(const string &in id)

Plugin manager only. Downloads a plugin from the registry, checks every file's SHA-256, and starts it without a restart. Use Pending(id) to follow the progress.

Example

// The browser's install button
if (installButton.Clicked())
    Plugins::Install(Registry::Id(i));

Remove¶

void Plugins::Remove(const string &in id)

Plugin manager only. Stops a plugin, removes its UI and deletes its folder.

Example

if (removeButton.Clicked())
    Plugins::Remove(id);

Pending¶

string Plugins::Pending(const string &in id)

How an install or removal is going: "" (nothing pending), "installing", "removing", or "error: ...".

Example

// Show progress on the button
string state = Plugins::Pending(id);
installButton.label = state == "" ? "install" : state;

DefaultIcon¶

string Plugins::DefaultIcon()

The path of the default icon the plugin manager ships, used for plugins that have no icon of their own.

Example

string icon = Plugins::Icon(i) == "" ? Plugins::DefaultIcon() : Plugins::Icon(i);

OpenFolder¶

void Plugins::OpenFolder()

Opens the plugins folder in File Explorer.

Example

if (folderButton.Clicked())
    Plugins::OpenFolder();

Folder¶

string Plugins::Folder()

The running plugin's own folder, ending in a backslash. Use it to name files the plugin ships, such as images for cosmetics.

Example

string ball = Plugins::Folder() + "ball.png";

ReadFile¶

string Plugins::ReadFile(const string &in file)

A text file from the plugin's own folder, all of it (Windows line ends become \n). file is relative to the folder and may name a subfolder ("data/routes.txt"). Only reads: a name with .., a drive, a leading slash or a Windows device name (CON, NUL, ...) reads nothing, and so does a missing file. Requires host 0.25.0.

Example

string text = Plugins::ReadFile("data/routes.txt");
array<string>@ lines = text.split("\n");

Base64Ints¶

array<int>@ Plugins::Base64Ints(const string &in b64, int bytes)

Numbers packed as base64, for compact data files: little-endian integers of bytes each, 1 (0 to 255), 2 (signed 16-bit) or 4 (signed 32-bit); any other bytes reads as 1. Characters that aren't base64 are skipped. Requires host 0.25.0.

Example

array<int>@ heights = Plugins::Base64Ints(line, 2);     // int16 samples

UpdateHost¶

void Plugins::UpdateHost()

Plugin manager only. Downloads the newest host the registry lists, checks it, and puts it in place. It takes over the next time the game starts. Use HostUpdateState() to follow the progress.

Example

if (updateButton.Clicked() && Registry::HostVersion() != Host::Version())
    Plugins::UpdateHost();

HostUpdateState¶

string Plugins::HostUpdateState()

How a host update is going: "", "downloading", "restart" (ready, restart the game), or "error: ...".

Example

if (Plugins::HostUpdateState() == "restart")
    statusText.text = "restart the game to finish the update";