{"id":75,"date":"2021-10-24T07:49:38","date_gmt":"2021-10-24T07:49:38","guid":{"rendered":"https:\/\/docs.sisus.co\/inity\/?p=75"},"modified":"2025-12-28T14:01:12","modified_gmt":"2025-12-28T14:01:12","slug":"wrapper","status":"publish","type":"post","link":"https:\/\/docs.sisus.co\/init-args\/wrappers\/wrapper\/","title":{"rendered":"1. Wrappers"},"content":{"rendered":"

Wrappers can be used to attach plain old C# objects to a GameObjects, have them receive callbacks during Unity events like Update and OnDestroy, and to start coroutines.<\/p>\n

Creating a Wrapper<\/h2>\n

Let\u2019s say you had a plain old C# class called Player:<\/p>\n

using<\/span> System;<\/span><\/span>\r\nusing<\/span> UnityEngine;<\/span><\/span>\r\n\r\n[<\/span>Serializable]<\/span><\/span>\r\npublic<\/span> class<\/span> Player<\/span><\/span>\r\n{<\/span><\/span>\r\n    [<\/span>SerializeField]<\/span><\/span>\r\n    private<\/span> Id id;<\/span><\/span>\r\n\r\n    [<\/span>SerializeField,<\/span> Range(<\/span>0f,<\/span> 10f)<\/span>]<\/span><\/span>\r\n    private<\/span> float<\/span> speed;<\/span><\/span>\r\n\r\n    public<\/span> Player<\/span>(<\/span>Id id,<\/span> float<\/span> speed)<\/span><\/span>\r\n    {<\/span><\/span>\r\n        this<\/span>.<\/span>id =<\/span> id;<\/span><\/span>\r\n        this<\/span>.<\/span>speed =<\/span> speed;<\/span><\/span>\r\n    }<\/span><\/span>\r\n}<\/span><\/span><\/pre>\n
The easiest way to create a Wrapper component for the class is to select the script, open its context menu in the Inspector and select Generate Wrapper<\/strong>.<\/p>\n
\"\"<\/p>\n
Or you could also create it manually by defining a class that inherits from Wrapper<Player>.<\/p>\n
[<\/span><\/span>AddComponentMenu(<\/span>\"Wrapper\/Player\")]<\/span>\r\nclass<\/span> PlayerComponent :<\/span> Wrapper<<\/span>Player> { }<\/span><\/span><\/pre>\n
The AddComponentMenu attribute is optional; it just makes the PlayerComponent appear as simply “Player” in the Inspector and the Add Component menu.<\/p>\n
If the wrapped class has the [Serializable] attribute, then an instance of it will be automatically created for any wrappers that exist as part of scene or prefab assets, and the objects serializable fields will be visible in the Inspector.<\/p>\n
\"\"<\/p>\n
Initializing a Wrapper<\/h2>\n
[Serializable] Attribute<\/h3>\n
As stated before, if the wrapped class has the [Serializable] attribute, then an instance will be automatically created for all wrappers that exist as part of scene or prefab assets.<\/p>\n
Provide Instance Via Constructor<\/h3>\n
If the wrapped object is not serializable, and doesn’t depend any external Object references or services<\/a>, then you can initialize the instance right in the wrapper’s parameterless constructor, and pass it to the base constructor which accepts the instance as an argument.<\/p>\n
[AddComponentMenu(\"Wrapper\/Player\")]<\/span>\r\nsealed class PlayerComponent : Wrapper<Player><\/span>\r\n{<\/span>\r\n    public PlayerComponent() : base(new Player(Id.NewId(), 0f)) { }<\/span>\r\n}<\/span><\/pre>\n
Pass Instance During Instantiation<\/h3>\n
As wrappers implement IInitializable<TWrapped><\/a>, it means that you can also pass an instance to the component when creating an instance using Instantiate or AddComponent<\/a>.<\/p>\n
For example, an instance of Player could be attached to a game object like this:<\/p>\n
Player player =<\/span> new<\/b><\/span> Player(<\/span>id,<\/span> 0f)<\/span>;<\/span><\/span>\r\ngameObject.<\/span>AddComponent<<\/span>PlayerComponent,<\/span> Player>(<\/span>player)<\/span>;<\/span><\/span><\/pre>\n
Wrapper Initializer<\/h3>\n
If the wrapped object depends on services<\/a>, or you want to assign some arguments using the Inspector, you can generate an Initializer<\/a> for the wrapper component.<\/p>\n
The initializer should derive from WrapperInitializer<T…>, with its generic arguments of being the types of the wrapper component, the wrapped object, and all the objects the wrapped object needs to be provided to it.<\/p>\n
public<\/span> class<\/span> PlayerInitializer<\/span> :<\/span> WrapperInitializer<<\/span>PlayerComponent,<\/span> Player,<\/span> Id,<\/span> float<\/span>><\/span><\/span>\r\n{<\/span><\/span>\r\n    private<\/span> class<\/span> Init<\/span><\/span>\r\n    {<\/span><\/span>\r\n        public<\/span> Id Id;<\/span><\/span>\r\n\r\n        [<\/span>Range(<\/span>0f,<\/span> 10f)<\/span>]<\/span> public<\/span> float<\/span> Speed;<\/span><\/span>\r\n    }<\/span><\/span>\r\n\r\n    protected<\/span> override<\/span> Player CreateWrappedObject<\/span>(<\/span>Id id,<\/span> float<\/span> speed)<\/span><\/span>\r\n    {<\/span><\/span>\r\n        Debug.<\/span>Assert(<\/span>id !<\/span>=<\/span> Id.<\/span>Empty)<\/span>;<\/span><\/span>\r\n        Debug.<\/span>Assert(<\/span>speed ><\/span> 0f)<\/span>;<\/span><\/span>\r\n\r\n        return<\/span> new<\/span> Player(<\/span>id,<\/span> speed)<\/span>;<\/span><\/span>\r\n    }<\/span><\/span>\r\n}<\/span><\/span><\/pre>\n
You can optionally also define a nested class named “Init<\/em>” inside the Initializer\u00a0 class, containing fields whose types match those of the arguments that the client accepts. If you do this, you can then attach property attributes to its fields, and their property drawers will be used when drawing the matching Init arguments in the Inspector.<\/div>\n
<\/div>\n
When you use a Wrapper Initializer, it will take care of serializing all the arguments that will be passed to the client. This means that the client class itself does not necessarily need to be serializable.<\/div>\n
\n
public<\/span> class<\/span> Player<\/span><\/span>\r\n{<\/span><\/span>\r\n    public<\/span> Id Id {<\/span> get<\/span>;<\/span> }<\/span><\/span>\r\n    public<\/span> float<\/span> Speed {<\/span> get<\/span>;<\/span> }<\/span><\/span>\r\n\r\n    public<\/span> Player<\/span>(<\/span>Id id,<\/span> float<\/span> speed)<\/span><\/span>\r\n    {<\/span><\/span>\r\n        Id =<\/span> id;<\/span><\/span>\r\n        Speed =<\/span> speed;<\/span><\/span>\r\n    }<\/span><\/span>\r\n}<\/span><\/span><\/pre>\n<\/div>\n
\"\"<\/h2>\n
Unity Events<\/h2>\n
Wrapped objects can receive callbacks during select Unity events from their wrapper by implementing one of the following interfaces:<\/p>\n
    \n
  1. IAwake <\/b>– Receive callback during the MonoBehaviour.Awake event.<\/li>\n
  2. I<\/b>O<\/b>nEnable<\/b> – Receive callback during the MonoBehaviour.OnEnable event.<\/li>\n
  3. I<\/b>S<\/b>tart<\/b> – Receive callback during the MonoBehaviour.Start event.<\/li>\n
  4. I<\/b>U<\/b>pdate<\/b> – Receive callback during the MonoBehaviour.Update event.<\/li>\n
  5. I<\/b>F<\/b>ixedUpdate<\/b> – Receive callback during the MonoBehaviour.FixedUpdate event.<\/li>\n
  6. I<\/b>L<\/b>ateUpdate<\/b> – Receive callback during the MonoBehaviour.LateUpdate event.<\/li>\n
  7. I<\/b>O<\/b>nDisable<\/b> – Receive callback during the MonoBehaviour.OnDisable event.<\/li>\n
  8. IOnDestroy<\/b> – Receive callback during the MonoBehaviour.OnDestroy event.<\/li>\n<\/ol>\n
    For example, to receive callbacks during the Update event the Player class would need to be modified like this:<\/p>\n
    public<\/b><\/span> class<\/b><\/span> Player :<\/span> IUpdate<\/span>\r\n{<\/span>\r\n        public<\/b><\/span> void<\/b><\/span> Update(<\/span>float<\/b><\/span> deltaTime)<\/span><\/span>\r\n        {<\/span><\/span>\r\n                \/\/ Do something every frame<\/span><\/span>\r\n        }<\/span><\/span>\r\n}<\/span><\/pre>\n
    Coroutines<\/h2>\n
    Wrapped objects can also start and stop coroutines in their wrapper.<\/p>\n
    To gain this ability the wrapped object has to implement the ICoroutines interface.<\/p>\n
    public<\/span> class<\/span> Player<\/span> :<\/span> ICoroutines<\/span>\r\n{<\/span><\/span>\r\n        public<\/span> ICoroutineRunner CoroutineRunner {<\/span> get<\/span>;<\/span> set<\/span>;<\/span> }<\/span><\/span>\r\n}<\/span><\/span><\/pre>\n
    The wrapper component gets automatically assigned to the CoroutineRunner property during its initialization phase.<\/p>\n
    You can start a coroutine from the wrapped object using CoroutineRunner.StartCoroutine.<\/p>\n
    public<\/span> class<\/span> Player<\/span> :<\/span> ICoroutines<\/span>\r\n{<\/span><\/span>\r\n        public<\/span> ICoroutineRunner CoroutineRunner {<\/span> get<\/span>;<\/span> set<\/span>;<\/span> }<\/span><\/span>\r\n\r\n        public<\/span> void<\/span> SayDelayed<\/span>(<\/span>string<\/span> message)<\/span><\/span>\r\n        {<\/span><\/span>\r\n                CoroutineRunner.<\/span>StartCoroutine(<\/span>SayDelayedCoroutine(<\/span>message)<\/span>)<\/span>;<\/span><\/span>\r\n        }<\/span><\/span>\r\n\r\n        IEnumerator SayDelayedCoroutine<\/span>(<\/span>string<\/span> message)<\/span><\/span>\r\n        {<\/span><\/span>\r\n                yield<\/span> return<\/span> new<\/span> WaitForSeconds(<\/span>1f)<\/span>;<\/span><\/span>\r\n\r\n                Debug.<\/span>Log(<\/span>message)<\/span>;<\/span><\/span>\r\n        }<\/span><\/span>\r\n}<\/span><\/span><\/pre>\n
    The started coroutine is tied to the lifetime of the GameObject just like it would be if you started the coroutine directly within a MonoBehaviour.<\/p>\n
    You can stop a coroutine that is running on the wrapper using CoroutineRunner.StopCoroutine or stop all coroutines that are running on it using CoroutineRunner.StopAllCoroutines.<\/p>\n
    public<\/span> void<\/span> OnDisable<\/span>(<\/span>)<\/span><\/span>\r\n{<\/span><\/span>\r\n        CoroutineRunner.<\/span>StopAllCoroutines(<\/span>)<\/span>;<\/span><\/span>\r\n}<\/span><\/span><\/pre>\n
    Wrapped Objects vs MonoBehaviour<T…><\/h2>\n
    Wrapping plain old C# objects using wrapper components is an alternative to deriving from the MonoBehaviour<T...><\/code> base classes. Both approaches make it easy to receive objects they depend on from the outside, and make it easy to create unit tests for the objects. You’ll probably mostly want to use one or the other in your project consistently, rather than mixing and matching them at random.<\/p>\n
    Wrapped Object Pros<\/h3>\n
    Unit testing wrapped objects can be even simpler and efficient, because you usually don’t even need to initialize any GameObjects or components when testing them, and can instead just test the plain old C# objects directly.<\/p>\n
    Your object won’t have any private unity event methods, that can’t be executed during Edit Mode unit tests without resorting to reflection. You can always easily execute any of their their lifetime events via the interfaces that they implement.<\/p>\n
    Additionally the pattern that wrapped objects use to handle coroutines makes it easy to swap the coroutine runner class during unit tests, making it possible to even unit tests coroutines, for example with the help of the EditorCoroutineRunner class.<\/p>\n
    An additional nice little benefit with using wrapped objects is that you can assign dependencies to read-only fields and properties in the constructor, which makes it possible to make your classes immutable. Having your wrapped objects be stateless can make your code less error-prone and makes it completely thread safe as well.<\/p>\n
    If you care about keeping your code as decoupled from the Unity framework as possible, so that it could be easier to port it to other platforms, then wrapped objects could also be able to help you with this.<\/p>\n
    Wrapped Object Cons<\/h3>\n
    Using wrapped objects instead of MonoBehaviour<T…> can introduce some additional boilerplate and complexity. In addition to creating your plain old C# object, you’ll always also need to generate a wrapper for it, resulting in one additional class (albeit a really simple one).<\/p>\n
    There’s also more of a learning cure compared to just using MonoBehaviour<T…>, because you’ll need to learn to use interfaces like IUpdate and ICoroutines when you need to make use of functionality that is already built into components.<\/span><\/p>\n
    Also, because constructor injection by its very nature doesn’t support circular references (A depends on B, and B depends on A), you can encounter runtime exceptions if you ever try to make two wrapped objects receive references to each other during their initialization.<\/p>\n","protected":false},"excerpt":{"rendered":"
    Wrappers can be used to attach plain old C# objects to a GameObjects, have them receive callbacks during Unity events like Update and OnDestroy, and to start coroutines. Creating a Wrapper Let\u2019s say you had a plain old C# class called Player: using System; using UnityEngine; [Serializable] public class Player { [SerializeField] private Id id; ..<\/p>\n
    <\/div>\n
    Read more<\/a><\/p>\n","protected":false},"author":3,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[13],"tags":[],"_links":{"self":[{"href":"https:\/\/docs.sisus.co\/init-args\/wp-json\/wp\/v2\/posts\/75"}],"collection":[{"href":"https:\/\/docs.sisus.co\/init-args\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/docs.sisus.co\/init-args\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/docs.sisus.co\/init-args\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/docs.sisus.co\/init-args\/wp-json\/wp\/v2\/comments?post=75"}],"version-history":[{"count":26,"href":"https:\/\/docs.sisus.co\/init-args\/wp-json\/wp\/v2\/posts\/75\/revisions"}],"predecessor-version":[{"id":1089,"href":"https:\/\/docs.sisus.co\/init-args\/wp-json\/wp\/v2\/posts\/75\/revisions\/1089"}],"wp:attachment":[{"href":"https:\/\/docs.sisus.co\/init-args\/wp-json\/wp\/v2\/media?parent=75"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/docs.sisus.co\/init-args\/wp-json\/wp\/v2\/categories?post=75"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/docs.sisus.co\/init-args\/wp-json\/wp\/v2\/tags?post=75"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}