> For the complete documentation index, see [llms.txt](https://postica.gitbook.io/binding-system-3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://postica.gitbook.io/binding-system-3/reference/extending/modifiers.md). # Custom Modifiers Adding a value transformation of your own. Modifiers change the values before they are read from or written to the source. Like [converters](/binding-system-3/reference/extending/converters.md) they are small to write, and unlike converters they are the extension point you will actually reach for, because most of what a connection needs is a change of value rather than a change of type. {% hint style="success" %} **Learn by doing:** [Writing Your First Modifier](/binding-system-3/tutorials/first-modifier.md) builds a Gamma modifier end to end, including the row summary and the inverse. {% endhint %} {% hint style="danger" %} **A modifier must not change the output type.** Input and output are the same type, or at most the output is of a type derived from the input. Crossing a type boundary is a [converter](/binding-system-3/reference/extending/converters.md), and `IConverter` is not one, so the two extension points do not overlap. {% endhint %} ## The minimum `BaseModifier` gives you the read/write plumbing, so a modifier is one method: ```csharp using System; using UnityEngine; using Postica.BindingSystem; using Postica.BindingSystem.Modifiers; [Serializable] [TypeDescription("Multiplies the value by a bindable factor.")] public class ScaleModifier : BaseModifier { [Tooltip("The factor to multiply by.")] public ReadOnlyBind factor = 1f.Bind(); public override string Id => "Scale"; // The one-line summary shown on a collapsed row. public override string ShortDataDescription => $"× {factor.ToString("factor")}"; protected override float Modify(float value) => value * factor; // Only needed if the modifier can be written through. protected override float InverseModify(float output) => output / factor; } ```

Member	What it is
`Id`	The name in the menu, and the registry key. Unique across the project. It is not persisted with saved instances, so it can be changed later.
`[TypeDescription]`	The tooltip in the Add Modifier menu.
`ShortDataDescription`	The summary on a collapsed row. Use `bind.ToString("name")` so a bound parameter shows its name rather than a stale value.
`Modify`	The read pass.
`InverseModify`	The write pass. Defaults to returning the value unchanged.
`ModifyMode`	Which passes engage. Settable on the row.

## Numeric modifiers for every numeric type Writing one modifier per numeric type is tedious. `NumericModifier` handles all of them through two overloads: ```csharp [Serializable] [TypeDescription("Returns the absolute value of the input numeric value.")] public sealed class AbsoluteValueModifier : NumericModifier { public override string Id => "Absolute Value"; protected override long Modify(long value) => value < 0 ? -value : value; protected override double Modify(double value) => value < 0 ? -value : value; } ``` That is the whole of the built-in **Absolute Value** modifier, and it works for `int`, `long`, `float`, `double` and the rest. ## The interfaces directly When `BaseModifier` does not fit, implement the interfaces yourself.

`IReadWriteModifier` implements both `IReadModifier` and `IWriteModifier`. Implement just one of those if the modifier only works in one direction. The smallest possible modifier is four members and one method: ```csharp public class InvertModifier : IReadWriteModifier { public string Id => "Invert"; public string ShortDataDescription => "[Invert X]"; public BindMode ModifyMode => BindMode.ReadWrite; public bool ModifyRead(in bool value) => !value; // reading from the source public bool ModifyWrite(in bool value) => !value; // writing to the source // The untyped fallback, used when the type is not known at compile time. public object Modify(BindMode modifyMode, object value) => !((bool)value); } ``` This is the built-in shape for modifiers that fan a value out: ```csharp public class PropagateBoolModifier : IReadWriteModifier { [SerializeField] private BindMode _mode; [WriteOnlyBind] public Bind[] targets = new Bind[0]; public bool ModifyRead(in bool value) { for (int i = 0; i < targets.Length; i++) targets[i].Value = value; return value; // pass the value along untouched } public bool ModifyWrite(in bool value) => ModifyRead(value); public object Modify(BindMode mode, object value) => ModifyRead((bool)value); public string Id => "Propagate Boolean"; public string ShortDataDescription => targets.Length == 1 ? "to another target" : $"to other {targets.Length} targets"; public BindMode ModifyMode { get => _mode; set => _mode = value; } } ``` Note the `in` parameter. That is what keeps value types from being boxed on the way through, and it is why a chain of five modifiers on a `float` allocates nothing.

Interface	What it is for
`IModifier`	The root. `Id`, `ShortDataDescription`, `ModifyMode` and the untyped `Modify`.
`IReadModifier<T>`	Read pass only.
`IWriteModifier<T>`	Write pass only.
`IReadWriteModifier<T>`	Both. The usual choice.
`IObjectModifier`	Applies to derived types, with the target type set at runtime through `TargetType`.
`IObjectModifier<T>`	The typed form. Recommended for any modifier that works on instance values and their derived types. Reference types only.
`ISmartModifier`	Receives the owning `IBind`, and can push a value up the chain.
`ISmartValueModifier<T>`	The typed form, with a `SetValue` callback, so it can force a value into the pipeline even when nothing asked for one.
`INullPropagatingModifier`	Handles a null input itself instead of being skipped.
`IRequiresAutoUpdate`	Tells the binding it must update automatically. Anything time based needs this.
`IDynamicComponent`	Declares that the output can change without the input changing.

{% hint style="info" %} `IModifier` still exists and still works, but it is `[Obsolete]`. If you are porting a 2.x modifier, change it to `IReadWriteModifier`. Nothing else about a 2.x modifier needs to change. {% endhint %} ## Modifiers that need time If your modifier animates, delays or smooths, it has to be re-evaluated even when the input has not changed. Two declarations do that: ```csharp public class MyTweenModifier : IReadModifier, IRequiresAutoUpdate, IDynamicComponent { public bool ShouldAutoUpdate => true; // the binding must update automatically public bool UpdateOnEnable => true; // and again when the context is re-enabled public bool IsDynamic => true; // do not cache my output // ... } ``` Without `IRequiresAutoUpdate`, the modifier only runs when something reads the binding. Without `IDynamicComponent`, [phased bindings](/binding-system-3/project-tools/performance/phased-bindings.md) may cache a value that should have moved. ## Drawing options

Attribute	What it does
`[OneLineModifier]`	Draw the modifier on one line rather than as a foldout. Right for a modifier with a single field.
`[ModifierOptions]`	Controls how the modifier is offered: a forced `ModifierMode`, whether similar modifiers for base types are also allowed, and whether it applies to derived types.
`[TypeDescription]`	The description in the menu.

## What the system requires of your class Four rules, all of them enforced by the registration scan rather than by the compiler, so getting one wrong means the modifier simply does not appear in the menu.

Rule	Why
A parameterless constructor	Instances are created with `Activator.CreateInstance`. No constructor arguments are ever passed.
Not `abstract`, not an interface	Base classes of your own are fine, they are simply not offered themselves.
Not an open generic	`MyModifier<T>` needs a closed subclass, or a registered template. See below.
Marked `[Serializable]`	Otherwise Unity cannot store the configured instance inside the binding.

To keep a modifier **out** of the bind menu, put `[HideMember]` on the class. The auto-registration scan skips it, and nothing else changes. {% hint style="info" %} A newly written modifier sometimes needs one more recompilation round before it shows up in the bind menu. If it is missing right after you save, trigger another compile before going looking for the cause. {% endhint %} ## Registration Auto registration finds your modifier. To register explicitly: ```csharp ModifiersFactory.Register(); // A configured instance, offered as-is ModifiersFactory.RegisterModifier(new ScaleModifier { factor = 2f.Bind() }); // A generic modifier, instantiated on demand ModifiersFactory.RegisterTemplate(typeof(MyModifier<>)); ``` `Register(bool registerForBaseTypes)` is worth knowing about. Pass `false` for a modifier specialised on one of your types, so that its base types keep offering the generic modifiers they would otherwise inherit. {% hint style="warning" %} `RegisterModifier` **throws** when the `Id` already exists, unlike converter registration which overwrites. Ids are unique across the project. {% endhint %} {% hint style="danger" %} **Do not rename or move the class once instances exist.** Modifiers are serialized with `[SerializeReference]`, which persists the assembly, namespace and class name. Renaming the class, changing its namespace or moving it to another assembly orphans every instance already saved in a scene, a prefab or an asset, and [Refactoring](/binding-system-3/project-tools/diagnostics/refactoring.md) cannot repair it, because it tracks serialized member paths rather than modifier types. This is why the deprecated `StringFormatModifier` and `StringConcatModifier` are still sitting in their original files, unregistered, rather than being deleted. The `Id` carries no such constraint and is safe to change. {% endhint %} ## Generic modifiers and your own types A modifier written as `MyModifier` cannot be serialized by Unity until some closed `MyModifier` exists. That is the same problem the built-in generic modifiers have, and it has the same solution: see [Standard Modifiers for Your Types](/binding-system-3/pipeline/standard-modifiers.md). ## Testing one ```csharp [Test] public void Scale_Multiplies() { var modifier = new ScaleModifier { factor = 3f.Bind() }; Assert.AreEqual(6f, ((IReadModifier)modifier).ModifyRead(2f)); } ``` ## Read the built-in ones Most of the built-in modifiers ship with their source visible, under `Runtime/Modifiers/`. They are meant to be read, copied and changed: if one of them is nearly what you need, starting from its code is faster than starting from this page. ## Related pages * [Modifiers](/binding-system-3/pipeline/modifiers.md): how the stack behaves. * [Modifier Catalogue](/binding-system-3/pipeline/modifier-catalogue.md): check before you write. * [Standard Modifiers for Your Types](/binding-system-3/pipeline/standard-modifiers.md): the generic ones, closed for your types.