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.

18.4 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  layerSurfaceShader.ts
 * @brief The ground's layers as one piece of shader code, shared by every shader that draws ground from layer files (Terrain Layers, Planet).
 *
 * What a pixel of ground is made of, from its paint: each layer's weight (broken up by noise of its own and sharpened), the layers read
 * without repeat near the eye and on a wider tile far off, projected on the planes the ground faces, then blended by the layers' heights.
 * Only the four layers with the most weight at a pixel are read: past four the rest are a sliver of the blend, and reading all eight cost
 * every pixel of ground the textures of all eight, as Unreal's landscape caps the layers a component weighs.
 *
 * A shader that uses it declares the params `layerParams` writes (its own defaults keep its own look), puts `LAYER_SURFACE_GLSL` /
 * `LAYER_SURFACE_WGSL` in its fragment, and calls `tnLayers`. The vertex stage and the lighting stay the shader's own.
 */

/** The defaults a shader gives the shared params: how a ground drawn with it looks before a material says otherwise. */
export interface LayerParamDefaults {
    sharpness: number;
    heightBlend: number;
    blendNoise: number;
    antiTile: number;
}

/** The `#pragma param` lines of the layers, with this shader's defaults. */
export function layerParams(d: LayerParamDefaults): string {
    return `#pragma param u_albedoLayers textureArray default(white)
#pragma param u_normalLayers textureArray default(flatnormal) texel(data)
#pragma param u_maskLayers textureArray default(white) texel(data)
// How many layers there are, and how many world units one repeat of each covers (layers 1 to 4, then 5 to 8).
#pragma param u_layerCount float default(0) range(0,8) ui(slider)
#pragma param u_tiles0 vec4 default(4,4,4,4)
#pragma param u_tiles1 vec4 default(4,4,4,4)
// Each layer's own height blend (below zero: the material's u_heightBlend), written from the layer files.
#pragma param u_heightBlends0 vec4 default(-1,-1,-1,-1)
#pragma param u_heightBlends1 vec4 default(-1,-1,-1,-1)
// How much a layer with more weight takes over from the others at the seam: 1 is a plain blend, higher a harder edge.
#pragma param u_sharpness float default(${d.sharpness}) range(1,8) ui(slider)
// How much the seams follow the layers' heights (their masks' blue): rock shows through the gaps in the grass before the grass gives
// way, and sand fills the low places between stones. 0 is a plain blend of the weights.
#pragma param u_heightBlend float default(${d.heightBlend}) range(0,1) ui(slider)
// How much each layer's weight is broken up by slow noise of its own before the strongest wins.
#pragma param u_blendNoise float default(${d.blendNoise}) range(0,1) ui(slider)
// From the middle distance on, each layer is also read on a tile u_farScale times as wide and mixed in, so its repeat is lost far off.
#pragma param u_farScale float default(4.3) range(1,32) ui(slider)
// How strongly each layer is read without repeat near the eye (hex tiling), so no tile is seen.
#pragma param u_antiTile float default(${d.antiTile}) range(0,1) ui(slider)
// How far round a cell may be turned (1 any way, 0 shifted only): a layer with a grain, sand in ripples or rock in beds, turned cell by
// cell is lit cell by cell, and shows the hexagons.
#pragma param u_antiTileTurn float default(1) range(0,1) ui(slider)
`;
}

/** The layers in GLSL: helpers, then `tnLayers`. Needs `precision highp sampler2DArray`. */
export const LAYER_SURFACE_GLSL = `float tnHash(vec2 p) {
    p = fract(p * vec2(0.1031, 0.1030));
    p += dot(p, p.yx + 33.33);
    return fract((p.x + p.y) * p.x);
}
float tnNoise(vec2 p) {
    vec2 i = floor(p), f = fract(p);
    f = f * f * (3.0 - 2.0 * f);
    return mix(mix(tnHash(i), tnHash(i + vec2(1.0, 0.0)), f.x), mix(tnHash(i + vec2(0.0, 1.0)), tnHash(i + vec2(1.0, 1.0)), f.x), f.y);
}
vec2 tnHash2(vec2 p) {
    return fract(sin(vec2(dot(p, vec2(127.1, 311.7)), dot(p, vec2(269.5, 183.3)))) * 43758.5453);
}
float tnTile(int i) { return i < 4 ? u_tiles0[i] : u_tiles1[i - 4]; }
float tnHeightBlend(int i) { float b = i < 4 ? u_heightBlends0[i] : u_heightBlends1[i - 4]; return b < 0.0 ? u_heightBlend : b; }

// One layer read at uv (in repeats) on one plane: its albedo, its tangent normal's slope (x, y) and its mask, from the gradients given.
struct TnTap { vec3 albedo; vec2 slope; vec3 mask; };
TnTap tnPlain(vec2 uv, float layer, vec2 gx, vec2 gy) {
    vec3 at = vec3(uv, layer);
    TnTap t;
    t.albedo = textureGrad(u_albedoLayers, at, gx, gy).rgb;
    t.slope = textureGrad(u_normalLayers, at, gx, gy).rg * 2.0 - 1.0;
    t.mask = textureGrad(u_maskLayers, at, gx, gy).rgb;
    return t;
}
// The same in one hex cell: shifted and turned by the cell's random numbers; the normal's slope turned back with it.
TnTap tnHexTap(vec2 uv, float layer, vec2 cell, vec2 gx, vec2 gy) {
    vec2 r = tnHash2(cell);
    float a = r.x * 6.2831853 * u_antiTileTurn;
    mat2 turn = mat2(cos(a), -sin(a), sin(a), cos(a));
    TnTap t = tnPlain(turn * uv + r, layer, turn * gx, turn * gy);
    t.slope = t.slope * turn;
    return t;
}
// A layer read without repeat (hex tiling, Mikkelsen 2022): three cells about a point blended by nearness, the higher reading winning.
TnTap tnHex(vec2 uv, float layer, vec2 gx, vec2 gy, float strength) {
    vec2 skewed = mat2(1.0, 0.0, -0.57735027, 1.15470054) * (uv * 3.4641016);
    vec2 base = floor(skewed);
    vec3 f = vec3(fract(skewed), 0.0);
    f.z = 1.0 - f.x - f.y;
    float s = step(0.0, -f.z), s2 = 2.0 * s - 1.0;
    vec3 w = vec3(-f.z * s2, s - f.y * s2, s - f.x * s2);
    TnTap c1 = tnHexTap(uv, layer, base + vec2(s, s), gx, gy);
    TnTap c2 = tnHexTap(uv, layer, base + vec2(s, 1.0 - s), gx, gy);
    TnTap c3 = tnHexTap(uv, layer, base + vec2(1.0 - s, s), gx, gy);
    vec3 h = vec3(c1.mask.b, c2.mask.b, c3.mask.b);
    w = pow(max(w * mix(vec3(1.0), 0.4 + h, strength), vec3(1e-4)), vec3(7.0));
    w /= dot(w, vec3(1.0));
    TnTap t;
    t.albedo = c1.albedo * w.x + c2.albedo * w.y + c3.albedo * w.z;
    t.slope = c1.slope * w.x + c2.slope * w.y + c3.slope * w.z;
    t.mask = c1.mask * w.x + c2.mask * w.y + c3.mask * w.z;
    return t;
}
// A tangent normal's slope laid on a plane whose texture runs along T and B, about the surface's normal N.
vec3 tnBend(vec2 slope, vec3 T, vec3 B, vec3 N) {
    T = normalize(T - N * dot(N, T));
    B = normalize(B - N * dot(N, B));
    return slope.x * T + slope.y * B;
}
// How strongly the layers are read without repeat (x) and how much of the wide tile is mixed in (y), at this distance from the eye.
vec2 tnNearFar(float eye) {
    float scale = tnTile(0);
    return vec2((1.0 - smoothstep(scale * 20.0, scale * 45.0, eye)) * u_antiTile, smoothstep(scale * 6.0, scale * 40.0, eye) * 0.65);
}

// What the layers make of a pixel: its colour, the slope its normal maps add, and its mask (occlusion, roughness, height).
struct TnSurface { vec3 albedo; vec3 slope; vec3 mask; };
// paintA / paintB: the weights of layers 1 to 4 and 5 to 8. at: where the ground is, as its layers are laid (the top plane reads at.xz,
// the sides (at.z, at.y) and (at.x, at.y)); dpx / dpy its gradients across the screen. N: the ground's normal. planes: how much of each
// plane is read (x, top, z). nearFar: tnNearFar.
TnSurface tnLayers(vec4 paintA, vec4 paintB, vec3 at, vec3 dpx, vec3 dpy, vec3 N, vec3 planes, vec2 nearFar) {
    int count = int(u_layerCount + 0.5);
    // Each painted layer's say, broken up by noise of its own so where two meet the edge is ragged, not the paint's gradient. Three
    // octaves: the slow one moves where the edge runs, the two finer break it up at the size of a paint texel and below. The four with
    // the most say are kept, heaviest first.
    vec4 wt = vec4(0.0);
    ivec4 id = ivec4(0);
    float sum = 0.0;
    for (int i = 0; i < 8; i++) {
        if (i >= count) break;
        float raw = i < 4 ? paintA[i] : paintB[i - 4];
        if (raw <= 0.0) continue;
        float tileSize = tnTile(i);
        float wander = tnNoise(at.xz / (tileSize * 2.3) + float(i) * 11.0 + 3.0) * 0.5
                     + tnNoise(at.xz / (tileSize * 0.45) + float(i) * 7.0 + 17.0) * 0.3
                     + tnNoise(at.xz / (tileSize * 0.11) + float(i) * 5.0 + 29.0) * 0.2;
        float v = raw * mix(1.0, 0.35 + 1.3 * wander, u_blendNoise);
        sum += v;
        if (v > wt.w) {
            if (v > wt.x) { wt = vec4(v, wt.xyz); id = ivec4(i, id.xyz); }
            else if (v > wt.y) { wt = vec4(wt.x, v, wt.yz); id = ivec4(id.x, i, id.yz); }
            else if (v > wt.z) { wt = vec4(wt.xy, v, wt.z); id = ivec4(id.xy, i, id.z); }
            else { wt.w = v; id.w = i; }
        }
    }
    wt = pow(wt / max(sum, 1e-4), vec4(u_sharpness));
    wt /= max(dot(wt, vec4(1.0)), 1e-4);

    vec3 albedo[4];
    vec3 bend[4];
    vec3 mask[4];
    for (int k = 0; k < 4; k++) {
        albedo[k] = vec3(0.0); bend[k] = vec3(0.0); mask[k] = vec3(1.0, 1.0, 0.0);
        if (wt[k] <= 1e-3) continue;
        int i = id[k];
        float layer = float(i), tile = tnTile(i);
        if (planes.y > 0.0) {
            // WebGL takes no ?: between structures.
            TnTap top;
            if (nearFar.x > 0.01) top = tnHex(at.xz / tile, layer, dpx.xz / tile, dpy.xz / tile, nearFar.x);
            else top = tnPlain(at.xz / tile, layer, dpx.xz / tile, dpy.xz / tile);
            if (nearFar.y > 0.01) {
                float big = tile * u_farScale;
                TnTap wide = tnPlain(at.xz / big + 0.21, layer, dpx.xz / big, dpy.xz / big);
                top.albedo = mix(top.albedo, wide.albedo, nearFar.y);
                top.mask = mix(top.mask, wide.mask, nearFar.y);
            }
            albedo[k] = top.albedo * planes.y;
            mask[k] = top.mask * planes.y;
            bend[k] = tnBend(top.slope, vec3(1.0, 0.0, 0.0), vec3(0.0, 0.0, 1.0), N) * planes.y;
        } else {
            mask[k] = vec3(0.0);
        }
        if (planes.x > 0.02) {
            TnTap x = tnPlain(at.zy / tile, layer, dpx.zy / tile, dpy.zy / tile);
            albedo[k] += x.albedo * planes.x; mask[k] += x.mask * planes.x;
            bend[k] += tnBend(x.slope, vec3(0.0, 0.0, 1.0), vec3(0.0, 1.0, 0.0), N) * planes.x;
        }
        if (planes.z > 0.02) {
            TnTap z = tnPlain(at.xy / tile, layer, dpx.xy / tile, dpy.xy / tile);
            albedo[k] += z.albedo * planes.z; mask[k] += z.mask * planes.z;
            bend[k] += tnBend(z.slope, vec3(1.0, 0.0, 0.0), vec3(0.0, 1.0, 0.0), N) * planes.z;
        }
    }
    // Then by height: each layer stands as high as its mask says, and where two meet the higher one shows. How much height decides is
    // each layer's own say, weighted by how much of that layer is here, so grass into sand blends by the paint and stones standing
    // through grass by their heights, with no one number for the whole ground.
    float top = -1.0;
    for (int k = 0; k < 4; k++) if (wt[k] > 1e-3) top = max(top, mask[k].b + wt[k] * 1.5);
    float hsum = 0.0, byHeight = 0.0;
    vec4 hw = vec4(0.0);
    for (int k = 0; k < 4; k++) {
        if (wt[k] <= 1e-3) continue;
        hw[k] = max(mask[k].b + wt[k] * 1.5 - (top - 0.35), 0.0);
        hsum += hw[k];
        byHeight += wt[k] * tnHeightBlend(id[k]);
    }
    TnSurface s;
    s.albedo = vec3(0.0); s.slope = vec3(0.0); s.mask = vec3(0.0);
    for (int k = 0; k < 4; k++) {
        float f = mix(wt[k], hw[k] / max(hsum, 1e-4), byHeight);
        s.albedo += albedo[k] * f; s.slope += bend[k] * f; s.mask += mask[k] * f;
    }
    return s;
}
`;

/** The same in WGSL, under the engine's conventions (params as `mc.<name>`, textures with their `_s` samplers). */
export const LAYER_SURFACE_WGSL = `fn tnHash(p0 : vec2f) -> f32 {
    var p = fract(p0 * vec2f(0.1031, 0.1030));
    p = p + dot(p, p.yx + 33.33);
    return fract((p.x + p.y) * p.x);
}
fn tnNoise(p : vec2f) -> f32 {
    let i = floor(p);
    var f = fract(p);
    f = f * f * (3.0 - 2.0 * f);
    return mix(mix(tnHash(i), tnHash(i + vec2f(1.0, 0.0)), f.x), mix(tnHash(i + vec2f(0.0, 1.0)), tnHash(i + vec2f(1.0, 1.0)), f.x), f.y);
}
fn tnHash2(p : vec2f) -> vec2f {
    return fract(sin(vec2f(dot(p, vec2f(127.1, 311.7)), dot(p, vec2f(269.5, 183.3)))) * 43758.5453);
}
fn tnTile(i : i32) -> f32 {
    if (i < 4) { return mc.u_tiles0[i]; }
    return mc.u_tiles1[i - 4];
}
fn tnHeightBlend(i : i32) -> f32 {
    var b = 0.0;
    if (i < 4) { b = mc.u_heightBlends0[i]; } else { b = mc.u_heightBlends1[i - 4]; }
    if (b < 0.0) { return mc.u_heightBlend; }
    return b;
}
struct TnTap { albedo : vec3f, slope : vec2f, mask : vec3f };
fn tnPlain(uv : vec2f, layer : i32, gx : vec2f, gy : vec2f) -> TnTap {
    var t : TnTap;
    t.albedo = textureSampleGrad(u_albedoLayers, u_albedoLayers_s, uv, layer, gx, gy).rgb;
    t.slope = textureSampleGrad(u_normalLayers, u_normalLayers_s, uv, layer, gx, gy).rg * 2.0 - vec2f(1.0);
    t.mask = textureSampleGrad(u_maskLayers, u_maskLayers_s, uv, layer, gx, gy).rgb;
    return t;
}
fn tnHexTap(uv : vec2f, layer : i32, cell : vec2f, gx : vec2f, gy : vec2f) -> TnTap {
    let r = tnHash2(cell);
    let a = r.x * 6.2831853 * mc.u_antiTileTurn;
    let turn = mat2x2f(cos(a), -sin(a), sin(a), cos(a));
    var t = tnPlain(turn * uv + r, layer, turn * gx, turn * gy);
    t.slope = t.slope * turn;
    return t;
}
fn tnHex(uv : vec2f, layer : i32, gx : vec2f, gy : vec2f, strength : f32) -> TnTap {
    let skewed = mat2x2f(1.0, 0.0, -0.57735027, 1.15470054) * (uv * 3.4641016);
    let base = floor(skewed);
    let fr = fract(skewed);
    let fz = 1.0 - fr.x - fr.y;
    let s = step(0.0, -fz);
    let s2 = 2.0 * s - 1.0;
    var w = vec3f(-fz * s2, s - fr.y * s2, s - fr.x * s2);
    let c1 = tnHexTap(uv, layer, base + vec2f(s, s), gx, gy);
    let c2 = tnHexTap(uv, layer, base + vec2f(s, 1.0 - s), gx, gy);
    let c3 = tnHexTap(uv, layer, base + vec2f(1.0 - s, s), gx, gy);
    let h = vec3f(c1.mask.b, c2.mask.b, c3.mask.b);
    w = pow(max(w * mix(vec3f(1.0), vec3f(0.4) + h, vec3f(strength)), vec3f(1e-4)), vec3f(7.0));
    w = w / dot(w, vec3f(1.0));
    var t : TnTap;
    t.albedo = c1.albedo * w.x + c2.albedo * w.y + c3.albedo * w.z;
    t.slope = c1.slope * w.x + c2.slope * w.y + c3.slope * w.z;
    t.mask = c1.mask * w.x + c2.mask * w.y + c3.mask * w.z;
    return t;
}
fn tnBend(slope : vec2f, T0 : vec3f, B0 : vec3f, N : vec3f) -> vec3f {
    let T = normalize(T0 - N * dot(N, T0));
    let B = normalize(B0 - N * dot(N, B0));
    return slope.x * T + slope.y * B;
}
fn tnNearFar(eye : f32) -> vec2f {
    let scale = tnTile(0);
    return vec2f((1.0 - smoothstep(scale * 20.0, scale * 45.0, eye)) * mc.u_antiTile, smoothstep(scale * 6.0, scale * 40.0, eye) * 0.65);
}
struct TnSurface { albedo : vec3f, slope : vec3f, mask : vec3f };
fn tnLayers(paintA : vec4f, paintB : vec4f, at : vec3f, dpx : vec3f, dpy : vec3f, N : vec3f, planes : vec3f, nearFar : vec2f) -> TnSurface {
    let count = i32(mc.u_layerCount + 0.5);
    var wt = vec4f(0.0);
    var id = vec4i(0);
    var sum = 0.0;
    for (var i = 0; i < 8; i = i + 1) {
        if (i >= count) { break; }
        var raw = 0.0;
        if (i < 4) { raw = paintA[i]; } else { raw = paintB[i - 4]; }
        if (raw <= 0.0) { continue; }
        let tileSize = tnTile(i);
        let wander = tnNoise(at.xz / (tileSize * 2.3) + vec2f(f32(i) * 11.0 + 3.0)) * 0.5
                   + tnNoise(at.xz / (tileSize * 0.45) + vec2f(f32(i) * 7.0 + 17.0)) * 0.3
                   + tnNoise(at.xz / (tileSize * 0.11) + vec2f(f32(i) * 5.0 + 29.0)) * 0.2;
        let v = raw * mix(1.0, 0.35 + 1.3 * wander, mc.u_blendNoise);
        sum = sum + v;
        if (v > wt.w) {
            if (v > wt.x) { wt = vec4f(v, wt.xyz); id = vec4i(i, id.xyz); }
            else if (v > wt.y) { wt = vec4f(wt.x, v, wt.yz); id = vec4i(id.x, i, id.yz); }
            else if (v > wt.z) { wt = vec4f(wt.xy, v, wt.z); id = vec4i(id.xy, i, id.z); }
            else { wt.w = v; id.w = i; }
        }
    }
    wt = pow(wt / max(sum, 1e-4), vec4f(mc.u_sharpness));
    wt = wt / max(dot(wt, vec4f(1.0)), 1e-4);

    var albedo : array<vec3f, 4>;
    var bend : array<vec3f, 4>;
    var mask : array<vec3f, 4>;
    for (var k = 0; k < 4; k = k + 1) {
        albedo[k] = vec3f(0.0);
        bend[k] = vec3f(0.0);
        mask[k] = vec3f(1.0, 1.0, 0.0);
        if (wt[k] <= 1e-3) { continue; }
        let i = id[k];
        let tile = tnTile(i);
        if (planes.y > 0.0) {
            var top : TnTap;
            if (nearFar.x > 0.01) { top = tnHex(at.xz / tile, i, dpx.xz / tile, dpy.xz / tile, nearFar.x); }
            else { top = tnPlain(at.xz / tile, i, dpx.xz / tile, dpy.xz / tile); }
            if (nearFar.y > 0.01) {
                let big = tile * mc.u_farScale;
                let wide = tnPlain(at.xz / big + vec2f(0.21), i, dpx.xz / big, dpy.xz / big);
                top.albedo = mix(top.albedo, wide.albedo, vec3f(nearFar.y));
                top.mask = mix(top.mask, wide.mask, vec3f(nearFar.y));
            }
            albedo[k] = top.albedo * planes.y;
            mask[k] = top.mask * planes.y;
            bend[k] = tnBend(top.slope, vec3f(1.0, 0.0, 0.0), vec3f(0.0, 0.0, 1.0), N) * planes.y;
        } else {
            mask[k] = vec3f(0.0);
        }
        if (planes.x > 0.02) {
            let x = tnPlain(at.zy / tile, i, dpx.zy / tile, dpy.zy / tile);
            albedo[k] = albedo[k] + x.albedo * planes.x;
            mask[k] = mask[k] + x.mask * planes.x;
            bend[k] = bend[k] + tnBend(x.slope, vec3f(0.0, 0.0, 1.0), vec3f(0.0, 1.0, 0.0), N) * planes.x;
        }
        if (planes.z > 0.02) {
            let z = tnPlain(at.xy / tile, i, dpx.xy / tile, dpy.xy / tile);
            albedo[k] = albedo[k] + z.albedo * planes.z;
            mask[k] = mask[k] + z.mask * planes.z;
            bend[k] = bend[k] + tnBend(z.slope, vec3f(1.0, 0.0, 0.0), vec3f(0.0, 1.0, 0.0), N) * planes.z;
        }
    }
    var top = -1.0;
    for (var k = 0; k < 4; k = k + 1) { if (wt[k] > 1e-3) { top = max(top, mask[k].b + wt[k] * 1.5); } }
    var hsum = 0.0;
    var byHeight = 0.0;
    var hw = vec4f(0.0);
    for (var k = 0; k < 4; k = k + 1) {
        if (wt[k] <= 1e-3) { continue; }
        hw[k] = max(mask[k].b + wt[k] * 1.5 - (top - 0.35), 0.0);
        hsum = hsum + hw[k];
        byHeight = byHeight + wt[k] * tnHeightBlend(id[k]);
    }
    var s : TnSurface;
    s.albedo = vec3f(0.0);
    s.slope = vec3f(0.0);
    s.mask = vec3f(0.0);
    for (var k = 0; k < 4; k = k + 1) {
        let f = mix(wt[k], hw[k] / max(hsum, 1e-4), byHeight);
        s.albedo = s.albedo + albedo[k] * f;
        s.slope = s.slope + bend[k] * f;
        s.mask = s.mask + mask[k] * f;
    }
    return s;
}
`;