Cocos Creator 3.0 Material Upgrade Guide

This article will detail the considerations for upgrading Cocos Creator 2.x materials to v3.0.

1. Introduction to the base design of the material system

1.1 The material system framework of Cocos Creator

The material system consists of four core classes from top to bottom: Material, Effect, Technique and Pass, whose relationship can be understood by the following class diagram:



The Material asset can be seen as an asset instance of the EffectAsset in the scene, and its own configurable parameters are effectAsset, technique, defines, states.


An Effect asset represents a material type and is the most important core asset in the material system. To implement a custom shading effect in the engine, it is necessary to write a custom Effect.


The solution to accomplish a final effect is referred to as a rendering technique , and a technique can be fused by one or more passes.


A Pass is a single GPU draw, typically including a vertex shader and a fragment shader, and there are many optional configuration parameters for Pass in Creator.

1.2 Material Instance Panel

The Material instance panel is the most intuitive material editing window for all developers, and all actual material instances are configured through it.

The Material instance panel in Cocos Creator 3.0 is as follows:


The Material instance panel of Cocos Creator 2.x looks like this:


Notice from the above two figures, the instance panel in v3.0 is quite complex compared to v2.4, partly because of the increased complexity of the material configuration, and partly because of the enhanced functionality of the panel.

The configurable items of the material panel are divided into five main types

  1. Effect asset: the drop-down box will list all the Effect assets in the current project, and developers can select the Effect asset used by the current material. Other properties will be reset as default when the Effect is switched.
  2. Technique rendering technique selection: the drop-down box will list all the Technique in the Effect asset currently in use, and there may be multiple Technique in the Effect asset, each Technique is suitable for different situations. For example, the Technique with less effect but better performance is more suitable for mobile platform.
  3. Macro options defined in Effect: these macros control whether code branches are enabled in shader programs.
  4. The list of properties defined in the Effect, dynamically chose according to the macro definition. They are shown in different input types as defined type in the effect, e.g.: number, color. The editable properties are generally the mapping of uniforms used by the shader, from v3.0, it's possible to specify the mapping of a property to a component in vector uniform by using the target parameter in Effect.
  5. v3.0 also added the PipelineStates option, which is mainly used to define the pipeline states of one pass, such as DepthStencilState, BlendState, CullMode, etc.

1.3 Editor Experience

There are also some differences between v2.x and v3.0 in the editor experience of the material system.

In v3.0, after selecting the node containing the model and material in the Hierarchy panel, the Inspector panel will display the component properties and the detailed Material configuration panel as follows.


In v2.x, when the node containing the model and material is selected in the Node Tree panel, the Properties panel will only show the component properties, not the detailed Material configuration panel:


Instead, you need to jump to the Assets panel and select the Material asset before you can edit it in the Properties panel:


2. Effect Assets

This section describes the commonalities and differences between assets in v2.x and v3.0.

2.1 Effect format and content

For the Effect asset, both v2.x and v3.0 use the YAML1.2 standard syntax and parser, and there are few differences between the two versions. The Effect asset defines a material type, and by following the syntax format, the following information can be defined:

  • Technique list of rendering techniques
  • A list of Pass for each Technique
  • A list of editable properties exposed to the editor in each Pass (including data type designation within the editor, component mapping relationships, etc.)
  • Shader programs for each Pass, including vertex and fragment shader programs

In terms of syntax details, such as Property declarations and macro definitions, the approach is the same:




2.2 Built-in Effect Types

There is a big difference between v2.x and v3.0 in terms of preset materials.

  • The preset materials in v2.x include 2D Sprite, classic blinn-phong lighting materials, unlit materials, default toon materials, particle materials, etc.

  • The preset materials in v3.0 are based on physically based rendering, including standard PBR material, Skybox, cartoon style material, 3D particle materials (CPU & GPU), particle trailing materials, traditional 2D Sprite materials, etc.

The v3.0 default standard material supports the standard Physically Based Rendering (PBR) process, which contains a lot of mapping information to enhance the quality and realism of the material, such as diffuse map, normal map, metallic texture, roughness texture, ambient light occlusion texture, and so on. The whole algorithm is based on the standard BRDF lighting model, which is not available in v2.x. The overall rendering quality of v3.0 is also much more realistic than v2.x.

2.3 Effect Writing Details Differences

Although the syntax rules of Effect in Cocos Creator are basically the same in v2.x and v3.0, there are still differences in many built-in header files, variable names and function names.

For example, in v3.0, it was cc_mainLitDir and the header file cc-global was included. In v2.x, you need to use cc_lightDirection[i] to get the direction of the light source, and you need to include the header cc-lights. See the third point below in the API Upgrade Guide section for more details on the differences.

Some default shader functions are unique to v3.0, such as CCStandardShading, CCToonShading, etc., which are not available on v2.x. Again, see the third point below in the API Upgrade Guide section.

Regarding uniform declarations, v3.0 forces the use of UBO for organization, and the minimum unit for memory layout is vec4, which no longer supports separate declarations of float or vec3 types of uniform.

In terms of header files, v3.0 has built-in editor header assets in the assets/chunks directory of Internal DB. They can be referenced directly with file name instead of file path, mainly for including some common tool functions and standard shading functions. The header files of v2.x are built into the editor, it is not possible see what they are.

2.4 New Pass Options

v3.0 adds some new Pass options:

  • PropertyIndex: specify which pass this pass's runtime uniform property data should be consistent with, e.g.: a pass such as forward add needs to be consistent with the base pass to ensure proper rendering. Once this parameter is specified, the material panel will no longer display any properties of this pass.

  • embeddedMacros: specifies additional constant macros to be defined on top of the shader for this pass. This parameter can be used to reuse shader assets when only the macro definition differs in multiple pass shaders.

For more details on the pass parameters, please refer to the parameter list documentation.

3. API Upgrade Guide

3.1 Built-in Uniform Difference List

If you want to use built-in variables in shader, you need to include the corresponding header file. The following table is a summary of commonly used functional uniforms, many of which are the same as v2.x and v3.0, and some of which are different.

v2.x Header & Name v3.0 Header & Name Type Usage Version Difference
cc-local.chunk & cc_matWorld cc-local.chunk & cc_matWorld mat4 Model space to world space matrix no difference
cc-local.chunk & cc_matWorldIT cc-local.chunk & cc_matWorldIT mat4 Model space to world space inverse substitution matrix no difference
cc-global.chunk & cc_time cc-global.chunk & cc_time vec4 x: global time in seconds since start
y: incremental time of current frame
z: total number of frames since start
no difference
cc-global.chunk & cc_screenSize cc-global.chunk & cc_screenSize vec4 xy: screen size
zw: inverse of the screen size
no difference
cc-global.chunk & cc_screenScale cc-global.chunk & cc_screenScale vec4 xy: screen scale
zw: inverse screen scale
no difference
none cc-global.chunk & cc_nativeSize vec4 xy: the size of the actual shading buffer
zw: the inverse of the size of the actual shading buffer
new in v3.0, not in v2.x
cc-global.chunk & cc_matView cc-global.chunk & cc_matView mat4 view matrix no difference
cc-global.chunk & cc_matViewInv cc-global.chunk & cc_matViewInv mat4 view inverse matrix no difference
cc-global.chunk & cc_matProj cc-global.chunk & cc_matProj mat4 projection matrix no difference
cc-global.chunk & cc_matProjInv cc-global.chunk & cc_matProjInv mat4 projection inverse matrix no difference
cc-global.chunk & cc_matViewProj cc-global.chunk & cc_matViewProj mat4 view projection matrix no difference
cc-global.chunk & cc_matViewProjInv cc-global.chunk & cc_matViewProjInv mat4 view projection inverse matrix no difference
cc-global.chunk & cc_cameraPos cc-global.chunk & cc_cameraPos vec4 xyz: camera position no difference
none cc-global.chunk & cc_exposure vec4 x: camera exposure
y: camera exposure countdown
z: whether HDR is enabled
w: HDR to LDR scaling parameter
new feature in v3.0, not in v2.x

Also, v2.x and v3.0 are very different in terms of light sources and shadows, and v3.0 is a big improvement over v2.x. The following table lists some common features of uniform.

v2.x Header & Name v3.0 Header & Name Type Usage Version Differences
cc-lights.chunk & cc_lightDirection[CC_MAX_LIGHTS] cc-global.chunk & cc_mainLitDir vec4 Get light direction v2.x: How many lights are affected by a single model drawing at a time in the shader The default maximum value is 1.0. To get the position information, fill in 0. For example, cc_lightDirection[0]
v3.0: xyz: main direction light direction
cc-lights.chunk & cc_lightColor[CC_MAX_LIGHTS] cc-global.chunk & cc_mainLitColor vec4 Control the color intensity of the light v2.x: exp of the light, which is the light's pow intensity.
v3.0: xyz - the main directional light color; w - the main directional light intensity
cc-lights.chunk & CC_CALC_LIGHTS cc-global.chunk & cc_ambientSky v2.x: macro definition
v3.0: vec4
controls the sky color intensity v2.x: this is a macro that is computed by threading in the ambient parameter for calculation. And there are function overloads that can be passed in with different parameters.
v3.0: xyz - sky color; w - brightness
none cc-global.chunk & cc_ambientGround vec4 xyz: ground reflected light color new feature in v3.0, not in v2.x
none cc-environment.chunk & cc_environment samplerCube xyz: IBL environment mapping new feature in v3.0, not in v2.x

3.2 Shader Built-In Functions and Variables

In v3.0, to interface with the engine's dynamic batching and instancing processes, include the cc-local-batch header file and get the world matrix via the CCGetWorldMatrix utility function.

New shading functions in v3.0

  • CCStandardShading

    The function name CCStandardShading needs to contain the header file shading-standard.chunk, which is used to perform the lighting calculations that make up the surface shader process.

      #include <shading-standard
      #include <output-standard>
      void surf (out StandardSurface s) {
          // fill in your data here
      vec4 frag () {
          StandardSurface s; surf(s);
          vec4 color = CCStandardShading(s);
          return CCFragOutput(color);

    It is easy to implement custom surface input, or other shading algorithms in this framework.

    Note: the CCFragOutput function does not generally need to be implemented by itself, it only serves the purpose of interfacing with the render pipeline. And for outputs containing lighting calculations, the output-standard header should be included instead of output since the results are already in HDR range.

  • CCToonShading

    Function name CCToonShading, which needs to contain the header file shading-toon.chunk for the lighting calculation for cartoon rendering.

      #include <shading-toon
      #include <output-standard>
      void surf (out ToonSurface s) {
          // fill in your data here
      vec4 frag () {
          ToonSurface s; surf(s);
          vec4 color = CCToonShading(s);
          return CCFragOutput(color);

v2.x is very different from v3.0 in terms of light and shadow calculation, mainly including the following two parts:

spherical light

The point light source in v2.x is adjusted to spherical light in v3.0, and there are many ready-made functions, which need to be added to the header file cc-forward-light.chunk when using them.

Name Type Info
cc_sphereLitPos[MAX_LIGHTS] vec4 xyz: sphere light position
cc_sphereLitSizeRange[MAX_LIGHTS] vec4 x: sphere light size
y: sphere light range
cc_sphereLitColor[MAX_LIGHTS] vec4 xyz: sphere light color
w: sphere light intensity

For additional details, please refer to the Common built-in shader Uniform documentation.


The spotlight in v3.0 has a lot of ready-made features, which need to be added to the header file cc-forward-light.chunk when using it.

Name Type Info
cc_spotLitPos[MAX_LIGHTS] vec4 xyz: spotlight position
cc_spotLitSizeRangeAngle[MAX_LIGHTS] vec4 x: spotlight size
y: spotlight range
z: spotlight angle
vec4 xyz: Spotlight direction
cc_spotLitColor[MAX_LIGHTS] vec4 xyz: spotlight color
w: spotlight intensity

Please refer to the Common shader built-in Uniform documentation for additional details.

3.4 Shadows

There is a difference between v2.x and v3.0 in shadow calculations. In v2.0 you need to add the header file shadow.chunk, while in v3.0 the header file cc-shadow.chunk should be used instead.

v2.0 header file shadow.chunk has the following common functional uniform and functions:

Name Type Info
cc_shadow_lightViewProjMatrix[CC_MAX_SHADOW_LIGHTS] mat4 Draws a shadow map in light coordinates
cc_shadow_info[CC_MAX_SHADOW_LIGHTS] vec4 Calculate shadow offset
Name (function) Type Info
getDepth float Returns the depth value
shadowSimple float Hard sampling of shadows can have jaggedness issues

v3.0 header file cc-shadow.chunk has the following common functions uniformly:

Name Type Info
cc_matLightPlaneProj mat4 Transform matrix for plane shadows
cc_shadowColor vec4 Shadow color

ShadowPCF Soft Shadows

header file function
v2.x: shadow.chunk shadowPCF3X3 (3 * 3 samples)
shadowPCF5X5 (5 * 5 samples)
v3.0: cc-shadow-map-fs.chunk CC_DIR_SHADOW_FACTOR: modify the value of the shadow color in memory directly

results matching ""

    No results matching ""