Introduction

Concept

Many games uses statistics mechanisms, for various reasons and differents ways.

Shiny Stats aims to help devs to introduce stats into their games and fine tune the meta. You can create simple to advanced stats mechanisms using Shiny Stats without coding from scratch all the mechanism it involves!

Glossary

Stats in game are confusing. Terms and their meaning differs from games to games. Here is our own vocabulary:

Components

Installation

ShinyStats script

One ShinyStats script must be in the game scene. This script is mandatory as it will store the Shiny Stats configuration for your game.
Best practice could be to place it into an empty dedicated GameObject.

ShinyStats window

Shiny Stats can be configured using the Shiny Stats Editor Window.

ShinyStatsEntity script

Attach the ShinyStatsEntity script to all entities in scenes and in folders (prefabs).
This script will store contextual configuration about the entity such as the current level, its class and its attributes settings.

ShinyStatsModifier script New in v1.1 !

Attach the ShinyStatsModifier script to any gameObject you want that is in a ShinyStatsEntity hierarchy (same gameObject or children).
The ShinyStatsEntity automatically detects the presence of ShinyStatsModifier scripts in children (of self) gameObjects. This script will store contextual configuration about the modifiers.

Configuration

In this section, we will cover all the functionalities of Shiny Stats.

General

Every good things comes with a cool name. The configuration name field is used to identify your game configuration. The entities will have the same configuration name.

Attributes

Attributes is considered as the secondary building element type to define the entity's abilities.
They have constant values that cannot be affected by the entity level. They can be consumed right away using the API and used as variables for stats.

Once the attributes are defined, you can set the attributes values of each entities in their respective Shiny Stats Entity inspector.

Classes

You can have several entities sharing the same attributes values thanks to classes.

You can define them in the home tab.

In the classes tab, you can setup the attributes values.

You can assign the class of each entity in their respective Shiny Stats Entity inspector once you have at least one class defined.
You can select Custom if you want to ignore the existing classes and use a custom configuration.

The Attributes values section will output the corresponding values.

Stats

Stats is the primary building element type to define the entity's abilities.
Unlike attributes, their values can be computed against the entity level.

You can define stats in the home tab.

The stats setup is done under the stats tab.

A stat can be computed using a Manual definition or a Expression definition. The entity to preview GameObject must be in the game scene.

Stat Definition

Manual stat definition

This is the easiest way to do stats !
Using this definition, you will define the stat value from each level by hand. In this mode, you cannot use the attributes and classes.

Expression stat definition

The stat will be computed using a math expression.
The level and the attributes can be used as variables in the math expression.

Info: The result box will appear red if the expression is invalid.

Basic Expressions

Constant example

[Intellect]

Linear example

[Level] * [Stamina]

Logarithmic (like) example

8 + [Strength] * [Level]^0.3

Power (like) example

8 + [Strength] * [Level]^2 / 1000

Advanced Expressions

Logic operators <, > and = will output 0 if false and 1 if true.
This can be used to apply restrictions to the function such as:

([Level] < 31) *
  [Level] * [Strength]
+
([Level] > 30) *
  ([Level] * [Strength] / 2 + 30 * [Strength] / 2)

Level

You can configure the level behavior globally in the home tab.

Minimal level and Maximal level will set the game's level range.
Initial level is the default level for an entity. Resetting an entity will set his level back to the initial value.
Infinite levels can be checked if you don't want a maximum value in your game mechanics.

Each Entity have its own level. You can review and manipulate it in the Shiny Stats Entity inspector or using the API.

Experience

Shiny Stats provide a experience system for entities to increase levels. This is a facultative feature you can activate under the home tab.

It uses a special stats Experience so you can configure the amount of point required to level up for each level.
Similar to levels, each entity have its own experience points. You can review them and edit them in the Shiny Stats Entity inspector or using the API. For each levels, an entity need to gather the amount of points in order to level up.

Can De-level to true will allow entities to lose a level when loosing experience points below 0. Else the experience points bound to 0.
Use surplus Exp points affects how a level-up works. Set to true, the surplus of experience (entity gained more exp than required to level up) will be stored in the next level Exp gauge. If false, the surplus is lost: the entity level up and its experience points is 0.

Global Variables New in v1.2 !

Global Variables are values meant to be used globally in the game. They can be read and modified on the go using the ShinyStats API. They can also be used as variable in Stats' math expression.

Modifier New in v1.1 !

Shiny Stats allows you to apply modification to entities. This is perfect to create status effects, buffs, de-buffs, wearable effect (weapon gameObject increasing strength for instance). This is a facultative feature you can use thanks to the Shiny Stats Modifier Script.

Read how to install modifiers regarding installation and integration.

Attribute/Stat - Name The Attribute or Stat you want to modify.
Multiply by/Add value - value The mathematical operation and value you want to apply.
Priority Useful when you want a modifier to apply before another (Resolve starts from 1 to 9).

You can review all the entity modifiers from the Shiny Stats Entity Inspector.

You can review the modifiers effects from the Shiny Stats Entity Inspector (left without, right with modifiers).

You can preview a stats with and without modifiers.

Usage

Entity synchronization

You have to manually synchronize your entities after editing the attributes, classes and stats.
This is being done using the Shiny Stats Entity inspector sync button.

This might be tedious to keep all the entities synchronized. You can secure this by introducing Semantic Version to your configuration label.

Tip: Shiny Stats warns you during the game runtime if there is a mismatch between an entity and the global config label.

Integrate to your game

Get Strength attribute value

  // Get the ShinyStatsEntity reference of the entity.
  var sse = GetComponent<ShinyStatsEntity>();

    // Get Strength attribute.
    var str = sse.EvaluateAttribute("Strength");
    

Evaluate the Attack power stat value

    // Get the ShinyStatsEntity reference of the entity.
    var sse = GetComponent<ShinyStatsEntity>();

      // Evaluate the Attack power stat (at current level).
      var atk = sse.EvaluateStat("Attack power");

      // Evaluate the Attack power stat (at a specific level).
      var atkLvl12 = sse.EvaluateStat("Attack power", 12);
      

Add experience points

      // Get the ShinyStatsEntity reference.
      var sse = GetComponent<ShinyStatsEntity>();

        // Add experience points. Level-up is automatically handled.
        var newExpPts = sse.AddExp(1200);
        

Use the math expression engine

        var expression = "45 * log(5, 10)";

        // Evaluate the expression.
        var val = ShinyStats.Evaluate(expression);
        

Math functions

All the math functions comes from the official Microsoft .Net Math class.

Meta AnalysisNew in v1.3 !

Intro

Under the panel Meta Analysis, you can find several ways to look at your meta, understand it and find the desired balance.

Stats per Entities (live scene)

This view helps to compare entities in scene at their current levels and active modifiers.

Stats per Classes

This view helps to compare classes at a specific level.

Single Stat in-depth

This view helps to overview a stat for each classes at each levels.

You may need to hit the button Compute Table when the config is changed to refresh the data.

Single Class in-depth

This view helps to overview a class for each stats at each levels.

You may need to hit the button Compute Table when the config is changed to refresh the data.

Stats per Classes, all Levels

This advanced view does not show a table since it would be quite big and poorly useful in the editor. It gives all the combination of classes, stats and levels possible to export so you can work in a Spreadsheet. See the CSV export and Spreadsheet section for more info.

CSV export and Spreadsheet

Each table can be exported with the button found at the table end. The exported CSVs are saved under the folder ShinyStats/Export/{ConfigLabel}/ (missing folders are automatically created).

API Reference

ShinyStats

Properties

Public Methods

ShinyStatsEntity

Properties

Events

Public Methods

Troubleshooting

My Shiny Stats Entity does not reflect the global configuration

Read Entity synchronization.

ShinyStats breaks appart when playing the game. The data is deleted or corrupted.

The issue arises when ShinyStats exists as a prefab in the scene—my recommended setup—and you make changes that are not then updated back to the prefab; instead, they remain within the scene file.
When you play the game under these conditions, it can lead to data inconsistencies that might cause you to experience bugs during game and lose any recent changes upon exiting the game. The problem stems from how Unity handles data saving: it properly saves prefab data (respect of the classes structure...), but doesn't reliably save changes made to gameObjects in the scene (arrays of values...😡).
To resolve this issue, ensure to always apply the modifications to the prefab before playing. Broadly, it's wise to keep an eye on your project's file versioning system to avoid such issues. The scene should not maintain any changes made to the ShinyStats prefab. This advice holds for ShinyStats Entity prefabs as well, and is generally a good practice with scripts that hold structured or complex data.

Modifier GameObjects added or removed are not automatically detected

This happens when the modifier gameObject is moved from its parent to another one (either from code or from the Unity Editor).
Fix this by clicking on Scan for modifiers manually in the Shiny Stats Entity Inspector or by calling ShinyStatsEntity.ScanForModifiers() from code.

Enable Shiny Stats traces

For issues investigation, we might ask you to enable the Shiny Stats traces. To enable the traces, add a SHINYSTATSTRACE variable in the Scripting Define Symbols text box under Edit/Project Settings/Player/Other Settings. Please note that enabling traces will slightly reduce the performance.