SDK Compatibility with Cubism 4.2 Features
Updated: 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 Names
- Series 4 SDK refers to SDKs prior to Cubism 4 SDK R4.
- 4.2 SDK refers to SDKs later than Cubism 4 SDK R5 beta1.
Table of new features in Editor 4.2 and their support by the 4.2 SDK
| 4.2 Editor new features | SDK support [support date] |
|---|---|
| Multiply Color/Screen Color | ✓ Supported [from beta1] |
| Blend Shape | ✓ Supported [from beta1] |
| FPS support for physics operations | ✓ Supported [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 and screen colors and blend shapes
The default values for each of the multiply and screen colors 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; backward compatibility is maintained when replacing the SDK.
Click here for more information on the loading of blend shape parameters.
| Cubism Editor version |
Embedded model data version |
Color information of multiply and screen colors of models |
Blend shape parameters information |
4.2 SDK behavior | Load |
|---|---|---|---|---|---|
| 4.2 | SDK 4.2/Cubism 4.2 support | Exported (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 and screen colors increases. |
| 4.2 | SDK 4.0/Cubism 4.0 support | Not exported (MOC3 file size is the same as 4.0, no change) |
Exported as a normal parameter with no key | Obtain the default value for each of multiply and screen color | No difference |
| 4.0 | SDK 4.0/Cubism 4.0 support | Not exported | Not exported | Obtain the default value for each of multiply and screen color | No difference |
Update from existing Series 4 SDK and forward compatibility
Updating from the existing Series 4 SDK to the 4.2 SDK works by replacing all files as usual.
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 page Comparing changes 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 page Comparing changes 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 page Comparing changes for detailed differences.
Changes from existing Series 4 SDK
When exporting data as model data for the 4.2 SDK in Cubism Editor 4.2, multiply and screen color information will be added to the Drawable data.
Processing for these features has been added to each SDK.
■ SDK for Unity
In Unlit.shader, expressions have been added to apply multiply and screen colors to the Fragment shader section.
In addition, a ColorField that allows the SDK to set color information for multiply and screen colors from the CubismRenderer inspector has been defined.
Function to enable use of SDK-specified color information
The SDK is typically designed to use color information imported from model data for the process of applying multiply and screen colors, but it is also possible to specify color information directly for the entire model or individual Drawables from the SDK side via code.
When using the desired color information from the SDK side, the user can set the desired multiply and screen colors for the entire model by enabling flags from the following properties defined in CubismRenderController when deciding whether to allow multiply and screen color operations from the SDK side for the entire model, that is, all Drawables.
- For multiply colors, OverwriteFlagForModelMultiplyColors
- For screen colors, OverwriteFlagForModelScreenColors
Flags for individual Drawables can be enabled from the following properties defined in CubismRenderer to allow the user to set multiply and screen colors for the specified Drawable.
- For multiply colors, OverwriteFlagForMultiplyColors
- For screen colors, OverwriteFlagForScreenColors
All Drawables are designed to use the set 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 and screen colors used on the SDK side are designed to be saved regardless of the flag status.
Function for receiving fact that Drawable’s multiply and screen colors have been changed
If a model parameter is associated with a change in multiply/screen color, the model may change the multiply/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 and screen colors have been changed at this time.
This function is a flag that is set when either the multiply or screen color is changed on the model side and does not determine whether the multiply 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 and screen colors 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 and screen colors in the SDK.
- SetMultiplyColor
- SetScreenColor
Function to enable use of SDK-specified color information
The SDK is typically designed to use color information imported from model data for the process of applying multiply and screen colors, but it is also possible to specify color information directly for the entire model or individual Drawables from the SDK side via code.
When using the desired color information from the SDK side, the user can set the desired multiply and screen colors for the entire model by enabling flags from the following functions defined in CubismModel when deciding whether to allow multiply and screen color operations from the SDK side for the entire model, that is, all Drawables.
- For multiply colors, SetOverwriteFlagForModelMultiplyColors
- For screen colors, SetOverwriteFlagForModelScreenColors
Flags for individual Drawables allow the user to set multiply and screen colors for a specified Drawable by enabling the flag from the following functions.
- For multiply colors, SetOverwriteFlagForDrawableMultiplyColors
- For screen colors, SetOverwriteFlagForDrawableScreenColors
All Drawables are designed to use the set 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 and screen colors used on the SDK side are designed to be saved regardless of the flag status.
Function for receiving fact that Drawable’s multiply and screen colors have been changed
If a model parameter is associated with a change in multiply/screen color, the model may change the multiply/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 and screen colors have been changed at this time.
This function is a flag that is set when either the multiply or screen color is changed on the model side and does not determine whether the multiply 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 and screen colors 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 and screen colors in the SDK.
- setMultiplyColorByTextureColor
- setScreenColorByTextureColor
- setMultiplyColorByRGBA
- setScreenColorByRGBA
Function to enable use of SDK-specified color information
The SDK is typically designed to use color information imported from model data for the process of applying multiply and screen colors, but it is also possible to specify color information directly for the entire model or individual Drawables from the SDK side via code.
When using the desired color information from the SDK side, the user can set the desired multiply and screen colors for the entire model by enabling flags from the following functions defined in CubismModel when deciding whether to allow multiply and screen colors operations from the SDK side for the entire model, that is, all Drawables.
- For multiply colors, setOverwriteFlagForModelMultiplyColors
- For screen colors, setOverwriteFlagForModelScreenColors
Flags for individual Drawables allow the user to set multiply and screen colors for a specified Drawable by enabling the flag from the following functions.
- For multiply colors, setOverwriteFlagForDrawableMultiplyColors
- For screen colors, setOverwriteFlagForDrawableScreenColors
All Drawables are designed to use the set 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 and screen colors used on the SDK side are designed to be saved regardless of the flag status.
Function for receiving fact that Drawable’s multiply and screen colors have been changed
If a model parameter is associated with a change in multiply/screen color, the model may change the multiply/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 and screen colors have been changed at this time.
This function is a flag that is set when either the multiply or screen color is changed on the model side and does not determine whether the multiply 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 parameters are 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 contains four float member variables.
The Cubism Core API of the 4.2 SDK is used to store and retrieve multiply and screen color data.
Multiply/screen colors related
csmGetDrawableMultiplyColors
This function returns the address to an array of multiply color for the ArtMesh.
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 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 blend shape parameters.
This is implemented so that parameters can be retrieved without distinguishing between blend shape parameters or regular parameters.
The Cubism Core API itself remains unchanged.
See the Cubism Core API Reference page 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 the 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
| Editor version to be used | Status of CMO3 files to be used | 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 (*) |
Note: 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 version to be used | Behavioral compatibility |
|---|---|
| R5 beta2 or earlier | The presence or absence of the FPS setting has no effect on the importing operation. The absence of the FPS setting has no effect. (As before) The behavior remains the same as before R5 beta2, no change. |
| 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. Note: As an error due to attempting to maintain the behavior as much as possible, the behavior of physics operations lags by one frame when compared to R5 beta2. |
With/without FPS setting in .physics3.json and SDK behavior
| FPS in JSON setting status | SDK version to be used | Physics operation nuances | Calculated cost per Update | Unit time calculation cost |
|---|---|---|---|---|
| None | R5 beta2 or earlier | Same as rendering FPS | Constant | Proportional to rendering FPS |
| Available | R5 beta2 or earlier | Same as rendering FPS | Constant | Proportional to rendering FPS |
| None | R5 beta3 or later | Same as rendering FPS | Constant (slightly increased compared to R4) | Proportional to rendering FPS |
| Available | 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 in OW Viewer and Editor
For Cubism Viewer (for OW) and Cubism Viewer for Unity, the physics behavior is the same as in Cubism SDK R5 beta3.