1. What the editor is
Polygon County is a desktop Python/Tkinter editor for building broad, game-scale terrain rather than sculpting individual centimetres. New projects default to a 6,000 m × 6,000 m world sampled on a 121 × 121 elevation-point grid (120 × 120 square cells at 50 m spacing). The New Blank Project dialog can instead author other map widths, depths, and grid spacings, provided each dimension is an exact multiple of the spacing. The map-size button beneath Width and Depth switches those two displayed values between metres and kilometres while preserving the same physical dimensions; grid spacing remains in metres. A terrain is limited to 16,777,216 elevation points.
The default elevation references are:
- Minimum / seabed: −20 m
- Sea level: 0 m
- Lowland reference: 10 m
- Maximum: 3,000 m
These four values are editable during project creation and become authoritative for that project. They must remain ordered from seabed through maximum. The maximum is an absolute world elevation; the usable relief span is maximum minus minimum.
The final terrain is assembled from two cooperating sources:
- Starting surface and landmass foundation. A project begins at either the world minimum (Sea) or the lowland reference (Land), and all visible landmasses combine into one lowermost foundation above it.
- Ordered feature stack. Persisted VistaWASM generation layers, hills, ridges, valleys, gradients, benches, and named Manual Sculpt offset layers are applied from bottom to top. They remain individually editable.
Vegetation is stored as editable polygon definitions. Individual tree and shrub placements are generated deterministically when previewed or exported; they are not stored as thousands of editable objects.
How the final terrain is assembled
Visible landmasses are combined first as one seamless, order-independent bottom foundation. If islands overlap or touch, their profiles connect without creating stack-order seams. All other visible terrain features are then applied in feature-stack order, from bottom to top. Vegetation generation uses the resulting final terrain for elevation and slope checks.
Visibility changes output; locking does not. A hidden object is omitted from terrain or vegetation generation. A locked object still generates normally but ignores accidental selection and movement on the canvas.
2. Install and start
Requirements
- Python 3.10 or newer
- Tkinter; normally included on Windows and macOS
- NumPy and Pillow, listed in
requirements.txt
Windows PowerShell
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python main.pymacOS or Linux
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python main.pySome Linux distributions provide Tkinter separately as a package such as python3-tk.
3. Interface tour
Tool selector and drawing instructions
Pan-and-zoom terrain canvas
Property tabs
- Menu bar: project, read-only project settings, export, undo/redo, display, and About commands.
- Left tool panel: selects exactly one editing tool at a time.
- Canvas: displays the generated terrain, overlays, feature handles, and optional vegetation markers.
- Right notebook: Features, Brush, View, Vegetation, and Settlement tabs begin at the top of the pane. Each page has its own persistent, high-contrast vertical scrollbar on the right edge, keeping the tab headers fixed while long controls scroll.
- Window title: project filename or name, an asterisk when unsaved changes exist, and the application version.
The vertical dividers between left, centre, and right panes can be dragged to give the canvas or property controls more room.
4. Quick-start workflow
- Open the demonstration project from File → Open Demonstration Project to explore a populated example, or create a blank project and choose a Sea or Land starting surface.
- For a Sea-start project, draw one or more landmasses. Select Draw landmass polygon, click at least three coastline points, and press Enter. A Land-start project already has full-map lowland and needs no landmass.
- Add a generated base when wanted. Choose New VistaWASM Generation, open Properties…, configure its map or landmass target, and use Regenerate and Apply. The accepted field sits immediately above the landmass foundation.
- Add macro features. Place hills and draw ridge, valley, gradient, or settlement-bench features above that base.
- Add local sculpting. Create or select a Manual Sculpt layer, place it at the intended stack position, and use Raise/Lower, Flatten to Height, or Smooth. Selecting a nonempty sculpt outlines its affected extent.
- Add vegetation regions. Draw forests, tree-scatter regions, and exclusions; adjust generation settings in the Vegetation tab.
- Inspect alternate views. Use elevation colour, greyscale, or shaded relief with optional contours and coastlines.
- Save the editable project as a
.cfe.jsonfile, then export the heightmap and vegetation for downstream use.
6. Left tool-panel reference
Selecting a tool changes what the left mouse button does. It also switches the right panel to the most relevant tab. Changing tools cancels any unfinished stroke, drag, spline, or polygon.
| Tool | Use | Result |
|---|---|---|
| Select / move / inspect | Click or drag visible, unlocked objects. Drag a numbered handle to edit one point, or drag the highlighted interior/corridor to move the complete object. | Selects terrain features and vegetation polygons and opens their relevant property tab. Pointer inspection in the status bar works with every tool. |
| Raise / lower brush | Left-drag on terrain after choosing Raise or Lower, radius, strength, and falloff in the Brush tab. | Adds signed, unclipped offsets to the active Manual Sculpt layer. The regenerated final terrain alone is clamped to project limits. |
| Flatten to height brush | Set an absolute target elevation, radius, strength, and falloff, then left-drag on terrain. | Pulls the surface at the active layer's stack position toward the target. At strength 1 with hard falloff, covered samples reach the exact height. Lower visible features contribute; upper features remain unchanged and are excluded from the target calculation. |
| Smooth brush | Left-drag after choosing radius, strength, iterations, and falloff in the Brush tab. | Smooths the surface at the active layer's exact stack position. Lower visible features contribute to the input; upper features are excluded, and only the active sculpt's offsets change. |
| Draw landmass polygon | Click at least three coastline vertices, then press Enter or double-click. | Creates a seabed-to-shore-to-inland foundation. Multiple landmasses combine seamlessly beneath all other terrain features. |
| Place hill / massif | Move the pointer to preview the footprint; click once to place it. | Creates an editable elliptical hill with parameters taken from the Features tab. |
| Draw ridge spline | Click at least two control points and finish the line. | Adds a broad, smoothed, tapered ridge corridor to the existing terrain. |
| Draw valley spline | Click at least two control points and finish the line. | Lowers terrain above a specified floor elevation; it does not raise terrain already below the floor. |
| Draw gradient polygon | Click at least three vertices and finish the polygon. | Adds an elevation adjustment that changes from a low value to a high value along a chosen world-space direction. |
| Draw settlement bench | Click at least three vertices and finish the polygon. | Partially or fully pulls terrain toward a target elevation, with an optional outward blend for smooth access slopes. |
| Draw forest region | Draw a polygon around a dense forest area. | Creates deterministic trees and optional shrub understory subject to spacing, height, slope, density, and species settings. |
| Draw tree-scatter region | Draw a polygon around sparse countryside vegetation. | Creates isolated trees and compact clusters using minimum/maximum spacing and clustering controls. |
| Draw vegetation exclusion | Draw a polygon where generated vegetation must not appear. | Filters placements from all visible forest and scatter regions. Visible exclusions affect preview and export. |
7. Canvas controls and selection rules
Mouse controls
| Input | Effect |
|---|---|
| Move pointer | Shows world X, world Z, triangle-interpolated terrain elevation, and the active visual-grid interval in the bottom status bar. It reports Grid Off when disabled. Outside the terrain it reports “Outside terrain.” |
| Left click | Performs the selected tool’s action: select/start moving, apply the first brush dab, place a hill, or add a drawing point. |
| Left drag | Continues a brush stroke, moves a selected whole object, or drags a selected numbered control point/vertex. |
| Double left click | While drawing a spline or polygon, adds the final point and completes the object. |
| Mouse wheel | Zooms in or out around the pointer, keeping the world point under the cursor stationary. |
| Middle-button drag | Pans the terrain without changing it. |
| Right-button drag | Also pans the terrain. |
Keys used while drawing
| Key | Effect |
|---|---|
| Enter | Finishes the active spline or polygon. Splines need at least two distinct points; polygons need at least three. |
| Backspace | Removes the most recently added drawing point. Removing the last point ends the empty drawing. |
| Escape | Cancels the active drawing and removes its temporary points. |
| Home | Fits the complete terrain to the canvas. |
Clicking the canvas gives it keyboard focus. Polygon edges close automatically between the last and first vertices; you do not need to click the first point again.
Selecting and moving objects
- Select an object by clicking its visible shape with Select / move / inspect, or select it in the relevant right-panel list.
- The selected object is drawn with a highlighted outline and label. Splines and polygons show numbered handles.
- Drag a numbered handle to move only that control point or vertex.
- Drag a hill, spline corridor, or polygon interior between handles to move the whole object. Movement is constrained to the current project world.
- If the selected highlighted polygon overlaps another object, clicking inside the selected polygon keeps it selected and starts moving it instead of selecting the overlay.
- When nothing is already selected at an overlap, visible vegetation polygons are tested before terrain features. Within a category, the front/top object wins.
- Locked objects are ignored by canvas hit testing and cannot be moved on the canvas. They can still be selected, edited, hidden, reordered, duplicated, deleted, or unlocked from the lists.
- Hidden objects do not affect generated output and are skipped by ordinary canvas selection. They remain available in the sidebar.
8. Project Settings window
Choose File → Project Settings… to inspect the former right-panel project summary. The reusable window is read-only and non-modal, leaving the right-panel tabs at the top of their pane.
| Label | Meaning |
|---|---|
| Name | The name stored inside the project. The window title uses the filename after a save. |
| World | World width and depth in metres; normally 6,000 × 6,000 m. |
| Grid | Cell count and cell spacing; normally 120 × 120 cells at 50 m. |
| Starting surface | Whether the project began as a flat Sea or Land surface. |
| Elevation refs | Minimum / sea level / lowland reference / maximum elevation, in that order. |
| Features | Number of procedural and Manual Sculpt terrain features in the feature stack. |
| Settlement | Current settlement-region, road, and building counts. |
9. Features tab
Feature stack and common controls
The list is shown topmost first. For normal features, higher entries are applied later and therefore can modify the result of lower entries. Landmasses always form the bottom foundation and are combined independently of their order among themselves.
Each row begins with [on] or [off]. Locked rows also show [locked], followed by the feature type and name.
| Control | What it does |
|---|---|
| Feature list | Selects a terrain feature and loads its fields. The scrollbar reaches features beyond the six visible rows. |
| New Sculpt Layer | Creates a blank, selected Manual Sculpt layer. It is inserted above the selected ordinary feature, at the bottom of the ordinary stack when a landmass is selected, or topmost when nothing is selected. |
| New VistaWASM Generation | Creates a blank, undoable generation layer directly above all landmass-foundation inputs, selects it, and opens its scrollable Properties window. It contributes nothing until generation completes successfully. |
| Show/hide | Toggles whether the selected feature contributes to the generated final terrain. Hidden features remain saved and editable. |
| Lock/unlock | Toggles canvas protection. Locked features cannot be selected or moved accidentally on the canvas but still affect terrain. |
| Up | Moves the selected feature one step toward the top/later part of the stack. Landmasses cannot move above non-landmass features. |
| Down | Moves the selected feature one step toward the bottom/earlier part of the stack. Non-landmass features cannot move below the landmass foundation. |
| Duplicate | Creates and selects an unlocked copy with a new ID and “copy” name. Geometric features shift 100 m in +X/+Z and increment their seed; Manual Sculpt and Vista layers instead copy their exact stored grids. |
| Delete | Removes the selected feature. Undo restores it. |
| Clear Layer | For a selected visible, unlocked Manual Sculpt layer, clears its affected offset rectangle as one compact undoable command. An already-clear layer creates no history entry. |
| Name | Changes the selected feature’s human-readable name. Blank input keeps the current name. |
| Apply feature properties | Validates and commits the Name and type-specific fields as one undoable edit. |
| Enter in a numeric field | Performs the same action as Apply feature properties. |
VistaWASM generation properties
A Vista row is a versioned, deterministic Python/NumPy port of VistaWASM's CPU terrain generator. The selected row shows a Properties… button; it opens a reusable non-modal window with its own vertical scrollbar. The controls remain a local draft until Regenerate and Apply finishes, so closing the window, cancelling, or encountering an error leaves the previously accepted terrain untouched.
| Control group | Meaning |
|---|---|
| Target and composition | Choose the entire map or one existing landmass. Additive relief adds the generated field relative to Base elevation; Generated elevation blends toward the field. Blend strength scales either operation. Landmass edge feather fades the layer inward and preserves the authored coastline and surrounding seabed. |
| Generation frame | Persists the world-space X/Z origin and rectangular width/depth used by large-scale shaping. Refit frame to target explicitly replaces it with the map or landmass bounds and sets a corresponding starting noise scale; ordinary target or geometry changes do not silently refit it. |
| Seed and elevation | Seed is deterministic. Base elevation supplies the generated centre level; Vertical scale applies Vista's approximate ±900 m relief convention. |
| Fractal noise | Noise family, 1–16 octaves, gain, lacunarity, domain warp, and Base noise scale. Noise scale is expressed in world metres, so changing map dimensions does not implicitly change feature wavelength. |
| Large-scale shaping | Optional 0–1 Island, Terrace, Basin, Canyon, and Crater strengths, independently composable with the selected noise family. |
| Erosion | Optional hydraulic and thermal passes with rain, sediment capacity, talus angle, and an explicit quality/pass cap. Evaporation is shown as reserved because VistaWASM 0.1 stores it but does not use it. |
| Output | Reports point dimensions, 50/250/500 m or other project spacing, raw field memory, generator version, progress, cancellation, and failure. A successful result becomes one undoable feature replacement and is saved with the project. |
A selected Vista feature draws only its persisted generation-frame rectangle and, for a landmass target, that target's outline. It has no draggable map footprint: targeting, framing, and regeneration are deliberate numeric operations in Properties.
Manual Sculpt layer summary
A Manual Sculpt row is a named full-grid elevation-offset layer in the ordinary terrain stack. Its read-only summary reports point-grid dimensions, nonzero sample count, minimum and maximum offsets, exclusive grid bounds, and world-space bounds. Selecting a nonempty layer draws a dashed rectangle around that affected extent on the canvas. Name, show/hide, lock/unlock, ordering, duplicate, and delete use the common controls above and participate in undo/redo.
Hill / massif fields
| Field | Meaning | Accepted range |
|---|---|---|
| Centre X (m) | Horizontal/east position of the ellipse centre. | 0–6,000 |
| Centre Z (m) | Vertical-on-map/south position of the ellipse centre. | 0–6,000 |
| Summit radius X (m) | Inner high-ground/summit extent along the hill's local X axis before rotation. | 1–project width |
| Summit radius Z (m) | Inner high-ground/summit extent along the hill's local Z axis before rotation. | 1–project depth |
| Flank run (m) | Additional world-space slope distance beyond the summit ellipse. The hill reaches zero contribution at the outer toe ellipse, whose X/Z radii are the summit radii plus this value. | 1–longest project dimension |
| Rotation (°) | Rotates the elliptical footprint clockwise in editor world axes. | −36,000–36,000 |
| Height (m) | Maximum elevation added by the hill profile. | 0.1–3,000 |
| Summit fullness (0–1) | Fine-tunes how much height is retained toward the edge of the summit ellipse. It does not change flank distance; use Slope profile for flank shape. | 0–1 |
| Asymmetry (0–1) | Controls deterministic, seed-based irregularity around the hill. | 0–1 |
| Slope profile | Maps normalized progress from the summit-side edge of the flank (0) to the outer toe (1). The compact preview updates immediately; expand Advanced profile settings to edit shoulder, toe, steepness, curvature, and terraces. | Smooth / Gentle / Steep / Convex / Concave / Escarpment / Terraced / Custom |
| Summit X (m) | Moves the summit from the centre along the hill’s local X direction. | ±60% of Summit radius X |
| Summit Z (m) | Moves the summit from the centre along the hill’s local Z direction. | ±60% of Summit radius Z |
| Deterministic seed | Changes the reproducible asymmetry pattern without changing the main dimensions. | Signed 64-bit integer |
| Elevation profile | Disabled uses Height; Absolute elevation interpolates raise-only world targets; Relative height interpolates rises above the incoming surface. | Disabled / Absolute elevation / Relative height |
| Start / End | Values at the S and E sides of the directional hill profile. | Absolute: project minimum to maximum Relative: 0 to project elevation span |
| Profile direction (deg) | World-space direction from S to E, independent of footprint Rotation. 0° points east/+X and 90° points south/+Z. | -36,000 to 36,000 |
| Reverse profile | Swaps the Start and End values without moving or rotating the hill footprint. | Action |
When a hill is selected, the solid gold outline is the summit/high-ground ellipse and the dashed orange outline is the outer toe where hill contribution reaches zero. The area between them is the authored flank.
Ridge and valley spline fields
The same panel edits both types. With Elevation profile Disabled, the bold type label identifies whether Height / floor means added ridge height or an absolute valley floor. Profile interpolation follows distance along the smoothed spline, not control-point index.
| Field | Meaning | Accepted range |
|---|---|---|
| Crest / valley width (m) | For a ridge, the full-width high crest corridor around the smoothed centreline. For a valley, the unchanged total influence corridor width. | 1–longest project dimension |
| Ridge side run (m) | Ridge only: additional physical slope distance on each side from the crest edge to zero contribution. It does not change crest width or endpoint taper. The field is disabled for valleys. | 1–longest project dimension |
| Height / floor (m) | For a ridge, elevation added at full influence. For a valley, the absolute target floor; only terrain above that floor is lowered. | Ridge: 0.1–3,000 Valley: project min–max |
| Side profile bias (0–1) | The persisted side_falloff fine adjustment applied after the selected cross-section profile. Higher values retain more influence through the profile; it does not set physical run distance. | 0–1 |
| Endpoint taper (0–1) | Controls how strongly the spline fades at its two ends. 0 keeps full strength; 1 applies the complete taper envelope. | 0–1 |
| Smoothing (0–1) | Rounds the polyline between its stored control points while keeping those points editable. | 0–1 |
| Left / Right slope profile | Chooses independent cross-sections on each side while travelling S→E. A differing pair shows the S/E direction marker even when the longitudinal elevation profile is Disabled. | Eight presets per side |
| Advanced profile settings | Edit one selected side's shoulder, toe, steepness, curvature, terrace count, and terrace strength. Valid edits change that side to Custom. | Terraces: 0–4; other limits are enforced by the editor |
| Seed | Stored deterministic seed for the feature. | Signed 64-bit integer |
| Elevation profile | Disabled uses Height/Floor. Absolute elevation uses raise-only ridge targets or literal lower-only valley world targets. Relative height uses ridge rise or valley depth against the incoming stack surface. Valley-only Terrain-following grade derives a smoothed, coherent downhill floor from the incoming centreline, then cuts toward it. | Ridge: Disabled / Absolute elevation / Relative height Valley: those modes plus Terrain-following grade |
| Start / End | Elevation, rise, or depth at the spline's authored S/E direction. Terrain-following values are non-negative depths; the geographically higher incoming end determines the grade direction without moving points or reassigning these values. | Absolute: project minimum to maximum Relative or terrain-following: 0 to project elevation span |
| Maximum carve depth (m) | Shown only for a terrain-following valley. Limits how far the guided valley may cut below the terrain entering the feature, preventing a mountain valley from accidentally excavating hundreds of metres because of its longitudinal grade. | Greater than 0, up to 3,020 m; default 100 m |
| Reverse profile | Swaps Start and End values without reordering or moving control points. | Action |
When a ridge is selected, the inner gold band is its crest corridor and the wider orange band reaches the outer toe. The spline centreline and numbered control points remain visible above both. Unselected ridges keep the normal uncluttered view.
Landmass / coastline polygon fields
| Field | Meaning | Accepted range |
|---|---|---|
| Seabed (m) | Elevation reached away from the coastline on the water side. | Project min–max |
| Sea level (m) | Exact elevation assigned along the polygon edge. | At least Seabed, up to project max |
| Inland (m) | Elevation reached inside the polygon after the onshore transition. | At least Sea level, up to project max |
| Offshore blend (m) | Distance outside the coastline over which terrain changes from sea level to seabed. 0 makes the transition immediate. | 0–6,000 |
| Onshore blend (m) | Distance inside the coastline over which terrain changes from sea level to inland elevation. 0 makes the transition immediate. | 0–6,000 |
| Coast profile | Current Smoothstep preserves the legacy broad profile. Linear-Start Ease departs sea level with a non-zero slope. Linear Fidelity Band uses a grid-relative linear signed-distance band and a smooth outer transition to improve the reconstructed 0 m contour. | Current Smoothstep / Linear-Start Ease / Linear Fidelity Band |
| Seed | Stored deterministic seed. | Signed 64-bit integer |
Directional gradient polygon fields
| Field | Meaning | Accepted range |
|---|---|---|
| Low adjustment (m) | Elevation added at the low end of the gradient. Negative values lower terrain. | −3,000–3,000 |
| High adjustment (m) | Elevation added at the high end of the gradient. | −3,000–3,000 |
| Direction (°) | Direction from low toward high: 0° east/right (+X), 90° south/down (+Z), 180° west, 270° north. | −36,000–36,000 |
| Ramp position (0–1) | Locates the ramp centre between the polygon vertices' minimum and maximum projection along Direction. 0 is the low projected end, 0.5 is the middle, and 1 is the high projected end. | 0–1 |
| Ramp run (m) | Physical low-to-high transition width centred at Ramp position. Low/high plateaus occupy the remaining polygon; changing this value never resizes the polygon. | 1–longest project dimension |
| Ramp profile | Maps normalized ramp progress from low/start (0) to high/end (1) using the shared terrain profile presets and Custom parameters. | Smooth / Gentle / Steep / Convex / Concave / Escarpment / Terraced / Custom |
| Edge blend (m) | Distance inside the boundary over which the adjustment fades in. 0 applies full adjustment to the edge. | 0–6,000 |
| Deterministic seed | Stored seed for reproducible project data. | Signed 64-bit integer |
When a Gradient is selected, dashed parallel lines mark the ramp start and end while a cyan LOW-to-HIGH arrow shows its direction. The polygon outline remains the independent region mask.
Settlement bench polygon fields
| Field | Meaning | Accepted range |
|---|---|---|
| Target elevation (m) | Elevation toward which existing terrain is pulled inside the polygon. | Project min–max |
| Flatten strength (0–1) | 0 leaves terrain unchanged; 1 makes the interior fully flat at the target; intermediate values partially flatten. | 0–1 |
| Outer blend (m) | Distance outside the polygon over which bench influence fades to zero. | 0–6,000 |
| Seed | Stored deterministic seed. | Signed 64-bit integer |
10. Brush tab
The Brush tab contains settings for all three brush tools. Values are read as the stroke begins; there is no separate Apply button. Brush dabs are applied immediately, while the terrain image preview is coalesced to at most 2.5 updates per second. Contours and sea-level coastlines remain static during the stroke and rebuild exactly once when the mouse button is released.
| Control | What it does | Accepted range |
|---|---|---|
| Active sculpt layer | Names the visible, unlocked Manual Sculpt layer targeted by Raise/Lower, Flatten, or Smooth. Selecting another procedural feature retains the last valid active layer. If no target exists, starting a brush creates one; an explicitly selected hidden or locked sculpt blocks the stroke instead of redirecting it. | Status display |
| Radius (m) | World-space radius of the circular brush. The dashed white cursor shows its footprint. | 1–longest project dimension |
| Soft falloff | On: influence fades smoothly from a flatter centre to zero at the edge. Off: all covered grid points receive equal influence. | On / off |
| Raise | Makes the raise/lower brush add the Strength value at full influence. | Mode choice |
| Lower | Makes the raise/lower brush subtract the Strength value at full influence. | Mode choice |
| Raise/lower Strength (m) | Height change per brush dab at full influence. A continuous drag places evenly spaced dabs. | 0.1–100 |
| Flatten Target elevation (m) | Absolute project elevation toward which the active-layer surface is pulled. | Project min–max |
| Flatten Strength (0–1) | Blend fraction toward the target for each dab. 1 reaches the target wherever brush influence is full; repeated weaker dabs converge toward it. | 0.01–1 |
| Smoothing Strength (0–1) | Blend fraction toward the local 3 × 3 mean per iteration. Higher values remove relief faster. | 0.01–1 |
| Iterations | Number of smoothing passes performed for each dab. More iterations produce stronger, broader smoothing and cost more processing. | 1–20 |
11. View tab
| Control | What it does | Accepted range |
|---|---|---|
| Elevation colour | Selects the sea-aware coloured map view. | Display choice |
| Greyscale heightmap | Selects a black-to-white visualization of the authoritative elevation range. | Display choice |
| Shaded relief | Selects light-and-shadow terrain visualization. | Display choice |
| Inland palette | Changes Elevation Colour and Shaded Relief between green Temperate European inland terrain and Sandy Desert. The band from sea level to the project lowland reference remains textured sand in either palette. | Temperate European / Sandy Desert |
| Terrain grid | A synchronized dropdown containing Disabled, Default, Bold 1, Bold 2, and Bold 3. It controls the same visibility and style setting as View → Show Terrain Grid. Exactly one visual interval is shown at a time: 50, 100, 250, 500 m, or 1 km depending on zoom. This does not change terrain sampling. | Disabled / four styles |
| Show contour overlay | Same toggle as View → Show Contours. | On / off |
| Contour interval (m) | Vertical height difference between adjacent contour levels. | 1–1,000 |
| Direction (deg) | Compass-like direction from which shaded-relief light arrives. Try 315° for light from the upper left. | 0–360 |
| Elevation (deg) | Light height above the horizon. Low values cast stronger-looking relief; 90° is overhead. | 0–90 |
| Vertical exaggeration | Multiplies perceived terrain steepness for hillshade only. It does not alter saved or exported elevations. | 0.01–100 |
| Apply visualization | Commits contour interval and lighting values, rebuilds the view, and marks the project dirty if persisted visualization settings changed. | Button |
| Fit terrain to window | Same command as View → Fit Terrain to Window and Home. | Button |
Display mode, inland palette, contour visibility, coastline visibility, and tree-preview visibility reset to their defaults when a project is opened. Grid visibility, contour interval, and shaded-relief settings are saved in the project. Palette and sand texture are display-only and do not change saved terrain or exports.
12. Vegetation tab
Object list and actions
The list includes forests, tree-scatter regions, and exclusions. Rows show [on]/[off], optional [locked], object type, name, and the selected region's most recently calculated tree count state.
| Control | What it does |
|---|---|
| Vegetation list | Selects a region or exclusion and highlights its polygon. Forest/scatter rows report that their tree count is not calculated, calculating, stale, unavailable, or show the exact count. The scrollbar reaches objects beyond the five visible rows. |
| Show/hide | For forests/scatters, toggles placement generation. For exclusions, toggles whether the exclusion filters placements. |
| Lock/unlock | Protects the selected polygon from canvas selection and movement without changing generation or visibility. |
| Duplicate | Creates a copy shifted 100 m in +X/+Z where possible, selects it, gives it a new ID and “copy” name, starts it unlocked, and increments generation seed by one where applicable. |
| Delete | Removes the selected object. Undo restores it. |
| Generate/show placement preview | Generates and shows markers when switched on, and clears them when switched off. Off by default. The preview is deliberately not live: terrain, region, seed, undo, and redo changes do not regenerate it. Switch it off and on again when you want a fresh preview. Region polygon outlines remain visible independently. |
| Reroll seed | Assigns a new random seed to the selected forest or scatter region. This is undoable and does not regenerate a visible preview; switch the preview off and on to see the new result. Exclusions have no seed. |
| Name | Changes the selected object’s name. An exclusion exposes Name but no generation fields. |
| Apply vegetation properties | Validates and commits all visible fields for the selected object as one undoable edit, then synchronously calculates the selected forest/scatter's exact tree count. The count uses current terrain constraints and visible exclusions but does not include understory shrubs. Terrain, polygon/settings, or exclusion changes mark an earlier count stale until Apply is used again. |
| Enter in a field | Performs the same action as Apply vegetation properties. |
Forest-specific fields
| Field | Meaning | Accepted range |
|---|---|---|
| Distribution | Continuous / Even fills the woodland without forced clearings. Natural Patchy adds broad local-density differences and optional clearings. | Two modes |
| Average spacing (m) | Target mean distance between generated forest-tree samples. Smaller values create denser forest and substantially more placements. | 0.1–3,000 |
| Spacing variation | Allows local spacing from average × (1 − variation) to average × (1 + variation). | 0–0.9 |
| Edge falloff (m) | Reduces tree acceptance near the inside of the polygon boundary. 0 disables the edge-density fade. | 0–6,000 |
| Density variation | Strength of smooth, seed-based broad density patches. 0 is more uniform; 1 gives the strongest variation. | 0–1 |
| Shrub density | Probability/intensity of understory shrubs generated around accepted forest trees. | 0–1 |
| Shrub radius (m) | World-space radius around a canopy tree in which its understory shrubs may be placed. | 0.1–1,000 |
| Patchiness | Strength of Natural Patchy density contrast and local-spacing changes. These controls appear only in Natural Patchy mode. | 0–1 |
| Patch scale (m) | Approximate scale of the broad woodland stands, sparse areas, and clearings. Larger values create larger structures rather than small speckles. | 25–6,000 |
| Clearing tendency | Raises the low-density cutoff in Natural Patchy mode, making genuine empty areas more likely. | 0–1 |
Tree-scatter-specific fields
| Field | Meaning | Accepted range |
|---|---|---|
| Grouping | Compact copses separates group spacing from spacing inside each copse. Legacy diffuse groups is retained for pre-v6 projects and exact compatibility. | Two modes |
| Group spacing min (m) | Minimum end of the broad spacing distribution between copse or isolated-tree anchors. | 10–3,000 |
| Group spacing max (m) | Upper end of the broad anchor spacing distribution. It cannot be lower than Group spacing min or greater than 19 times that minimum. Apply reports both valid remedies when the range is too wide. | Minimum–min × 19, capped at 6,000 |
| Clustering (0–1) | Biases non-isolated groups toward more members and tighter placement inside their radius. | 0–1 |
| Isolated proportion | Probability that an accepted anchor remains a single tree rather than spawning a group. | 0–1 |
| Copse radius (m) | Maximum distance of a compact-copse member from its group anchor. | 1–3,000 |
| Tree spacing in copse (m) | Minimum spacing between trees inside and across compact copses; it may be much smaller than Group spacing. | 0.1–Copse radius |
| Trees per copse min/max | Member-count bounds for a non-isolated compact copse, including its anchor tree. | Integers, minimum 2 |
Common forest and scatter generation fields
| Field | Meaning | Accepted range |
|---|---|---|
| Minimum elevation (m) | Lowest final-terrain elevation at which a placement is allowed. | −20–3,000 |
| Maximum elevation (m) | Highest allowed final-terrain elevation. It cannot be lower than Minimum elevation. | Minimum–3,000 |
| Maximum slope (deg) | Steepest final-terrain slope that accepts vegetation. | 0–90 |
| Seed | Controls all repeatable placement positions, species choices, rotation, and scale for that region. | Signed 64-bit integer |
| Species weights | Comma-separated name=weight pairs, for example oak=0.55, pine=0.3, birch=0.15. Weights are normalized; they do not need to add to one. | Non-negative finite weights; at least one positive |
All placement constraints and exported Y positions use the regenerated final terrain, so changing landmass or terrain-feature properties can change vegetation eligibility even when a region seed stays the same. During a live terrain drag, the map refreshes immediately while potentially expensive vegetation placement regeneration is deferred until release.
Vegetation exclusions
An exclusion has a name, polygon geometry, visibility, and lock state, but no generation fields or seed. When visible, it removes any forest tree, shrub, or scattered tree whose X/Z point lies inside the polygon. Hide the exclusion to disable it without deleting it.
12A. Settlement tab and tools
Settlement planning is manual-first and does not alter terrain. Its object list and Delete, Duplicate, and Clear controls remain visible above three workflow tabs: Details contains properties for the selected region, road, or house; Survey contains buildability controls and survey results; and Houses contains new-house defaults, frontage assistance, and candidate generation. Start with Settlement Survey, click at least three polygon vertices, and press Enter. The Survey tab reports area, elevation range, relief, slope statistics, and cumulative slope bands from the current composed terrain.
| Control or tool | What it does |
|---|---|
| Show buildability overlay | Shows cached slope categories only inside the current survey or selected settlement region. Ground at or below sea level is marked as water/non-buildable. |
| Convert survey to region | Creates a persistent, editable settlement-intent polygon from the current analytical survey. |
| Draw settlement region | Creates a persistent planning polygon directly. Select it to move the polygon or individual numbered vertices. |
| Draw road spine | Creates an editable planning polyline. Selection reports total length and mean/maximum longitudinal grade, including a ROAD STEEP warning. |
| Place House | Plants one generic footprint at the clicked terrain position. Selection reports sampled ground elevation and warnings for steep terrain, sea-level sites, and building overlap. |
| House frontage assist | When the click is within the configured road search distance, faces the house toward the nearest road segment and applies the requested setback. Rotation remains manually editable. |
| Preview / Accept / Cancel | Multi-select a settlement region and one or more roads, choose spacing and seed, then preview deterministic candidates. Accept commits all candidates as one undo command; Cancel leaves the project unchanged. |
| Create vegetation exclusion | Creates or replaces an explicit exclusion linked to the selected building, road, or region. Road exclusions follow the complete polyline as a round-capped corridor: authored road width plus 5 m clearance on each side. Moving, reshaping, or changing the width of a linked road updates its corridor; vegetation placements regenerate only when explicitly requested. |
A selected Gradient shows dashed ramp-start and ramp-end lines plus a LOW-to-HIGH direction arrow. Ramp run controls the distance between the lines; Edge blend remains the separate polygon-mask feather.
The Details tab shows only fields relevant to the selected object: common name/visibility/lock fields for every object, width and surface for roads, and semantic type, optional runtime asset ID, rotation, separate footprint width/depth, and the read-only frontage-road ID for houses. New-house defaults in the Houses tab are independent of edits to an existing selected house. Frontage assistance records the selected road ID; the final rotation remains authoritative. Selecting a region displays its area, building count, road length, elevation range, mean slope, buildable percentage, and count of warned buildings. Region-plus-road multi-selection remains active when switching to the Houses tab for candidate generation.
13. Project files and exports
Editable project: .cfe.json
The schema-v8 project file contains the Sea/Land starting-surface choice, world settings, every procedural and Manual Sculpt terrain feature, explicit hill flank runs, ridge side runs, Gradient ramp position/run/profile, versioned Vista settings and accepted generated fields, hill/ridge/valley longitudinal and cross-section profiles, valley maximum-carve limits, all vegetation regions and exclusions, settlement regions, roads, buildings, visibility and lock states, seeds, and persisted visualization settings. Schema-v3 projects load with disabled longitudinal profiles and Smooth cross-sections; schema-v4 projects load with Smooth cross-sections. A hill record from any supported schema that lacks flank_run_m is deterministically converted from its old radius/profile/softness curve. A Ridge without side_run_m keeps two percent of its old total width as a compatibility crest and derives the run from the remaining half-width, preserving its outer footprint. A Gradient without ramp fields receives a centred full-projection Gentle/linear ramp, preserving its old directional interpolation and Edge blend. Current saves write all migrated values explicitly. Schema-v3/v4/v5 vegetation loads with its legacy sampling, diffuse grouping, and proportional-understory defaults so it preserves former placement behavior. Schema-v6 valleys gain a 100 m maximum-carve default without changing their existing mode or terrain result. Manual Sculpt offsets and Vista generated heights are compressed inside their feature records; the starting elevation grid and other derived final terrain are reconstructed rather than saved. Saves are validated and written atomically through a temporary file.
- If a Save As name does not end in
.cfe.json, the editor appends it. - If the entered name ends in plain
.json, that suffix is replaced by.cfe.json. - The editor opens schema-v3, schema-v4, schema-v5, schema-v6, schema-v7, and schema-v8
.cfe.jsonprojects and saves schema v8. - An asterisk in the window title means the current project has unsaved changes.
Complete export bundle
Export → Export Bundle to Folder… writes the conventional files terrain_heightmap.png, terrain_heightmap.json, terrain_heights.csv, terrain_heights.npy, generated_vegetation.json, and county_features.json. The command regenerates the authoritative terrain once, performs the complete vegetation generation once, and stages every file in the selected folder before publishing the set. If generation fails, existing bundle files are left untouched. The editor remains occupied while the synchronous export runs; watch the status bar, and wait for the Export bundle complete popup before using the files.
16-bit PNG and metadata
The PNG contains one unsigned 16-bit sample per terrain point: 121 × 121 at the default 6 km / 50 m configuration, or the dimensions derived from the project’s selected map and grid spacing. Value 0 represents the project minimum and value 65,535 represents its maximum; out-of-range output is clipped. The adjacent metadata file records the exact world size, spacing, cell/point dimensions, elevation references, their uint16 codes, row/column orientation, and cell-diagonal convention.
big.png also writes big.json. A project named big.cfe.json is a different filename and is not overwritten. However, any unrelated existing big.json in that directory is the metadata target, so choose the PNG basename accordingly.
CSV and NPY
Both contain the regenerated final grid from the landmass foundation and visible ordered feature stack. CSV is human-readable text in metres. NPY preserves the exact float32 array without pickled objects.
Vegetation JSON
Vegetation export always performs a fresh complete generation. It is independent of the canvas marker level-of-detail and whether the preview checkbox is on. Hidden forest/scatter regions generate nothing; visible exclusions remove placements. The JSON declares the coordinate system and includes a total object count. Because dense vegetation may take a while, the standalone command displays a Vegetation export complete popup after the file has been written successfully.
Runtime county features JSON
county_features.json is the clean runtime-facing schema-v3 export. It regenerates the final terrain before export. Settlement-region polygons remain 2D. Roads retain their exact ordered authored X/Z control points, width, and surface and declare elevation_mode: "follow_terrain"; the consumer conforms its own path geometry to the paired final terrain. Buildings retain their authored X/Z position and gain one centre-sampled terrain_y_m. Hidden county objects remain present with visible: false. It does not contain road Y samples or ribbon geometry, the terrain feature stack, Manual Sculpt arrays, generation settings, editor locks, undo state, or UI state.
Roads contain no exported Y samples, cross-sections, surface offset, or ribbon mesh. The paired final heightmap owns elevation everywhere along each follow_terrain path, including between sparse controls, and the consumer chooses its own internal tessellation and rendering geometry. Building Y remains one unoffset final-terrain sample at the authored centre and does not alter the editable settlement plan.
The coordinate metadata states the existing editor convention: metres from the northwest/top-left origin, +X east/right, +Z south/down, and +Y up. Building rotation 0° faces −Z/north and positive rotation turns clockwise when viewed from +Y. That rotation is final; the runtime does not recompute frontage. County Features JSON has its own export_batch_id UUID. The bundle command guarantees that its files were produced together from one terrain regeneration, but it does not add a cross-file manifest or batch ID to the other formats.
Unsaved-changes prompt
New, Open, Open Demonstration Project, Exit, and closing the window protect dirty work:
- Yes: save, then continue if saving succeeds.
- No: discard the current unsaved changes and continue.
- Cancel: return to the current project without continuing.
14. Keyboard and mouse shortcut reference
| Shortcut | Action |
|---|---|
| Ctrl+N | New blank project, then choose Sea or Land start |
| Ctrl+O | Open project |
| Ctrl+S | Save |
| Ctrl+Shift+S | Save As |
| Ctrl+Z | Undo |
| Ctrl+Y | Redo |
| Home | Fit terrain to window |
| Enter | Finish active canvas spline/polygon; in property entries, apply that panel’s properties |
| Backspace | Remove last active drawing point |
| Escape | Cancel active canvas drawing |
| Mouse wheel | Zoom around pointer |
| Middle drag | Pan |
| Right drag | Pan |
| Left drag | Use brush or move selected object/handle, depending on tool |
15. Numeric input and validation behavior
Most numeric entries accept direct typing. Apply them with the panel’s Apply button or, for feature and vegetation entry fields, Enter.
- Most values outside an accepted range are clamped to the nearest limit and the field is rewritten with the effective value. Forest properties are stricter: Apply leaves the forest unchanged and reports the specific invalid field in the status bar.
- Invalid, blank, non-finite, or non-numeric input falls back to the current value or the control’s documented default.
- Integer seed fields are limited to signed 64-bit values.
- Relational fields are enforced: maximum elevation cannot be less than minimum; scatter group-spacing maximum must be between its minimum and 19 times that minimum; copse tree spacing cannot exceed its radius; landmass elevations must remain Seabed ≤ Sea level ≤ Inland.
- Forest Apply validates spacing, variation, falloff, density and patch controls, shrub settings, elevations, slope, signed 64-bit seed, and species-weight syntax before updating the project.
- Polygons require at least three distinct points and non-zero area. Splines require at least two distinct points.
- All feature and vegetation points remain inside the world. Whole-object translation stops at the boundary rather than letting part of an object move outside.
- If a complete object fails validation, the status bar reports the reason and the update is not committed.
16. Recommended workflows
Build an island chain
- Draw each island as a separate landmass polygon.
- Use the same sea level and compatible inland/seabed references for consistent shores.
- Overlap polygons where land should connect; the bottom foundation merges them seamlessly.
- Turn on Show Sea-Level Coastlines to inspect the generated project sea-level contour.
- Lock finished landmasses to avoid disturbing them while adding hills and vegetation.
Create a mountain-and-valley system
- Draw broad ridge splines first, with moderate smoothing and endpoint taper.
- Add hills/massifs for important peaks.
- Draw target-floor valleys over the ridge system and move them above ridges in the feature stack when they must cut through the raised terrain.
- Use shaded relief and contours to inspect drainage-scale shapes.
- Add a Manual Sculpt layer at the intended stack position and use Raise/Lower, stack-aware Flatten, or stack-aware Smooth for local corrections.
Author ascending ridges, descending valleys, and directional hills
- Select a ridge, choose Relative height, enter a smaller Start rise and larger End rise, and Apply. Follow the cyan S/E arrow to confirm the ascent direction.
- Select a valley, keep its geometry fixed, enter a smaller Start depth and larger End depth for a progressively deeper channel, and Apply. Use Reverse profile when the fall runs the wrong way.
- Select a hill, choose Absolute elevation or Relative height, set different Start/End values, and set Profile direction. Confirm the arrow rotates independently of the elliptical footprint.
- Set Endpoint taper to 1 on a spline and inspect both ends: their influence still reaches zero. Reduce taper if the authored endpoint values must affect terrain closer to the spline endpoints.
- Move a relative profile above and below a Bench, Gradient, or Manual Sculpt layer to inspect its stack-aware result. Landmasses remain the order-independent foundation.
Build an ordered Manual Sculpt stack
- Add a procedural feature, select it, then choose New Sculpt Layer. The new sculpt is inserted immediately above the selected feature.
- Rename the sculpt for its purpose, such as
Manual Sculpt: Hill Asymmetry, and make local Raise, Lower, Flatten, or Smooth corrections. - Add the next procedural feature and another sculpt above it. Flatten and Smooth always use only the landmass foundation and visible features below the active sculpt.
- Use Up and Down to test order. Additive features may commute, while moving a sculpt across a Bench or Valley can intentionally change the result.
- Use visibility to compare layers, lock finished layers, and use Clear Layer when you want to preserve the layer identity and stack position while removing its offsets.
Prepare a settlement area
- Draw a settlement bench around the buildable area.
- Set Target elevation and a partial Flatten strength if some natural relief should remain.
- Increase Outer blend for gentler access slopes.
- Draw a vegetation exclusion over roads/buildings and leave it visible.
Design dense forest efficiently
- Draw the forest boundary and keep placement preview off while editing very dense regions.
- Choose Continuous / Even when the polygon should remain fully wooded, including deliberately extreme high-count settings.
- Choose Natural Patchy for broad stands and open areas; tune Patchiness, Patch scale, and Clearing tendency rather than forcing gaps into every forest.
- Lower Average spacing for greater density; use Spacing variation and Density variation for a less regular appearance.
- Use Edge falloff for a gradual tree line and Shrub density/radius for local understory.
- Set elevation and slope limits to avoid beaches, water, cliffs, or high peaks.
- Turn preview on only when you need a visual sample. After edits, switch it off and on to refresh it. Export always generates the complete deterministic result.
17. Troubleshooting and useful details
| Symptom | Likely cause and remedy |
|---|---|
| A feature will not select or move on the canvas | It may be locked or hidden. Select it in the Features/Vegetation list, then use Lock/unlock or Show/hide. Ensure the Select / move / inspect tool is active. |
| Clicking an overlap chooses the wrong object | Select the intended polygon in its sidebar list first, then drag within its highlighted interior. The selected highlighted polygon has priority through overlaps. |
| Up or Down refuses to move a feature | The item is already at that end of the stack, or the move would cross the enforced boundary between the landmass foundation and other features. |
| A sculpt brush refuses to begin | The explicitly selected Manual Sculpt layer may be hidden or locked. Show or unlock it, or select another visible, unlocked sculpt. If no sculpt exists and no invalid sculpt is explicitly selected, the editor creates one automatically. |
| Vegetation preview shows fewer markers when zoomed out | This is intentional level-of-detail culling, capped to keep navigation responsive. Zoom in for more local detail or export JSON for the complete set. |
| Vegetation preview does not follow edits | This is intentional: the placement preview is not live. Switch Generate/show placement preview off and on to rebuild it. Generation is deterministic; use Reroll seed first if you want a different arrangement. |
| Reroll does nothing for an exclusion | Exclusions filter placements and have no generation seed. Select a forest or tree-scatter region. |
| No vegetation is generated | Check region visibility, elevation range, maximum slope, polygon area, spacing, and whether a visible exclusion covers the region. Preview must be enabled to retain canvas markers, but export does not require it. |
| Project will not open | Confirm the filename ends in .cfe.json and the document uses schema version 3, 4, 5, 6, 7, or 8. Plain JSON and schema-v1/v2 files are not accepted. |
| A profile endpoint does not reach its entered elevation | Endpoint taper and side/radial falloff still multiply profile influence. A complete spline taper deliberately suppresses the first and last samples; absolute ridge/hill targets also never lower terrain, and absolute valley targets never raise it. |
| A number changes after Apply | The editor clamped it to the allowed range or restored a valid fallback. See the field tables above. |
| A white coastline is visible through a selection outline | This is intentional. The project sea-level contour is raised above selection overlays so it remains readable. Toggle it in the View menu if unwanted. |
Terrain interpolation and exports
Each terrain cell, at the project’s selected spacing, is divided on a northwest-to-southeast diagonal. Pointer elevation queries and metadata use triangles NW–NE–SE and NW–SE–SW. PNG/CSV/NPY rows increase along +Z and columns increase along +X.
For a formal pre-release walkthrough, use docs/MANUAL_RELEASE_CHECKLIST.md. It covers the complete ordered sculpt workflow, history, persistence, vegetation, exports, 25 m grids, and desktop smoke checks.