SDK Compatibility of Cubism 4.2 Features

[Last update: 06/16/2022]

This section describes the changes in the Cubism 4.2 SDK, as well as notes and changes regarding compatibility between the existing Series 4 SDK and the Cubism 4.2 SDK.

 

About the name

  • Series 4 SDK refers to SDKs prior to Cubism 4 SDK R4.
  • 4.2 SDK refers to Cubism 4 SDK R5 beta1 or later.

 

4.2 Correspondence table of new features in Editor and 4.2 SDK

4.2 Editor New Features SDK support [support date]
Multiply Color/Screen Color 〇 Support [from beta1]
Blend Shape 〇 Support [from beta1]
FPS support for physics operations 〇 Support [from beta3]
Enhanced Manual Mesh Editing No SDK support for editing functions
Paste Form Special No SDK support for editing functions
Parameter Bookmarks No SDK support for editing functions
Enhancement of Automatic Generation of Four Corner Forms No SDK support for editing functions
Runtime Model Track No SDK support for editing functions
Freeze No SDK support for editing functions
Improved Shortcut Settings No SDK support for editing functions

 

Compatibility

Backward compatibility and load

Multiply Color and Screen Color and Blend Shapes

The default values for each of the Multiply Color and Screen Color are set as follows in RGBA to obtain the same drawing results as the Series 4 SDK.

  • Multiply Color (1.0, 1.0, 1.0, 1.0)
  • Screen Color (0.0, 0.0, 0.0, 1.0)

The common behavior is shown in the table below, and no disruptive changes in this feature occur at this time, and backward compatibility is maintained when replacing the SDK.

The loading of Blend Shape parameters is described here.

Cubism Editor
Version

Embedded
Model Data
Version

Color Information of Multiply Color and
Screen Color of the Model

Blend Shape
Parameters Information
4.2 SDK Behavior Burden
4.2 “SDK 4.2 / Cubism 4.2 support”

Be written out
(MOC3 file size increased in size for the new features)

Exported as Blend Shape parameters Obtain color information values from the model's Drawable data The load for the calculation of Multiply Color and Screen Color increases.
4.2 “SDK 4.0 / Cubism 4.0 support”

Not written out
(MOC3 file size is the same as 4.0, no change)

Writes out as a normal parameter with no key. Obtains the default value for each of Multiply Color and Screen Color. No difference
4.0 “SDK 4.0 / Cubism 4.0 support” Not written out Not written out Obtains the default value for each of Multiply Color and Screen Color. No difference

 

Update from existing Series 4 SDK and forward compatibility

When updating from the existing Series 4 SDK to the 4.2 SDK, there is no need to replace all files, the same as for previous updates.

Please note that model data exported for the 4.2 SDK cannot be read by existing Series 4 SDKs.
When trying to read model data exported for the 4.2 SDK with an existing Series 4 SDK, CubismCore outputs the following error when calling the csmReviveMocInPlace function.

[CSM] [E]csmReviveMocInPlace is failed. The Core unsupport later than moc3 ver:[3]. This moc3 ver is [4].

 

Multiply Color, Screen Color

Update from customized existing Series 4 SDK

■SDK for Unity

If you have customized the SDK and are having difficulty updating as usual, you can overwrite “Cubism  Core” with the 4.2 SDK and overwrite the following items in the Framework folder.

  • Live2D/Cubism/Rendering/CubismRenderer.cs
  • Live2D/Cubism/Rendering/CubismRenderController.cs
  • Live2D/Cubism/Rendering/CubismShaderVariables.cs
  • Contents of Live2D/Cubism/Core folder

Please check the Github compare URL for detailed differences.


SDK for Native

If you have customized the SDK and are having difficulty updating as usual, you can overwrite “Cubism  Core” with the 4.2 SDK and overwrite the following items in the Framework folder.

  • CubismModel
  • CubismRenderer for each platform
  • CubismShader for each platform
  • CubismType_D3D11.hpp (DirectX 11 only)
  • MetalShaderTypes.h (Metal only)
  • MetalShaders.metal (Metal only)

Please check the Github compare URL for detailed differences.


■SDK for Web

If you have customized the SDK and are having difficulty updating as usual, you can overwrite the “Cubism Core” with the 4.2 SDK and overwrite the following items in the Framework folder.

  • cubismmodel.ts
  • cubismrenderer.ts
  • cubismrenderer_webgl.ts

Please check the Github compare URL for detailed differences.

 

Changes from existing Series 4 SDK

When exporting data as model data for the 4.2 SDK in CubismEditor 4.2, Multiply Color and Screen Color information will be added to the Drawable data.
Processing for these has been added to each SDK.

 

■SDK for Unity

In Unlit.shader, expressions have been added to apply Multiply Color and Screen Color to the Fragment shader section.
In addition, a ColorField that allows the SDK to set color information for Multiply Color and Screen Color from the CubismRenderer inspector has been defined.


Function to enable use of SDK-specified color information

The SDK is basically designed to use color information imported from model data for the process of applying Multiply Color and Screen Color, but it is also possible to specify color information directly to the entire model or individual Drawables from the SDK side via code.
When using arbitrary color information from the SDK side, the user can set arbitrary Multiply Color and Screen Color for the entire model by enabling flags from the following properties defined in CubismRenderController when deciding whether to allow Multiply Color and Screen Color operations from the SDK side for the entire model, that is, all Drawables.

  • For Multiply Color, OverwriteFlagForModelMultiplyColors
  • For Screen Color, OverwriteFlagForModelScreenColors

Flags for individual Drawables can be enabled from the following properties defined in CubismRenderer to allow the user to set Multiply Color and Screen Color for the specified Drawable.

  • For Multiply Color, OverwriteFlagForMultiplyColors
  • For Screen Color, OverwriteFlagForScreenColors

All Drawables are designed to use arbitrary color information from the SDK side, regardless of the flag status for individual Drawables, when the model-wide flag is enabled.
If the model-wide flag is disabled, the flag status for the individual Drawable is applied.

Multiply Color and Screen Color used on the SDK side are designed to be saved regardless of the flag status.


Function for receiving that Drawable’s Multiply Color and Screen Color have been changed

If a model parameter is associated with a change in Multiply Color/Screen Color, the model may change the Multiply Color/Screen Color when the model is animated, for example.
IsBlendColorDirty is implemented in CubismDynamicDrawableData as a function that can receive the fact that the Multiply Color and Screen Color have been changed at this time.

This function is a flag that is set when either the Multiply Color or Screen Color is changed on the model side and does not determine whether the Multiply Color or Screen Color has been changed.

Also, it does not work with Multiply Color and Screen Color information operations from the SDK side.

To handle CubismDynamicDrawableData data, the event OnDynamicDrawableData of CubismModel must be used.

 

■SDK for Native

Expressions have been added to apply Multiply Color and Screen Color to the shader portion of each platform.
In addition, the following functions are provided in the CubismModel class to set the respective color information for Multiply Color and Screen Color in the SDK.

  • SetMultiplyColor
  • SetScreenColor


Function to enable use of SDK-specified color information

The SDK is basically designed to use color information imported from model data for the process of applying Multiply Color and Screen Color, but it is also possible to specify color information directly to the entire model or individual Drawables from the SDK side via code.
When using arbitrary color information from the SDK side, the user can set arbitrary Multiply Color and Screen Color for the entire model by enabling flags from the following functions defined in CubismModel when deciding whether to allow Multiply Color and Screen Color operations from the SDK side for the entire model, that is, all Drawables.

  • For Multiply Color, SetOverwriteFlagForModelMultiplyColors
  • For Screen Color, SetOverwriteFlagForModelScreenColors

Flags for individual Drawables allow the user to set Multiply Color and Screen Color for a specified Drawable by enabling the flag from the following functions.

  • For Multiply Color, SetOverwriteFlagForDrawableMultiplyColors
  • For Screen Color, SetOverwriteFlagForDrawableScreenColors

All Drawables are designed to use arbitrary color information from the SDK side, regardless of the flag status for individual Drawables, when the model-wide flag is enabled.
If the model-wide flag is disabled, the flag status for the individual Drawable is applied.

Multiply Color and Screen Color used on the SDK side are designed to be saved regardless of the flag status.


Function for receiving that Drawable’s Multiply Color and Screen Color have been changed

If a model parameter is associated with a change in Multiply Color/Screen Color, the model may change the Multiply Color/Screen Color when the model is animated, for example.

The CubismModel implements GetDrawableDynamicFlagBlendColorDidChange as a function that can receive the fact that the Drawable’s Multiply Color and Screen Color have been changed at this time.

This function is a flag that is set when either the Multiply Color or Screen Color is changed on the model side and does not determine whether the Multiply Color or Screen Color has been changed.
Also, it does not work with Multiply Color and Screen Color information operations from the SDK side.

 

■SDK for Web

Added expressions to apply Multiply Color and Screen Color to the shader part of cubismrenderer_webgl.ts.
In addition, the following functions are provided in the CubismModel class to set the respective color information for Multiply Color and Screen Color in the SDK.

  • setMultiplyColorByTextureColor
  • setScreenColorByTextureColor
  • setMultiplyColorByRGBA
  • setScreenColorByRGBA

Function to enable use of SDK-specified color information

The SDK is basically designed to use color information imported from model data for the process of applying Multiply Color and Screen Color, but it is also possible to specify color information directly to the entire model or individual Drawables from the SDK side via code.
When using arbitrary color information from the SDK side, the user can set arbitrary Multiply Color and Screen Color for the entire model by enabling flags from the following functions defined in CubismModel when deciding whether to allow Multiply Color and Screen Color operations from the SDK side for the entire model, that is, all Drawables.

  • For Multiply Color, setOverwriteFlagForModelMultiplyColors
  • For Screen Color, setOverwriteFlagForModelScreenColors

Flags for individual Drawables allow the user to set Multiply Color and Screen Color for a specified Drawable by enabling the flag from the following functions.

  • For Multiply Color, setOverwriteFlagForDrawableMultiplyColors
  • For Screen Color, setOverwriteFlagForDrawableScreenColors

All Drawables are designed to use arbitrary color information from the SDK side, regardless of the flag status for individual Drawables, when the model-wide flag is enabled.
If the model-wide flag is disabled, the flag status for the individual Drawable is applied.

Multiply Color and Screen Color used on the SDK side are designed to be saved regardless of the flag status.


Function for receiving that Drawable’s Multiply Color and Screen Color have been changed

If a model parameter is associated with a change in Multiply Color/Screen Color, the model may change the Multiply Color/Screen Color when the model is animated, for example.

The CubismModel implements getDrawableDynamicFlagBlendColorDidChange as a function that can receive the fact that the Drawable’s Multiply Color and Screen Color have been changed at this time.

This function is a flag that is set when either the Multiply Color or Screen Color is changed on the model side and does not determine whether the Multiply Color or Screen Color has been changed.
Also, it does not work with Multiply Color and Screen Color information operations from the SDK side.

To handle CubismDynamicDrawableData data, the event OnDynamicDrawableData of CubismModel must be used.

 

Blend Shape function

Changes and load from existing Series 4 SDK

There are no changed functions, and Blend Shape parameters can be retrieved in the same way as regular parameters.
No special handling is required, but the computational cost is different for normal parameter combinations and for combinations using Blend Shapes.

 

While normal parameters tend to increase exponentially in data and computational cost, Blend Shapes tend to increase linearly.
The Blend Shape parameter is also available in the SDK at a lower cost than previous parameters.

 

Cubism Core API changes

Changes from the existing Series 4 SDK Cubism Core

In the Cubism Core of the 4.2 SDK, several functions have been added in line with the aforementioned additions, and some behavioral changes have been made.
Below is a brief description of each added function and behavior change.

 

Structure

csmVector4

This structure has four float member variables inside.
4.2 SDK's Cubism Core API is used to store and retrieve Multiply Color and Screen Color data.

 

Multiply Color/Screen Color Related

csmGetDrawableMultiplyColors

This function returns the address to the ArtMesh's Multiply Color array.

 

csmGetDrawableScreenColors

This function returns the address to an array of Screen Color for the ArtMesh.

 

csmBlendColorDidChange

This is a dynamic flag that is enabled when the Multiply Color or Screen Color is changed on the Cubism Core side.

 

Blend Shape Related

Behavior change

Functions that act on parameter data, such as the csmGetParameterCount function, now support parameters for Blend Shapes.
It is implemented so that parameters can be retrieved without distinguishing between parameters for Blend Shapes or regular parameters.

The Cubism Core API itself remains unchanged.

Please refer to the Cubism Core API Reference for detailed information on the functions and features added to the 4.2 SDK Cubism Core.

 

FPS support for physics operations

Up to Cubism SDK R5 beta2, the physics behavior did not match that of the Editor due to the rendering FPS of the SDK.
Starting with Cubism SDK R5 beta3, the physics calculation method has been changed so that the SDK will reproduce the physics behavior set in the Editor no matter what rendering FPS is used.

Due to the change in the physics calculation method, it is necessary to communicate the physics calculation setting FPS from the Editor to the SDK side.
Therefore, in Cubism 4.2.00 or later, the FPS settings are written to .physics3.json when exporting built-in data.

Using the FPS settings exported to .physics3.json and linearly interpolating in time the intervening states that would occur due to differences in rendering FPS, the behavior results are now as close to Editor as possible.

If there is no FPS setting item in .physics3.json, the physics will behave according to the same rendering FPS as before, ensuring the same behavior as in the previous SDK.

 

Export of FPS settings from Editor to .physics3.json

Use
Editor Version
CMO to be used 3File Status FPS in .physics3.json
Before 4.2.00 beta2 All None
4.2.00 Official Version or later Saved in 4.1.01 or earlier and not opened physics None
4.2.00  Official Version or later Physics processing in 4.1.02 beta1 or later Yes (*)

*: You can choose not to include the FPS in the .physics3.json file depending on the settings at the time of MOC3 export.

 

Compatibility of behavior with FPS settings in .physics3.json

SDK in use Version
Behavioral Compatibility
R5 beta2 or earlier The presence or absence of the FPS setting has no effect on the loading operation.
The absence of the FPS setting has no effect. (As before)
The behavior remains the same as before R5 beta2 and before.
R5 beta3 or later If an FPS setting exists, use the FPS setting to match the physics behavior with the Editor.

If the FPS setting does not exist, the calculation works as it did before R5 beta2.
*As an error in maintaining the behavior as much as possible, the behavior of physics operations lags by one frame when compared to R5 beta2.

 

FPS setting in .physics3.json and SDK behavior

FPS in json setting status
SDK Version Physics operation nuances Calculated cost per Update Unit Time Calculation Cost
None R5 beta2 or earlier Same as rendering FPS Certain Proportional to rendering FPS
Yes R5 beta2 or earlier Same as rendering FPS Certain Proportional to rendering FPS
None R5 beta3 or later Same as rendering FPS Constant (slightly increased compared to R4) Proportional to rendering FPS
Yes R5 beta3 or later FPS setting in .physics3.json Varies depending on FPS and rendering FPS set in .physics3.json

(Slight decrease or slight increase)
Proportional to the FPS set in .physics3.json

 

Changes on OWViewer and Editor

For Cubism Viewer (for OW) and Cubism Viewer for Unity, the physics behavior is the same as in Cubism SDK R5 beta3.

 

© 2010 - 2022 Live2D Inc.