Cosmetics¶

Custom balls, hats and goal explosions (the Customize page's bfx). Each one gets a tile in a custom section at the bottom of its tab, and choosing it works like choosing one of the game's. See the custom cosmetics guide for models and how it all fits together; most plugins use Cosmetic Kit rather than calling these directly, so the player's choice is remembered.

Custom cosmetics are only worn on the player's own ball (the menu ball and the racing ball). The game's save, and what other players see, keep the last game cosmetic chosen. Files (images, models) must be inside the plugins folder. Ids must be unique per kind; start them with your plugin's id.

AddBall¶

bool Cosmetics::AddBall(const string &in, const string &in, const string &in, const string &in = "", const string &in = "")

Adds a ball. AddBall(id, name, image, preview, model):

Argument	What it is
`id`	A unique key for this ball, never shown to players. What the player wears is remembered by it, so keep it the same across versions. Start it with your plugin's id and a dot so no two plugins pick the same one: `"my-balls.planet"`.
`name`	The ball's name, shown in the game: `"planet"`.
`image`	The ball's texture: the full path of a PNG in your plugin's folder, twice as wide as it is tall (1024x512). Left to right goes once around the ball, top to bottom from pole to pole. Or `""` for a clear glass ball, to show a `model` inside it.
`preview`	The picture on its tile on the Customize page (a PNG in your folder), or `""` to show the texture.
`model`	Optional: a model file of 3D parts built around the ball and rolling with it (raised details, lights, a spinning blade), a 3D model file (`.glb`, `.gltf` or `.obj`, from host 0.16.0), or `""` for none.

Returns false, and logs why, if it can't be added.

Example

string f = Plugins::Folder();       // this plugin's own folder (where planet.png is)
Cosmetics::AddBall("my-balls.planet",       // id: "<plugin id>.<ball>"
                   "planet",                // name on its tile
                   f + "planet.png",        // texture (1024x512)
                   f + "planet_tile.png",   // tile picture
                   f + "rings.txt");        // model: rings around it ("" for none)

AddHat¶

bool Cosmetics::AddHat(const string &in, const string &in, const string &in, double, const string &in = "", const string &in = "")

Adds a hat. AddHat(id, name, mesh, scale, preview, model):

Argument	What it is
`id`	A unique key, as for balls: `"my-hats.cone"`.
`name`	Its name, shown in the game.
`mesh`	A mesh asset from the game or engine to wear (`"/Engine/BasicShapes/Cone.Cone"`), or `""` when the hat is a `model` instead.
`scale`	Its size where the game puts hats (the top of the ball): 1 is as it is; the engine's 1 m shapes want about 0.45.
`preview`	The picture on its tile, or `""` for none.
`model`	Optional: a model file built on the top of the ball, a 3D model file (`.glb`, `.gltf` or `.obj`, from host 0.16.0), or `""`.

Example

string f = Plugins::Folder();
// a mesh hat
Cosmetics::AddHat("my-hats.cone", "cone", "/Engine/BasicShapes/Cone.Cone", 0.45, f + "cone.png", "");
// a hat made from a model file
Cosmetics::AddHat("my-hats.basket", "fruit basket", "", 1.0, f + "basket.png", f + "basket.txt");

AddBfx¶

bool Cosmetics::AddBfx(const string &in, const string &in, const string &in, double, const string &in = "", const string &in = "",

Adds a goal explosion, based on one of the game's. AddBfx(id, name, base, scale, preview, effect, sound):

Argument	What it is
`id`	A unique key, as for balls: `"my-bfx.confetti"`.
`name`	Its name, shown in the game.
`base`	One of the game's goal explosions to start from (a data asset path, such as `"/Game/Art/DataAssets/GoalExplosions/Fire1/DA_Fire1.DA_Fire1"`).
`scale`	Its size: 1 is the same as the base.
`preview`	The picture on its tile, or `""` for none.
`effect`	Optional: another of the game's Niagara effects to play instead of the base's, or `""`.
`sound`	Optional: another of the game's sounds to play instead of the base's, or `""`.

It plays at checkpoints and in the Customize preview.

Example

Cosmetics::AddBfx("my-bfx.confetti", "confetti",
                  "/Game/Art/DataAssets/GoalExplosions/Fire1/DA_Fire1.DA_Fire1",   // base
                  1.0,                                                             // scale
                  Plugins::Folder() + "confetti.png",                              // tile picture
                  "/Game/Art/NS_BallExplosion.NS_BallExplosion",                   // effect: the confetti burst
                  "/Game/Sound/Menus/SFX_ConfettiGun.SFX_ConfettiGun");            // sound

Count¶

int Cosmetics::Count(Kind)

How many custom cosmetics of a kind there are.

Example

Log::Info(Cosmetics::Count(Cosmetics::Ball) + " custom balls");

Equip¶

bool Cosmetics::Equip(Kind, const string &in)

Wears a custom cosmetic (its id), or "" for the game's own. False if there's no such custom cosmetic. Use it to put back what the player wore last time.

Example

Cosmetics::Equip(Cosmetics::Ball, Storage::Get("ball", ""));

Equipped¶

string Cosmetics::Equipped(Kind)

The custom cosmetic the player wears, or "" while it's one of the game's. It changes when the player picks a tile.

Example

Storage::Set("ball", Cosmetics::Equipped(Cosmetics::Ball));

AddExtra¶

bool Cosmetics::AddExtra(const string &in, const string &in, const string &in, const string &in, const string &in)

Adds an extra: another kind of cosmetic in a slot of its own ("arms"; lowercase letters, digits, dashes and spaces), worn on the player's own balls with their ball and hat, like a custom one (local only). It is a model file in the models format or a 3D model file, built on the ball like a ball's model: put it in a travel group to keep it upright and facing where the ball goes. Each slot gets a tab of its own on the Customize page, after balls, hats and bfx (shown in local mode), with a "none" tile first. The arguments are the slot, an id, the name on its tile, its tile picture and the model. False (and a log line saying why) if it can't be made. Requires host 0.19.0.

Example

string f = Plugins::Folder();
Cosmetics::AddExtra("arms", "my-arms.buff", "Buff Arms", f + "buff.png", f + "models/buff_arms.txt");

EquipExtra¶

bool Cosmetics::EquipExtra(const string &in, const string &in)

Wears an extra in its slot, or "" to take the slot's extra off. False if there's no such extra. Use it to put back what the player wore last time. Requires host 0.19.0.

Example

Cosmetics::EquipExtra("arms", Storage::Get("arms", ""));

EquippedExtra¶

string Cosmetics::EquippedExtra(const string &in)

The extra worn in a slot, or "" for none. It changes when the player picks a tile. Requires host 0.19.0.

Example

Storage::Set("arms", Cosmetics::EquippedExtra("arms"));

PreviewBall¶

bool Cosmetics::PreviewBall(double &out x, double &out y, double &out z, double &out radius, double &out facing)

While the Customize page is shown: the menu ball's middle, its radius in cm (as it's scaled: 35 on this build) and the yaw in degrees that faces the camera. For showing a cosmetic that isn't a model, such as a bounce effect, when it's picked. False when the page isn't shown. Requires host 0.20.0.

Example

double x, y, z, radius, facing;
if (Cosmetics::PreviewBall(x, y, z, radius, facing))
    Draw::Effect("/Game/Art/NS_BallExplosion.NS_BallExplosion", x, y, z - radius, 0.3);

Cosmetics::Kind¶

Cosmetics::Ball, Cosmetics::Hat, Cosmetics::Bfx