Maximum Number of Masks in SDK for Unity

Updated: 05/25/2023

Summary

By default in the Cubism SDK for Unity, all displayed models share a single texture for the mask.
Therefore, even if each model does not exceed the maximum number of masks, if multiple models are placed on the screen, the maximum number of mask textures will be reached, and the clipping display may be corrupted.

There are three ways to avoid this, each with different characteristics.

1. Set the mask texture for each model
2. Change the timing for registering/deleting assignments to/from the mask texture
3. Increase the number of textures inside the mask texture

See “Comparison of Cubism SDKs” for more information on the characteristics of mask textures in Unity.

Set the mask texture for each model

This method allows clipping to be displayed without being affected by other placed models by preparing a mask texture for each model.

Note, however, that this may affect performance because multiple mask textures must be prepared.

To set the mask texture for each model, follow the steps below.

1. Create a dedicated mask texture

2. Set the created mask texture to the Mask Texture of the CubismMaskController attached to the model prefab

Create a dedicated mask texture

Create an instance of a mask texture dedicated to the model.

There are multiple ways to create this.
Please use one of the following methods for this task.

• Duplicate the GlobalMaskTexture included with the Cubism SDK for Unity
• Create an instance of the CubismMaskTexture class
• Use the model as it was generated on import

Duplicate the GlobalMaskTexture included with the Cubism SDK for Unity

The mask texture shared by the model can be found in the following locations in the project from which the SDK was imported.

/Assets/Live2D/Cubism/Rendering/Resources/Live2D/Cubism/GlobalMaskTexture

Duplicate it by selecting the mask texture and pressing Ctrl + D, etc.

Create an instance of the CubismMaskTexture class

The editor extension included with the Cubism SDK for Unity creates an instance of the CubismMaskTexture class.
To generate this, right-click on the Project window in Unity or click on the + button and click [Create] > [Live2D Cubism] > [Mask Texture].

Use the model as it was generated on import

In the Cubism 4 SDK for Unity R7 or later, when a model is imported, a dedicated mask texture is generated in the same location as the .model3.json.

Set the created mask texture to the Mask Texture of the CubismMaskController attached to the model prefab

With the model prefab selected, drag and drop the mask texture onto the Mask Texture in the Inspector window.

Change the Timing for Registering/Deleting Reference to/from the Mask Texture

This method is used when the number of models displayed on the screen is small or the total number of masks has not reached the maximum number but the display is corrupted.

In the Cubism SDK for Unity, when a model prefab is generated in the scene, a reference to itself is registered to the mask texture, and the mask texture generates the mask with information obtained from the registered model.
The timing when the reference registered to this mask texture is deleted is when the model is deleted.

Therefore, simply hiding the model will leave references in the mask texture.
This means that even if there are only a few models displayed on the screen, if there are multiple models in the hidden state, the maximum number of masks may be exceeded and the display may be corrupted.

This method changes the timing when the model registers/deletes references to the mask texture to when the model is displayed/not displayed.
This method is also the least burdensome when compared to other methods that increase the number of textures.

However, if the total number of masks for the displayed model has reached the maximum number, this method cannot be used.
In that case, please try other methods.

To register/delete references to mask textures, rewrite the CubismMaskController event function.

1. Rewrite the event function for the process of registering a reference
2. Rewrite the event function for the process of deleting a reference

Rewrite the event function for the process of registering a reference

Rewrite Start() of the CubismMaskController class to OnEnable().

        private void OnEnable()
        {
            // Fail silently.
            if (MaskTexture == null)
            {
                return;
            }
            MaskTexture.AddSource(this);
            // Get cubism update controller.
            HasUpdateController = (GetComponent<CubismUpdateController>() != null);
        }

Rewrite the event function for the process of deleting a reference

Rewrite OnDestroy() of the CubismMaskController class to OnDisable().

        private void OnDisable()
        {
            if (MaskTexture == null)
            {
                return;
            }
            MaskTexture.RemoveSource(this);
        }

Increase the number of textures inside the mask texture

In the Cubism SDK for Unity R7 and later, the number of textures that a mask texture can hold internally can be optionally increased.
The number can be increased as much as the specifications allow without limit, so that clipping can be displayed successfully even when the maximum number of masks available for a single model is exceeded.
This method can also be used in conjunction with the other two above methods.

To increase the number of textures that the mask texture will hold, select the mask texture and set the RenderTextureCount value from the Inspector to the desired number.
If this value is set to 0, a single mask texture is retained internally as before.