---
title: "shadowfx: Cast terrain shadows from a height tile"
description: "See how sunlight falls across hills as the sun moves through the sky."
canonical: https://appliedmanifold.com/docs/ground/shadows/
site: "Applied Manifold: The spatial compute cloud for 3D reality"
---

[Home](https://appliedmanifold.com/) / [Docs](https://appliedmanifold.com/docs/) / [geofx](https://appliedmanifold.com/docs/ground/) / shadowfx

DOCS // shadowfx

# Cast terrain shadows from a height tile

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

## 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](https://appliedmanifold.com/docs/ground/shadows/#hills-shadows) · [Engine import](https://appliedmanifold.com/docs/ground/shadows/#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

```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](https://api.spatialcompiler.dev/share/AWsrDwBqb2JfZGJxNWMzbXA3MDBzaGplZ2RzMjQY9RLOPueXaVn5rHrrJyATLQ6jf3mnbdMWE8MrDfNT0HtEVu9rwSZOwQ) · Draft · $1.50
`job_dbq5c3mp700shjegds24`

![Hills terrain shaded by precomputed 8-direction horizon shadow maps](https://appliedmanifold.com/showcase/hosted/shadows/hero_1600.webp)

8-direction horizon shadow maps cast ridge shadows across the 512 m hills tile

[Hilly terrain tile with a road and hollow](https://appliedmanifold.com/docs/ground/examples/#hills)

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.

| File | What it is |
| --- | --- |
| `horizon_0.png``horizon_1.png` | Two RGBA textures storing 8-direction horizon angles (4 directions per map) |
| `horizon.json` | Sector count and directional metadata for reading the horizon maps |
| `terrain_horizon.gdshaderinc` | Godot shader include |
| [`preview_shadow.png`](https://appliedmanifold.com/showcase/hosted/shadows/preview_shadow.png) | Shadow 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

| Engine | Import |
| --- | --- |
| Godot | Keep 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. |
| Unity | Bind 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 Engine | Bind 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.js | Bind 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.
