SDK Compatibility with Cubism 4.2 Features

Updated: 06/16/2022

This page is for Cubism version 4.2 or earlier. Click here for the latest version.

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 featuresSDK 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 EditingNo SDK support for editing functions
Paste Form SpecialNo SDK support for editing functions
Parameter BookmarksNo SDK support for editing functions
Enhancement of Automatic Generation of Four Corner FormsNo SDK support for editing functions
Runtime Model TrackNo SDK support for editing functions
FreezeNo SDK support for editing functions
Improved Shortcut SettingsNo 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 usedFPS in .physics3.json
Before 4.2.00 beta2AllNone
4.2.00 official version or laterSaved in 4.1.01 or earlier and not opened physicsNone
4.2.00 official version or laterPhysics processing in 4.1.02 beta1 or laterYes (*)

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 earlierThe 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 laterIf 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 usedPhysics operation nuancesCalculated cost per UpdateUnit time calculation cost
NoneR5 beta2 or earlierSame as rendering FPSConstantProportional to rendering FPS
AvailableR5 beta2 or earlierSame as rendering FPSConstantProportional to rendering FPS
NoneR5 beta3 or laterSame as rendering FPSConstant (slightly increased compared to R4)Proportional to rendering FPS
AvailableR5 beta3 or laterFPS setting in .physics3.jsonVaries 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.

Was this article helpful?
YesNo
Please let us know what you think about this article.