Contents16 sections
geofx runs on the hosted API: try it in the Playground.
Use the grid, shape and erosion settings to define the landform. Material rules assign a surface to each part of the tile.
Add gullies between height samples
Set erosion.filter = "gully" for slope-aligned channels. erosion.amplify controls how many finer draw resolutions the compiler uses. Both settings affect the draw surface. The simulation heights and material masks keep their original values. The draw detail stays within draw.detail_max_m. See the Ochre Pass spec.
Base settings
[meta]
Names the ground.
| Key | Values | Default | Meaning |
|---|---|---|---|
name | string | "" | Ground name; used in every file name. Empty means the spec file's name. |
seed | 0 to 4294967295 | 0 | Seed for every random choice. |
notes | string | "" | Free text. |
[grid]
The world and the sim height.
| Key | Values | Default | Meaning |
|---|---|---|---|
size_m | 16 to 16384 m | [512,512] | Size of one tile (district), x and z. |
cell_m | 0.0625 to 64 m | 1 | Spacing of sim height samples; size_m / cell_m must be whole. A tile has size_m / cell_m + 1 samples a side. |
tiles | 1 to 64 | [1,1] | Tiles along x and z. |
origin_m | -1000000 to 1000000 m | [0,0] | World position of the corner sample of tile (0, 0). |
height_min_m | -10000 to 10000 m | -16 | Height of the integer 0. |
height_range_m | 1 to 8192 m | 128 | Height of the integer 65535 above height_min_m; the step is height_range_m / 65535. |
whole_limit | 129 to 16385 samples | 4097 | Most sim samples a side for whole; a larger world is WORLD_TOO_LARGE. |
[draw]
The draw-side grid.
| Key | Values | Default | Meaning |
|---|---|---|---|
cell_m | 0.03125 to 64 m | 0.5 | Spacing of draw maps; must be grid.cell_m / 2^k, k 0 to 5. |
detail_max_m | 0 to 1 m | 0.05 | Most the draw-only height may differ from the sim surface; it is clamped there. |
[source]
What comes in.
| Key | Values | Default | Meaning |
|---|---|---|---|
height | string | "" | A heightmap beside or under the spec: .r16 (raw little-endian u16), 16-bit greyscale .png, or .exr (one channel, float or half). {ti} and {tj} name one file a tile. Empty: the shape stack makes the height. |
height_mode | fixed, base | "fixed" | fixed: the game owns this height and every sim sample is written as read. base: a starting shape the bake may change. |
height_min_m | -10000 to 10000 m | "grid" | How the input's integers map to metres: the height of 0. "grid" is grid.height_min_m. |
height_range_m | 1 to 8192 m | "grid" | How the input's integers map to metres: the height of 65535 above the minimum. "grid" is grid.height_range_m. |
height_size | 0 to 65537 samples | [0,0] | Samples a side of a .r16 file; [0, 0] takes a square from its size. |
lock | string | "" | base mode: an 8-bit greyscale image at the sim grid; 255 is never moved, 0 moves freely. |
cover | string | "" | An existing cover map (8-bit RGBA) over the world; its channels drive the cover_r to cover_a rules. |
cover_cell_m | 0.25 to 1000 m | 20 | Size of one cover texel. |
layout | string | "" | A district layout file (geofx.md 5.4): sites, roads, rail, water and material areas become constraints. |
[[shape]]
The base shape: any number of operations, applied in order. You can write this section more than once.
| Key | Values | Default | Meaning |
|---|---|---|---|
op | noise, ridged, billow, warp, terrace, plateau, ridge, basin, tilt, image, smooth, clamp | "noise" | The operation (geofx.md 6.2). |
blend | add, max, min, replace, multiply | "add" | How its value meets the height so far (not warp, smooth, clamp). |
amplitude_m | -2000 to 2000 m | 6 | Height of the feature. |
scale_m | 1 to 100000 m | 192 | Size of the largest feature (noise kinds, warp). |
octaves | 1 to 16 | 6 | Layers of finer noise. |
lacunarity | 1.5 to 4 | 2 | Each octave's size divisor. |
gain | 0.1 to 0.9 | 0.5 | Each octave's amplitude factor. |
warp_m | 0 to 10000 m | 0 | warp: how far positions are pushed before the following ops read them. |
centre_m | -1000000 to 1000000 m | [0,0] | Centre of plateau, ridge (first end) and basin. |
end_m | -1000000 to 1000000 m | [0,0] | ridge: second end. |
radius_m | 0.5 to 100000 m | 64 | Size of plateau, ridge and basin; smooth: the blur radius. |
falloff_m | 0 to 100000 m | 32 | Width of the smooth edge of plateau, ridge and basin. |
steps | 2 to 256 | 8 | terrace: terraces over the height range. |
sharpness | 0 to 1 | 0.7 | terrace: 0 leaves the slope, 1 makes flat steps. |
slope_deg | -60 to 60 deg | [0,0] | tilt: slope along x and z. |
file | string | "" | image: 8 or 16-bit greyscale image over the world, 0 to amplitude_m. |
min_m | -20000 to 20000 m | -10000 | clamp: lower bound. |
max_m | -20000 to 20000 m | 10000 | clamp: upper bound. |
mask | string | "" | An 8-bit greyscale image over the world that scales this op's effect. |
[[constraints]]
Sites, roads and areas: a shape on the ground and what it forces there. You can write this section more than once.
| Key | Values | Default | Meaning |
|---|---|---|---|
shape | polygon, polyline, circle, image | "polygon" | The area. |
points_m | -1000000 to 1000000 m | [] | polygon (closed by itself) or polyline points. |
width_m | 0.1 to 1000 m | 6 | polyline: full width. |
centre_m | -1000000 to 1000000 m | [0,0] | circle: centre. |
radius_m | 0.1 to 100000 m | 16 | circle: radius. |
file | string | "" | image: 8-bit mask over the world; above 127 is inside. |
action | flat, keep, raise, lower, no_erosion, material, wear, wet | "flat" | What it forces (geofx.md 6.3). |
height_m | -20000 to 20000 m | "mean" | flat: the level; mean is the mean of the height under the shape before constraints. |
slope_deg | 0 to 30 deg | 0 | flat along a polyline: largest grade along it. |
depth_m | 0 to 1000 m | 1 | raise, lower: how far. |
falloff_m | 0 to 1000 m | 4 | Width of the blend round the shape. |
material | string | "" | material: a name in [[materials]], forced there. |
amount | 0 to 1 | 1 | wear, wet: the mask value inside. |
tolerance_m | 0 to 10 m | 0.01 | flat and keep: the height inside must be within this of the target, or CONSTRAINT_BROKEN. |
[masks]
The draw masks and how they are packed.
| Key | Values | Default | Meaning |
|---|---|---|---|
file0 | wetness, flow, sediment, wear, slope, curvature, occlusion, relief, zero, one | ["wetness","flow","sediment","wear"] | Channels R, G, B, A of <name>_masks0.png. |
file1 | wetness, flow, sediment, wear, slope, curvature, occlusion, relief, zero, one | ["slope","curvature","occlusion","relief"] | Channels of <name>_masks1.png, or [] for no file. |
flow_exponent | 1 to 10 | 1.1 | Multiple flow direction: share to each lower neighbour goes as slope to this power. |
flow_area_m2 | 1 to 1000000000 m2 | 20000 | Upstream area that maps to 255 (logarithmic). |
curvature_radius_m | 0.5 to 512 m | 4 | Scale of the curvature measure. |
curvature_range | 0.001 to 10 1/m | 0.05 | Curvature that maps to 0 and 255 about the middle 128. |
occlusion_rays | 4 to 64 | 16 | Directions of the horizon search. |
occlusion_radius_m | 1 to 2048 m | 32 | How far it searches. |
relief_radius_m | 1 to 4096 m | 64 | relief: height above the lowest point within this radius, over relief_range_m. |
relief_range_m | 0.1 to 4096 m | 16 | relief: the height that maps to 1. |
wear_radius_m | 0 to 64 m | 2 | Blur of the wear from roads, sites and wear constraints. |
[wetness]
The baked, dry-weather wetness.
| Key | Values | Default | Meaning |
|---|---|---|---|
base | 0 to 1 | 0.1 | Wetness of ordinary ground. |
twi_range | 0 to 40 | [6,14] | The wetness index ln(a / tan b) that maps to base and to 1. |
sediment_weight | 0 to 1 | 0.3 | Added wetness where sediment lies. |
relief_weight | 0 to 1 | 0.3 | Added wetness in low ground (relief near 0). |
max | 0 to 1 | 1 | Upper bound before wet constraints. |
[[materials]]
Ground materials, 1 to 16, each with rules for where it lies. You can write this section more than once.
| Key | Values | Default | Meaning |
|---|---|---|---|
name | string | "" | Required: letters, digits and _, at most 32. Used in layout.json and by constraints. |
id | -1 to 255 | -1 | The game's material row id, written in material_id; -1 is the list index. |
colour | 0 to 255 sRGB | [] | For previews only; [] takes the fixed palette's colour for its place in the list. |
weight | 0 to 100 | 1 | Base weight. |
sharpness | 0.1 to 16 | 1 | Above 1 makes edges between materials harder. |
height_m | -100000 to 100000 m | [] | A trapezoid ramp on height_m: 0 below a, rising to 1 at b, 1 to c, falling to 0 at d. [] has no effect. |
slope_deg | -100000 to 100000 deg | [] | A trapezoid ramp on slope_deg: 0 below a, rising to 1 at b, 1 to c, falling to 0 at d. [] has no effect. |
flow | -100000 to 100000 | [] | A trapezoid ramp on flow: 0 below a, rising to 1 at b, 1 to c, falling to 0 at d. [] has no effect. |
wetness | -100000 to 100000 | [] | A trapezoid ramp on wetness: 0 below a, rising to 1 at b, 1 to c, falling to 0 at d. [] has no effect. |
sediment | -100000 to 100000 | [] | A trapezoid ramp on sediment: 0 below a, rising to 1 at b, 1 to c, falling to 0 at d. [] has no effect. |
wear | -100000 to 100000 | [] | A trapezoid ramp on wear: 0 below a, rising to 1 at b, 1 to c, falling to 0 at d. [] has no effect. |
curvature | -100000 to 100000 | [] | A trapezoid ramp on curvature: 0 below a, rising to 1 at b, 1 to c, falling to 0 at d. [] has no effect. |
occlusion | -100000 to 100000 | [] | A trapezoid ramp on occlusion: 0 below a, rising to 1 at b, 1 to c, falling to 0 at d. [] has no effect. |
relief | -100000 to 100000 | [] | A trapezoid ramp on relief: 0 below a, rising to 1 at b, 1 to c, falling to 0 at d. [] has no effect. |
cover_r | -100000 to 100000 | [] | A trapezoid ramp on cover_r: 0 below a, rising to 1 at b, 1 to c, falling to 0 at d. [] has no effect. |
cover_g | -100000 to 100000 | [] | A trapezoid ramp on cover_g: 0 below a, rising to 1 at b, 1 to c, falling to 0 at d. [] has no effect. |
cover_b | -100000 to 100000 | [] | A trapezoid ramp on cover_b: 0 below a, rising to 1 at b, 1 to c, falling to 0 at d. [] has no effect. |
cover_a | -100000 to 100000 | [] | A trapezoid ramp on cover_a: 0 below a, rising to 1 at b, 1 to c, falling to 0 at d. [] has no effect. |
noise_amount | 0 to 1 | 0 | Seeded noise added to this material's weight. |
noise_scale_m | 0.25 to 1000 m | 8 | Size of that noise. |
[material_map]
How materials are written.
| Key | Values | Default | Meaning |
|---|---|---|---|
encoding | weights, index | "weights" | weights: four materials a RGBA8 file, filterable. index: one RGBA8 file: R the first material's index, G the second's, B the blend. |
id_map | bool | true | Writes <name>_material_id.png: the id of the material with the largest weight, 8-bit, never filtered. |
layers_per_texel | 2 to 4 | 4 | weights: at most this many materials keep weight at a texel. |
[export]
Engines and file forms.
| Key | Values | Default | Meaning |
|---|---|---|---|
targets | godot, unity, unreal, roblox, threejs | ["godot"] | One output folder each. A target whose build stage is not in this program fails with STAGE_FAILED; `targets` in the schema output says which are built. |
height_formats | r16, png16, exr32 | ["r16","png16"] | Files for the sim height. exr32 is one 32-bit float channel in metres. |
name_style | keep, lower_snake | "lower_snake" | File stems. |
[budget]
Limits; 0 sets none. A missed limit is BUDGET_EXCEEDED, exit 5, with every file written.
| Key | Values | Default | Meaning |
|---|---|---|---|
max_texture_mb | number | Video memory of one tile's draw maps with their mip chains (geofx.md 10). | |
max_samples_per_pixel | 0 to 64 | 0 | Texture reads a pixel the generated glue makes on its default path. |
max_bytes | integer | Largest output folder a target. | |
fail_on | FLAT_TERRAIN, OVER_ERODED, SPIKES, CONSTRAINT_BROKEN, MESH_ERROR_HIGH, EDGE_ARTIFACTS, HEIGHT_CLIPPED, HEIGHT_STEP_COARSE, HEIGHT_QUANTISED, DETAIL_CLAMPED, MATERIAL_UNCOVERED, MATERIAL_LAYERS_DROPPED, WETNESS_SATURATED, TILE_ALONE, FIXED_HEIGHT_KEPT, STAMP_CLIPPED, STAMP_VOLUME, TEXTURE_DOWNSIZED, TARGET_RESAMPLED, STAGE_NOT_BUILT | [] | Warnings that fail the bake with BUDGET_EXCEEDED. |
[preview]
The previews.
| Key | Values | Default | Meaning |
|---|---|---|---|
size_px | 256 to 4096 px | 1024 | Edge of each panel of the contact sheet. |
sun_deg | 0 to 360 deg | [45,315] | Light of the shaded relief and the perspective views: elevation 5 to 90, azimuth 0 to 360. |
thumbnail_px | 64 to 1024 px | 256 | Edge of preview_thumb.png. |
Questions
How does erosion.filter add gullies without changing simulation heights?
Setting erosion.filter to gully carves slope aligned channels on the draw surface while keeping simulation heights and material masks unchanged.
What happens when a geofx world exceeds whole_limit?
If the simulation samples per side exceed whole_limit, which defaults to 4097 samples, the compiler stops with a WORLD_TOO_LARGE error.
How do source.height_mode fixed and base differ?
Fixed mode writes every input simulation sample as read, while base mode treats the input heightmap as a starting shape the bake can modify.