Materials and shaders (REDengine 4, game 2.31)

Maturity: Draft. The resource model, template catalogue, G-buffer layout, deferred BRDF and the skin SSS pipeline are consolidated from source, installed resources and compiled programs. Runtime evidence is partial: the first photo-mode session (25 September) showed the colour shift working, distinct coverage steps, close-up breakup of a skin-coincident plate and uniformly glossy flat finishes; the second (26 September, partial) confirmed that the 0.4 mm plate lift removes the breakup (see in-game test asks, experiment 017 and experiment 020).

This page explains how Cyberpunk 2077 materials work well enough to:

• make the browser preview faithful;
• design makeup finishes that have a realistic chance of rendering correctly in game at the first attempt.

Hair is covered only at overview level here. See hair shading for the in-depth study.

Per-family references. The systematic shader study keeps one evidence-level reference per template family, with every parameter, pass, program hash and grade: skin, hair, eye, decals, multilayered and metal and glass. The shader fact index maps each engine fact to the Studio preview materials and export compilers that rely on it, so a correction reaches all of them.

Evidence grades:

• source: engine, framework or tool source, or disassembled compiled programs;
• resource: installed game or mod resources;
• wiki: Cyberpunk Modding Docs at commit be2f44eed8419342ec13f72ed9cab008e9f7b289;
• runtime: observed in the running game;
• hypothesis: not yet established.

Pinned sources:

Compiled-program hashes and the reproducible method are in the shader-system evidence note.

1. The material resource model

mesh (.mesh)
 ├─ appearances[k].chunkMaterials[submesh] ──name──► materialEntries[i] {name, isLocalInstance, index}
 │                                                      │ local                     │ external
 │                                   localMaterialBuffer.materials[index]   externalMaterials[index] (.mi path)
 │                                   (embedded CMaterialInstance)                   │
 └──────────────────────────────────────────────────────┴──► CMaterialInstance ── baseMaterial ──► (.mi …) ──► CMaterialTemplate (.mt/.remt)
                                                                  sparse name→value overrides          parameters, techniques/passes, materialType

1.1 Resource types

1.2 Parameter types

Template parameters are CMaterialParameter* objects with parameterName and register source (G/CMaterialParameter.hpp:19-20).

How values reach the program [source: the 2.31 executable, research/materials/shader-system/exe_hair.py params]. The material constant-buffer packer (RVA 0x4ff4d4, called once per stage, vertex then pixel, by 0x1eb374) walks a layout of 4-byte entries (data offset, parameter type, register) and writes one float4 per register. The type is what each CMaterialParameter* class reports (its vtable slot 28): Texture 1, Color 2, Cube 3, Vector 4, Scalar 5, TextureArray 7, SkinParameters 10, HairParameters 13, Gradient 16, and so on. Color (4 bytes) becomes (srgb(R), srgb(G), srgb(B), A/255) through the engine's 256-entry sRGB-to-linear table, the same table the skin-profile colours and the debug-draw vertex colours go through; Vector is copied and Scalar broadcast to all four lanes; the resource types (Texture, Cube, TextureArray, SkinParameters, HairParameters, Foliage, Gradient) write an integer looked up for the bound resource (a texture index, and, by their use in the programs, the skin-profile slot and the gradient row [hypothesis for the meaning]). So a template that raises a Color to 2.2 itself (eye_shadow's ShadowColor) applies that power on top of the decoding. This covers material parameters packed by this routine; runtime overrides through other paths (scripts, effects) were not read.

WolvenKit maps each class to its value field in MaterialExtractor.cs:626-646. There is no .mltemplate parameter type. A template is reached only through Multilayer_Layer.material source.

Stage slots. parameters, usedParameters and samplerStates are three-slot arrays indexed like EMaterialShaderTarget: [0] unused, [1] vertex, [2] pixel.

• The indexing is source-supported: G/EMaterialShaderTarget.hpp:12-15, and WolvenKit reads only slot 2.
• In every template inspected, vertex-animation parameters sit in [1] and all surface parameters in [2] resource.
• usedParameters[2] gives the constant-buffer register the compiled pixel program uses (§3.1).

Wrong resource type or unresolved path renders black and shiny wiki (materials/materials-troubleshooting.md L17-25).

Inconsistent parameter names. The same concept has different names across templates (Albedo, BaseColor, DiffuseTexture, Color). Always read the template wiki (configuring-materials/README.md L82-88) resource.

1.3 How an instance chain resolves

1.4 Mesh-side binding

Name lookup. chunkMaterials[submesh] names a materialEntries entry. That entry's isLocalInstance and index choose between two lists source:

• the local list, localMaterialBuffer.materials (embedded CR2W files) or preloadLocalMaterialInstances;
• the external list, externalMaterials (async .mi refs) or preloadExternalMaterials.

ArchiveXL loads through exactly this pair (src/App/Extensions/Mesh/Extension.cpp:410-427).

Unnamed chunks. A chunk without a valid material name renders invisible source (WolvenKit CMeshPreProcessor.cs:144-162).

Preload lists. Do not mix preload and non-preload lists of the same kind wiki (3d-objects-.mesh-files/README.md L230-241):

• mixing them makes non-preload materials render transparent on first use;
• WolvenKit's export also collides on names when the lists are mixed source (MaterialExtractor.cs:223-271).

Dynamic materials (ArchiveXL) source (Extension.cpp, Dynamic.cpp):

• Template entries. A chunk name prefix@tmpl binds to a template entry named @tmpl.
• Soft references. Resource values and baseMaterial paths starting with * are soft and are substituted:
  • {material} is the prefix;
  • {material.N} is the Nth +-separated part;
  • other {attr} tokens come from context attributes.
• Optional values. A trailing ? makes the value optional; if it is unresolved, the parameter is removed.
• Base chains. Soft .mi base chains are cloned recursively.
• @context. Local entry 0 named @context supplies override parameters and attributes.
• Emulation gap. WolvenKit's Material.json export only emulates * and {material} source (ArchiveXlHelper.cs:14-61). Offline exports of CCXL-style chains can therefore silently fall back to defaults.

2. Rendering pipeline: what a material can and cannot express

2.1 Passes and render stages

Each template holds techniques[] → passes[]. A pass carries source (G/MaterialPass.hpp:21-30) resource:

• stage names (stagePassNameRegular, stagePassNameDiscarded);
• depth and stencil state;
• the rasterizer: cull, winding and offsetMode, e.g. OFFSET_DecalBias;
• per-target blend for up to 8 targets, with write masks;
• enablePixelShader.

The depth test is GreaterEqual in G-buffer passes, i.e. a reversed-Z depth buffer resource.

The full stage list, with compilation counts, is in the local material-index.json produced by the evidence tool.

2.2 The G-buffer

The layout below is decoded from the tiled deferred light (m_shaderLightsComputeGlobalLocalShadows_Clustered_*) and from the skin, metal_base and mesh_decal writers. All of it is source (compiled programs; see the evidence note).

Grades for the less certain rows:

• Stencil-class identity: the enum values match the light's class switch and the templates' materialType → source/resource match. The actual stencil write was not traced → hypothesis.
• GBuffer2.z: the all-classes global light (…_11111111, 6606735909222169407) forms saturate((z − 1/3) × 1.5) (%85–%87) and uses it only in the Foliage branch (class 5, block %1051), as the weight of a back-lit transmission lobe added to diffuse (%1186–%1204); Eye forces it to 0. The Subsurface branch and the local-light path never read it (experiment 017). The SSS UseTranslucency setup (11387959167119825062) does: for Subsurface pixels it adds a sun transmission term weighted by the same saturate((z − 1/3) × 1.5) (for skin 0.1 + 0.9·G) and by a thickness falloff from a back-face depth target, before the blur source (skin reference §6.4). When that variant runs is hypothesis. The debug-view enum EEnvManagerModifier still lists a "Translucency" view (G/EEnvManagerModifier.hpp:24-40); whether that view shows this channel is hypothesis.

Which templates carry which class resource:

No template uses Cloth.

2.3 The deferred lighting model

Decoded from the global-light compute shader source:

Consequence (the central fact for makeup). The G-buffer stores one surface per pixel: one base colour, one normal, one metalness and one roughness. There is no clear-coat, sheen, second normal (except Eye), anisotropy (except Hair) or specular-tint channel. Anything that needs a second reflection lobe must come from a separate forward pass drawn after lighting. The stock examples are multilayered_clear_coat's unlit pass (dual-source blend One/Src1Color) and eye_shadow's transparent_back_face pass (One/SrcAlpha) resource source.

2.4 What a post_gbuffer decal does to the pixel under it

All source/resource (mesh-decal contract, evidence note):

1. What it blends, and in what space. It blends base colour, normal and metalness/roughness into GBuffer0–2 with SrcAlpha/InvSrcAlpha. Each target gets its own alpha (colour, normal and surface coverage). Colour is written as sqrt(colour), so decal colour blending happens in square-root (gamma-2) space, not linear.
2. Write mask RGB, stencil disabled. The decal never changes the lighting class, skin-profile slot or .w payloads. Makeup on skin is still lit as Subsurface skin. Metalness ≥ 0.1 on a Subsurface pixel takes the class's non-SSS albedo path (§2.3).
3. GBuffer2.z and skin translucency. The decal writes 1/3, so where surface coverage is non-zero it blends skin's 0.4 + 0.6·G toward 1/3. The deferred light ignores that channel for skin, but the SSS translucency setup weights its sun transmission by it, so a covering decal removes transmission under it source. The transmission needs thin geometry (a small front-to-back depth), so it matters on ears and nostrils, not under eye or lip makeup (skin reference §6.4).
4. Opacity curve. Coverage is saturate((a−0.5)·tan((c+1)·π/4)+0.5)² · (1 − influence·secondaryMask). Each target's alpha multiplies it by DiffuseAlpha, NormalAlpha or RoughnessMetalnessAlpha. All three default to 0, so an instance must enable them.
5. Placement and depth. Rasterizer state is front-face cull with CCW winding, which is equivalent to back-face cull with CW. The pass tests depth GreaterEqual without writing it, and offsetMode OFFSET_DecalBias (value 3 of PSODescRasterizerModeOffsetMode) adds a depth bias whose values are engine-side and unknown. DepthThreshold (default 0.5) discards decal pixels farther than that from the scene depth; it does not settle coincident surfaces source.
6. Vanilla face decals do not rely on the bias. The 2.31 female eye-makeup, lip, freckle and pimple meshes are the head's vertices pushed 0.40 mm out along the head's normals (median residual 5 µm), and their morph targets keep the offset along each target's normal; they have one LOD like the head. The brow mesh is lifted 0.35 mm the same way (eyebrows). A plate coincident with the head broke into skin-coloured patches close up in photo mode, and was clean at medium distance resource runtime (first session, finish board results). XF Studio now lifts its packaged plate 0.4 mm the same way (experiment 017); in session 2 the 0 mm plate broke up again at an extreme close-up while the 0.1 mm and 0.4 mm lifts stayed clean runtime (experiment 020). The close-up-only mechanism (a depth bias that absorbs less world-space mismatch near the camera) is hypothesis.

3. Compiled shaders: finding and reading them

3.1 Where they are and how templates map to programs

Stage labels. WolvenKit labels the first GUID "pixel". In all 19,647 records it is the vertex program; 2,564 records have no pixel program source.

Template-to-program link. Templates connect to programs only through a lookup key: the hashed template name plus a hash of the permutation (vertex factory and flags, technique index, render stage, pass index); see §8.1. No template field stores a shader GUID source. The name is the template resource's own CMaterialTemplate.name, not its depot path (three vanilla templates' names differ from their file stems, and the cache keys follow the name): a mod's copy of mesh_decal.mt at another path (the legacy XF generator's mesh_decal__emp_front.mt, identical to vanilla except materialPriority) keeps name = mesh_decal resource and drew in game [runtime: the reference character wears the legacy build; no capture on file], so tools must identify a template by that name. The Studio's renderer does (head CC rendering §3). materialPriority is EMP_Normal (0) or EMP_Front (1); serializers omit the default [source: WolvenKit RED4 enums].

Constant registers.

• Material constants are cb4, one register per usedParameters[2] register ([1] for vertex programs).

  • Each program keeps a %ShaderSpecificConstants type with one field per register: i32 for Texture/TextureArray/Cube, float for Scalar, <4 x float> for Vector/Color.
  • Across one representative program per template, 314 of 314 checked templates agree, and no program reads a cb4 register that the template does not own source.

• Textures are bindless. The program loads an index from that cb4 register and indexes t0, space1. Multilayer layer textures are the exception: their index comes from a structured-buffer load.

• Engine buffers keep their struct names in the DXIL resource metadata; their member names do not survive, so individual registers are identified by use source:

  Register	Struct
  cb0	GlobalShaderConsts
  cb1	CameraShaderConsts
  cb2	ENV_PROBES
  cb3	CustomPixelConsts / CustomVertexConsts
  cb5	FrequentVertexConsts
  cb6	COM / VER (static compute programs)
  cb7	MaterialModifiersConsts
  cb12	SharedPixelConsts
  cb13	CSConstants

3.2 Repeatable method

research/materials/shader-system/ contains:

• shader_cache.py (index / find / static / extract / summary);
• template_summary.py (parameters, registers, passes and blend states for all 373 templates);
• shader_annotate.py (annotate, optionally --decompile / search).

Recipe:

1. Serialize the templates with WolvenKit CLI 8.17.4: unbundle memoryresident_1_general.archive -r "\.(mt|remt)$", then convert serialize.

2. Find the compilation with shader_cache.py find <template> --info "<stage>'.*VF: MeshSkinned\]". The eye plate, head and eyes are MeshSkinned.

3. Annotate with shader_annotate.py annotate <template> --guid <pixelGUID>. This extracts and disassembles with Windows SDK dxc -dumpbin, then writes readable pseudo-HLSL with names for:

   • template parameters and textures;
   • engine struct names;
   • the vertex inputs behind each interpolator;
   • G-buffer and blend roles for each target.

   shader_annotate.py search finds the programs that contain a code pattern. extract and summary remain for raw work.

4. Read structured source if needed. --decompile adds <GUID>.decompiled.hlsl: dxil-spirv (DXIL to SPIR-V) and SPIRV-Cross (to HLSL), both built from source, with the same names applied.

   • It gives real loops, typed values and a named per-register cb4. HLSL output compiles with dxc for 244 of 253 templates.
   • It is HLSL for about three quarters of templates; forward programs with wave ops or float-granular cbuffer views fall back to GLSL.
   • Renaming was checked not to change the compiled program. The decompilers themselves are a second reading, not proof.
   • Its _N are not SSA numbers (annotation results).

5. Check against the disassembly (<GUID>.annotated.ll) before relying on either listing. The lifted pseudo-HLSL folds expressions and keeps loops as goto; it is a reading aid, not compilable source.

6. Write it down. Record the program GUID, the SHA-256 and SSA ranges. SSA numbers are only valid within that one program.

Older one-off extractors (projects/xf-studio/authoring/tools/inspect_shader_cache.ts, extract-brow-shader.ts, inspect-eye-skin-cache.ts, experiments/014-native-eye-gradient/inspect-cache.ts) cover the same v10 format for single studies.

3.3 Compiled-program index (MeshSkinned unless noted)

4. Template catalogue (characters and makeup)

Parameters and registers below are from the serialized 2.31 templates resource. Channel semantics are from compiled programs where cited source; everything else is marked. "Reg" is the cb4/usedParameters[2] register.

4.1 base\materials\skin.mt (and skin_blendable, skin_morph)

Class: Subsurface.

Passes: gbuffer_regular/velbuff (opaque), skin_translucency (depth only), cascade, highlights.

Vertex factories include MeshSkinned and the LightBlockers variants resource.

Every parameter, pass, program hash, the instance chains of the player head and body, and the full program walk-through are in the skin reference; the table below is the summary.

Vertex colour. The wiki reads vertex colour as R = AO, G = SSS mask and B = "improved facial lighting" wiki (shader-docs.md L47-51). The skin writer stores GBuffer2.z = 0.4 + 0.6·G: its vertex program passes COLOR.y straight through to the interpolator the pixel program reads source (annotation results). The deferred light ignores GBuffer2.z for skin (only Foliage reads it, §2.2); the SSS translucency setup uses it as the weight of sun transmission, which is consistent with the wiki's "SSS mask" reading source.

Wetness. With rain (MaterialModifiersConsts[3]), the program darkens porous (rough) skin and makes smooth skin glossier, strongest on up-facing surfaces, with drops, streaks and drips inside 60, 30 and 15 m; dry skin is unaffected source (skin reference §5.7). Outdoor test captures should record the weather.

Roughness under eye makeup. On the pale default head the Roughness map's R channel reads about 0.57–0.66 at the vanilla eye-makeup vertices (h0_000_wa_c__basehead_rm01.xbm, before the detail bias) resource (experiment 017).

No specular antialiasing. Neither the skin writer nor mesh_decal derives roughness from normal-map variance. Decal textures are read with implicit-LOD Sample through one anisotropic, trilinear, wrapping sampler, so a texture's mip chain is the only filter a mod controls source (Glitter in game §1).

Gotcha. The Blender add-on maps Roughness G to Metallic and marks its microdetail masking as uncertain (material_types/skin.py:341,626). It uses Principled random-walk SSS, which is an approximation, not the engine path.

4.2 Eye family: eye.mt, eye_gradient.mt, eye_blendable.mt, eye_morph.mt

Class: Eye.

Passes: opaque G-buffer, velocity, cascade shadows (the eyeball casts sun shadows), depth, highlights and an editor pick pass; no translucency pass. eye.mt defaults: RoughnessScale 0.4934, RefractionIndex 0.97, EyeRadius 0.0152 resource. eye_blendable adds a braindance Fresnel rim to the colour and eye_morph a scripted wipe of the gradient; otherwise the four share one arithmetic source (eye reference §2).

Gotchas:

• The Eye class stores a second vector, the iris normal, octahedral-encoded to 10 bits per axis in GBuffer2.zw plus two low bits each in GBuffer0.w and GBuffer1.w; GBuffer1.rgb holds the cornea normal. It disables the translucency term (§2.3). The full program, the 71 creator colours and the preview spec are on eye rendering.
• IrisMask is a gamma texture, yet the gradient profiles are authored for its raw R range; the Rebecca eyes' normal map is a gamma texture too, and decoding its flat texels would tilt the iris normal 54° over the whole eye. Whether the engine decodes either is open (eye rendering §2.3).
• Eye pixels are outside the SSS passes; the ambient pass multiplies their indirect light by 1 + cb6[9].w and can bypass their occlusion (eye reference §6.3–6.4).
• The Blender add-on samples eye roughness G, contradicting the compiled R source. CCXL eye guides note the eye UVs are Y-flipped wiki (ccxl-eye-textures.md L267-271).

4.3 Hair (hair.mt family) — overview only

Class: Hair. There are three cooperating passes resource source:

• hair_alpha_accum: alpha write mask only; alpha is accumulated atomically from Strand_Alpha R.
• hair_basecolor_blend: additive; the two red-channel strand maps address a runtime gradient texture (the static cache names a HairProfilesGradients resource).
• hair_gbuffer_solid: opaque, depth-writing.

The light builds an anisotropic tangent frame for the Hair class. The sun and every local light use the same Karis-style model; only the intensity triple differs (cb0[12] for the sun, cb0[13] for local lights), and neither reads the Scattering thickness in GBuffer2.z source. .hp profiles hold two gradient ramps (gradientEntriesID, gradientEntriesRootToTip).

See hair-shading.md for the detailed formula work, the hair reference for the template, passes, lashes, cap and what still blocks correct hair colour, and the lash follow-up and hair-profile resolution.

4.4 eye_shadow.mt / eye_shadow_blendable.mt — the eye's occlusion and tear shell, not cosmetic eyeshadow

Class: Standard, EMP_Front.

Pass: transparent_back_face, forward-lit, CULL_None, blend One/SrcAlpha, i.e. out = highlight + dst·alpha resource source.

Vertex factories: eye_shadow has MeshSkinned; eye_shadow_blendable has only MeshStatic and MeshExtSkinned resource. The blendable's pixel program is identical to eye_shadow's, and its Fresnel parameters are read by no program; it adds only a braindance glitch and fade on the vertex side source (eye reference §7.1).

Naming gotcha. This template's name refers to the ocular occlusion/tear film. The Blender add-on reads Mask R as alpha and A as coat, which does not match the program. The vanilla user is the player eye mesh's wetness chunk eyeWetness_MAT (eyeshadow_base.mi: ShadowColor 125,58,58, Intensity 0.7, Exponent 0.8; female chunk 2, male chunk 1) resource. Only the luminance of ShadowColor is used, the highlight has no Fresnel, and the probe contribution is multiplied by zero, so the shell adds no environment reflection source (eye rendering §4).

4.5 mesh_decal family (post_gbuffer, all Standard class, MeshSkinned available)

Common parameters. Every member shares DiffuseTexture/DiffuseColor/DiffuseAlpha, UV*, SecondaryMask*, NormalTexture/NormalAlpha/NormalAlphaTex/UseNormalAlphaTex/NormalsBlendingMode(+Alpha), RoughnessTexture/MetalnessTexture with scale and bias, AlphaMaskContrast, RoughnessMetalnessAlpha, Animation* and DepthThreshold resource.

Compiled contract for mesh_decal source. Every program of the family, its passes and per-target blend states, and what each variant changes are in the decal reference:

• Normal is RG with reconstructed Z.
• Roughness and Metalness each read R × scale + bias, and they share one blend alpha (with GBuffer2.z): a decal cannot write roughness without also blending metalness towards its own value.
• Texture UVs are transformed by UVScale/UVOffset/UVRotation (in half-turns) about 0.5 and then folded by sign·frac, so a UV window must keep the mesh inside one unit of the fold.
• There are independent colour, normal and surface coverages. Colour and surface coverage are the squared contrast-adjusted colour-map alpha; normal alpha is not squared: NormalAlpha × (UseNormalAlphaTex ? NormalAlphaTex.R : colour-map alpha).
• NormalsBlendingMode > 0.5 loads the existing G-buffer normal and composes the decal normal with it by reoriented normal mapping (Barré-Brisebois & Hill) in the plate's tangent frame, lerped by NormalsBlendingModeAlpha.R (white by default). Its normal alpha is also multiplied by saturate(50 − 50·z): a flat texel (z = 1) writes nothing, and full weight needs about 11.5° of tilt. Because the blend lerps the encoded normal, a partly faded facet keeps only about alpha × its tilt (a 5° facet keeps about 1°). NormalsBlendingModeAlpha below 1 lerps towards the decal normal mirrored in X and Y, so it must stay white. Mode 0 replaces the normal with the plate normal plus the map at the plain alpha. source (decompiled 16098255505177109230; see the Shimmer design and decal reference §4.5)

2.31 has no mesh_decal_normal template (the 16 compiled templates are mesh_decal plus __blackbody, _blendable, _double_diffuse, _emissive, _emissive_subsurface, _gradientmap_recolor(_2, _blendable, _emissive), _morph, _multitinted, _parallax, _particles, _revealed, _wet_character; the …_gradient name belongs to the braindance blackwall_blendable_mesh_decal_gradient); scars and face cyberware write their normals through plain mesh_decal [source: installed shader cache index]. Every vanilla female face decal uses mesh_decal or mesh_decal_double_diffuse resource.

4.6 Multilayered: engine\materials\multilayered.mt, multilayered_clear_coat.mt

multilayered.mt is Standard class. It is canBeMasked = 0, opaque and depth-writing, drawn in the depth prepass, with blending off on every target; its only transparency is the engine's whole-draw dissolve (§1.3) resource source. The game uses it for earrings and piercings, the 37 graphic eye designs, and most clothing, weapons and props. The family reference is the multilayered reference; line references are in the multilayered shader evidence.

Inputs:

• MultilayerSetup (.mlsetup: an ordered list of layers, each naming a layer template, .mltemplate) and MultilayerMask (.mlmask: one mask per layer, stored as a BC4 tile atlas with tile tables) resource;
• GlobalNormal with its intensity, UV scale and bias;
• runtime-filled MaskAtlas, MaskTiles, Layers (StructBuffers), LayersStartIndex, SetupLayerMask and Mask* dimensions source.

Evaluated per pixel source. The G-buffer program (4792354088802328889, one program for MeshSkinned and MeshStatic) loops over the layers at every pixel; it does not sample a cache. The static m_surfaceCache_GenerateMultilayer compute program repeats the same arithmetic into cache pages, and the internal multilayered_baked.mt (9875025106086992270) reads them as a virtual texture (an indirection texture, 120-texel pages, a page-feedback buffer) source; when the engine switches a mesh to it is open. A variant pass adds rain and wetness on top at runtime; that is weather, not material. Layer textures are read with explicit gradients, and the normal and microblend gradients are scaled by NormalsTextureDDXYMultiplier / MicroblendsTextureDDXYMultiplier (default 1): a per-material mip bias for the maps that cause specular aliasing source (multilayered reference §5.4).

Layer values are name lookups. Each layer stores colorScale, normalStrength, rough/metalLevelsIn/Out as CNames that key into its template's override tables; its numeric fields are opacity, matTile, mbTile, microblend* and offsetU/V source (G/Multilayer_Layer.hpp:22-40). The tables hold {n, v} entries; colour names are <hex>_<hex> with null in either half, and null_null/null are ordinary entries present in every vanilla template resource. Each template also has a defaultOverrides selection and colorMaskLevelsIn/Out. The wiki gives up to 20 layers wiki (multilayered/README.md L27, L80).

How the layers combine [source unless marked]:

Colour maps are sRGB (isGamma), roughness, metalness, normals and microblends linear resource. How community tools differ (the Blender add-on stacks bottom-up with a lerp, ignores the colour mask, and writes the program's contrast form as saturate((m − (1 − c)(1 − a))/c), the reciprocal reading; WolvenKit's preview paints flat colours) is recorded in the evidence note [community].

What the Studio draws. The preview's layered adapter (layered-material.ts) bakes this arithmetic once per material over the mesh's own UV range, accumulating in half floats, into two packed 8-bit maps (sRGB colour with roughness in alpha; the tangent normal with metalness in alpha) and lights them as a standard metal/rough surface. A bake is sized by texel density on the part's surface (about 20 texels a millimetre, 256–2048: a stud is 256², the eyeball 2048² as its UVs span several tiles), chunks with identical stacks and UV ranges share one bake, and a hidden slot is baked when first shown; five piercing chunks keep about 2 MiB of maps where they kept 160 MiB. Real-GPU tests match the bake to its CPU reference within one byte for constant and for tiled, offset, masked sRGB maps. It draws layered chunks on any slot whose render mask draws them in the scene: the V's piercings and the graphic eye designs so far (head CC rendering). The host clamps a setup's and a template's stored numbers to plausible ranges (a paint template's colour table holds up to 906 entries). A layer whose microblend is absent or unreadable is drawn over the values of base\surfaces\microblends\default.xbm (RGB (126, 127, 255), alpha 104/255) and noted, not over alpha 1: under the reciprocal contrast, alpha 1 let a low-contrast layer cover every texel above its contrast [offline; what the engine does with a layer that names no microblend is unread]. The rendered look is hypothesis until an in-game comparison.

multilayered_clear_coat.mt resource source:

• The G-buffer pass is opaque, depth-writing and Standard class. It also stores a per-pixel coat amount, the summed shares of the layers in [CoatLayerMin, CoatLayerMax], as GBuffer2.z = 1/3 + ⅔·coat [source: 3911537533623547427].
• A second unlit forward pass, depth test Equal, blends One/Src1Color (dual source): coat weight saturate((GBuffer2.z − 1/3)·1.5) × Opacity, adding a coat reflection (its own roughness ≥ 0.04 and Fresnel) and attenuating the base per channel [source: 5403688829342147459]. The coat therefore lands only on its own base pass's pixels (multilayered reference §6).
• Parameters: CoatTintFwd/Side, CoatTintFresnelBias, CoatSpecularColor, CoatRoughnessBase, CoatReflectionPower, CoatFresnelBias, CoatNormalStrength, CoatLayerMin/Max, Opacity.
• A community test shows angle-dependent tint on a garment wiki (multilayered-material-properties.md L121-133, image clearcoat_1.png/clearcoat_2.png, discovered by Rebecca).
• Not an overlay: its base pass replaces the surface, and skin's Subsurface class with it.

Multilayered and makeup. On a face plate, any multilayered template would be an opaque Standard surface replacing the skin: no soft coverage, no SSS or skin lobes, no skin normal, black where no layer covers. Mixed finishes are already expressible per texel in a decal, which keeps the skin, and both are limited to one surface per pixel; the coat's second lobe cannot sit over skin. The makeup export therefore stays on the decal family source (multilayered reference §8).

4.7 engine\materials\metal_base.remt and glass_onesided.mt

Full reference: metal and glass. Both appear on arm cyberware (Gorilla Arms, Mantis Blades), the teeth mesh's unused default appearance, the accessories some CCXL hairstyles carry (earrings, hair pins) and many clothing items. The preview draws metal_base since 27 September (src/metal-base-material.ts, without the alpha test yet); glass_onesided has no adapter.

metal_base.remt is Standard class: a depth prepass, an opaque G-buffer pass (Index 1; Index 2 adds rain), and a post_gbuffer decal mode resource source.

• Inputs source: saturate(BaseColor.rgb × BaseColorScale.rgb); metalness and roughness each from the R channel of their own map through saturate(x·scale + bias); an RG normal with Z reconstructed and XY × NormalStrength; every UV × LayerTile except Emissive. Defaults: grey colour, metalness 0, roughness 1, flat normal.
• Output source: the plain Standard G-buffer (sqrt(colour), the normal with .w 0, metalness, roughness, 1/3), lit by the Standard deferred light and ambient composite (§2.3). Nothing about metal is special to the template: it is metalness and roughness.
• Alpha test source: the Discarded variant discards where BaseColor.a < AlphaThreshold (0.38) when an engine flag is set; the cyberware decal chunks set enableMask 1 resource, and the wiki ties transparency to enableMask wiki (textured-material-properties.md L25); the link between them is hypothesis.
• Emission source: only when EmissiveEV > 0: the colour lerps toward EmissiveColor × BaseColor by the emissive mask, and GBuffer2.w stores a flag and sqrt(EV/10) in 7 bits, EV = max(log2(mask) + EmissiveEV, 0); the ambient composite adds the albedo times a per-frame function of it (2^EV if its constant is 10·ln 2 hypothesis).

glass_onesided.mt writes no G-buffer. It is a forward transparent pass with dual-source blending, out = radiance + background × T per channel, plus a distortion pass and a transparent_mark_rt pass resource source:

• Transmittance T = lerp(1, tint′·(1 − mask), Opacity), where tint′ is GlassTint × TintColor darkened and saturated toward grazing angles. It ignores the reflection's Fresnel source.
• Reflection: F0 comes from FresnelBias (0 → 0.25, 1 (default) → 0.08, 2 → 0.04), not from IOR, which only the distortion pass reads. Roughness is saturate(GlassRoughnessBias + Roughness.R) (default 0). The environment term is Karis's analytic environment BRDF over box-projected probes; the direct term is a sun-only GGX lobe. The program has no local-light loop, so point, spot and photo-mode lights do not reflect in it source.
• Distortion: active only when IOR > 1 or BlurRadius > 0. It adds a screen-space refraction offset (Snell's law 50 units along the ray, or a slab of RefractionDepth) and a blur radius source.
• Gorilla Arms glass sets GlassSpecularColor to black: it reflects nothing, only tints (TintColor 240, 235, 228), refracts (IOR 1.32) and blurs (BlurRadius 1) the mechanism behind it resource.
• glass.mt is the same with a back-face pass first (OpacityBackFace, BackFacesReflectionPower); its parameters are documented in wiki glass-material-properties.md.

Relatives:

• pbr_simple.mt has scalar Color, Roughness and Metalness only resource.
• metal_base_glitter.mt is noise/time emissive, not a glint BRDF source glitter investigation.
• metal_base_blackbody.mt drives the Gorilla Arms thermal glow chunks (EmissiveEV 10) resource; not read.

5. Texture conventions

6. Makeup finish implications

"Plate" means the owned morph-skinned eye-makeup mesh drawn over the head. Every decal route keeps the underlying Subsurface class (§2.4).

The Studio exports each preset as one decal draw, so per-texel inputs can vary within a preset but material constants cannot. The implemented routes are in finish-export.ts; each finish has a design page. None has been seen in game; the finish board is the prepared test.

Plate depth. Every route draws on the plate lifted 0.4 mm off the skin, like the vanilla face decals (§2.4 item 6).

Plate texel density and the UV window. The plate keeps the head's UV0, so a head-atlas texture spends only a 0.453 × 0.145 rectangle on it: at 1024 a texel is about 0.56 × 0.40 mm on the lids (569 and 405 mm per UV unit, area-weighted medians). The vanilla eye-makeup mesh has its own UV layout at about 66 mm per UV unit, so its 1024 texels are 0.065 mm resource (experiment 018). mesh_decal transforms every texture UV by UVScale/UVOffset from the UV as stored in the mesh source, so Build now maps just the plate's rectangle onto a 2048 × 512 texture for the flat and faceted routes: about 0.13 × 0.12 mm per texel at today's texel count and memory [offline]. The V sign follows from two offline facts: the Studio authors in glTF UV (1 − stored V), and WolvenKit's XBM import stores image rows bottom to top; so UVOffsetY is negative (−1.66 for the built-in plate) and the verifier checks the stored row order on every build. The Fresnel route's gradient-recolour template has no UV transform and stays on the 1024 head atlas. The window's placement has not been seen in game (experiment 019). Shimmer's grain is one texel of this window (0.13 × 0.12 mm).

Calibration against skin. Finish roughness sits on top of skin, not a Standard surface: skin's own roughness under the lids is about 0.6, vanilla eye makeup writes 0.50 at full surface alpha (and breaks its coverage with a ×30 noise mask), and the Subsurface class sums two GGX lobes at 0.97× and 1.6× the written roughness. On the first in-game board, Matte, Satin, Glossy and Metallic read uniformly glossy; experiment 017 separates "values too glossy" (Gloss D: all +0.12) from "written roughness not what you see" (Gloss B: surface alpha 0; Gloss C: roughness forced to 1) [hypothesis until that session]. CDPR's own makeup gives the calibration points resource: eye makeup 0.50 at full surface weight with noise-broken coverage, matte lipstick roughness 1.0 at 35–40 % weight, glossy lipstick keeping the skin's roughness (plus metalness 1 at 5 %), gold and silver blush metalness 1 at roughness ≈ 0.51 (if its sRGB-flagged roughness texture is read raw; ≈ 0.22 if decoded, face makeup open question 1). None of them writes one constant roughness at full weight over a whole mark, as the flat route does; that uniformity, which replaces the skin's pore-level roughness variation, is the decal-side suspect for the "plastic" read (decal reference §9.1) hypothesis.

What the preview predicts for Board 1 [offline; approximation of the light]. Since the authored plate is lit once with the skin's light (head CC rendering §3), Board 1 in the preview (default V, reference profile, both lighting presets, three studio key angles) reads much closer to the in-game report than before. Metallic becomes a bright, pale, sheet-like reflection as bright as the bare lid skin at the same pixels (0.89–1.12 of its median luminance, from 0.37–0.41) with 2.7–4.7 times the skin's highlight: at metalness 0.65 the reflection takes F0 from the pigment through skin's two summed lobes, and the SSS stand-in is off. Glossy shows 1.1–4.9 times the skin's highlight (0.5–2.3 before), and Satin about the skin's own (1.0–1.2), so it does not read as satin. Matte does not read glossy (at or below the skin's highlight), so the light alone does not explain the in-game report for Matte; the close-up breakup and the photo-mode per-light roughness shift remain the suspects there. With Gloss D's values (all +0.12) the preview lowers highlight peaks by 15–30 % on Satin and Glossy and Metallic's highlight by about a quarter, but moves the broad sheen by under 10 % and leaves Metallic as bright: D alone is not predicted to make the board read matte and satin, and for Metallic the metalness is the larger lever. Statistics are per-stripe percentiles of private captures (tools/plate-light-look.ts); the in-game Gloss A–D frames decide.

Cross-cutting guidance for the browser preview:

1. Blend decal colour in sqrt space, and apply the decal's squared coverage curve. The preview does, for the V's own face decals and for the authored plate, whose layers blend as the export's one merged decal (head CC rendering §3).
2. Use F0 = 0.04 for non-metals, and treat roughness as perceptual (α = r²).
3. Light makeup on skin with the skin's light: renormalised Burley diffuse and the profile's two lobes, once, on the blended surface. The preview does for the skin, the face decals (per pass) and the authored plate (once, on the blended surface; head CC rendering §3).
4. Present Glossy as the one lobe the game can draw (the game-matched model does); a clear coat would need a second, forward pass.
5. Sample skin roughness from R, with B gating the bias, and eye roughness from R × scale.

7. Open questions

These become backlog items.

1. GBuffer2.z for skin. Answered source: the SSS translucency setup (11387959167119825062) weights a sun transmission term by it; the static index's other GUID under that name (2220067148481019988) is a sun-light program. Still open: which setting enables the translucency variant, and what its camera vector and per-pixel factor are (skin reference §6.4).
2. Stencil write. Confirm that the engine writes materialType into stencil bits 5–7, via a runtime capture or the pass stencil setup code.
3. Skin-profile table. The table holds 8 slots per frame; roughness0/1 and lobeMix form the dual-lobe specular kernel (§2.3), and the CPU builds each slot's blur kernel and strength from blurSize, diffuse and falloff (answered source: skin reference §6.3.2). Open: the kernel's absolute screen scale; whether the separable or the stochastic blur runs at a given setting; what happens with more than 8 distinct .sp on screen; which lights set the per-light roughness byte, and to what (photo-mode lights in particular).
4. Metal ≥ 0.1 threshold. The SSS blur and combine skip pixels whose blended metalness exceeds 0.1 source; the flag controlling the light's albedo = 1 path is unknown. Does metallic makeup over skin show a visible SSS seam at soft edges (the lifted metal ramp on the next candidate)? The preview switches its SSS stand-in off on the authored plate's blended metalness, so Metallic crosses it at about 15 % coverage over dielectric skin; the albedo = 1 path is not modelled.
5. Eye second vector. Answered source: it is the iris normal from the Normal map at the refracted coordinate; the light uses it for Lambert diffuse and the specular horizon, and the cornea normal for specular and ambient. No program reads Blick, SubsurfaceFactor or AntiLightbleed*. Remaining eye questions are on eye rendering.
6. eye_shadow as a gloss shell. Is it usable as a glossy-makeup shell (sorting, transparent_back_face stage semantics, blink, cost)? (Its vanilla user is the eye mesh's wetness chunk.) Known from the programs: only eye_shadow itself compiles for MeshSkinned; with Intensity 0 it adds a direct-light-only GGX highlight with no Fresnel and no environment reflection, so a wet look would show only under direct lights (eye reference §7.2).
7. Runtime gradient atlases. Recover the .gradient atlas construction (row assignment, colour space, filtering, and whether stops are rescaled like .hp). This affects the gradient eyes and mesh_decal_gradientmap_recolor_2. The .hp bake is decoded (hair reference §7); brows sample an ordinary gradient texture, not an atlas (eyebrows). A clue: mesh_decal_gradientmap_recolor_2 reads the eye's atlas and raises all four channels, alpha included, to 0.45, which suggests the atlas stores its channels with a 2.2 power (decal reference §5.3).
8. Unmapped debris. Recover the G-buffer render-target formats (8-bit vs 10-bit precision affects the sqrt encoding) and the meaning of the low 5 stencil bits.
9. Ray-tracing libraries. Parse the ray-tracing libraries in staticshader_final.cache. Their names survive (ShadeSurfaceWithLightSample*, GBuffer0..2), which could confirm the BRDF and G-buffer semantics independently.
10. Multilayer levels. Answered source: the pairs feed a clamped scale/bias chain (saturate(saturate(x·a + b)·c + d)), identical in the G-buffer and surface-cache programs. For multilayered, game captures of the ring eye designs now support two CPU mappings: microblendContrast enters as its reciprocal, and colorMaskLevelsOut = (0, 0) tints (the ring's red comes from a template storing (0, 0)) [game capture, 27 September 2026, eye rendering §6.6]. Still open: whether colorScale is linearised and matTile multiplied by tilingMultiplier, and when the surface cache is used (evidence).
11. Color parameter encoding. Answered: sRGB-decoded RGB, linear alpha [source; runtime-supported]. The executable's material constant-buffer packer converts every Color parameter's RGB through the engine's sRGB-to-linear table and its alpha as byte/255 (§1.2). Session 4's skin-tone frames agree: senna amber and limestone against warm ivory darken the skin more than byte/255 can at full mask weight, and limestone's blue-to-green ratio rises where byte/255 must lower it; the sRGB fit holds even with a free tone-curve exponent per region [runtime, provisional: Ultra+'s RT skin tuning was on and the frames are display-referred; experiment 029 §4.2]. The preview decodes every Color it reads this way (skin and teeth TintColor, decal and brow colours, the eye shell's ShadowColor before its own 2.2 power), and the Colour-shifting export writes FresnelColor sRGB-encoded. Still open from the old question: what is MaterialModifiersConsts[2].x on the player head? It also gates the opacity of mesh_decal_emissive_subsurface (the glitter accent), and [0].z/.w drive the Discarded dissolve.
12. Debug views. Can the engine's EEnvManagerModifier debug views (G-buffer, Roughness, Metalness, Translucency, MaterialID) be enabled from CET or RED4ext? That would turn most questions here into one capture session.
13. Decal depth bias. What depth bias does OFFSET_DecalBias apply, and does it explain why a coincident decal failed only close up?
14. Temporal filtering and upscalers. Which program is the main anti-aliasing? Does the engine apply a negative texture LOD bias under DLSS, FSR3 or XeSS? How do the upscalers treat stable 2–3 pixel glints? Tracked in Glitter in game.
15. Decal normal source. A mode-1 decal composes with a copy of the G-buffer normal (t74). Is it refreshed between decal draws, so that overlapping normal-writing decals compose with each other rather than with the skin (decal reference §4.5)?
16. Glass and local lights. The glass_onesided transparent program reflects only the sun and the probes; it has no local-light loop source. Confirm with a photo-mode light moved across the Gorilla Arms window, and settle what enables metal_base's alpha-test variant and its post_gbuffer pass (metal and glass §8–9).

8. Custom shaders: from template to pipeline state

How the engine turns a material template into GPU work, for the XF Shaders track (our own material shaders). Everything here is offline evidence from the 2.31 executable, CD PROJEKT RED's address library and the cache file; the full trace with addresses, IDs and grades is the pipeline trace, and exe_shaders.py re-proves it. Nothing is confirmed in game yet; the probe plan is the test.

8.1 How a technique is found source

• One cache, one lookup key. shader_final.cache is opened once at start-up; only its RDHS magic is checked on load. A compiled technique is found by a 64-bit key: fold32(FNV-1a-64(template name)) << 32 | permutation, where the permutation is FNV-1a-32 over the vertex factory and its Discarded/PreSkinned/Dismembered flags, the technique index, the render-stage name and the pass index. The recipe reproduces all 19,647 records.
• The name is the template's name CName, not its file. A copy of mesh_decal.mt that keeps name = mesh_decal reaches mesh_decal's programs; a copy with a new name finds none.
• Programs are per template. Each of the 19,037 programs belongs to exactly one template name, even when bytes are identical elsewhere. A record names a vertex program and an optional pixel program by GUID; each program names the engine modifier slots it reads (its parameter set).
• All programs are vs_6_0/ps_6_0, signed, with no embedded root signature.

8.2 From technique to pipeline state source

1. A draw binds a material for a pass; the render template keeps its own technique map and compiles on a miss (key lookup, then the pixel and vertex programs).
2. Each program becomes a GpuApi shader, deduplicated by an FNV-1a-32 hash of its bytecode. The bytecode is referenced, not copied.
3. The command list collects the shaders and the pass's states into a D3D12_GRAPHICS_PIPELINE_STATE_DESC. At draw time it hashes the state fields (not the bytecode), seeded by the shaders' IDs, and resolves a PSO from an 8,192-entry cache.
4. A missing PSO is loaded from an ID3D12PipelineLibrary by a name derived from the shader hashes, else created with ID3D12Device::CreateGraphicsPipelineState, synchronously or as a CompilePSOAsync job.
5. One global graphics root signature, built at start-up, serves every material draw; bindless textures sit in t0, space1.

8.3 What this means for custom shaders

• The cleanest detour is the cache reader's two lookups (find technique, get program). A copied template with its own name is recognised by its key; the plugin answers with the original's record and its own pixel program under its own GUID, and everything downstream (shader, PSO, pipeline library) separates by itself. Vanilla users of the same template never see it [source for the path; the design is a proposal].
• A replacement pixel program must match the original's input and output signatures, stay within the global root signature's bindings, read material constants from cb4 at the template's registers, reuse the original's parameter set, and be signed SM 6.0 DXIL.
• Shipping shaders natively is not possible additively: there is one cache file and no mod path. A plugin-read side cache in the same format is the practical form of "a package ships compiled shaders".
• Every function on the path has an address-library ID, so hooks need no pattern scanning, as with ArchiveXL; object offsets remain version-bound and must be gated.

In-game test asks

Batch these into one prepared session with fixed camera, FOV and light, and record game and framework versions.

1. Finish board (first photo-mode session held 25 September). The finish board packaged asks 1–3 as six selector presets through the production pipeline, with its own test card: flat finishes and single-lobe Glossy (Board 1), faceted Shimmer and a coarse glitter proxy (Board 2), and the Fresnel colour shift with its strength-0 control (Boards 3 and 4).
   • Capture a camera orbit under fixed light, then a light sweep under a fixed camera, at close and face framing, with a blink.
   • The eye_shadow gloss shell (Glossy route 2) is not on the board; it needs a second component.
2. Sqrt-space blend check. Board 5: black Matte patches at 25/50/75 % coverage under the eyes, contrast 0, captured in photo mode with fixed exposure.
   • Compare measured luminance with linear and sqrt-space predictions.
3. Metal threshold edge. Board 6: a metalness ramp 0 → 0.3 and five steps (0.05–0.3) over Satin.
   • Look for a visible seam at 0.1.
4. Plate depth and gloss (partly run). Experiment 017 packages the depth comparison (0, 0.1, 0.2 and 0.4 mm lifts), the gloss controls (surface off, roughness forced to 1, roughness +0.12) and a stronger Shimmer, with its own test card. Session 2 (26 September) settled the depth ask: at an extreme close-up 0 mm breaks up while 0.1 and 0.4 mm stay clean, so 0.4 mm stays the default runtime (experiment 020 results). Under a controlled photo-mode light (session 4, 28 September) runtime: Gloss C (roughness forced to 1) is clearly the flattest, so the written roughness is what shows. A, B and D look wet, A the most, and their stripes don't separate at face framing. Shimmer · strong reads as a regular grid of dots far too large ("at the scale you'd see under a microscope"), so it needs randomised, much finer facets or a sheen-first design; the Metal ramp's stripes are its own test pattern (experiment 029 §3.2). It replaced an earlier backlit-translucency ask for the eyelids, which stays unnecessary: the translucency term needs thin geometry, which eyelids over the eyeball are not.
5. Back-lit ear. Answered in session 4 runtime: translucency runs. A photo-mode light behind and beside the head makes the whole ear glow red-orange, redder than the directly lit neck (ear R/G 1.42 against 1.04), and the no-light frames are neutral. This was with Ultra+'s Character Subsurface Translucency toggle on, so that toggle is a dependency. The light was a local photo-mode light at midnight, while the decoded translucency setup has only a sun term, so local lights reach a transmission path too [hypothesis for which] (skin reference §6.4, experiment 029 §4.6).
6. Debug views. If a debug-view toggle is found (open question 12), capture Albedo, Roughness, Metalness, Translucency and MaterialID views of the plate once.

Related: Glitter in game · mesh-decal contract · glossy feasibility · colour-shift feasibility · multilayered assessment · multilayered evidence · glint feasibility · finish taxonomy · skin trace · eye/lip optics · backlog. Community sources are acknowledged in the community credits.