Simple Status 1.1.3

Overview

Provides an API for adding custom status messages that fit in with those of vanilla Rust. This plugin requires another plugin to utilize it, it does not do anything on its own. Check out the "Works With" list above for some plugins that utilize this API.

 

Commands

/ts

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

 

/simplestatus.clearcache

Clears the cache and status data. Only useable as an admin or from the server console. Mostly helpful if you're developing a plugin and want to force it to refresh.

 

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!

 

API

void CreateStatus(Plugin plugin, string statusId, string backgroundColor = "1 1 1 1", string title = "Text", string titleColor = "1 1 1 1", string text = null, string textColor = "1 1 1 1", string imageName = null, string imageColor = "1 1 1 1")
// Registers a new status, should be called during plugin init.
  
void SetStatus(ulong 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 SetStatusColor(ulong userId, string statusId, string color = null)
// Sets the background color of a status for a player. Assign to null to restore the original status color.

void SetStatusTitle(ulong userId, string statusId, string title = null)
// Updates the title property with the specified localization message id.

void SetStatusTitleColor(ulong userId, string statusId, string color = null)
// Sets the color of the title for a player status. Assign to null to restore the original color.
  
void SetStatusText(ulong userId, string statusId, string text = null)
// Sets the text property with the specified localization message id.
  
void SetStatusTextColor(ulong userId, string statusId, string color = null)
// Sets the color of the text for a player status. Assign to null to restore the original color.

void SetStatusIcon(ulong userId, string statusId, string imageLibraryNameOrAssetPath = null)
// Updates the icon for a player status. Accepts a registered image libary name, sprite asset path or item id. See image types section of
// documentation for how to support different images.
  
void SetStatusIconColor(ulong userId, string statusId, string color = null)
// Sets the color of the icon color for a player status. Assign to null to restore the original color.

void SetStatusProperty(ulong 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 OnStatusUpdate hook for valid property keys.
  
int GetDuration(ulong 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(ulong userId, string statusId, int duration)
// Called when a status is initially set for a player.
  
void OnStatusEnd(ulong userId, string statusId, int duration)
// Called when a status is removed for a player. (When the duration reaches 0).
  
void OnStatusUpdate(ulong userId, string statusId, string property, string value)
// Called when a status property is updated.
// The 'property' parameter can be: 'title', 'titleColor', 'text', 'textColor', 'icon', 'iconColor', 'color'

 

Image Types

Using the API you can specify different image types with a prefix. For raw images, prefix the image with "raw:" for item icon ids prefix it with "itemid:". If you want to use a sprite asset path, the plugin will be expecting "assets/". If you just want to use a simple recolorable image then no prefix is required. Here are examples:

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

// An example of adding a star image with ImageLibrary
ImageLibrary.Call<bool>("AddImage", "https://i.imgur.com/vnHTj1C.png", "star", 0UL);

// Sets the icon to the star image added by image library.
SimpleStatus.Call("SetStatusIcon", player.userID, "MyStatusID", "star");

// Sets the icon to the star image, but it will be rendered as a RawImageComponent.
SimpleStatus.Call("SetStatusIcon", player.userID, "MyStatusID", "raw:star");

// Sets the icon to the item icon for scrap which has an id of 1326180354.
SimpleStatus.Call("SetStatusIcon", player.userID, "MyStatusID", "itemid:1326180354");

// Sets the icon to the asset image for the "enter" UI icon.
SimpleStatus.Call("SetStatusIcon", player.userID, "MyStatusID", "assets/icons/enter.png");

Code Example

This is an example of a plugin that utilizes Simple Status to produce the image in the thumbnail. For plugin developer reference.

using Oxide.Core.Libraries.Covalence;
using Oxide.Core.Plugins;
using System.Collections.Generic;

namespace Oxide.Plugins
{
    [Info("SimpleStatusDemo", "mr01sam", "1.1.0")]
    [Description("Allows plugins to add custom status displays for the UI.")]
    partial class SimpleStatusDemo : CovalencePlugin
    {
        [PluginReference]
        private readonly Plugin ImageLibrary;

        [PluginReference]
        private readonly Plugin SimpleStatus;

        public static SimpleStatusDemo PLUGIN;

        private void OnServerInitialized()
        {
            PLUGIN = this;
            ImageLibrary.Call<bool>("AddImage", "https://i.imgur.com/vnHTj1C.png", "star", 0UL);

            // EXAMPLE: SimpleStatus.CallHook("CreateStatus", <plugin>, <statusId>, <backgroundColor>, <title>, <titleColor>, <text>, <textColor>, <imageLibraryNameOrAssetPath>, <iconColor>);
            // TIP: The icon can be either an asset sprite or an image library PNG. In this example we are using sprites for title1 and title2 while using a image library PNG for title3.
            SimpleStatus.CallHook("CreateStatus", this, "status1", "0.77255 0.23922 0.15686 1", "title1", "0.91373 0.77647 0.75686 1", "text1", "0.91373 0.77647 0.75686 1", "assets/icons/home.png", "0.91373 0.77647 0.75686 1");
            SimpleStatus.CallHook("CreateStatus", this, "status2", "0.35490 0.40980 0.24510 1", "title2", "0.69804 0.83137 0.46667 1", "text2", "0.69804 0.83137 0.46667 1", "assets/icons/info.png", "0.69804 0.83137 0.46667 1");
            SimpleStatus.CallHook("CreateStatus", this, "status3", "0.08627 0.25490 0.38431 1", "title3", "0.25490 0.61176 0.86275 1", "text3", "0.25490 0.61176 0.86275 1", "star", "0.25490 0.61176 0.86275 1");
        }

        [Command("show")]
        private void CmdShow(IPlayer player, string command, string[] args)
        {
            int duration = int.MaxValue;
            if (args.Length > 0)
            {
                int.TryParse(args[0], out duration);
            }
            var basePlayer = player.Object as BasePlayer;
            // EXAMPLE: SimpleStatus.CallHook("SetStatus", <userId>, <statusId>, <duration>, <pauseWhenOffline>);
            // TIP: If you want the status to have no duration (be infinite) pass the duration as max value int otherwise,
            //      pass the number of seconds you want it to appear for.
            SimpleStatus.CallHook("SetStatus", basePlayer.userID, "status3", duration);
            SimpleStatus.CallHook("SetStatus", basePlayer.userID, "status2", duration);
            SimpleStatus.CallHook("SetStatus", basePlayer.userID, "status1", duration);
        }

        [Command("change")]
        private void CmdChange(IPlayer player, string command, string[] args)
        {
            var basePlayer = player.Object as BasePlayer;
            // EXAMPLE: SimpleStatus.CallHook("SetStatusProperty", <userId>, <statusId>, <property dictionary>);
            // TIP: You can set multiple properties at once with this method. See documentation for the keys for each
            //      property.
            SimpleStatus.CallHook("SetStatusProperty", basePlayer.userID, "status3", new Dictionary<string, object>
            {
                ["title"] = "changes",
                ["titleColor"] = GetRandomColor()
            });
        }

        [Command("hide")]
        private void CmdHide(IPlayer player, string command, string[] args)
        {
            var basePlayer = player.Object as BasePlayer;
            // TIP: To remove a status from a player, set the duration to 0.
            SimpleStatus.CallHook("SetStatus", basePlayer.userID, "status3", 0);
            SimpleStatus.CallHook("SetStatus", basePlayer.userID, "status2", 0);
            SimpleStatus.CallHook("SetStatus", basePlayer.userID, "status1", 0);
        }

        private string GetRandomColor() => $"{UnityEngine.Random.Range(0f, 1f)} {UnityEngine.Random.Range(0f, 1f)} {UnityEngine.Random.Range(0f, 1f)} 1";

        protected override void LoadDefaultMessages()
        {
            lang.RegisterMessages(new Dictionary<string, string>
            {
                ["title1"] = "Simple",
                ["title2"] = "Status",
                ["title3"] = "Rocks!",
                ["text1"] = "Make",
                ["text2"] = "Custom",
                ["text3"] = "Statuses",
                ["changes"] = "Changes!"
            }, this);
        }
    }
}