DecoratorBase Class

Abstract base class for "decorator" types use in Context-based decoration.

While you can inherit from this directly to create new "decorator" types, in most cases you probably want to inherit instead from ValueToClassDecorator<InstanceT, DecorationT>, ClassToClassDecorator<InstanceT, DecorationT>, or ClassToValueDecorator<InstanceT, DecorationT>.

Context-based decoration is a pattern for easily augmenting existing data with additional information ("decorating" it). This is useful for any situation where you want more data to be associated with a specific instance than is provided by that instance by default. For example, PokeInteractors do not expose a notion of "handedness" indicating whether the user is poking with the left or right hand; however, if knowing that information is important for your scenario, you can make it available by decorating the interactor with a handedness value.

The simplest mechanism of decoration is to simply make a Dictionary in which you could associate an individual interactor with a handedness value. This solution is perfectly viable, but it leaves certain question unaddressed. Where is that Dictionary? How do you access it? Who is responsible for removing decorations when the information becomes outdated (such as when the interactor is destroyed)? And, if decorations are added at runtime, how can they be safely queried without risking order-of-operations dependencies?

Another simple mechanism of decoration in Unity is appending MonoBehaviours as decorations. For example, you could make an InteractorHandedness MonoBehaviour with a queryable Handedness field, then attach an instance of that MonoBehaviour to the GameObject of each PokeInteractor you wished to decorate; then, to retrieve your decoration, you could call GetComponent<InteractorHandedness> on the PokeInteractor. This, too, is viable and addresses some of the unanswered questions of a pure Dictionary-based approach. However, it also introduces some limitations and inconveniences: decorations must be characterized as MonoBehaviours or other types fetchable using GetComponent, limiting the types of data that can be used as decorations; and they must be attached to specific GameObjects, which can complicate their integration with prefabs and can have other undesirable side effects such as cluttering the Editor interface.

DecoratorBase and its descendant types (ValueToClassDecorator<InstanceT, DecorationT>, ClassToClassDecorator<InstanceT, DecorationT>, and ClassToValueDecorator<InstanceT, DecorationT>) support Context-based decoration, an alternative pattern to the two described above which avoids some of the issues with each. Conceptually, these decorators are simply Dictionaries that live as singletons on the Context, resolving questions about the decorator's ownership and accessibility. These decorators also automatically manage the lifecycle of their entries (the exact mechanism of which varies by concrete type), resolving questions about removing outdated information. The decorators also all provide both synchronous and asynchronous query mechanisms to deal with the the fact that decorations can be added at any time, providing callers methods to either try to retrieve any decorations available immediately or asynchronously wait until a decoration becomes available. All these capabilities are provided without any constraint on either what can be decorated or what can be used as a decoration: decorations need not be Unity types, and they needn't show up in the Editor unless the developer of the decoration wants them to. In sum, Context-based decoration, supported by DecoratorBase and its descendant types, provides a convenient and flexible way to decorate arbitrary instances with arbitrary data without incurring some of the costs of other approaches.

This is not the say that DecoratorBase and its descendant types should supersede all other forms of decoration. These tools are powerful and valuable for appropriate uses, but may not be valuable for others. Note the conspicuous absence of a ValueToValueDecorator type; this is omitted because value-to-value decoration provides no way for decorators to automatically manage the lifecycle of the decorative relationship (because values have no lifecycle), reducing the utility of a value-to-value decorator over a simple Dictionary to the point where a simple Context-local Dictionary singleton is more appropriate than a specialized decorator type. For further information on the lifecycle management features of the decorators, see the remarks on ValueToClassDecorator<InstanceT, DecorationT>, ClassToClassDecorator<InstanceT, DecorationT>, and ClassToValueDecorator<InstanceT, DecorationT>.