Shadow

In the 3D world, light and shadow have always been extremely important components that enrich the entire environment. High quality shadows can make the game world look more realistic.

Cocos Creator 3.0 currently supports both Planar and ShadowMap shadow types.

Enable Shadow Effect

To enable the shadow effect for an object, proceed as follows:

1. Check Scene in the Hierarchy panel, and then check the Enabled property in the Shadows component of the Inspector panel.

   

2. Check light in the Hierarchy panel, and then check the Shadow Enabled property in the Dynamic Shadow Settings component of the Inspector panel.

   

3. Select the 3D node that needs to display shadows in the Hierarchy panel, and then set the Cast Shadows property to ON in the MeshRenderer component of the Inspector panel.

   If the shadow type is ShadowMap, set the Receive Shadows property on the MeshRenderer component to ON.

Note: if the shadows are not displayed properly, adjust the direction of the directional light.

Shadow Type

The shadow type can be set in the Type property of the Shadows component.

Planar Shadow

The Planar shadow type is generally used for simpler scenes.

Property	Description
Enabled	Whether to enable shadow effect
Type	Shadow type
Saturation	Set the shadow saturation, it is recommended to set it as 1. If it is necessary to reduce the saturation of the directional light shadows, it is recommended to do it by increasing the ambient light instead of adjusting this value
ShadowColor	Shadow color
Normal	The normal line perpendicular to the shadow, used to adjust the slope of the shadow
Distance	The distance of the shadow in the direction of the normal to the origin of the coordinate

Adjust the direction of the directional light to adjust the position of the shadow.

Note: planar shadows are only cast on planar surfaces, not on objects, which means that the ReceiveShadow property in the MeshRenderer component is invalid.

ShadowMap

ShadowMap renders the scene with the lights as the viewpoint. From the position of the lights, the places in the scene that are not visible are where the shadows are created.

Property	Explanation
Enabled	Whether to enable the shadow effect.
Type	Choose the shadow type.
MaxReceived	The maximum number of lights supported for shadow generation, default is 4, can be adjusted as needed.
ShadowMapSize	Set the texture size of the shadow, Currently supports Low_256x256, Medium_512x512, High_1024x1024, Ultra_2048x2048 four kinds of precision textures.

Note: starting with v3.3, the Linear and Packing options for Shadows in the Inspector panel have been removed, and Creator will automatically determine the hardware capabilities and choose the best way to render the shadows.

ShadowMap receives and displays shadow effects generated by other objects when ReceiveShadow on the object MeshRenderer component is enabled.

ShadowMap is generally used for scenes that require more realistic and complex light and shadow effects. The downside is that if the lights is not moved, then the previously generated Shadow Map can be reused, while once the lights is moved, then a new ShadowMap needs to be recalculated.

Shadow Properties

After enabling shadows of type ShadowMap, the Dynamic Shadow Settings option will appear in the light source's Inspector. If not properly enabled, please refer to the Enable Shadows section above.

The current engine support for ShadowMap across different light sources is as follows:

Light Type	Support
Directional Light	Supported
Spot Light	Supported
Sphere Light	Not Supported

Directional Light Shadow Properties

Property	Description
ShadowEnabled	Whether to enable directional light shadows
ShadowPcf	Sets shadow edge anti-aliasing level, currently supporting HARD, SOFT, SOFT_2X, SOFT_4X. See PCF Soft Shadows section below for details.
ShadowBias	Sets shadow offset value to prevent Z-Fighting
ShadowNormalBias	Sets normal offset value to prevent jagged edges on curved surfaces
ShadowSaturation	Adjusts shadow saturation, recommended to set to 1.0. To reduce directional light shadow saturation, increase ambient light instead of adjusting this value
ShadowInvisibleOcclusionRange	Sets whether shadows from objects outside Camera's visible range should be cast into visible range. Increase value if needed
ShadowDistance	Sets shadow effect range within Camera's visible range. Shadow quality is inversely proportional to this value

For directional light usage, refer to Directional Light.

FixedArea Mode

FixedArea mode controls whether to manually set the shadow effect range within Camera's visible range:

• When unchecked (default), engine uses same clipping process and camera calculations as CSM (Cascaded Shadow Map) mode, calculating shadow range based on Camera's direction and position.
• When checked, shadow range is controlled by manually setting Near, Far, and OrthoSize properties. Shadows follow directional light node's position, distributed near its bounding box rather than following camera.

Property	Description
ShadowFixedArea	Whether to enable fixed area shadows
ShadowNear	Sets main light camera's near clipping plane
ShadowFar	Sets main light camera's far clipping plane
ShadowOrthoSize	Sets main light camera's orthographic viewport size. Shadow quality is inversely proportional to this value

Spot Light Shadow Properties

Property	Description
ShadowEnabled	Whether to enable spot light shadows
ShadowPcf	Sets shadow edge anti-aliasing level, currently supporting HARD, SOFT, SOFT_2X, SOFT_4X. See PCF Soft Shadows section below for details.
ShadowBias	Sets shadow offset value to prevent z-fighting
ShadowNormalBias	Sets normal offset value to prevent jagged edges on curved surfaces

For spot light usage, refer to Spot Light.

PCF Soft Shadows

Percentage Closer Filtering (PCF) is a simple, common technique for shadow edge anti-aliasing that smooths shadow edges to eliminate jagged artifacts in shadow maps. It works by sampling around the current pixel (fragment), calculating the proportion of samples closer to the light source compared to the fragment, then using this proportion to scale diffuse and specular light components before shading the fragment to achieve blurred shadow edges.

Currently Cocos Creator supports Hard Sampling, 4x Sampling (SOFT mode), 9x Sampling (SOFT_2X mode), and 16x Sampling (SOFT_4X mode). Higher multipliers mean larger sampling areas and softer shadow edges.

Support dynamic batching to improve performance

For models with instancing enabled in the material, the planar shadow will automatically draw with instancing as well, see the Dynamic Batching documentation for details.