Simple Status 1.2.19

Overview

Provides an API for adding custom status messages that fit alongside the vanilla Rust status UI. Simple Status does not add gameplay statuses on its own; it provides an API that other plugins can use to display them.

As of version 1.3.0, Simple Status supports Facepunch's native CustomVitals system. Compatible statuses are rendered using the native Rust status UI, while unsupported features automatically fall back to the Legacy CUI renderer when required.

Simple Status also supports Advanced Status integration and can automatically switch between Advanced Status, native CustomVitals, and Legacy CUI depending on the server configuration and the features used by each status.

Commands

/ts

Toggles the visibility of statuses for a player. This command can be changed in the config settings.

Configuration

{
  "ChatMessageSteamId": 0,
  "ToggleStatusCommand": "ts",
  "UseCustomVitals": true,
  "UseInternalCustomVitalsWrapper": true,
  "ForceCustomVitalsForUnsupportedStatuses": false,
  "IgnoreAdvancedStatus": false
}

UseCustomVitals - Enables the native Facepunch CustomVitals renderer when available.

UseInternalCustomVitalsWrapper - Uses Simple Status' built-in Facepunch CustomVitals wrapper. This does not require Carbon. If disabled, Simple Status will attempt to use the Carbon/CarbonAliases CustomVitalManager provider instead.

ForceCustomVitalsForUnsupportedStatuses - Forces statuses to remain on CustomVitals even when they use unsupported features. Unsupported features such as progress bars or asset-path icons will not be rendered.

IgnoreAdvancedStatus - When enabled, Simple Status will not use Advanced Status as its renderer and will instead use CustomVitals or Legacy CUI.

Custom Status Framework

This plugin is a sequel to Custom Status Framework and features much better performance. They do the same thing, but are NOT compatible with each other. Do not load both on your server or you may run into issues. Plugins that require Custom Status Framework will need to be updated to  support Simple Status, it is not backwards compatible. If you are a plugin developer and need help writing your plugin to use Simple Status, please reach out to me!

Advanced Status

Simple Status can integrate automatically with Advanced Status. When Advanced Status is installed and IgnoreAdvancedStatus is disabled, it remains the preferred renderer for traditional Simple Status statuses.

If Advanced Status is not being used, Simple Status can render compatible statuses through Facepunch's native CustomVitals system and automatically fall back to Legacy CUI when required.

Developers using the regular Simple Status API do not need to explicitly support each renderer.

API

void CreateStatus(Plugin plugin, string statusId, Dictionary<string, object> properties)
// Registers a status definition.
// OnSimpleStatusReady() is recommended when Simple Status may load after your plugin.
// See the Properties section for supported values.

void SetStatus(string userId, string statusId, int duration = int.MaxValue, bool pauseOffline = true)
// Assigns a player a status with a duration. Set duration to int.MaxValue for an infinite status. Set to 0 to clear a status.

void SetStatusProperty(string userId, string statusId, Dictionary<string, object> properties)
// Set multiple properties for a player status with a single API call. Will minimize the number of redraws, so its better than individually setting properties.
// See the properties section for a list of properties to set.
  
int GetDuration(string userId, string statusId)
// Returns the duration in seconds of a status that a player has. Returns 0 if the player does not have that status.

Hooks

void OnStatusSet(string userId, string statusId, int duration)
// Called when a status is initially set for a player.
  
void OnStatusEnd(string userId, string statusId, int duration)
// Called when a status is removed for a player. (When the duration reaches 0).
  
void OnStatusUpdate(string userId, string statusId, string property, string value)
// Called when a status property is updated.
// See the properties section for a list of properties to set.

Properties

// The following are valid property keys that are used in multiple API methods
var properties = new Dictionary<string, object>
{
    ["color"] = "1 1 1 1",          // Background color
    ["title"] = "hello",             // Left-side text. Localization keys are supported.
    ["titleColor"] = "0 0 0 1",      // Left-side text color
    ["text"] = "subtext",            // Right-side text. Set null to use the duration counter for timed statuses.
    ["textColor"] = "0 0 0 1",       // Right-side text color
    ["icon"] = "star",               // ImageLibrary key, direct URL, raw image key, asset path, or itemid. See Image Types.
    ["iconColor"] = "0 0 0 1",       // Icon color
    ["progress"] = 0.0,              // Progress value between 0.0 and 1.0. Progress bars require Legacy CUI.
    ["progressColor"] = "0 0 0 0.5", // Progress bar color
    ["rank"] = 0                      // Lower ranks are rendered before higher ranks.
};

Image Types

Simple Status supports several icon formats:

ImageLibrary key

["icon"] = "my_icon"

The image must already be registered with ImageLibrary.

Direct image URL

["icon"] = "https://example.com/icon.png"

As of 1.3.0, direct URLs are automatically downloaded through ImageLibrary. Once the image becomes available, Simple Status automatically refreshes affected players.

Raw ImageLibrary key

["icon"] = "raw:my_icon"

Rust asset path

["icon"] = "assets/icons/example.png"

Asset paths can be found here  and item ids can be found here.

Item ID

["icon"] = "itemid:123456789"

Rust asset paths and itemid: icons are supported by the Legacy CUI renderer, but Facepunch CustomVitals does not currently support these formats directly.

When CustomVitals is enabled and a status uses an unsupported icon type, Simple Status automatically falls back to Legacy CUI for that player's Simple Status statuses and prints a one-time compatibility warning.

ImageLibrary keys and direct image URLs are recommended for plugins that want to remain compatible with native CustomVitals.

Native CustomVitals

Version 1.3.0 adds native support for Facepunch CustomVitals.

Standard Simple Status properties map automatically to the native Rust status UI, including:

• background color
• title/left text
• text/right text
• text colors
• compatible icons
• icon color
• rank
• native countdown timers

Some Simple Status features do not currently have a native CustomVitals equivalent:

• progress bars
• Rust assets/... icon paths
• itemid: icons

By default, if any active Simple Status status for a player requires one of these features, all regular Simple Status statuses for that player are temporarily rendered through Legacy CUI. This keeps status ordering and layout consistent.

A one-time console warning identifies which plugin, status, and unsupported feature caused the fallback.

Setting ForceCustomVitalsForUnsupportedStatuses to true disables this automatic fallback, but unsupported features will not be displayed.

Public CustomVitals API

bool IsInternalCustomVitalsWrapperAvailable()

bool SetCustomVital(Plugin plugin, ulong userId, string vitalId, Dictionary<string, object> properties)

bool RemoveCustomVital(Plugin plugin, ulong userId, string vitalId)

bool RemoveCustomVitals(Plugin plugin, ulong userId)

bool RemoveAllCustomVitals(Plugin plugin)

bool HasCustomVital(Plugin plugin, ulong userId, string vitalId)

The Public CustomVitals API provides direct access to Simple Status' internal Facepunch CustomVitals wrapper. It is available when UseCustomVitals and UseInternalCustomVitalsWrapper are enabled and the internal wrapper is available.

This API is separate from the regular Simple Status API and is intended for plugins that specifically need direct native CustomVitals access.

Code Example

This is an example of a plugin that utilizes Simple Status to produce the image in the thumbnail. For plugin developer reference. Download link below:
SimpleStatusDemo.cs