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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file groundBlendShader.ts
* @brief The Model shader, for a rock, a kerb or a foundation that has to stand in the ground rather than on it.
*
* @details Where the surface comes close to what stands behind it, it gives way to the picture of that very pixel, so whatever
* the ground is drawn with, its layers, its light and its shadows are what the seam fades into, with nothing baked and
* nothing to keep in step. The same closeness can bring a second layer up the surface (dirt climbing a rock), and a
* vertex colour's red can paint that layer by hand. How close is measured as height above what is behind, not along the
* view, so the band does not widen and narrow as the camera tilts.
*
* Derived from Model, so a material moved onto it keeps every map and param it had. Such a material is drawn after a copy
* of the opaque scene is taken, which is the whole of its cost.
*/
/** The fade and the second layer, added to Model's params. */
const PARAMS = `// How high above what stands behind it the surface has fully arrived, in world units. 0 leaves a hard edge.
#pragma param u_blendDistance float default(30) range(0,100000) ui(slider)
// How much the edge of that fade wanders, and the world size of its wander.
#pragma param u_blendNoise float default(0.5) range(0,1) ui(slider)
#pragma param u_blendNoiseScale float default(40) range(0.01,100000) ui(slider)
// A second layer: its picture, its colour, how rough it is, and how long one repeat is in the world (0 reads the mesh's own uv).
#pragma param u_layer2 texture default(white)
#pragma param u_layer2Tint color default(1,1,1,1)
#pragma param u_layer2Roughness float default(1) range(0,1) ui(slider)
#pragma param u_layer2Tile float default(0) range(0,100000) ui(slider)
// 1 lets a vertex colour's red paint the second layer, and stops the colour tinting the surface.
#pragma param u_vertexBlend float default(0) range(0,1) ui(slider)
// How far up from what stands behind it the second layer reaches, as a distance field does. 0 keeps it off.
#pragma param u_layerReach float default(0) range(0,100000) ui(slider)
#pragma param u_sceneDepthMap texture default(white) texel(data)
`;
const GLSL_HELPERS = `
float groundNoiseHash(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }
// Soft noise in the world, about 0..1, so the seam is not a ruled line round the object.
float groundNoise(vec2 p) {
vec2 i = floor(p);
vec2 f = fract(p);
f = f * f * (3.0 - 2.0 * f);
return mix(mix(groundNoiseHash(i), groundNoiseHash(i + vec2(1.0, 0.0)), f.x),
mix(groundNoiseHash(i + vec2(0.0, 1.0)), groundNoiseHash(i + vec2(1.0, 1.0)), f.x), f.y);
}
`;
const WGSL_HELPERS = `
fn groundNoiseHash(p : vec2f) -> f32 { return fract(sin(dot(p, vec2f(127.1, 311.7))) * 43758.5453); }
fn groundNoise(p : vec2f) -> f32 {
let i = floor(p);
var f = fract(p);
f = f * f * (3.0 - 2.0 * f);
return mix(mix(groundNoiseHash(i), groundNoiseHash(i + vec2f(1.0, 0.0)), f.x),
mix(groundNoiseHash(i + vec2f(0.0, 1.0)), groundNoiseHash(i + vec2f(1.0, 1.0)), f.x), f.y);
}
`;
const GLSL_SURFACE = ` float groundFade = 1.0;
float layerWeight = u_vertexBlend > 0.5 ? v_color.r : 0.0;
vec3 groundBehind = vec3(0.0);
#ifdef MESH_NORMALS
if (texture(u_sceneDepthMap, vec2(0.5)).a < 0.75 && texture(u_sceneColor, vec2(0.5)).a < 0.75) {
highp vec3 W = v_worldXYZ;
vec4 onScreen = u_projection * vec4(W, 1.0);
vec2 groundUv = clamp(onScreen.xy / max(onScreen.w, 1e-4) * 0.5 + 0.5, vec2(0.001), vec2(0.999));
highp float own = u_camera.w > 0.5 ? length(W - u_camera.xyz) : -dot(W, u_camera.xyz);
highp float along = texture(u_sceneDepthMap, groundUv).r - own;
// Height above what is behind, which is the ray's fall: it does not change as the camera tilts. Past a dozen times the
// band along the ray, what is behind is some other surface beyond, however level with this one it happens to be.
highp float above = abs(viewDirection(W).y) * max(along, 0.0);
float reach = max(u_blendDistance, u_layerReach);
float near = 1.0 - smoothstep(8.0, 12.0, along / max(reach, 1e-3));
float wander = (groundNoise(W.xz / max(u_blendNoiseScale, 0.01)) - 0.5) * u_blendNoise;
if (u_blendDistance > 0.0) {
groundFade = mix(1.0, smoothstep(0.0, 1.0, above / u_blendDistance + wander), near);
groundBehind = texture(u_sceneColor, groundUv).rgb;
}
if (u_layerReach > 0.0) layerWeight = max(layerWeight, near * (1.0 - smoothstep(0.0, 1.0, above / u_layerReach + wander)));
}
#endif
vec4 base = texture(u_textures[0], uv) * u_tint;
if (u_vertexBlend <= 0.5) base *= v_color;
if (layerWeight > 0.0) {
#ifdef MESH_NORMALS
vec2 layerUv = u_layer2Tile > 0.0 ? v_worldXYZ.xz / u_layer2Tile : v_texCoord;
#else
vec2 layerUv = v_texCoord;
#endif
base = mix(base, texture(u_layer2, layerUv) * u_layer2Tint, layerWeight);
}
`;
const WGSL_SURFACE = `#ifdef MESH_NORMALS
// Before any branch: a derivative needs every fragment of its quad.
let layerWorld = v.v_worldXYZ.xz / max(mc.u_layer2Tile, 1e-4);
let layerWorldDx = dpdx(layerWorld);
let layerWorldDy = dpdy(layerWorld);
#endif
var groundFade = 1.0;
var layerWeight = 0.0;
if (mc.u_vertexBlend > 0.5) { layerWeight = v.v_color.r; }
var groundBehind = vec3f(0.0);
#ifdef MESH_NORMALS
let groundWanted = textureSampleLevel(u_sceneDepthMap, u_sceneDepthMap_s, vec2f(0.5), 0.0).a < 0.75
&& textureSampleLevel(u_sceneColor, u_sceneColor_s, vec2f(0.5), 0.0).a < 0.75;
if (groundWanted) {
let W = v.v_worldXYZ;
let onScreen = frame.projection * vec4f(W, 1.0);
let screenW = max(onScreen.w, 1e-4);
// This device's rows run down the texture, so clip y is flipped on the way to a uv.
let groundUv = clamp(vec2f(onScreen.x / screenW * 0.5 + 0.5, 0.5 - onScreen.y / screenW * 0.5), vec2f(0.001), vec2f(0.999));
var own = -dot(W, frame.camera.xyz);
if (frame.camera.w > 0.5) { own = length(W - frame.camera.xyz); }
let along = textureSampleLevel(u_sceneDepthMap, u_sceneDepthMap_s, groundUv, 0.0).r - own;
let above = abs(viewDirection(W).y) * max(along, 0.0);
let reach = max(mc.u_blendDistance, mc.u_layerReach);
let near = 1.0 - smoothstep(8.0, 12.0, along / max(reach, 1e-3));
let wander = (groundNoise(W.xz / max(mc.u_blendNoiseScale, 0.01)) - 0.5) * mc.u_blendNoise;
if (mc.u_blendDistance > 0.0) {
groundFade = mix(1.0, smoothstep(0.0, 1.0, above / mc.u_blendDistance + wander), near);
groundBehind = textureSampleLevel(u_sceneColor, u_sceneColor_s, groundUv, 0.0).rgb;
}
if (mc.u_layerReach > 0.0) { layerWeight = max(layerWeight, near * (1.0 - smoothstep(0.0, 1.0, above / mc.u_layerReach + wander))); }
}
#endif
var base = textureSampleGrad(t0, s0, uv, duvx, duvy) * mc.u_tint;
if (mc.u_vertexBlend <= 0.5) { base = base * v.v_color; }
if (layerWeight > 0.0) {
#ifdef MESH_NORMALS
var layerUv = v.v_texCoord;
var layerDx = duvx;
var layerDy = duvy;
if (mc.u_layer2Tile > 0.0) {
layerUv = layerWorld;
layerDx = layerWorldDx;
layerDy = layerWorldDy;
}
base = mix(base, textureSampleGrad(u_layer2, u_layer2_s, layerUv, layerDx, layerDy) * mc.u_layer2Tint, layerWeight);
#else
base = mix(base, textureSampleGrad(u_layer2, u_layer2_s, v.v_texCoord, duvx, duvy) * mc.u_layer2Tint, layerWeight);
#endif
}
`;
function swap(source: string, from: string, to: string): string {
if (!source.includes(from)) throw new Error(`the Model shader no longer has what Ground Blend is made from: ${from.slice(0, 60)}`);
return source.replace(from, () => to);
}
/** Ground Blend from the Model shader's source. A refraction reads the same picture, and the two would fight over it, so it is taken out. */
export function deriveGroundBlend(model: string): string {
let s = swap(model, '#pragma shader "Model"', '#pragma shader "Ground Blend"');
s = swap(s, '#pragma param u_transmission float default(0) range(0,1) ui(slider)\n', '');
// With no such param the engine knows this always wants the copy (MaterialStore::usesSceneColor), and the branch below is never taken.
s = s.replace(/mc\.u_transmission/g, '0.0').replace(/u_transmission/g, '0.0');
s = swap(s, '#pragma param u_iridescence float', `${PARAMS}#pragma param u_iridescence float`);
s = swap(s, 'float specularAA(highp vec3', `${GLSL_HELPERS}float specularAA(highp vec3`);
s = swap(s, 'fn specularAA(dndx : vec3f', `${WGSL_HELPERS}fn specularAA(dndx : vec3f`);
s = swap(s, ' vec4 base = texture(u_textures[0], uv) * v_color * u_tint;\n', GLSL_SURFACE);
s = swap(s, ' var base = textureSampleGrad(t0, s0, uv, duvx, duvy) * v.v_color * mc.u_tint;\n', WGSL_SURFACE);
s = swap(s, 'float roughness = u_roughness * mr.g;', 'float roughness = mix(u_roughness * mr.g, u_layer2Roughness, layerWeight);');
s = swap(s, 'var roughness = mc.u_roughness * mr.g;', 'var roughness = mix(mc.u_roughness * mr.g, mc.u_layer2Roughness, layerWeight);');
s = swap(s, 'fragColor = vec4(lit + seen + u_emissive.rgb * texture(u_emissiveMap, uv).rgb, alpha);',
'fragColor = vec4(mix(groundBehind, lit + seen + u_emissive.rgb * texture(u_emissiveMap, uv).rgb, groundFade), alpha);');
s = swap(s, 'frag.color = vec4f(lit + seen + emit, alpha);', 'frag.color = vec4f(mix(groundBehind, lit + seen + emit, groundFade), alpha);');
s = swap(s, 'return vec4f(lit + seen + emit, alpha);', 'return vec4f(mix(groundBehind, lit + seen + emit, groundFade), alpha);');
return s;
}