SeawispHunter.RolePlay.Attributes README

There comes a time when many a gamedev sets out for adventure but first must
create their own stat class. That is to say a class which captures a game
"stat", or "statistic" for lack of a better word, like health, attack, defense,
etc. This one is mine. Oh wait! there is a better word: "attribute." But I don't
want to take "attribute"¹ from your game, so I'll call mine
IModifiableValue<T>. Consider it a sound building block for you to create
your own attribute class.

These attributes and their derivatives may affect and be effected by a multitude
of transient things, e.g, a sword that bestows an attack advantage; a shield
that raises one's defense; a ring that regenerates health. Because of that
attributes ought to respect the following requirements.

Requirements

An attribute's value shall be altered non-destructively.
Because so many things may alter an attribute, it shall notify us when changed.

Features

Interface Based

The heart of this library is defined by a few interfaces. So one can substitute
their own implementations. Especially helpful if one wants to define modifiers
in Unity for instance.

Supports Generics

Too many libraries decide all attributes must be a float or an int. With
this library one can choose which type suits an attribute, and they may still
interact with one another.

Generic Math

Many a library probably shied away from generics because .NET has not had
generic math support, i.e., it was not possible to write T Plus<T>(T a, T b) => a + b. The release of .NET 7 will have that support, which this library makes
use of. In addition a workaround makes it
possible to present the same API with netstandard2.0, which is important if one
wants to use this library with Unity3D.

Flexible Modifiers

Sure, one can add, minus, multiply, and divide their stats, but what about
clamping the value? Is it easy to add that feature? With this library one can
implement their own modifier or create ad hoc ones
easily.

Barebones Example

var health = new ModifiableValue<float>(100f);
Console.WriteLine($"Health is {health.value}."); // Prints: Health is 100.
health.modifiers.Add(Modifier.Times(1.10f, "+10% health")); 
Console.WriteLine($"Health is {health.value}."); // Prints: Health is 110.
health.modifiers.Add(Modifier.Plus(5f, "+5 health"));
Console.WriteLine($"Health is {health.value}."); // Prints: Health is 115.

Attribute

At its root, an attribute has an initial.value. With no modifiers present, its
value equals its initial.value; its value is altered by modifiers starting
from its initial.value.

public interface IModifiableValue<T> {
  T initial.value { get; set; }
  T value { get; }
  /** The list implementation sets up property change events automatically. */
  ICollection<IModifier<T>> modifiers { get; }
  event PropertyChangedEventHandler PropertyChanged;
}

Just to be explicit, an attribute's value $v$ that had an initial value $i$ and three
modifiers $m_1, m_2, m_3$ would be computed like this:

$$ v = m_3(m_2(m_1(i))) $$

Modifier

A modifier accepts a value and can change it arbitrarily.

public interface IModifier<T> {
  bool enabled { get; set; }
  T Modify(T given);
  event PropertyChangedEventHandler PropertyChanged;
}

However, often times the changes one wants to make are simple: add a value,
multiple a value, or substitute a value so these are made convenient for int,
float, and double types.

public static class Modifier {
  public static IModifier<T> Plus(T value, string name = null);
  public static IModifier<T> Minus(T value, string name = null);
  public static IModifier<T> Times(T value, string name = null);
  public static IModifier<T> Divide(T value, string name = null);
  public static IModifier<T> Substitute(T value, string name = null);
}

Change Propogation

These classes use the INotifyPropertyChanged interface to propogate change
events, so any modifier that's changed or added will notify its attribute which
will notify any of its listeners. No need to poll for changes to an attribute.

Abridged API

The API shown above is abridged to make its most salient points easy to
understand. The actual code includes some abstractions like IValue<T> and
IReadOnlyValue<T> which are used to make attributes reuseable as modifiers
for instance.

Indeed this README has outright
lies
and is better for it.

Further Examples

Using Notifications

var health = new ModifiableValue<float>(100f);
health.PropertyChanged += (_, _) => Console.WriteLine($"Health is {health.value}.");
health.modifiers.Add(Modifier.Times(1.10f, "+10% health"));
// Prints: Health is 110.
health.modifiers.Add(Modifier.Plus(5f, "+5 health"));
// Prints: Health is 115.

Modeling a Consumable Attribute

Let's create a current health value to pair with a max health attribute.

var maxHealth = new ModifiableValue<float>(100f);
var health = new BoundedValue<float>(maxHealth.value, 0f, maxHealth);

health.PropertyChanged += (_, _) => Console.WriteLine($"Health is {health.value}/{maxHealth.value}.");
// Prints: Health is 100/100.
health.value -= 10f;
// Prints: Health is 90/100.
maxHealth.modifiers.Add(Modifier.Plus(20f, "+20 level gain"));
// Prints: Health is 90/120.

Using an Attribute as a Modifier

In addition to creating modifiers with a static value like Modifier.Plus(20f),
one can also create dynamic modifiers based on other values or attributes.

Suppose "max health" is affected by "constitution" like this.

var constitution = new ModifiableValue<int>(10);
int level = 10;
// We can project values with some limited LINQ-like extension methods.
var hpAdjustment = constitution.Select(con => (float) Math.Round((con - 10f) / 3f) * level);
var maxHealth = new ModifiableValue<float>(100f);

maxHealth.PropertyChanged += (_, _) => Console.WriteLine($"Max health is {maxHealth.value}.");
maxHealth.modifiers.Add(Modifier.Plus(hpAdjustment));
// Prints: Max health is 100.
constitution.initial.value = 15;
// Prints: Max health is 120.

Note: the attributes are different data types: constitution is an int,
maxHealth is a float.

One might notice that hpAdjustment depends on the value of level. One would
hope that a change to level would notify hpAdjustment and ultimately
maxHealth; however, because level is an int that won't happen. See the
Advanced Examples for how to include level changes
elegantly.

Creating New Modifiers

New modifiers can be created by implementing the IModifier<T> interface or by
using the convenience methods in Modifier like FromFunc() shown below.
Perhaps one has armor that bestows different affects depending on the phase of
the moon².

var moonArmor = new ModifiableValue<float>(20f);
moonArmor.modifiers.Add(Modifier.Create((float x) => DateTime.Now.IsFullMoon() ? 2 * x : x));

Ordering Modifiers

The priority of a modifier defines its order. The default priority is 0. Lower
numbers apply earlier; higher numbers apply later. Modifiers of the same
priority apply in the order of they were inserted. This also demonstrates how we
can clamp a value by creating an ad hoc modifier with a Func<float,float>.

var maxMana = new ModifiableValue<float>(50f);
var mana = new Modifiable<IReadOnlyValue<float>,float>(maxMana); // maxMana is an IReadOnlyValue.
var manaCost = Modifier.Minus(0f);
mana.modifiers.Add(manaCost);
mana.PropertyChanged += (_, _) => Console.WriteLine($"Mana is {mana.value}/{maxMana.value}.");
mana.modifiers.Add(priority: 100, Modifier.Create((float x) => Math.Clamp(x, 0, maxMana.value));
// Prints: Mana is 50/50.
manaCost.value = 1000f;
// Prints: Mana is 0/50.

Time Out a Modifier

There are EnableAfter() and DisableAfter() extension methods for IModifier<T>.

var armor = new ModifiableValue<int>(10);
var powerUp = Modifier.Plus(5);
armor.modifiers.Add(powerUp);
health.PropertyChanged += (_, _) => Console.WriteLine($"Armor is {armor.value}.");
// Prints: Armor is 15.
powerUp.DisableAfter(TimeSpan.FromSeconds(20f));
// ... 
// [Wait 20 seconds.]
// Prints: Armor is 10.

Advanced Examples

Synthesizing Multiple Values

In the above constitution example, level is an int so hpAdjustment does
not update when it's changed. Instead, we can take another page out of LINQ and
use a Zip() extension method to synthesize two values. This way a change to
either level or constitution will notify hpAdjustment and therefore
maxHealth.

var constitution = new ModifiableValue<int>(10);
var level = new Value<int>(10);
// We can project values, with some limited LINQ-like extension methods.
var hpAdjustment = constitution.Zip(level, (con, lev) => (float) Math.Round((con - 10f) / 3f) * lev);
var maxHealth = new ModifiableValue<float>(100f);

maxHealth.PropertyChanged += (_, _) => Console.WriteLine($"Max health is {maxHealth.value}.");
maxHealth.modifiers.Add(Modifier.Plus(hpAdjustment));
// Prints: Max health is 100. (unchanged)
constitution.initial.value = 15;
// Prints: Max health is 120.
level.value = 15;
// Prints: Max health is 130.

Writing Your Own Attribute Class

One can go far with IModifiableValue<T> but one may want to organize modifiers
beyond just their order at some point. There are plenty of ways to do this.
Seeing as this library's design was informed by a number of sources:

RPGSystems: Stat System 03: Modifiers by Jacob Penner;
Character Stats (aka Attributes) System by Kryzarel.

What would their stats classes look like rewritten in this library?

Jacob Penner's Stat Class

Here is an example of what an attribute class might look like if organized
like Jacob
Penner:

public class PennerStat<T> : ModifiableValue<T> {
  public readonly IModifiableValue<T> baseValuePlus = new ModifiableValue<T>();
  public readonly IModifiableValue<T> baseValueTimes = new ModifiableValue<T>(one);
  public readonly IModifiableValue<T> totalValuePlus = new ModifiableValue<T>();
  public readonly IModifiableValue<T> totalValueTimes = new ModifiableValue<T>(one);

  public PennerStat() {
    // value = (baseValue * baseValueTimes + baseValuePlus) * totalValueTimes + totalValuePlus
    modifiers.Add(100, Modifier.Times(baseValueTimes));
    modifiers.Add(200, Modifier.Plus(baseValuePlus));
    modifiers.Add(300, Modifier.Times(totalValueTimes));
    modifiers.Add(400, Modifier.Plus(totalValuePlus));
  }

  private static T one => Modifier.GetOp<T>().one;
}

Kryzarel's Stat Class

Kryzarel's
Stat class might look like this:

public class KryzarelStat<T> : ModifiableValue<T> {
  public enum Priority {
    Flat = 100,
    PercentAdd = 200,
    PercentTimes = 300
  };

  public readonly IModifiableValue<T> flat = new ModifiableValue<T>();
  public readonly IModifiableValue<T> percentAdd = new ModifiableValue<T>(one);
  public readonly IModifiableValue<T> percentTimes = new ModifiableValue<T>(one);

  public KryzarelStat() {
    // value = (baseValue + flat) * percentAdd * percentTimes
    modifiers.Add((int) Priority.Flat, Modifier.Plus(flat));
    modifiers.Add((int) Priority.PercentAdd, Modifier.Times(percentAdd));
    modifiers.Add((int) Priority.PercentTimes, Modifier.Times(percentTimes));
  }

  private static T one => Modifier.GetOp<T>().one;
}

Some care might need to be taken when adding modifiers to preserve the
original's behavior.

var stat = new KryzarelStat(30f);
stat.flat.modifiers.Add(Modifier.Plus(10f)); // flat expects plus modifiers (or subtract).
stat.percentAdd.modifiers.Add(Modifier.Plus(10f)); // percentAdd expects plus modifiers (or subtract).
stat.percentTimes.modifiers.Add(Modifier.Times(1.2f, "+20%")); // percentTimes expects times modifiers (or divide but who does that?).

But that's either a discipline you can adopt or a convenience method you can
write. A small price to pay for the flexibility these modifiers
provide.

Other Stat Classes

See the
Style.cs
file for more examples.

And please feel free to share any that you develop with me
@shanecelis.

Notes

Dealing with Math in Generics

.NET 7 has generic math
operators, which
will be a godsend. It will allow us to write methods like this:

T Plus<T>(T a, T b) where T : INumber<T> => a + b;

which is invalid for prior versions.

This attributes library makes use of this generic math, however, we also want to
support netstandard2.0 because that's what Unity supports. So here's a trick
given by this article
to allow you to do generic math without .NET 7's INumber<T> support.

interface IOperator<T> {
  T Plus(T a, T a)
}

struct OpFloat : IOperator<float> {
  public float Plus(float a, float b) => a + b;
}

void SomeProcessing<T, TOperator>(...) where TOperation : struct, IOperator<T> {
  T var1 = ...;
  T var2 = ...;
  T sum = default(TOperator).Plus(var1, var2);  // This is zero cost!
}

void Caller() {
  SomeProcessing<float, OpFloat>(...);
}

License

This project is released under the MIT license.

Acknowledgments

This project was inspired and informed by the following sources:

How to Make an RPG: Stats by Dan Schuller;
RPGSystems: Stat System 03: Modifiers by Jacob Penner;
Using the Composite Design Pattern for an RPG Attributes System Daniel Sidhion;
Character Stats (aka Attributes) System by Kryzarel.
Kryzarel has an associated Unity3D Character Stats asset.

I am indebted to each of them for the generosity they showed in writing about
the role playing attributes problem, both for their prose and code.

Or "Attribute", "IAttribute", etc. ↩
Unfortunately there is no such extension method IsFullMoon() for DateTime by
default but one can add it. ↩

FreakyFreakyNerd/SeawispHunter.RolePlay.Attributes

SeawispHunter.RolePlay.Attributes README

Requirements

Features

Barebones Example

Attribute

Modifier

Change Propogation

Abridged API

Further Examples

Using Notifications

Modeling a Consumable Attribute

Using an Attribute as a Modifier

Creating New Modifiers

Ordering Modifiers

Time Out a Modifier

Advanced Examples

Synthesizing Multiple Values

Writing Your Own Attribute Class

Jacob Penner's Stat Class

Kryzarel's Stat Class

Other Stat Classes

Notes

Dealing with Math in Generics

License

Acknowledgments

On this page

Languages

Contributors

FreakyFreakyNerd/SeawispHunter.RolePlay.Attributes

SeawispHunter.RolePlay.Attributes README

Requirements

Features

Barebones Example

Attribute

Modifier

Change Propogation

Abridged API

Further Examples

Using Notifications

Modeling a Consumable Attribute

Using an Attribute as a Modifier

Creating New Modifiers

Ordering Modifiers

Time Out a Modifier

Advanced Examples

Synthesizing Multiple Values

Writing Your Own Attribute Class

Jacob Penner's Stat Class

Kryzarel's Stat Class

Other Stat Classes

Notes

Dealing with Math in Generics

License

Acknowledgments

Footnotes

On this page

Languages

Contributors