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(terrain): a baked occlusion over the ground - Terrain.occlusionMap is an image whose red says how much of the sky reaches the ground, for the gullies and cliff feet no screen-space pass sees across; it dims the light from all round and leaves the sun's to the shadows

yhhba5f01c2cdee
diff --git a/docs/astro/src/content/docs/graphics/terrain.mdx b/docs/astro/src/content/docs/graphics/terrain.mdx
index 2dfd0d280..22c9aae89 100644
--- a/docs/astro/src/content/docs/graphics/terrain.mdx
+++ b/docs/astro/src/content/docs/graphics/terrain.mdx
@@ -41,6 +41,7 @@ The ground is one of two kinds, chosen by `extent`:
| `splatmap2` | Area only. The weights of layers 5 to 8, read with the first. |
| `colorMap` | Area only. A picture laid over the whole area and mixed into the ground's colour by its alpha: a meadow's flowers, the regions of a map, scorched ground. One texture for the whole terrain, on top of the layers; its import Use is Colour. |
| `colorMapStrength` | How much of the colour map is mixed in where its alpha is whole (1). Read each frame: changing it rebuilds nothing. |
+| `occlusionMap`, `occlusionStrength` | Area only. An image over the whole area whose red says how much of the sky reaches the ground there: a baked occlusion for gullies, hollows and the foot of a cliff, which are too large for a screen-space pass to see. It dims the light that comes from all round and leaves the sun's own to the shadows, so it is quiet in full sun and tells in shade. Its import Use is Data. |
| `layers` | The [terrain layers](#terrain-layers) the ground is drawn with, up to eight, in the order the paint weighs them. Empty draws the four layer colours or the Terrain material's textures. |
| `rockSlope`, `dirtHeight`, `snowHeight` | How steep ground must be to turn to rock, and the heights, as a share of `height`, where grass gives way to dirt and where snow begins. |
| `layerColor0`–`3` | Grass, dirt, snow, rock: the colours the ground is drawn in when it has no material. |
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx
index f6590b4cc..0163c6c00 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx
@@ -33,6 +33,7 @@ description: 一个 Terrain 组件,用高度图或噪声生成地面,可以是
| `splatmap2` | 仅区域。第 5 到 8 层的权重,与第一张一起读取。 |
| `colorMap` | 仅区域。铺在整块区域上的一张图,按它的 alpha 混进地面颜色:草甸上的花色、地图上的分区、烧焦的地面。整块地形一张,叠在图层之上;导入用途是颜色。 |
| `colorMapStrength` | alpha 为满的地方混入多少颜色图(1)。每帧读取:改它不会重建任何东西。 |
+| `occlusionMap`、`occlusionStrength` | 仅区域。铺在整块区域上的一张图,红色通道说明那里的地面能接到多少天空光:给沟壑、洼地、崖脚用的烘焙遮蔽,这些尺度太大,屏幕空间的遮蔽看不到。它只压暗来自四周的光,太阳的直射留给阴影,所以在阳光下很轻,在背阴处明显。导入用途是数据。 |
| `layers` | 绘制地面所用的[地形层](#地形层),最多八个,按地表图权重的顺序。为空则用四种图层颜色或 Terrain 材质的贴图。 |
| `rockSlope`、`dirtHeight`、`snowHeight` | 地面要多陡才变成岩石,以及草地转为泥土、雪开始出现的高度(占 `height` 的比例)。 |
| `layerColor0`–`3` | 草、泥土、雪、岩石:没有材质时地面绘制用的颜色。 |
diff --git a/sdk/src/asset/textureUse.ts b/sdk/src/asset/textureUse.ts
index b1538ede4..c9865ff52 100644
--- a/sdk/src/asset/textureUse.ts
+++ b/sdk/src/asset/textureUse.ts
@@ -12,7 +12,7 @@
/** Component type to the texture fields of it that are read as numbers. */
export const DATA_TEXTURE_FIELDS: Readonly<Record<string, readonly string[]>> = {
// The splatmaps are weights, four a texel: a picture's clear-texel fill writes its neighbours' colour wherever the fourth is 0.
- Terrain: ['heightmap', 'splatmap', 'splatmap2'],
+ Terrain: ['heightmap', 'splatmap', 'splatmap2', 'occlusionMap'],
// How many plants stand where: a number a texel.
Foliage: ['densityMap'],
};
diff --git a/sdk/src/terrain/terrainPlugin.ts b/sdk/src/terrain/terrainPlugin.ts
index d705aea20..0a5baf3a1 100644
--- a/sdk/src/terrain/terrainPlugin.ts
+++ b/sdk/src/terrain/terrainPlugin.ts
@@ -89,6 +89,10 @@ export interface TerrainData {
colorMap: number;
/** How much of the colour map is mixed in where its alpha is whole. */
colorMapStrength: number;
+ /** An image over the whole of an area whose red says how much of the sky reaches the ground there: a baked occlusion, for the folds no screen-space pass can see across. */
+ occlusionMap: number;
+ /** How much of the occlusion map is applied. */
+ occlusionStrength: number;
/**
* The terrain layers (`.esterrainlayer` files, up to eight) the ground is drawn with, in the order the paint weighs them. With any,
* the ground is drawn on the Terrain Layers shader (its material, if one is named, must be on it); with none, by the four colours.
@@ -142,7 +146,7 @@ const rgb = (r: number, g: number, b: number): Color => ({ r, g, b, a: 1 });
* @experimental
*/
export const Terrain: ComponentDef<TerrainData> = /* @__PURE__ */ defineComponent<TerrainData>('Terrain', {
- extent: TerrainExtent.Area, provider: NOISE_PROVIDER, world: '', generatorVersion: 1, heightmap: 0, tiles: '', heightmapFormat: HeightmapFormat.Grey, splatmap: 0, splatmap2: 0, colorMap: 0, colorMapStrength: 1, layers: [] as string[], material: 0,
+ extent: TerrainExtent.Area, provider: NOISE_PROVIDER, world: '', generatorVersion: 1, heightmap: 0, tiles: '', heightmapFormat: HeightmapFormat.Grey, splatmap: 0, splatmap2: 0, colorMap: 0, colorMapStrength: 1, occlusionMap: 0, occlusionStrength: 1, layers: [] as string[], material: 0,
// Lengths at the engine's reference of 100 units a metre (ecs/worldUnits.ts): a kilometre of ground 150 m high on 2 m cells in any project.
sizeX: 100000, sizeZ: 100000, height: 15000, cellSize: 200, detail: 1, drawDistance: 400000,
collision: true, collisionDistance: 6400, collisionLayer: 0, friction: 0.6,
@@ -150,7 +154,7 @@ export const Terrain: ComponentDef<TerrainData> = /* @__PURE__ */ defineComponen
rockSlope: 0.35, dirtHeight: 0.62, snowHeight: 0.88,
layerColor0: rgb(0.28, 0.46, 0.2), layerColor1: rgb(0.45, 0.36, 0.24), layerColor2: rgb(0.93, 0.95, 0.98), layerColor3: rgb(0.4, 0.38, 0.36),
}, {
- assetFields: [{ field: 'heightmap', type: 'texture' }, { field: 'splatmap', type: 'texture' }, { field: 'splatmap2', type: 'texture' }, { field: 'colorMap', type: 'texture' }, { field: 'material', type: 'material' }],
+ assetFields: [{ field: 'heightmap', type: 'texture' }, { field: 'splatmap', type: 'texture' }, { field: 'splatmap2', type: 'texture' }, { field: 'colorMap', type: 'texture' }, { field: 'occlusionMap', type: 'texture' }, { field: 'material', type: 'material' }],
worldUnitFields: ['sizeX', 'sizeZ', 'height', 'cellSize', 'drawDistance', 'collisionDistance'],
fields: {
extent: { enum: [{ label: 'Area', value: TerrainExtent.Area }, { label: 'Infinite', value: TerrainExtent.Infinite }], category: 'Shape', tooltip: 'An area of its own size, from a heightmap or noise; or ground that goes on for ever, from noise read anywhere (the same seed is the same ground).' },
@@ -164,6 +168,8 @@ export const Terrain: ComponentDef<TerrainData> = /* @__PURE__ */ defineComponen
splatmap2: { tooltip: 'An image whose red, green, blue and alpha are the weights of layers 5 to 8.', category: 'Layers', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
colorMap: { tooltip: 'A picture laid over the whole area and mixed into the ground\'s colour by its alpha. Its Use is Colour.', category: 'Layers', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
colorMapStrength: { min: 0, max: 1, step: 0.01, slider: true, category: 'Layers', tooltip: 'How much of the colour map is mixed in where its alpha is whole.', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
+ occlusionMap: { tooltip: 'An image over the whole area whose red says how much of the sky reaches the ground: white all of it, black none. It dims the light from all round, not the sun\'s. Its Use is Data.', category: 'Layers', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
+ occlusionStrength: { min: 0, max: 1, step: 0.01, slider: true, category: 'Layers', tooltip: 'How much of the occlusion map is applied.', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
layers: { tooltip: 'The terrain layers (.esterrainlayer, up to eight) the ground is drawn with, in the order the paint weighs them. Empty draws the four layer colours.', category: 'Layers' },
material: { tooltip: 'A material on the Terrain shader (on Terrain Layers when the ground has layers). Empty uses the stock one.', category: 'Layers' },
sizeX: { min: 1, category: 'Shape', tooltip: 'An area\'s size along x; for ground without end, the span its hills are spread over.' },
@@ -252,6 +258,8 @@ interface Built {
packing: boolean;
/** Whether the colour map is on the material: so taking it off is written once, and ground without one is written nothing. */
washed: boolean;
+ /** The same of the occlusion map. */
+ shaded: boolean;
}
/** Where a terrain's ground stands: still being made, ready, or failed (with why). */
@@ -594,7 +602,7 @@ export const TerrainsRes = /* @__PURE__ */ defineResource<Terrains>(/* @__PURE__
/** What, changed, rebuilds the ground: everything but the colours, the colour map, the detail and the collision, which are read each frame. */
function signatureOf(data: TerrainData, at: { x: number; z: number }): string {
const { layerColor0: _a, layerColor1: _b, layerColor2: _c, layerColor3: _d, detail: _e, drawDistance: _f,
- collision: _g, collisionDistance: _h, collisionLayer: _i, friction: _j, colorMap: _k, colorMapStrength: _l, layers, ...rest } = data;
+ collision: _g, collisionDistance: _h, collisionLayer: _i, friction: _j, colorMap: _k, colorMapStrength: _l, occlusionMap: _m, occlusionStrength: _n, layers, ...rest } = data;
// Which layers are only what the arrays are packed from; whether there are any is which shader the ground is drawn with.
const shape = { ...rest, layered: (layers?.length ?? 0) > 0 };
// Ground read from a provider is the world's where the terrain stands: moved, it is read again; and a game's own provider is read
@@ -675,7 +683,7 @@ export class TerrainPlugin implements Plugin {
signature, data: { ...data }, source: null, surface: null, epoch: (built?.epoch ?? 0) + 1, loading: true, cancel: null,
table: new PageTable(ATLAS_SIZE), heights: 0, paint: 0, mesh: 0, instance: 0,
nodes: new Map(), spare: [], wanted: new Map(), asked: new Set(), pending: false, failure: null, edits: 0,
- paint2: 0, arrays: [], packed: '', packing: false, washed: false,
+ paint2: 0, arrays: [], packed: '', packing: false, washed: false, shaded: false,
};
terrains.built_.set(entity, built);
void this.load(app, entity, built);
@@ -1016,10 +1024,13 @@ export class TerrainPlugin implements Plugin {
const b = source.bounds;
set('u_terrainBounds', b ? { x: b[0], y: b[1], z: b[2], w: b[3] } : { x: -1e9, y: -1e9, z: 1e9, w: 1e9 });
const wash = b && built.data.colorMap ? built.data.colorMapStrength : 0;
- if (wash > 0 && b) {
- set('u_colorMap', Material.tex(built.data.colorMap));
- set('u_colorMapArea', { x: b[0], y: b[1], z: b[2] - b[0], w: b[3] - b[1] });
- }
+ const shade = b && built.data.occlusionMap ? built.data.occlusionStrength : 0;
+ // Both maps lie over the whole area.
+ if ((wash > 0 || shade > 0) && b) set('u_colorMapArea', { x: b[0], y: b[1], z: b[2] - b[0], w: b[3] - b[1] });
+ if (wash > 0) set('u_colorMap', Material.tex(built.data.colorMap));
+ if (shade > 0) set('u_occlusionMap', Material.tex(built.data.occlusionMap));
+ if (shade > 0 || built.shaded) set('u_occlusionStrength', shade);
+ built.shaded = shade > 0;
if (wash > 0 || built.washed) set('u_colorMapStrength', wash);
built.washed = wash > 0;
// The four layer colours are the Terrain shader's; ground with layers is drawn by another, which has no such params.
diff --git a/sdk/src/terrain/terrainShader.ts b/sdk/src/terrain/terrainShader.ts
index 74343a674..2ef722ec6 100644
--- a/sdk/src/terrain/terrainShader.ts
+++ b/sdk/src/terrain/terrainShader.ts
@@ -135,6 +135,10 @@ const TERRAIN = `#pragma shader "Terrain"
#pragma param u_colorMap texture default(white)
#pragma param u_colorMapStrength float default(0) range(0,1) ui(slider)
#pragma param u_colorMapArea vec4 default(0,0,1,1)
+// How much of the sky reaches the ground, baked over the same area: its red dims the light that comes from all round (a gully, the foot
+// of a cliff), and leaves the sun's own to the shadows.
+#pragma param u_occlusionMap texture default(white) texel(data)
+#pragma param u_occlusionStrength float default(0) range(0,1) ui(slider)
#pragma param u_roughness float default(0.92) range(0,1) ui(slider)
// The ground in pages (pages.ts; the Terrain component writes these): heights and normals, and the paint, in two atlases; heights over
// u_heightRange above u_terrainOrigin; level 0 drawn out to u_lodRange0, each level twice as far; nothing off u_terrainBounds.
@@ -315,7 +319,12 @@ void main() {
SurfaceExt ext = surfaceExtNone(N);
vec3 viewDir = viewDirection(P);
- vec3 lit = applyLightingSurface(albedo, N, P, viewDir, 0.0, roughness, 0.5, 1.0, ext);
+ float open = 1.0;
+ if (u_occlusionStrength > 0.0) {
+ vec2 under = (Pw.xz - u_terrainOrigin.xz - u_colorMapArea.xy) / max(u_colorMapArea.zw, vec2(1e-4));
+ if (all(greaterThanEqual(under, vec2(0.0))) && all(lessThanEqual(under, vec2(1.0)))) open = mix(1.0, textureLod(u_occlusionMap, under, 0.0).r, u_occlusionStrength);
+ }
+ vec3 lit = applyLightingSurface(albedo, N, P, viewDir, 0.0, roughness, 0.5, open, ext);
fragColor = vec4(lit, 1.0);
#ifdef ES_GBUFFER
fragSurface = vec4(packNormal(N), roughness, 0.75);
@@ -480,7 +489,12 @@ fn packNormal(n : vec3f) -> vec2f {
let ext = surfaceExtNone(Ns);
let viewDir = viewDirection(P);
- let lit = applyLightingSurface(albedo, Ns, P, viewDir, 0.0, roughness, 0.5, 1.0, ext);
+ var open = 1.0;
+ if (mc.u_occlusionStrength > 0.0) {
+ let under = (Pw.xz - mc.u_terrainOrigin.xz - mc.u_colorMapArea.xy) / max(mc.u_colorMapArea.zw, vec2f(1e-4));
+ if (all(under >= vec2f(0.0)) && all(under <= vec2f(1.0))) { open = mix(1.0, textureSampleLevel(u_occlusionMap, u_occlusionMap_s, under, 0.0).r, mc.u_occlusionStrength); }
+ }
+ let lit = applyLightingSurface(albedo, Ns, P, viewDir, 0.0, roughness, 0.5, open, ext);
#ifdef ES_GBUFFER
var frag : FragOut;
frag.color = vec4f(lit, 1.0);
@@ -536,6 +550,10 @@ const TERRAIN_LAYERS = `#pragma shader "Terrain Layers"
#pragma param u_colorMap texture default(white)
#pragma param u_colorMapStrength float default(0) range(0,1) ui(slider)
#pragma param u_colorMapArea vec4 default(0,0,1,1)
+// How much of the sky reaches the ground, baked over the same area: its red dims the light that comes from all round (a gully, the foot
+// of a cliff), and leaves the sun's own to the shadows.
+#pragma param u_occlusionMap texture default(white) texel(data)
+#pragma param u_occlusionStrength float default(0) range(0,1) ui(slider)
// The ground in pages, as the Terrain shader has them, with the paint of layers 5 to 8 in an atlas of its own.
#pragma param u_terrainPages float default(0) range(0,1) ui(slider)
#pragma param u_heightPages texture default(white) texel(data)
@@ -753,7 +771,12 @@ void main() {
SurfaceExt ext = surfaceExtNone(N);
vec3 viewDir = viewDirection(P);
- vec3 lit = applyLightingSurface(colour, N, P, viewDir, 0.0, roughness, 0.5, surface.r, ext);
+ float open = 1.0;
+ if (u_occlusionStrength > 0.0) {
+ vec2 under = (Pw.xz - u_terrainOrigin.xz - u_colorMapArea.xy) / max(u_colorMapArea.zw, vec2(1e-4));
+ if (all(greaterThanEqual(under, vec2(0.0))) && all(lessThanEqual(under, vec2(1.0)))) open = mix(1.0, textureLod(u_occlusionMap, under, 0.0).r, u_occlusionStrength);
+ }
+ vec3 lit = applyLightingSurface(colour, N, P, viewDir, 0.0, roughness, 0.5, surface.r * open, ext);
fragColor = vec4(lit, 1.0);
#ifdef ES_GBUFFER
fragSurface = vec4(packNormal(N), roughness, 0.75);
@@ -974,7 +997,12 @@ fn packNormal(n : vec3f) -> vec2f {
let ext = surfaceExtNone(N);
let viewDir = viewDirection(P);
- let lit = applyLightingSurface(colour, N, P, viewDir, 0.0, roughness, 0.5, surface.r, ext);
+ var open = 1.0;
+ if (mc.u_occlusionStrength > 0.0) {
+ let under = (Pw.xz - mc.u_terrainOrigin.xz - mc.u_colorMapArea.xy) / max(mc.u_colorMapArea.zw, vec2f(1e-4));
+ if (all(under >= vec2f(0.0)) && all(under <= vec2f(1.0))) { open = mix(1.0, textureSampleLevel(u_occlusionMap, u_occlusionMap_s, under, 0.0).r, mc.u_occlusionStrength); }
+ }
+ let lit = applyLightingSurface(colour, N, P, viewDir, 0.0, roughness, 0.5, surface.r * open, ext);
#ifdef ES_GBUFFER
var frag : FragOut;
frag.color = vec4f(lit, 1.0);
diff --git a/sdk/tests/texture-use.test.ts b/sdk/tests/texture-use.test.ts
index f1ce65032..b543b3782 100644
--- a/sdk/tests/texture-use.test.ts
+++ b/sdk/tests/texture-use.test.ts
@@ -17,6 +17,8 @@ describe('the fields that read a texture as numbers', () => {
it('answer for one field', () => {
expect(readsTextureAsNumbers('Terrain', 'heightmap')).toBe(true);
expect(readsTextureAsNumbers('Terrain', 'splatmap')).toBe(true);
+ expect(readsTextureAsNumbers('Terrain', 'occlusionMap')).toBe(true);
+ expect(readsTextureAsNumbers('Terrain', 'colorMap')).toBe(false);
expect(readsTextureAsNumbers('Terrain', 'material')).toBe(false);
expect(readsTextureAsNumbers('Sprite', 'texture')).toBe(false);
});
diff --git a/sdk/tests/world-units.test.ts b/sdk/tests/world-units.test.ts
index 0f54cba49..3d983a23b 100644
--- a/sdk/tests/world-units.test.ts
+++ b/sdk/tests/world-units.test.ts
@@ -44,6 +44,7 @@ describe('world-unit defaults', () => {
expect(t.frequency).toBe(3);
// And the colour map: none, and all of one when it is set.
expect([t.colorMap, t.colorMapStrength]).toEqual([0, 1]);
+ expect([t.occlusionMap, t.occlusionStrength]).toEqual([0, 1]);
});
it('never touch a value the scene states, nor a field that is not a length', () => {