Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(character): hair has a lobe gain, and an imported hair material sets it from what the source states

yhhf3ece05449d7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 941db058d..c2e3af63f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ published separately; it ships inside the editor.
### Added
+- **Hair that reads as hair.** The Hair shader has a lobe gain, u_lobeGain, for how much of the strand highlight a lamp draws apart from the reflection of the environment, and an imported hair material now sets it with the rest from what the source states: the specular factor as the environment's Fresnel, the roughness factor, a quarter of the lamp highlight, and a third of the shader's own strand shift and second highlight so the cards read as locks of hair and not plates. Against Blender's render of the same frame the hair comes out with a sheen on each lock and dark gaps between them, where it was a flat red plate.
- **Character materials shade like the source.** A model imported with Character Materials now shades like the Principled shader it was authored against: a glTF carries no subsurface scattering and no second strand highlight, so the Skin shader's scattering, wrap and fuzz and the Hair shader's second highlight, translucency and root darkening are written as off, and a hair material's specular factor is scaled to the strand highlight's own units. Measured against Blender's render of the same frame, a character's hair comes out about 15 percent brighter than the reference where it was two to three times too bright, and the skin no longer glows in the shadows.
- **AgX view transform.** A new post-process effect, agx, applies the AgX view transform Blender renders with, taken from the data Blender ships: scene-linear colour goes in and display-linear comes out, so put it last and leave the project's output transform at none. Its contrast setting is the look (1 is AgX Base, 1.2 is Medium High Contrast), it carries its own table, and against Blender's own render of the same frame the colours of a character come out within about two percent.
- **Hair maps from the model.** A hair material's strand-direction map, highlight-shift map and tip softness are now imported from the model: a glTF has no slot for them, so a material names them in its extras (flow_map, shift_map, suggested_tipSoftness) and the importer binds them to the Hair shader instead of leaving the highlight to be worked out from the surface.
@@ -50,6 +51,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Faces speckled with dirt in shadow.** The high quality profile's shadow cascades are now 1024 texels on a 4096 atlas (they were 512 on 2048). At 512 a cascade's texel is several millimetres across a close character, so a brow, a hairline or a lash card sitting a fraction of a millimetre above the skin fell inside one texel of it and the shadow speckled the face with dirt; at 1024 the face is clean. Medium and low are unchanged.
+- **Ambient occlusion at metre scale.** The ambient-occlusion effects, ssao and gtao, accept a radius down to a centimetre (they stopped at one world unit), so a 3D scene measured in metres can use them on hair and faces. A radius of 0.05 separates the cards of a hair mesh without the black speckle a larger one leaves on their edges.
- **Global illumination at metre scale.** The global-illumination effects accept lengths down to a centimetre: the voxel size of voxelGI, and the radius and thickness of ssgi, used to stop at four, ten and one world units, so a 3D scene measured in metres could not set them small enough to do anything. Against Blender's render of the same frame, a character lit by one sun gets its soft bounce light in the shadows once they are set to metre-scale values.
- **Lite engine builds compile.** The lite WeChat and mini-game engine builds compile again: the pass that puts the opaque scene back after water and glass named the post-process pipeline outside the guard that leaves it out of those builds, so every package without post-processing failed to build.
- **Shadow cascades fit the scene.** A directional light's shadow cascades are now spread over the geometry that is in the scene instead of over the whole view. A close shot of a character in a view that reaches fifty metres used to spend its first cascade on three metres and drew blocky, misplaced shadow edges; the cascades now end where the scene's geometry ends (rounded in quarter octaves, so the split does not swim as the camera moves), and the shadow lands where it should.
diff --git a/docs/astro/src/content/docs/graphics/materials.mdx b/docs/astro/src/content/docs/graphics/materials.mdx
index 17c17de19..b662da3b0 100644
--- a/docs/astro/src/content/docs/graphics/materials.mdx
+++ b/docs/astro/src/content/docs/graphics/materials.mdx
@@ -69,7 +69,7 @@ blurring the picture. `u_preIntegrate` takes the wrap past the terminator per co
**Hair** (`builtin:hair`) lights a strand as a strand. `u_flowMap` says which way the strands run (red and green are a direction across the
texture), the diffuse light is Kajiya-Kay (a strand is lit by how far the light is from along it), and the shine is two narrow
highlights along the strand, shifted against each other by `u_shiftMap` (`u_shiftAmount`, `u_shiftTile`): a white one near the surface and a coloured
-one under it (`u_secondaryTint`). `u_roughness` sets how tight the lines are. Light comes through the strands from behind (`u_translucency`),
+one under it (`u_secondaryTint`). `u_roughness` sets how tight the lines are, and `u_lobeGain` how much of the highlight a lamp draws apart from the reflection of the environment (`u_specular`). Light comes through the strands from behind (`u_translucency`),
`u_sharpen` keeps the fine strands a card is covered in from washing out at a slant, and `u_rootDark` darkens the roots by the occlusion map.
`u_alphaCutoff` cuts a card out by its texture's alpha, feathered by alpha-to-coverage under MSAA, and the card then casts its own shape into shadow maps. `u_tipSoftness` adds the soft outer band: where the alpha falls from the cutoff down by that much, a second blended pass draws the strand's tip fading out, sorted with the other blended draws, so tips do not stair-step under coverage (0 leaves it out). The card's own shape goes into shadow maps too, not the rectangle it is drawn on. A hair model is usually cards or ribbons, not strands; this shader gives the shading of a strand to what the geometry gives it.
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
index 4ac6e35c6..87799ec54 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
@@ -51,7 +51,7 @@ std140 uniform 块,于是 CPU 能按名字设置、并安全地送到 GPU。一
**皮肤**(`builtin:skin`)不模糊画面。光进入皮肤又在不远处出来,会让弯曲表面的受光一侧变软,这里按颜色分开做:漫反射光取自比表面自己的法线更软的法线,红色最软(`u_blurRed`、`u_blurGreen`,是法线贴图的 mip 层级),所以毛孔和高光保持清晰。明暗交界线被染暖(`u_sssColor`、`u_sssWrap`),薄的或曲率大的地方会透光(`u_translucency`、`u_thinness`:耳朵、鼻翼、手指),高光是两层(`u_specular`、`u_lobe2`、`u_lobe2Roughness`),另有一层很淡的绒毛光照亮边缘(`u_fuzz`)。打开 `u_subsurface` 还会把它标记给[次表面散射](/docs/zh-cn/graphics/post-processing/#次表面散射)特效,在更大的尺度上扩散剩下的光,代价是会模糊画面。`u_preIntegrate` 让明暗交界线之后的环绕光按颜色分开(红色最远),并在表面急转的地方变宽,所以鼻翼和耳朵边缘会透出光,而平坦的脸颊保持清晰;`u_curvature` 是每个世界单位内多快的转折算作急转。`u_detailMap` 是平铺在表面上的第二张细法线图(`u_detailTile`),用来补烘焙贴图没有足够像素表现的毛孔和皮纹:它按 `u_detailStrength`(0 表示不用)叠在高光读取的锐利法线上,不叠在柔和的漫反射法线上。导入时关闭 sRGB,并把环绕方式设为重复。它对每个像素做三次光照计算,所以适合镜头里的角色皮肤,不适合一群人。
-**头发**(`builtin:hair`)把发丝当发丝来打光。`u_flowMap` 说明发丝朝哪个方向(红、绿是贴图上的一个方向),漫反射是 Kajiya-Kay(发丝被光照亮的程度取决于光离它的走向有多远),高光是两条沿发丝的窄高光,由 `u_shiftMap` 把它们错开(`u_shiftAmount`、`u_shiftTile`):一条白的靠近表面,一条带颜色的在下面(`u_secondaryTint`)。`u_roughness` 决定线条有多紧。光会从发丝背面透过来(`u_translucency`),`u_sharpen` 让发片上密布的细发丝在斜着看时不被冲淡,`u_rootDark` 按遮蔽图把发根压暗。`u_alphaCutoff` 按贴图的 alpha 把发片抠出形状,在 MSAA 下由 alpha-to-coverage 柔化边缘,`u_tipSoftness` 增加柔和的外缘:alpha 从裁剪值往下降这么多的范围内,由第二遍混合绘制把发丝尖端渐隐地画出来,和其他混合绘制一起排序,所以发梢不会在覆盖率下出现阶梯(0 表示不用)。发片投进阴影图里的也是这个形状,而不是它所在的矩形。头发模型通常是发片或发带而不是真正的发丝;这个着色器把发丝的明暗给了几何本身给不了的部分。
+**头发**(`builtin:hair`)把发丝当发丝来打光。`u_lobeGain` 决定灯光画出多少发丝高光(环境反射则只由 `u_specular` 决定)。`u_flowMap` 说明发丝朝哪个方向(红、绿是贴图上的一个方向),漫反射是 Kajiya-Kay(发丝被光照亮的程度取决于光离它的走向有多远),高光是两条沿发丝的窄高光,由 `u_shiftMap` 把它们错开(`u_shiftAmount`、`u_shiftTile`):一条白的靠近表面,一条带颜色的在下面(`u_secondaryTint`)。`u_roughness` 决定线条有多紧。光会从发丝背面透过来(`u_translucency`),`u_sharpen` 让发片上密布的细发丝在斜着看时不被冲淡,`u_rootDark` 按遮蔽图把发根压暗。`u_alphaCutoff` 按贴图的 alpha 把发片抠出形状,在 MSAA 下由 alpha-to-coverage 柔化边缘,`u_tipSoftness` 增加柔和的外缘:alpha 从裁剪值往下降这么多的范围内,由第二遍混合绘制把发丝尖端渐隐地画出来,和其他混合绘制一起排序,所以发梢不会在覆盖率下出现阶梯(0 表示不用)。发片投进阴影图里的也是这个形状,而不是它所在的矩形。头发模型通常是发片或发带而不是真正的发丝;这个着色器把发丝的明暗给了几何本身给不了的部分。
**眼睛**(`builtin:eye`)用两张贴图和几个数值做出一只眼睛。`u_depthMap` 在虹膜和角膜穹顶上为白色,`u_irisNormalMap` 是这个穹顶的法线(两张都要以关闭 sRGB 的方式导入)。视线在角膜处折射(`u_ior`)再下行到虹膜(`u_irisDepth`),所以眼球转动时虹膜在表面后面移动。虹膜本身由 `u_irisColor` 到 `u_irisColor2` 绘制,带纤维纹理、深色角膜缘(`u_limbal`)和瞳孔(`u_pupilSize`),衬在眼白(`u_scleraColor`)上,眼白的光会绕过明暗交界线(`u_scleraWrap`)。角膜近似镜面(`u_corneaRoughness`、`u_specular`),所以每盏灯和天空都会变成一个眼神光。眼睑会给眼睛投下阴影:`u_lidMap` 是手绘的遮蔽图(眼睛睁开处为白色),`u_lidShadow` 会在表面朝上的地方(从 `u_lidStart` 即与世界上方向的点积起,到正上方)变暗并淡化角膜的反射,在头部直立时这就是上眼睑。网格上画的眼睛贴图会与结果相乘。
diff --git a/pipeline/src/assets/modelImport.ts b/pipeline/src/assets/modelImport.ts
index 1b8cb04a3..e5cef593e 100644
--- a/pipeline/src/assets/modelImport.ts
+++ b/pipeline/src/assets/modelImport.ts
@@ -704,11 +704,13 @@ function hasProduct(material: ImportedMaterial, refs: ProductRefs): boolean {
}
/**
- * How much of the Hair shader's `u_specular` one unit of a glTF specular factor is. The factor scales a Fresnel reflectance of 0.04; the engine's
- * strand highlight is an authored lobe with a peak of about half the light, so the same factor is far too bright without this. Measured against
- * Blender's Principled at roughness 0.43 and a specular level of 0.3 (tools/render-align in the star-neighbors game).
+ * How much of the Hair shader's strand highlight the lamps draw for a glTF's specular factor. The factor scales a Fresnel reflectance of 0.04,
+ * which `u_specular` carries into the reflection of the environment; the engine's strand highlight is an authored lobe with a peak of about
+ * half the light, so under a lamp it is far too bright unless it is turned down on its own. Measured against Blender's Principled at roughness
+ * 0.43 and a specular level of 0.3 (tools/render-align in the star-neighbors game).
*/
-const HAIR_SPECULAR_PER_GLTF = 0.07;
+const HAIR_LOBE_GAIN = 0.28;
+const HAIR_ENV_GAIN = 0.65;
/**
* What the character shaders read, from what the source says: the maps they share, and the cutout hair needs. What a glTF does not say it
@@ -730,9 +732,16 @@ function characterProperties(shading: CharacterShading, material: ImportedMateri
properties.u_blurRed = 0; properties.u_blurGreen = 0;
}
if (shading === 'hair') {
- properties.u_translucency = 0; properties.u_shiftAmount = 0; properties.u_rootDark = 0;
- properties.u_secondaryTint = { r: 0, g: 0, b: 0, a: 1 };
- properties.u_specular = (material.specular ?? 1) * HAIR_SPECULAR_PER_GLTF;
+ // A little of the shader's own strand character is kept (a per-strand shift of the highlight and a tinted second lobe, at a third of their
+ // strength): without it the cards read as plates, not locks of hair.
+ properties.u_translucency = 0; properties.u_shiftAmount = 0.3; properties.u_rootDark = 0;
+ properties.u_secondaryTint = { r: 0.25, g: 0.15, b: 0.08, a: 1 };
+ // The Hair shader has no use for the packed roughness (a strand's width is its own), so the factor is the whole answer.
+ if (rough !== undefined) properties.u_roughness = rough;
+ // Principled reflects F0 = 0.04 x the factor; the Hair shader's F0 is 0.046, so u_specular is the ratio, and its reflection of the environment at
+ // this roughness comes out about half as bright again as Blender's, which HAIR_ENV_GAIN takes back.
+ properties.u_specular = ((material.specular ?? 1) * 0.04 / 0.046) * HAIR_ENV_GAIN;
+ properties.u_lobeGain = HAIR_LOBE_GAIN;
properties.u_alphaCutoff = material.alphaCutoff ?? 0.5;
bind('u_flowMap', material.flowTexture);
bind('u_shiftMap', material.shiftTexture);
diff --git a/sdk/src/character/characterShaders.ts b/sdk/src/character/characterShaders.ts
index f33d2d463..05be180bb 100644
--- a/sdk/src/character/characterShaders.ts
+++ b/sdk/src/character/characterShaders.ts
@@ -28,6 +28,8 @@ const HAIR = `#pragma shader "Hair"
// centre line. The second is the coloured one, tinted by u_secondaryTint.
#pragma param u_roughness float default(0.3) range(0.05,1) ui(slider)
#pragma param u_specular float default(1) range(0,2) ui(slider)
+// How much of the strand highlight the lamps draw, apart from the reflection of the environment (which u_specular alone sets): 1 is the authored lobe.
+#pragma param u_lobeGain float default(1) range(0,2) ui(slider)
#pragma param u_shiftPrimary float default(-0.1) range(-1,1) ui(slider)
#pragma param u_shiftSecondary float default(0.2) range(-1,1) ui(slider)
#pragma param u_secondaryTint color default(0.75,0.45,0.25,1)
@@ -109,7 +111,7 @@ void main() {
float noise = (texture(u_shiftMap, v_texCoord * u_shiftTile).r - 0.5) * u_shiftAmount;
SurfaceExt ext = surfaceExtNone(N);
ext.aniso = vec4(T, 0.0);
- ext.misc = vec4(0.046, 1.0, u_shiftPrimary + noise, u_shiftSecondary + noise);
+ ext.misc = vec4(0.046, max(u_lobeGain, 0.001), u_shiftPrimary + noise, u_shiftSecondary + noise);
ext.scatter = vec4(base.rgb * u_secondaryTint.rgb * 1.6, 0.35);
ext.trans = vec4(u_translucency, 0.25, 0.0, 0.0);
vec3 viewDir = viewDirection(P);
@@ -189,7 +191,7 @@ fn packNormal(n : vec3f) -> vec2f {
let noise = (shiftTex - 0.5) * mc.u_shiftAmount;
var ext = surfaceExtNone(N);
ext.aniso = vec4f(T, 0.0);
- ext.misc = vec4f(0.046, 1.0, mc.u_shiftPrimary + noise, mc.u_shiftSecondary + noise);
+ ext.misc = vec4f(0.046, max(mc.u_lobeGain, 0.001), mc.u_shiftPrimary + noise, mc.u_shiftSecondary + noise);
ext.scatter = vec4f(base.rgb * mc.u_secondaryTint.rgb * 1.6, 0.35);
ext.trans = vec4f(mc.u_translucency, 0.25, 0.0, 0.0);
let viewDir = viewDirection(P);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 91df03d38..fb70b2b9d 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -56,6 +56,12 @@ export const NOTED = {
{"note":"The lite WeChat and mini-game engine builds compile again: the pass that puts the opaque scene back after water and glass named the post-process pipeline outside the guard that leaves it out of those builds, so every package without post-processing failed to build."},
'fix(postprocess): voxelGI and ssgi take voxel sizes, radii and thicknesses down to a centimetre':
{"note":"The global-illumination effects accept lengths down to a centimetre: the voxel size of voxelGI, and the radius and thickness of ssgi, used to stop at four, ten and one world units, so a 3D scene measured in metres could not set them small enough to do anything. Against Blender's render of the same frame, a character lit by one sun gets its soft bounce light in the shadows once they are set to metre-scale values."},
+ 'fix(render): the high quality profile\'s shadow cascades are 1024 texels, so a face is no longer speckled with dirt':
+ {"note":"The high quality profile's shadow cascades are now 1024 texels on a 4096 atlas (they were 512 on 2048). At 512 a cascade's texel is several millimetres across a close character, so a brow, a hairline or a lash card sitting a fraction of a millimetre above the skin fell inside one texel of it and the shadow speckled the face with dirt; at 1024 the face is clean. Medium and low are unchanged."},
+ 'fix(postprocess): ssao and gtao take a radius down to a centimetre':
+ {"note":"The ambient-occlusion effects, ssao and gtao, accept a radius down to a centimetre (they stopped at one world unit), so a 3D scene measured in metres can use them on hair and faces. A radius of 0.05 separates the cards of a hair mesh without the black speckle a larger one leaves on their edges."},
+ 'feat(character): hair has a lobe gain, and an imported hair material sets it from what the source states':
+ {"note":"The Hair shader has a lobe gain, u_lobeGain, for how much of the strand highlight a lamp draws apart from the reflection of the environment, and an imported hair material now sets it with the rest from what the source states: the specular factor as the environment's Fresnel, the roughness factor, a quarter of the lamp highlight, and a third of the shader's own strand shift and second highlight so the cards read as locks of hair and not plates. Against Blender's render of the same frame the hair comes out with a sheen on each lock and dark gaps between them, where it was a flat red plate."},
'fix: serialize binaryen optimization on windows': { internal: 'Uses one optimizer worker after wider builds reproduced heap corruption with four; release optimization flags stay unchanged.' },
'feat: add budgeted 2d and 3d particle scene collisions': { note: 'Budgeted particle scene collisions.' },
'feat(editor): add particle collision authoring and diagnostics': { note: 'Budgeted particle scene collisions.' },