Shader Chunk Migrations

Introduction 

The PlayCanvas Engine's material shader chunk system is undergoing substantial changes in order to support a more flexible material system. Please see this page for more context.

In order to help users migrate their existing custom shader chunks, this page lists the changes made to chunks and organizes them by engine release (starting v1.51).

Chunk API Versions 

The debug version of the Engine will report any API changes to the runtime console when it detects overridden chunks. For example:

Console output

Once an application's chunks have been updated to the latest API they must be flagged as such. For example, after updating a material's custom chunks to the latest engine release (say v1.55), specify this in the chunks object as follows:

material.chunks.diffusePS = '...';
material.chunks.APIVersion = pc.CHUNKAPI_1_55;

By doing this you will no longer see warning messages in the console.

Chunk changes 

The following tables break down the chunk changes by Engine release.

Engine v1.55 

Chunk	Changes
`clearCoatNormalPS`	refrain from generating world CC reflection, now done on the backend instead normalize final world space normal
`combineXXXX`	Updated all combine chunks to be more consistent between phong and blinn-phong chunks. These chunks will undergo more changes in future and may even be removed completely.
`diffusePS`	Fix gamma handling relative to albedo detail
`diffuseDetailMapPS`	Gamma correct detail map before combining with base albedo
`emissivePS`	set `dEmissive` global instead of returning the value in order to bring it in line with the other frontend components
`lightmapSingleVert.js`	removed (unused)
`lightmapDirPS`, `lightmapSinglePS`	renamed the lightmap function to `getLightMap()` instead of `addLightMap()` changed the implementation to write `dLightmap` and `dLightmapDir` global instead of updating `dDiffuseLight` and `dSpecularLight` directly backend now handles combining lightmap in `lightmapAddPS` and `lightmapDirAddPS`
`normalMapFastPS`	removed
`normalMapPS`	added `MAPTEXTURE` #define like the other chunks normalize final normal when normal texture isn't defined, calculate normal from geometry normal instead
`normalDetailMapPS`	remove two (mostly) unnecessary calls to `normalise` - final normal is normalized instead
`clusteredLightPS`	remove dead code
`endPS`	combine emissive with `dEmissive` instead of a call to `getEmission()`
`lightmapAddPS`, `lightmapDirAddPS`	new chunks for adding the lightmap values passed in from the backend
`lightSpecularAnisoGGXPS`	added clear coat `#define`
`lightSpecularBlinnPS`, `lightSpecularPhongPS`	added clear coat `#define`, removed call to `antiAliasGlossiness()`
`normalVertexPS`	removed chunk, moved functionality to `normalMapPS` frontend chunk
`specularAaNonePS`, `specularAaToksvigPS`, `specularAaToksvigFastPS`	removed
`startPS`	removed global declarations, generate them on demand instead