Custom Status Framework 1.1.3

This plugin does not introduce any functionality by itself, but rather provides a framework for other plugins to manipulate the status list that appears in the game UI on the right.

New Version Available

This plugin has been rewritten to improve performance! The new version is now called Simple Status and can be downloaded (for free) here:

Why is it a new plugin and not just an update to this one? Because I understand that many people have already written awesome plugins that utilize CSF and in order to maximize performance, the plugin needed a complete overhaul. So instead of forcing all those developers to update their plugins, I'm letting CSF stay its own thing for now, but I strongly encourage developers to move to Simple Status when they can. With the release of this new plugin, I do not plan on updating CSF at this time.

Positioning

As of v1.1.0 you can optionally designate where on the screen the custom statuses are stacked. The vanilla position will stack the statuses nicely on top of the default game ones, this requires more server processing, but achieves a seamless look with the Rust UI. If you don't mind sacrificing that for greater performance, you can optionally change the position property to any other valid position and the plugin won't have to track all those vanilla Rust statuses.

Valid Positions:

• top left
• top
• top right
• left
• vanilla (default)
• right
• bottom left
• bottom
• bottom right

Performance Tuning

If you are not seeing performance issues, there is no need to make any changes.

As of v1.1.0 there are configuration options that will help you increase performance on your server by disabling/adjusting feature. If you are having performance issues with CSF, please refer to the following configuration tips:

Tip 1: Avoid using the "vanilla" position

In the config you have the option to specify a position. This is where the statuses for CSF are stacked. By default, this is set to "vanilla", which means that any custom statuses will stack on top of the vanilla rust ones. This provides a clean and seamless look, however, in order to achieve this, the plugin must calculate all the scenarios for which vanilla statuses are show and then redraw them for each player on the server - which can cause performance issue. For optimal performance, change the "Position" property to any other valid value (see the Positioning section).

Tip 2: Make sure "Fast Refresh" is set to "false"

By default, as of v.1.1.0, statuses are refreshed once every second, which means that it may take up to one second for a player's status to be removed from their screen. If you you enable "Fast Refresh" in the config, statuses will be updated at a much quicker rate, but this will put more stress on the server. For optimal performance, set "Fast Refresh" to false.

Tip 3: Limit the number of CSF plugins that use global statuses

The more plugins you have that rely on CSF the more updates will need to be made. If a CSF dependent plugin is written optimally (avoiding global/dynamic statuses) then it won't hurt performance much. However, if you are running a lot of plugins that *do* use dynamic/global statuses, then you might see performance issues. It is up to the developer of CSF dependent plugins to utilize CSF efficiently. Try disabling plugins one at a time to see which ones are causing poor performance.

Developer API

Check out this demo for a code example of how to use the API for this plugin. (Updated 9/15/2023)

Note for developers: when possible, avoid using dynamic statuses, as they are a significant performance draw. If possible, instead manually update statuses when appropriate.

	// API Documentation for Custom Status Framework v1.0.5

	// Returns a list of all statuses for a player, both vanilla and custom ones.
        List<string> GetStatusList
        (
            BasePlayer basePlayer
        )
          
        // Returns true if a player has a status matching the given id.
        bool HasStatus
        (
            BasePlayer basePlayer, 
            string id
        )
          
        // Method for showing a simple temporary status to a player.
        // This status will appear and then disappear after some time.
        void ShowStatus
        (
            BasePlayer basePlayer, 
            string id, 
            string color = null, 
            string text = null, 
            string textColor = null, 
            string subText = null, 
            string subTextColor = null, 
            string imageLibraryIconId = null, 
            string iconColor = null, 
            float seconds = 4f
        )
          
        // Creates a status for the given player.
        private void SetStatus
        (
            BasePlayer basePlayer, 
            string id, 
            string color, 
            string text, 
            string textColor, 
            string subText, 
            string subTextColor, 
            string imageLibraryIconId, 
            string iconColor
        )
          
        // Removes the specified status from the given player.
        private void ClearStatus
        (
            BasePlayer basePlayer, 
            string id
        )

        // Performs a ClearStatus and then a SetStatus.
        // Useful if you want to simply refresh a status value.
        private void UpdateStatus
        (
            BasePlayer basePlayer, 
            string id, string color, 
            string text, 
            string textColor, 
            string subText, 
            string subTextColor, 
            string imageLibraryIconId,
            string iconColor
        )

        // Creates a global status with a static value.
        // The value of this status will not change, but will be dynamically applied to all
        // players who meet the specified condition function.
        private void CreateStatus
        (
            string id, 
            string color, 
            string text, 
            string textColor, 
            string subText, 
            string subTextColor, 
            string imageLibraryIconId, 
            string iconColor, 
            Func<BasePlayer, bool> condition
        )
          
        // Creates a global status with a dynamic value.
        // The value of this status will change, and is dynamically set for each player
        // based on the return of the dynamicValue function.
        // This status will be dynamically applied to all players who meet the specified
        // condition function.
        private void CreateDynamicStatus
        (
            string id, 
            string color, 
            string text, 
            string textColor, 
            string subTextColor, 
            string imageLibraryIconId, 
            string iconColor, 
            Func<BasePlayer, bool> condition, 
            Func<BasePlayer, string> dynamicValue
        )
          
        // Deletes a global status by id.
        private void DeleteStatus
        (
            string id
        )