DOCS // geofx

geofx spec keys Available

geofx spec keys, defaults and ranges come from the release schema. Set the erosion filter and amplification to cut channels along runoff paths.

Contents16 sections
  1. Add gullies between height samples
  2. Base settings
  3. [meta]
  4. [grid]
  5. [draw]
  6. [source]
  7. [[shape]]
  8. [[constraints]]
  9. [masks]
  10. [wetness]
  11. [[materials]]
  12. [material_map]
  13. [export]
  14. [budget]
  15. [preview]
  16. Questions

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.

KeyValuesDefaultMeaning
namestring""Ground name; used in every file name. Empty means the spec file's name.
seed0 to 42949672950Seed for every random choice.
notesstring""Free text.

[grid]

The world and the sim height.

KeyValuesDefaultMeaning
size_m16 to 16384 m[512,512]Size of one tile (district), x and z.
cell_m0.0625 to 64 m1Spacing of sim height samples; size_m / cell_m must be whole. A tile has size_m / cell_m + 1 samples a side.
tiles1 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-16Height of the integer 0.
height_range_m1 to 8192 m128Height of the integer 65535 above height_min_m; the step is height_range_m / 65535.
whole_limit129 to 16385 samples4097Most sim samples a side for whole; a larger world is WORLD_TOO_LARGE.

[draw]

The draw-side grid.

KeyValuesDefaultMeaning
cell_m0.03125 to 64 m0.5Spacing of draw maps; must be grid.cell_m / 2^k, k 0 to 5.
detail_max_m0 to 1 m0.05Most the draw-only height may differ from the sim surface; it is clamped there.

[source]

What comes in.

KeyValuesDefaultMeaning
heightstring""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_modefixed, 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_m1 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_size0 to 65537 samples[0,0]Samples a side of a .r16 file; [0, 0] takes a square from its size.
lockstring""base mode: an 8-bit greyscale image at the sim grid; 255 is never moved, 0 moves freely.
coverstring""An existing cover map (8-bit RGBA) over the world; its channels drive the cover_r to cover_a rules.
cover_cell_m0.25 to 1000 m20Size of one cover texel.
layoutstring""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.

KeyValuesDefaultMeaning
opnoise, ridged, billow, warp, terrace, plateau, ridge, basin, tilt, image, smooth, clamp"noise"The operation (geofx.md 6.2).
blendadd, max, min, replace, multiply"add"How its value meets the height so far (not warp, smooth, clamp).
amplitude_m-2000 to 2000 m6Height of the feature.
scale_m1 to 100000 m192Size of the largest feature (noise kinds, warp).
octaves1 to 166Layers of finer noise.
lacunarity1.5 to 42Each octave's size divisor.
gain0.1 to 0.90.5Each octave's amplitude factor.
warp_m0 to 10000 m0warp: 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_m0.5 to 100000 m64Size of plateau, ridge and basin; smooth: the blur radius.
falloff_m0 to 100000 m32Width of the smooth edge of plateau, ridge and basin.
steps2 to 2568terrace: terraces over the height range.
sharpness0 to 10.7terrace: 0 leaves the slope, 1 makes flat steps.
slope_deg-60 to 60 deg[0,0]tilt: slope along x and z.
filestring""image: 8 or 16-bit greyscale image over the world, 0 to amplitude_m.
min_m-20000 to 20000 m-10000clamp: lower bound.
max_m-20000 to 20000 m10000clamp: upper bound.
maskstring""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.

KeyValuesDefaultMeaning
shapepolygon, polyline, circle, image"polygon"The area.
points_m-1000000 to 1000000 m[]polygon (closed by itself) or polyline points.
width_m0.1 to 1000 m6polyline: full width.
centre_m-1000000 to 1000000 m[0,0]circle: centre.
radius_m0.1 to 100000 m16circle: radius.
filestring""image: 8-bit mask over the world; above 127 is inside.
actionflat, 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_deg0 to 30 deg0flat along a polyline: largest grade along it.
depth_m0 to 1000 m1raise, lower: how far.
falloff_m0 to 1000 m4Width of the blend round the shape.
materialstring""material: a name in [[materials]], forced there.
amount0 to 11wear, wet: the mask value inside.
tolerance_m0 to 10 m0.01flat and keep: the height inside must be within this of the target, or CONSTRAINT_BROKEN.

[masks]

The draw masks and how they are packed.

KeyValuesDefaultMeaning
file0wetness, flow, sediment, wear, slope, curvature, occlusion, relief, zero, one["wetness","flow","sediment","wear"]Channels R, G, B, A of <name>_masks0.png.
file1wetness, flow, sediment, wear, slope, curvature, occlusion, relief, zero, one["slope","curvature","occlusion","relief"]Channels of <name>_masks1.png, or [] for no file.
flow_exponent1 to 101.1Multiple flow direction: share to each lower neighbour goes as slope to this power.
flow_area_m21 to 1000000000 m220000Upstream area that maps to 255 (logarithmic).
curvature_radius_m0.5 to 512 m4Scale of the curvature measure.
curvature_range0.001 to 10 1/m0.05Curvature that maps to 0 and 255 about the middle 128.
occlusion_rays4 to 6416Directions of the horizon search.
occlusion_radius_m1 to 2048 m32How far it searches.
relief_radius_m1 to 4096 m64relief: height above the lowest point within this radius, over relief_range_m.
relief_range_m0.1 to 4096 m16relief: the height that maps to 1.
wear_radius_m0 to 64 m2Blur of the wear from roads, sites and wear constraints.

[wetness]

The baked, dry-weather wetness.

KeyValuesDefaultMeaning
base0 to 10.1Wetness of ordinary ground.
twi_range0 to 40[6,14]The wetness index ln(a / tan b) that maps to base and to 1.
sediment_weight0 to 10.3Added wetness where sediment lies.
relief_weight0 to 10.3Added wetness in low ground (relief near 0).
max0 to 11Upper 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.

KeyValuesDefaultMeaning
namestring""Required: letters, digits and _, at most 32. Used in layout.json and by constraints.
id-1 to 255-1The game's material row id, written in material_id; -1 is the list index.
colour0 to 255 sRGB[]For previews only; [] takes the fixed palette's colour for its place in the list.
weight0 to 1001Base weight.
sharpness0.1 to 161Above 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_amount0 to 10Seeded noise added to this material's weight.
noise_scale_m0.25 to 1000 m8Size of that noise.

[material_map]

How materials are written.

KeyValuesDefaultMeaning
encodingweights, 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_mapbooltrueWrites <name>_material_id.png: the id of the material with the largest weight, 8-bit, never filtered.
layers_per_texel2 to 44weights: at most this many materials keep weight at a texel.

[export]

Engines and file forms.

KeyValuesDefaultMeaning
targetsgodot, 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_formatsr16, png16, exr32["r16","png16"]Files for the sim height. exr32 is one 32-bit float channel in metres.
name_stylekeep, lower_snake"lower_snake"File stems.

[budget]

Limits; 0 sets none. A missed limit is BUDGET_EXCEEDED, exit 5, with every file written.

KeyValuesDefaultMeaning
max_texture_mbnumberVideo memory of one tile's draw maps with their mip chains (geofx.md 10).
max_samples_per_pixel0 to 640Texture reads a pixel the generated glue makes on its default path.
max_bytesintegerLargest output folder a target.
fail_onFLAT_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.

KeyValuesDefaultMeaning
size_px256 to 4096 px1024Edge of each panel of the contact sheet.
sun_deg0 to 360 deg[45,315]Light of the shaded relief and the perspective views: elevation 5 to 90, azimuth 0 to 360.
thumbnail_px64 to 1024 px256Edge 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.