DOCS // shadowfx

Cast terrain shadows from a height tile

See how sunlight falls across hills as the sun moves through the sky.

Contents7 sections
  1. Output files
  2. Estimate and bake
  3. Hills horizon shadow maps
  4. Engine import
  5. Use the horizon textures in a material
  6. Use the height tile from geofx
  7. Questions

Output files

You receive shadows/horizon_0.png, shadows/horizon_1.png, shadows/horizon.json and shadows/terrain_horizon.gdshaderinc alongside your geofx terrain files.

Hills horizon shadow maps · Engine import

Estimate and bake

Send your geofx TOML in spec with module set to geofx and terrain_shadows set to 8. The same job returns your geofx files and two horizon images.

First call MCP estimate with the request payload and check the quoted price. If approval is required and the user agrees, include the returned quote.id as accept_quote in submit, or use POST /v1/estimate then POST /v1/jobs over REST with the same approval flow.

ridge.geo.toml
[meta]
name = "ridge"
seed = 42

[grid]
size_m = [512, 512]
cell_m = 1.0

[[shape]]
op = "ridged"
amplitude_m = 40
scale_m = 320
octaves = 7
MCP request
JSON
{
  "module": "geofx",
  "operation": "bake",
  "quality": "draft",
  "spec": "[meta]\nname = \"ridge\"\nseed = 42\n\n[grid]\nsize_m = [512, 512]\ncell_m = 1.0\n\n[[shape]]\nop = \"ridged\"\namplitude_m = 40\nscale_m = 320\noctaves = 7\n",
  "terrain_shadows": 8
}

Hills horizon shadow maps

Precompute 8-direction horizon angles for the 512 m hills tile so ridges cast moving shadows as the sun crosses the sky.

Hosted output files · Draft · $1.50
job_dbq5c3mp700shjegds24

Hills terrain shaded by precomputed 8-direction horizon shadow maps
8-direction horizon shadow maps cast ridge shadows across the 512 m hills tile

Hilly terrain tile with a road and hollow

This spec pairs the 513 by 513 hills terrain with an 8-sector horizon shadow pass.

spec.geo.toml
# Procedural hills for one 512 m area, from nothing: ridges pushed about by a warp, finer noise, a hollow
# that collects water, a flat site and a graded road. No input file.
[meta]
name = "hills"
seed = 42

[grid]
size_m = [512, 512]
cell_m = 1.0

[draw]
cell_m = 0.5
detail = "noise"

[[shape]]
op = "warp"
scale_m = 256
warp_m = 40

[[shape]]
op = "ridged"
amplitude_m = 40
scale_m = 320
octaves = 7

[[shape]]
op = "noise"
amplitude_m = 6
scale_m = 96
octaves = 6

[[shape]]
op = "basin"
centre_m = [330, 340]
radius_m = 60
falloff_m = 70
amplitude_m = 10

# A flat site and a road that climbs at most 6 degrees.
[[constraints]]
shape = "polygon"
points_m = [[60, 60], [150, 60], [150, 130], [60, 130]]
action = "flat"
falloff_m = 16

[[constraints]]
shape = "polyline"
points_m = [[0, 250], [200, 220], [512, 280]]
width_m = 8
action = "flat"
slope_deg = 6
falloff_m = 8

# Gravel on both, and wear along the road.
[[constraints]]
shape = "polyline"
points_m = [[0, 250], [200, 220], [512, 280]]
width_m = 8
action = "material"
material = "gravel"
falloff_m = 1.5

[[constraints]]
shape = "polygon"
points_m = [[60, 60], [150, 60], [150, 130], [60, 130]]
action = "material"
material = "gravel"
falloff_m = 2

[[constraints]]
shape = "polyline"
points_m = [[0, 250], [200, 220], [512, 280]]
width_m = 8
action = "wear"
amount = 1

# Friction [dry, wet], softness and roughness_m: geofx.md 6.11 gives each value and its source, or says it is not sourced.
[[materials]]
name = "grass"

[[materials]]
name = "rock"
slope_deg = [28, 38, 90, 90]
weight = 2
sharpness = 2
friction = [0.75, 0.5]
softness = 0
roughness_m = 0.02

[[materials]]
name = "dirt"
wear = [0.2, 0.6, 1, 1]
weight = 3
noise_amount = 0.3
noise_scale_m = 6

[[materials]]
name = "mud"
wetness = [0.55, 0.8, 1, 1]
weight = 2
friction = [0.55, 0.45]
softness = 0.0037
roughness_m = 0.01

[[materials]]
name = "gravel"
weight = 0
friction = [0.6, 0.55]
softness = 0.005
roughness_m = 0.01

# Erosion is build stage 3; off, the example asks for nothing that is not built and bakes with no warning.
[erosion]
enabled = false
terrain.shadow.toml
[[uses]]
name = "ground"
layout = "out/godot/layout.json"
layers = ["height"]
[horizon]
sectors = 8

Alongside the hills geofx maps, the compiler writes shadows/horizon_0.png, shadows/horizon_1.png, shadows/horizon.json and shadows/terrain_horizon.gdshaderinc.

FileWhat it is
horizon_0.pnghorizon_1.pngTwo RGBA textures storing 8-direction horizon angles (4 directions per map)
horizon.jsonSector count and directional metadata for reading the horizon maps
terrain_horizon.gdshaderincGodot shader include
preview_shadow.pngShadow preview

Bind horizon_0.png and horizon_1.png in your terrain shader and pass the current sun direction to compare against the stored horizon angles.

Engine import

EngineImport
GodotKeep the emitted PNG import settings for horizon_0.png and horizon_1.png, include terrain_horizon.gdshaderinc in your terrain shader, and multiply direct sunlight by the returned visibility.
UnityBind horizon_0.png and horizon_1.png as linear clamped textures with no mipmaps, port the horizon sampling and smoothstep visibility math to HLSL, and apply it to direct sun diffuse and specular.
Unreal EngineBind horizon_0.png and horizon_1.png as linear clamped textures without mipmaps, port the horizon angle lookup into a material function, and multiply direct sunlight by the visibility term.
three.jsBind horizon_0.png and horizon_1.png as linear clamped data textures without mipmaps, port the horizon shader math to GLSL, and multiply direct sun lighting by the returned visibility.

Use the horizon textures in a material

Each RGBA8 PNG stores four directions, one per channel. The bake writes two textures for eight sectors, four for sixteen, or eight for thirty-two. horizon.json records the input hashes and describes the packing.

In Godot, include terrain_horizon.gdshaderinc and bind the textures in order starting at shadowfx_horizon_0. Use the supplied import settings for lossless linear data. Pass a unit vector pointing toward the sun as shadowfx_world_to_sun. Convert world XZ to tile UV by subtracting the tile origin and dividing by its size.

Multiply direct sunlight on the surface by shadowfx_sun_visibility(tile_uv). The material keeps its ambient and sky lighting when a ridge hides the sun.

Use the height tile from geofx

Export a single geofx tile with r16 or png16 heights. Keep the exported height file with its layout. In [[uses]], give the input a name, set layout relative to the shadow spec and select layers = ["height"]. The compiler checks the grid and the height sample hash. Set pin to sha256: followed by the layout digest to require that exact layout.

Questions

How do you request terrain shadows in a geofx job?

Send your geofx TOML with module set to geofx and terrain_shadows set to 8 to receive horizon maps alongside your terrain files.

What files are returned for terrain shadows?

The job returns horizon_0.png, horizon_1.png, horizon.json and terrain_horizon.gdshaderinc inside the shadows folder alongside your geofx data.

How do terrain shadow maps shade ridges at runtime?

A shader compares the sun direction against stored 8 direction horizon angles so ridges cast moving shadows as the sun crosses the sky.