@genart-dev/plugin-terrain

Natural landscape element layers for genart.dev — 21 layer types, 114 presets, and 38 MCP tools for AI-agent control. Includes a depth lane system for multi-layer landscape composition and 13 scene recipe tools for instant complete landscapes.

Part of genart.dev — a generative art platform with an MCP server, desktop app, and IDE extensions.

Install

npm install @genart-dev/plugin-terrain

Usage

import terrainPlugin from "@genart-dev/plugin-terrain";
import { createDefaultRegistry } from "@genart-dev/core";

const registry = createDefaultRegistry();
registry.registerPlugin(terrainPlugin);

// Or access individual exports
import {
  ALL_PRESETS,
  getPreset,
  filterPresets,
  searchPresets,
  skyLayerType,
  profileLayerType,
  fieldLayerType,
  rockLayerType,
  treelineLayerType,
  celestialLayerType,
  starfieldLayerType,
  cliffFaceLayerType,
  snowfieldLayerType,
  // ... all 21 layer types exported
} from "@genart-dev/plugin-terrain";

Layer Types (21)

Active Layers (9)

Deprecated Layers (12)

These layers are deprecated in v0.5.0 and will be removed in v1.0.0. They are being extracted into dedicated plugins in the v2 roadmap. Calls will continue to work but emit a console.warn deprecation notice.

Moving to @genart-dev/plugin-atmosphere (Phase C):

Moving to @genart-dev/plugin-water (Phase D):

Moving to @genart-dev/plugin-architecture (Phase E):

Depth Lane System

All terrain layers support a depthLane property for coordinated multi-layer landscapes. Seven named lanes define depth ordering from farthest to nearest:

Each lane supports sub-levels (-1, -2, -3) for fine-grained ordering within a lane. Atmospheric depth is applied automatically — distant layers desaturate and shift toward blue (western mode) or warm paper tones (ink-wash mode).

Presets (114)

Sky (5)

Preview	ID	Name	Description	Tags
	dawn	Dawn	Early morning sky with warm pink-orange horizon fading to pale blue zenith	warm, morning, sunrise, soft
	noon	Noon	Clear midday sky with deep blue zenith and pale blue horizon	bright, clear, midday, blue
	golden-hour	Golden Hour	Late afternoon golden light with amber horizon and warm blue zenith	warm, golden, afternoon, atmospheric
	dusk	Dusk	Twilight sky with deep purple zenith and burnt orange horizon	cool, evening, twilight, purple
	night	Night	Dark night sky with near-black zenith and deep navy horizon	dark, night, cool, moody

Profile (6)

Each profile preset supports three optional runtime properties that tune the landform character:

• terrainType ('mountains' | 'hills' | 'plains') — scales noise amplitude and frequency. Mountains use full amplitude; hills use ~45%; plains use ~15% with compressed frequency.
• subRangeCount (0–3) — number of sub-range ridges drawn behind the main ridge, adding depth and layering.
• subRangeAmplitude (0.1–1.0) — scale factor for sub-range ridge heights relative to the main ridge.

Preview	ID	Name	Description	Ridges	Tags
	alpine-range	Alpine Range	Sharp, jagged alpine peaks with multiple receding ridges	5	mountains, alpine, jagged, dramatic
	rolling-hills	Rolling Hills	Gentle, smooth rolling hills with soft contours	3	hills, gentle, pastoral, soft
	mesa-plateau	Mesa Plateau	Flat-topped mesa formations with steep cliff sides	2	desert, mesa, flat-top, arid
	coastal-cliffs	Coastal Cliffs	Dramatic coastal cliffs with weathered profiles	2	coast, cliffs, dramatic, ocean
	sand-dunes	Sand Dunes	Smooth undulating sand dunes with minimal roughness	4	desert, dunes, smooth, sand
	foothills	Foothills	Low foothills transitioning from plains with moderate elevation	4	hills, foothills, transitional, moderate

Field (8)

Preview	ID	Name	Description	Tags
	meadow-grass	Meadow Grass	Lush green meadow with mixed grasses	meadow, grass, green, lush
	wheat-field	Wheat Field	Golden wheat field ready for harvest	wheat, golden, harvest, warm
	wildflower-meadow	Wildflower Meadow	Colorful wildflower-dotted grassland	wildflower, meadow, colorful, spring
	lavender-rows	Lavender Rows	Orderly rows of lavender in bloom	lavender, rows, purple, fragrant
	dry-savanna	Dry Savanna	Dry golden savanna grassland	savanna, dry, golden, hot
	rice-paddy	Rice Paddy	Flooded rice paddy with green shoots	rice, paddy, green, water
	autumn-stubble	Autumn Stubble	Harvested field with stubble remaining	autumn, stubble, brown, harvested
	snow-covered	Snow Covered	Field covered in a blanket of snow	snow, covered, white, winter

Rock (6)

Preview	ID	Name	Description	Tags
	granite-boulder	Granite Boulder	Large granite boulder with rough texture	granite, boulder, grey, rough
	sandstone-outcrop	Sandstone Outcrop	Layered sandstone outcrop with warm tones	sandstone, outcrop, warm, layered
	shan-shui-rock	Shan Shui Rock	Stylized Chinese landscape rock	shan-shui, rock, stylized, eastern
	mossy-rock	Mossy Rock	Weathered rock covered in green moss	mossy, rock, green, old
	slate-shelf	Slate Shelf	Flat shelf of layered slate	slate, shelf, flat, dark
	volcanic-basalt	Volcanic Basalt	Dark volcanic basalt columns	volcanic, basalt, dark, columnar

Treeline (6)

Preview	ID	Name	Description	Tags
	deciduous-canopy	Deciduous Canopy	Lush deciduous tree canopy in summer	deciduous, canopy, green, summer
	conifer-ridge	Conifer Ridge	Dense conifer ridge silhouette	conifer, ridge, dark, evergreen
	autumn-treeline	Autumn Treeline	Treeline in full autumn color	autumn, treeline, colorful, warm
	misty-forest	Misty Forest	Forest edge shrouded in mist	misty, forest, atmospheric, soft
	palm-fringe	Palm Fringe	Tropical palm tree silhouettes	palm, tropical, silhouette, coastal
	winter-bare	Winter Bare	Bare winter trees with no leaves	winter, bare, stark, cold

Celestial (6)

Preview	ID	Name	Description	Tags
	noon-sun	Noon Sun	Bright overhead sun	sun, noon, bright, warm
	golden-hour-sun	Golden Hour Sun	Low sun with golden glow	sun, golden, warm, atmospheric
	harvest-moon	Harvest Moon	Large amber harvest moon	moon, harvest, amber, warm
	crescent-moon	Crescent Moon	Thin crescent moon	moon, crescent, cool, night
	blood-moon	Blood Moon	Deep red lunar eclipse moon	moon, blood, red, dramatic
	polar-star	Polar Star	Bright northern star with glow	star, polar, bright, night

Starfield (5)

Preview	ID	Name	Description	Tags
	clear-night	Clear Night	Clear night sky with scattered stars	clear, night, scattered, standard
	dense-starfield	Dense Starfield	Densely packed star field	dense, starfield, packed, bright
	milky-way	Milky Way	Milky Way band across the sky	milky-way, band, galactic, dramatic
	sparse-stars	Sparse Stars	Few scattered stars in early twilight	sparse, stars, twilight, subtle
	twilight-stars	Twilight Stars	Stars emerging at dusk	twilight, stars, emerging, dusk

Cliff Face (5)

Preview	ID	Name	Description	Tags
	granite-cliff	Granite Cliff	Sheer granite cliff face	granite, cliff, sheer, grey
	sandstone-wall	Sandstone Wall	Warm sandstone cliff wall	sandstone, wall, warm, layered
	basalt-columns	Basalt Columns	Columnar basalt cliff formation	basalt, columns, dark, geometric
	limestone-face	Limestone Face	Pale limestone cliff with erosion	limestone, face, pale, eroded
	shale-cliff	Shale Cliff	Dark layered shale cliff	shale, cliff, dark, layered

Snowfield (4)

Preview	ID	Name	Description	Tags
	fresh-powder	Fresh Powder	Freshly fallen undisturbed snow	fresh, powder, white, pristine
	wind-swept	Wind Swept	Wind-sculpted snow with ridges	wind, swept, ridges, textured
	sun-crust	Sun Crust	Sun-crusted snow with icy surface	sun, crust, icy, sparkling
	deep-snow	Deep Snow	Deep snow with soft contours	deep, snow, soft, heavy

Deprecated Presets (63)

The 12 deprecated layer types retain their presets for backwards compatibility. See Deprecated Layers for the migration path.

Landscape Composites (6)

Multi-layer scenes combining sky, terrain, clouds, and water:

Preview	ID	Name	Layers
	mountain-dawn	Mountain Dawn	dawn sky + alpine-range profile + wispy-high clouds
	rolling-pastoral	Rolling Pastoral	noon sky + rolling-hills profile + fair-weather clouds
	desert-sunset	Desert Sunset	golden-hour sky + mesa-plateau + sand-dunes profiles
	coastal-storm	Coastal Storm	dusk sky + coastal-cliffs profile + storm clouds + choppy sea
	lake-at-night	Lake at Night	night sky + foothills profile + still-lake water
	mountain-stream-scene	Mountain Stream	noon sky + alpine-range profile + scattered clouds + mountain-stream water

Scene Recipes (12)

Multi-layer scenes assembled by the scene recipe MCP tools:

Preview	ID	Name	Layers
	mountain-valley	Mountain Valley	sky + alpine ridges + fog + treeline + field + haze
	river-scene	River Scene	sky + hills + river + shore + treeline + reflection
	coastal-moonlight	Coastal Moonlight	night sky + starfield + moon + water + shore + reflection
	park-riverside	Park Riverside	sky + terrain + river + path + treeline + field + building
	shan-shui	Shan Shui	sky + peaks + fog + rock + water + haze
	pastoral	Pastoral	golden-hour sky + hills + wheat field + path + fence + building + haze
	forest-clearing	Forest Clearing	sky + treeline + forest floor + fog + path
	alpine-lake	Alpine Lake	sky + alpine range + snowfield + water + reflection + cliff + haze
	japanese-garden	Japanese Garden	sky + water + bridge + rock + treeline + reflection + haze
	desert-expanse	Desert Expanse	sky + mesa + cliff + field + haze
	winter-woodland	Winter Woodland	sky + terrain + snow + treeline + fog
	tropical-coast	Tropical Coast	golden-hour sky + water + shore + boat + reflection + haze

Note: Scene recipes that include deprecated layers (clouds, fog-layer, haze, water, river, shore, reflection, building, bridge, path, fence, boat) will emit deprecation warnings at render time.

Examples

The examples/ directory contains .genart sketch files organized by category, with .png thumbnails and .genart-workspace files:

examples/
├── sky/               5 sky gradient presets
├── profile/           6 terrain ridgeline presets
├── field/             8 vegetation field presets
├── rock/              6 natural rock form presets
├── treeline/          6 canopy silhouette presets
├── celestial/         6 sun/moon/star presets
├── starfield/         5 star field presets
├── cliff-face/        5 cliff wall presets
├── snowfield/         4 snow ground presets
├── landscape/         6 composite scenes
├── scenes/           12 scene recipe compositions
└── terrain-gallery.genart-workspace  (all active sketches)

Regenerating examples:

node generate-genart-files.cjs        # Create .genart files from presets
node generate-workspace-files.cjs     # Create .genart-workspace files
node render-examples.cjs              # Render .png thumbnails (requires local CLI)
node generate-galleries.cjs           # Create category gallery montages

MCP Tools (38)

Exposed to AI agents through the MCP server when this plugin is registered.

Add Layer Tools — Active (9)

Add Layer Tools — Deprecated (12)

These tools still function but emit a deprecation warning. They will be removed in v1.0.0 when the target plugins are released.

Scene Recipe Tools (13)

Complete landscape compositions assembled from multiple layers:

Utility Tools (4)

Rendering

Each layer type renders via canvas2d:

• Sky — Three-stop vertical gradient (zenith → haze → horizon) with configurable haze band
• Profile — Back-to-front ridgeline silhouettes with fractal noise elevation and depth-aware color interpolation. terrainType scales noise amplitude/frequency for mountains, hills, or plains. subRangeCount adds secondary ridges behind the main ridge; subRangeAmplitude controls their relative height.
• Field — Depth-aware mark generation (grass blades, wheat stalks, flowers) with perspective scaling, constrained to the assigned depth lane vertical extent
• Rock — Procedural rock silhouettes with fractal detail and depth-placed shading
• Treeline — Canopy silhouette generation with per-tree variation and atmospheric coloring
• Celestial — Radial gradient glow with optional lens flare and corona effects
• Starfield — Pseudo-random star placement with brightness variation and optional galaxy band
• Cliff Face — Vertical wall silhouette with horizontal striation marks and depth tinting
• Snowfield — Horizontal coverage bands with drift accumulation noise and sparkle highlights

Utilities

Shared utilities exported for advanced use:

import {
  mulberry32,                          // Deterministic PRNG
  createValueNoise, createFractalNoise, // Procedural noise generators
  parseHex, toHex, lerpColor,          // Color interpolation
  darken, lighten,                     // Color adjustment
  applyDepthEasing,                    // Depth curve functions
  resolveDepthLane,                    // Depth lane resolution
  depthForLane,                        // Lane → depth value
  DEPTH_LANE_ORDER,                    // Lane names in order
  DEPTH_LANE_OPTIONS,                  // UI-ready enum options
} from "@genart-dev/plugin-terrain";

Preset Discovery

import { ALL_PRESETS, filterPresets, searchPresets, getPreset } from "@genart-dev/plugin-terrain";

// All 114 presets (51 active + 63 deprecated)
console.log(ALL_PRESETS.length); // 114

// Filter by category
const skyPresets = filterPresets({ category: "sky" });     // 5 presets
const profiles = filterPresets({ category: "profile" });   // 6 presets
const fields = filterPresets({ category: "field" });       // 8 presets

// Filter by tags
const dramatic = filterPresets({ tags: ["dramatic"] });

// Full-text search
const results = searchPresets("mountain");

// Look up by ID
const preset = getPreset("alpine-range");

Related Packages

Support

Questions, bugs, or feedback — support@genart.dev or open an issue.

License

MIT