Features Plugins Pricing Docs
DiscordDownload
Documentation

Everything in the studio, explained.

Heightmap Studio builds terrain for motocross, BMX and mountain bike games at real-world scale. This guide follows the order you build in: terrain, sculpt, paths, path forms, channels, bumps, ponds and rivers, texture painting, environment, export.

rocket_launchGetting started

Heightmap Studio is a desktop app for Windows and Linux, with game plugins and autosave built in.

Install on Windows

  1. Download the installer from the Download button. It is a single Heightmap-Studio-setup.exe.
  2. Unblock it. The installer is unsigned for now, so Windows Security may stop it. Right-click the file, open Properties, tick Unblock under the General tab, then Apply.
  3. Run the installer. Updates keep your presets, path form templates, license status and project files.

Your first track

  1. New project. Pick a map size in pixels and real-world dimensions in meters. Choose Custom terrain, Real-World capture, or Import a heightmap.
  2. Shape the ground. Tune the terrain generator, then switch to Sculpt (D) for hand-shaped features and erosion.
  3. Lay the path (T). Click anchors along your line. Set lane width, path depth, edge height and smoothing. Add an entry path if you want one.
  4. Place path forms (J). Click on a pathway, pick a template, drag to resize.
  5. Carve channels and bumps (B, P, K). Draw through corners and braking zones. Reshape any layer later from the Layers panel.
  6. Paint textures with Texture Painting and place trees and objects with Environment, then Export the 16-bit heightmap, or build straight into a game through a plugin.
lightbulb

Save early with Ctrl S. The .hm project keeps every layer editable. Exports are only snapshots.

dashboardThe interface

The toolbar runs down the left, tool panels float over the 3D canvas and hug their content, and the Layers panel sits on the right. Project actions live in the header.

ToolbarProject Settings, then the Heightmap group (Terrain, the sculpt brushes, Path, Path Forms, Channels & Bumps, Ponds & Rivers) and the Environment group (Texture Painting, Environment), then Plugins.
Tool panelFollows the active tool. Cross-section previews for channels and bumps, the path form profile preview, terrain tabs.
Canvas toolbarDraw, Pen and Select modes for the Path and Channels tools. Zoom and fit controls bottom-left.
3D viewThree.js viewport. Relief (display-only exaggeration), Key light, Exposure, Surface and Roughness are in Preferences > Lighting.
Layers panelChannel and bump layers, groups, the layer mask brush, reorder drafts with Apply Order, and Reset.
HeaderUndo and redo, New project, Open, Save, Save As, Package Project, Export, Preferences, and the View dropdown.

View

The header View picks what the 3D view shows. Automatic (the default) shows Solid while you use the Heightmap tools and Environment in Texture Painting, the Environment tool and game plugins. Solid is the plain terrain with strong relief lighting for sculpting, and every object as untextured clay. Environment shows the painted textures, textured objects, water and the sky, lit by the sky's sun. Picking Solid or Environment keeps that view in every tool, and the choice is remembered.

Preferences

PerformancePreview resolution, Object textures, the Performance level, limits for Background CPU jobs, Undo history, Undo memory and the Recently used model cache, Frame rate limit, Show FPS (on by default, with draw calls and triangles), Live animations, and experimental GPU Path carving and GPU Path Forms.
LibraryYour library folder (Move Everything, Use a Folder As Is, Show in Folder) and how often Recovery autosave runs.
LightingThe 3D view's Relief, Key light, Exposure, Surface and Roughness.
ToolsBrings back the deprecated Masks tool.
AI AssistantThe local MCP server for plugin authors, see AI assistant (MCP).

Canvas navigation

  • Scroll zooms toward the cursor. F fits the map to the window.
  • Space and drag pans temporarily from any tool. Pan/Zoom is also a tool of its own.
  • [ and ] resize the active brush, or both channel widths while drawing channels.

terrainTerrain

The Terrain tool (G) has three tabs: Custom generates a landscape from a seed, Real-World captures elevation for a real location, and Import loads a grayscale heightmap PNG. All three share map scaling and the reference overlay.

Map dimensions

X width, Y length and Z height range are in meters and define the real-world scale for every other tool. A 1025 px map at 500 m wide gives roughly 0.49 m per pixel. The Z range is the height span a full black-to-white heightmap covers.

Custom terrain

Sections fold so the panel stays short. Every slider regenerates the map and the 3D view live.

Procedural TerrainSeed (type or roll the dice) and Base height, the elevation of flat ground.
Ground variationHill height, Hill count, Hill spread (narrow steep hills to broad ones that run together), Height spread, Roughness, Octaves, Persistence, Lacunarity.
Hill shapeRounded, Peaked, Ridged (sharp ridgelines) or Mesa (flat tops, steep sides), with Sharpness and a Stretch along a Direction for long ridges.
LandformTilt the whole map toward an uphill direction, cut Valleys into the raised ground, raise the Edge for an amphitheatre, keep a level Flat area in the middle.
Sand dunesWind-shaped ridges with height, spacing and wind direction.
TerracesCut the ground into a set number of steps for quarries and canyon walls.

Presets

Farmland, Hillside, Sand Dunes, Mountain Ridges, Desert Mesa, Quarry, Valley Bowl and Canyon, plus flat pads and rolling bases. Save your own and they travel between projects.

Real-World terrain

Search for a location, frame the map or aerial crop, and capture. The capture becomes the heightmap and the aerial image loads automatically as a tracing overlay, so you can lay the real layout straight over the real ground. New Terrain Capture returns to the map picker.

Import a heightmap

Import accepts grayscale PNGs; white is high, black is low. 16-bit PNGs keep their full precision. 1025 px and 2049 px maps become terrain bases for the Path and Path Forms tools. Other sizes still work for channel and bump editing.

Reference overlay

Load a map, sketch or texture over the canvas for tracing. Opacity controls how strongly it shows. It is display only and never changes the heightmap or any export.

elevationSculpt brushes

Press D or pick a brush in the toolbar's Heightmap group. Sculpt paints a map-space layer above terrain, paths, path forms, channels, bumps and texture height, so sculpted detail stays in place when the objects under it move. One undo step per stroke.

BrushWhat it doesShift
RaisePushes terrain up. Max height stops raising at that elevation (0 = no limit).Lowers instead
LowerPushes terrain down. Max depth is how far below the surface one stroke can dig.Raises instead
Smooth SSoftens the visible surface under the brush. Uses Brush Size, Hardness and Smooth Amount.Un-smooths
FlattenPulls terrain toward the height sampled where the stroke starts.
Flatten SlopePlanes terrain along the grade under the first click, keeping the slope instead of leveling it.
RampGrades the band under the stroke from the start height to the end height. One stroke lays one complete ramp; Strength does not apply.
NoiseAdds rough variation. Size is the feature scale in meters, Variance mixes in finer detail and uneven strength.Inverts
ErosionWater and sediment simulation on the GPU at full map resolution. Paint an area or Apply to Entire Heightmap.
CloneCopies terrain from elsewhere on the map.Shift-click sets the source
TerracePulls height toward flat steps. Steps sets how many levels the lowest-to-highest range is cut into.
Erase SculptRemoves Sculpt layer changes to reveal the editable objects below.

Shared sliders

RadiusBrush radius in meters.
StrengthBrush intensity on a 1 to 10 scale.
Edge hardness0 feathers across the whole radius; higher values keep full strength further out before a quick falloff. All modes except Erosion.
ShapeBlends the footprint from round at 0 to square at 1.
Ignore PathsKeeps every brush off the pathways and entry paths. Applies to strokes painted while it is on.

Erosion

Rain runs downhill, fast water cuts branching gullies that join into valleys, slow water drops its sediment into the valley floors, and steep faces slump to the talus angle. Water from the ground around a stroke still flows in, but nothing outside the brush changes.

StrengthHow easily the ground erodes.
IterationsHow long it rains. More grows longer channels that join into valleys.
RainHow much water falls. More water gathers into fewer, bigger channels.
SmoothnessRounds off the fine grain and sharp rill edges, from crisp to soft, weathered ground.
DepthHow deep the deepest channel is cut, in meters. Everything else scales with it so the pattern stays the same.
info

Erosion paints live like the other brushes. The simulation grid stays on the GPU for the whole stroke and only the stroke's area is simulated, so each frame re-solves in a few milliseconds.

routePath tool

Press T. The Path tool is a pen-style spline along your line. Each pathway carves a clean lane that follows the terrain and blends into the surrounding ground, and path forms, bumps and masks all key off it.

Lane widthWidth of the cut lane in meters.
Path depthHow far the lane sits below the surrounding ground.
Edge heightRaises or lowers the lane edges for berms and crowned straights, with Edge width and Edge fade.
Elevation smoothingHow much the lane's height profile is averaged along its length.
Entry PathAn optional entry lane, such as a start straight or a drop-in, that snaps onto the pathway with its own width and taper.
SegmentsDrag ready-made straights and corners onto an open pathway endpoint to speed up layout.

Editing anchors

  • Click to add anchors, drag to move them. Delete removes the selected anchors.
  • Shift drag raises or lowers a path point. Hold Shift while placing to snap new anchors.
  • Ctrl drag banks a path point up or down.
  • Alt drag a path point left or right to adjust the width at that point.
  • An open pathway continues from its highlighted last point. Click the first point to close the loop; right-click a point on a closed pathway and choose Disconnect Point to open it there.

A red 20 m band along the map edges marks a safe area that leaves room for trees and scenery. It is only a guide: paths can still go there.

Path settings save as presets. Path Guides can be exported as .obj polylines in real meters, see Export.

landscapePath Forms

Press J and click a pathway. The form snaps to the spline and tilts with it. Pick a template, then drag the form to move it along the line.

Templates

Double, Kicker, Roller, Single Takeoff, Step-up and Tabletop ship with the app. Each has a default height and a length-to-height ratio. Custom templates you save appear alongside them.

Shaping a path form

  • Section shaped forms expose takeoff, top and landing fractions, each with its own curve, plus gap depth for doubles.
  • Curve profile forms follow a drawn height-over-length curve from the template editor.
  • Height and length are in meters. Shift while dragging adjusts length.
  • Alt drag an existing form to duplicate it and move the copy in one drag.
  • In the 3D view, clicking the middle band of a form (marked by cage lines) adds a shape point; clicking anywhere else on its body moves it.

Template editor

Click to add anchors on the height-over-length graph, drag anchors or the green handles to shape curves, Alt-click or Delete removes a selected anchor. Set a name, default height and the template to start from, then Save or Save as New. Templates import and export as .jump files.

Path Form layers

Path forms have their own layer panel while the tool is active: reorder, hide, select or delete placed forms. Forms can be adjusted or replaced at any time and never flatten into the terrain until export.

gestureChannels

A channel is a directional cross-section: it digs a trough on one side of the stroke and raises a berm on the other. B opens Channels in freehand Draw, P in Pen mode.

Input modes

  • Draw is freehand. Press, drag the path, release to create a new channel layer.
  • Pen places bezier anchors. Click to add, drag while placing or drag existing handles to shape curves. Enter applies, Esc cancels, Backspace removes the last point.
  • Select selects or moves an existing layer. Switch to Pen while one layer is selected to reopen its committed path.

Direction and side

The trough and berm are calculated from the stroke direction, so drawing the same path in the opposite direction flips the cross-section. Hold Shift while drawing to flip the side without changing direction. The cursor previews the footprint: the dug trough, the raised berm and the falloff ring.

Channel shape

DepthHow deep the trough cuts, in meters.
Depth widthWidth of the trough across the stroke.
Depth sharpnessRounded trough at 0, a V at 1.
Depth edgeHow far the trough edge blends outward.
HeightBerm height in meters.
Height widthWidth of the berm.
Height sharpnessSoft mound at 0, a sharp lip at 1.
FadeDistance the whole shape settles back into the terrain.

Draw stroke

StrengthOverall intensity of the stroke as a percentage.
SmoothSmooths the freehand path before carving.
TaperLength over which the channel fades in and out at both ends, in meters.
Clamp to valid rangeKeeps the carved result inside the heightmap's representable range.

Multi-channel

Toggle Multi-channel and one stroke lays Channel count parallel channels (2 to 12) spread center-out across the Lane width. Variation breaks each channel into random gaps, brush-spacing style, so the corner reads like it has been ridden rather than printed.

Presets

Channel shapes save as .rutpreset.json files from the preset dropdown and import on any machine. Older preset files stay compatible.

wavesBumps

Press K. Draw a line through a braking zone and the tool scatters regular bump stamps along it inside a lane, or lays a single continuous ridge. The panel shows a live top-down preview as you tune it.

Scatter

LengthLength of each bump along the stroke.
Length variationRandom variation in bump length.
Lane widthHow wide the bump field spreads across the stroke.
SpacingDistance between bumps along the stroke.
Placement variationRandom jitter in where each bump lands.

Shape

HeightHow high each bump rises, in meters.
DepthHow deep the trough cuts. In Scatter mode the trough flows into the raised crest.
WidthBump width across the stroke.
FadeSide blend distance into the surrounding terrain.
BlurSoftens the footprint by fading the carved change back toward neutral terrain.

Bump runs are layers like channels: reshape them from the panel, mask parts of them with the layer mask brush, group and reorder them. Bump settings save as presets.

waterPonds & Rivers

Press W. Ponds & Rivers carves water beds into the terrain with the Path tool's pen: a pond is a closed shore, a river an open course drawn upstream first. It only shapes the ground; the water itself is placed in the Environment tool's Water tab, and a new pond or river adds its water there for you.

Drawing

  • Pick the Pond or River tab. With nothing selected, the settings are for the next one, and clicking open ground starts drawing it.
  • A pond carves once its shore is closed: select its last point, then click its first point. A river carves when you finish drawing it (Enter, Esc or clicking off it) and when you let go of a point, handle or the whole river while dragging.
  • The canvas toolbar has Grab and Pen. With either, click a pond or river to select it and drag to move it. With the Pen, hover its line to add a point and drag a point to adjust it.
LevelAuto level fills a pond to the lowest point of its shore, or follows a river's ground along its course without climbing downstream, a set distance below. Turn it off to set the Water level yourself.
ShapeRiver Width, then Carve terrain (off keeps only the outline), Depth, Shore slope width and Bank height.
EdgesEdge fade blends the banks into the ground around them; Edge roughness and Roughness size make the waterline wobble.

Ponds and rivers are terrain records like path forms: they save, undo and recompile with the terrain, and the exported heightmap is always the bed. The bottom bar deletes the selected one.

format_paintTexture Painting

Texture Painting sits in the toolbar's Environment group. It stacks up to 16 tiling texture layers over the terrain, each with a mask that decides where it shows. Masks are built from mask layers (images or terrain modes) and your own brush strokes, and strokes are stored as resolution independent edits, so masks export sharp at 8K and beyond.

Adding texture layers

With nothing selected, the left panel is the Texture Library: click a texture to add it as a layer. Add Texture Layer in the right panel opens the same library in a window with two tabs:

  • Library lists your own textures from your library's Textures folder. The app ships no textures of its own, so it starts empty.
  • Download searches Poly Haven and ambientCG together, with a Source filter, categories and a resolution. Each card names its source, and a downloaded texture is saved to your Library tab.

Import your own (DDS, TGA, PNG, JPG) adds a texture to your library. Pick the colour image alone, or a texture's files together: normal, height, ambient occlusion and roughness maps are told apart from the colour by their names (normal, nrm or _n; height, displacement or disp; ao; roughness), and DirectX normals are flipped. The selected texture shows tiled 3 x 3 beside the list so you can see how it repeats. Pick a Rotation, a Texture size in meters and whether the layer should Start With Fill or Paint On, then Add Layer.

info

Earlier versions shipped six built-in textures (Dirt Dark, Dirt Light, Grass, Gravel, Sand Dark and Sand Light). A project that used one keeps the layer and its masks with an empty texture: pick a new one with Change Texture on the layer's texture card.

Layer settings

Click a layer card to show its settings in the left panel, under the Texture and Mask tabs. Back to Library returns to the library.

Texture, Normal, HeightClick a card to change the texture, or to add a normal map or height map for it.
BlendOpacity blends the layer by its mask. Height also weighs its height map (or the texture's brightness) against the layers beneath, so the higher surface shows first, with Sharpness for the edge. Not on the base layer.
Texture sizeHow many meters one tile covers, 0.25 to 50 m. Rotation turns it in 90° steps.
Surface heightHeight map relief for games that support it, 0 to 10 cm. Needs a height map; 0 turns it off.
OpacityOverall strength of the layer.
Hue, Saturation, BrightnessColour adjustments. Reset Color clears them and Save to Library keeps the adjusted texture in My Textures.
Normal strengthStrength of the layer's normal map, when it has one.
RoughnessHow matte the ground is, for the 3D view and games: 1 is fully matte, lower values pick up highlights (wet mud, puddles). With a roughness map, Roughness min and Roughness max set the range the map is remapped into.

Masks

A layer's mask comes together in three steps: its mask layers combine into one shape, the Mask tab adjusts that shape, and the layer's own start and brush strokes decide where it may show. The bottom visible layer is the base and always covers everything.

Fill / Paint OnFill shows everywhere and you erase it away. Paint On starts empty and you paint it in.
InvertFlips the combined mask layers.
LevelsBlack point, White point and Midtones tighten or soften the mask. Reset Levels puts them back.
Edge roughnessRoughness, Scale and Seed break up the mask's edges into ragged, natural patches. Solid areas stay solid.
Keep Off PathsCuts the layer away from the pathway, other paths and the entry path, each with its own edge margin, plus an Edge fade. Follow Path mask layers are never cut, and brush strokes can still paint over a path.
Show MaskShows the mask in greyscale on the terrain.
Clear Master BrushRemoves the layer's own brush strokes.

Mask layers

Open a layer card's Mask group and click Add Mask Texture to open the Add Mask Layer window. Pick a placement and an image, choose Fill or Paint On, then Add to Mask. Click a mask layer row to edit it in its own panel, where Reset Mask clears its strokes and Delete Mask Layer removes it. Drag a mask layer onto another texture layer's card, or between its mask layers, to move it there.

The image galleries show the preset patterns and, above them, My Masks. Import a grayscale image saves the image to the Masks folder of your library, so it is listed under My Masks in every project from then on. Images you put in that folder yourself (subfolders too) show there as well, and removing one from My Masks moves the file to the Recycle Bin. A mask layer keeps its own copy of the image in the project, so a project never depends on the folder.

PlacementWhat it does
Follow PathLays a grayscale image along the Pathway or Entry Path, with Repetitions (Width), Texture width and Edge fade.
Custom PathThe same along a path you draw with Draw Path on the canvas toolbar.
FillCovers the map with the image, with Repetitions and edge margins that keep it off the pathway, entry path and other paths.
RepeatTiles the image across the map at a Tile size in meters.
TerrainComputes the mask from the heightmap: Terrain Edges (Raised, Hollows or Both, with Scale and Sharpness), Slope (From angle, To angle, Softness), Altitude (From height, To height, Softness), Water Flow (Smoothing), Cavity (Scale, Depth, Sharpness) or Puddles (where rain water would stand: Rain, Max depth, Min depth, Min size, Max size, Min width, Edge depth, Wet margin; put a water or wet mud texture on it). Terrain Edges and Cavity read the Whole terrain, Channels, bumps and sculpt only, or Channels only.

Every mask layer has a Blend mode (Normal, Overlay, Screen, Add, Multiply, Subtract) and an Opacity. In mask images, white shows the texture and black hides it.

Painting

The brush paints the selected mask layer when one is selected, otherwise the texture layer's own mask. The brush shows and the eraser hides, with Radius, Hardness and Opacity on the canvas toolbar. Hold Shift to swap them; [ and ] change the radius. The base layer cannot be painted.

Layer cards

The right panel lists the Texture Layers, top layer first. Drag the handles to reorder, double-click a name to rename, and use the eye to hide a layer. Mask normal on a card generates a normal map from the mask's edges, with its own Intensity. The bottom bar duplicates, hides or deletes the selected item. Grass that grows over a layer's mask is made in the Environment tool's Vegetation tab, see Environment.

Export and bake

  • Export Masks... in the bottom bar writes one PNG per layer at 2048 to 16384 px: Layer masks (as painted), or Visible weights (normalized) that add up to full white. Include mask normals adds the generated normal maps.
  • Bake to Heightmap on the Mask tab raises the terrain where the mask shows, with Bake height and Bake blur. Remove Bake takes it out again.
lightbulb

Set the header View to Environment to see your textures, objects and sky in the 3D view from any tool.

Legacy Masks tool

The older Masks tool is deprecated and hidden unless you turn it on in Preferences > Tools. While it is on, its mask groups feed the Texture Mask (DDS DXT5 / TGA 32-bit), Path Textures, Background / Paint and Edge Mask exports in the header Export menu.

forestEnvironment

The Environment tool, in the toolbar's Environment group, places what sits on the terrain. Its left panel has Objects, Vegetation, Sky and Water tabs (icons, named on hover). For objects and plants the right panel switches between Settings, Placement and Animations for the selected item. Every game plugin builds from the same objects.

Your library

Models, plants, skies, textures and masks live in your library folder (by default Documents\Heightmap Studio), so every project can use them. It holds Projects, Textures, Masks, Objects, Vegetation, Skies, Presets, Brushes and Plugins folders. Change it in Preferences > Library with Move Everything... or Use a Folder As Is..., or open it with Show in Folder.

  • Textures added by hand. Put a folder holding a texture's files, or loose images, in the Textures folder and they show in Texture Painting's library, picked up on launch and whenever a texture library opens. Loose images that belong to one texture (rock_albedo.png and rock_normal.png, say) are moved into a folder of their own. Colour, normal, height, AO and roughness maps are told apart by their names, and DDS and TGA files get a PNG copy beside them.
  • Masks. Mask images imported in Texture Painting are saved to the Masks folder, and any image you put there shows under My Masks. See Mask layers.
  • Deleting. Delete in Add from Library moves the asset's folder to the Recycle Bin, so it can be restored, and warns when the open project uses it.

Objects

Import Model copies an FBX, GLB, glTF or MX Simulator .jm file into the library and adds it to the project. Add from Library opens the library window, where Add to Project brings in anything you imported before, and Browse Sketchfab finds models online. Import from Project brings another track's objects in (see below). An FBX becomes a group of its parts in the Layers list, with its pivot at the bottom centre of what it shows.

  • Shift or Ctrl click selects several rows, and double-clicking renames one. Names carry into game builds.
  • Drag rows like Path Form layers: the rows make room as you drag, and you can drop between objects of a group, onto a group to add to it, or back out of a group, without anything moving in the world. Groups drag to reorder. Move to group in an object's settings does the same for every selected row.
  • Right-click for Join Objects, New Group, Split into Parts, Save as New Model and, with two objects selected, Replace with. The eye hides an item and leaves it out of builds.
  • A group's origin sits at the bottom centre of its objects, so it turns and scales about the middle of what it holds.
  • A red name means a problem, such as missing textures. The item's settings list what is wrong.

Moving objects

Click an object in the 3D view (clicks pass through the cut-out holes of fences and leaves) and use the canvas toolbar. Move is one tool: the arrows move the object, the rings around them rotate it, and pressing the object itself drags it anywhere over the ground (an array slides along its path). Scale resizes it, and Select drags a box. It works on whole objects, objects of a group and joined objects.

PivotBottom (the default), Center or Top of the object, always centred across: where the handles sit and what the object turns and scales about.
Snap to TerrainOn by default. A moved or rotated object rests on the ground however it is turned: a tilted object stands on its lowest edge, a level one on a slope sits on its centre. Turn it off to keep an object's height and get the up arrow back.
Tilt to GroundOn by default. A dragged object also stands on the slope where it lands. Turn it off for things that must stand straight, like trees.

Placement

PlacementSettings
FreeX, Z, Rotation and Height, or a Vertical offset with Snap to surface on. Move and Scale on the canvas toolbar.
PathOne object, or an Array of copies, along a Path (Pathway, either pathway edge, the Entry path, either entry path edge or the Terrain edge). Type Stepping, Follow slope or Connected (with Bend to path), then Array: off places one object at Start along path, which you drag along the path in the 3D view; on adds Fit type Fill Path or Custom, Amount, Length, Spacing (the gap between copies: 0 sets them end to end, a negative value overlaps them), Side step, Rise step and Avoid other paths. Lateral offset and Rotation offset apply to both.
ScatterCopies spread over a Scatter mask: a Painted mask (Paint, Clear), a painted mask another item uses (Painted: <name>, so several items scatter over one area) or any Texture Painting layer. Objects per 100 m², Scatter seed, Avoid overlap, Avoid paths with a Distance from paths, Avoid water with a Distance from water, Rotation, Rotation variation (0 all the same, 180 any direction) and Size variation (up to 50% bigger or smaller). Each copy sits on the lowest ground under its base, so nothing floats on slopes.

Every placement has Tilt and Roll. The Settings tab holds the Name, Scale and Size, physics (Collision, Moveable, Weight, In Game) with Copy Settings and Paste Settings, and the model's License and Author. Ctrl C, Ctrl V and Ctrl D copy, paste and duplicate the selection, beside the original: a Free object 2 m along X, a Path object 2 m further along its path, a scatter with a new seed so its copies mix in with the original's. An object copied from a group goes back into that group, right after the original.

Import from Project and Replace with

  • Import from Project, in the Object Library, brings another track's objects into this one with their settings, for running a series. Pick a project and untick what you do not want; only its settings are read, so even a large project opens at once. Arrays stay on their path, scatters on their texture layer, and Free objects keep their spot and sit on this terrain. Anything that cannot come across as it was is listed first: a path this track does not have makes it a Free object, a texture layer it does not have (matched by name) makes it a Free group at the map centre, and objects off this map are left out. Objects already here (same name and model) are skipped or replaced, and this track's material settings are kept unless you tick Use the imported material settings.
  • Replace with, in the right-click menu with two objects selected (Shift-click), gives the first the second's model and keeps everything about where the first sits: its spot, its Path, Array, Scatter and Snap settings, turn and scale. Duplicate a banner array, move it, Shift-click another banner and replace the copy with it. The second object is left as it is.

Save as New Model

Save as New Model, in an object's settings and the right-click menu, saves whatever is selected as a model of its own in your library: one object, a group, a combined object, some objects of a group, or a mix. Each object keeps its own turn and scale, and the model is centred on its bottom. Its levels of detail, material settings, texture animations, object names, collision and joined objects come with it, and its textures are copied into its own folder, so it keeps working whatever happens to the models it came from. Your project stays as it was; the window that confirms the save can add the new model to it.

Materials and animations

The cog on a row opens the object's Materials window. For each texture it sets a Surface type (Default, Foliage, Water, Glass), linked maps (Normal, Specular, Reflection, Roughness, Metallic, Occlusion, Emission, Opacity), and Roughness (0 mirror smooth, 1 fully matte) and Metallic, which show in the 3D view with reflections of the track sky. Change Texture on the Texture slot swaps the texture from the texture library or a file: when other objects use the same model, Apply to All changes every one and Apply to This Object only the one you are editing, so a duplicated banner can carry a different print. It also replaces a missing texture. The Animations tab turns a texture into a looping animation: Import Frames, then set the Loop time and the frame order.

Levels of detail

The Levels of Detail tab of the Materials window (or Edit Levels of Detail in an object's settings) makes lighter Medium and Light versions of an imported model with Generate Levels, an optional Plane (cards) level, an optional Billboard for plants (pictures of the model from every side, turned toward the camera, which TrackDayR and MXGP 26 draw far away instead of the Plane), or loads your own LOD file for each level, with a 3D preview and Wireframe before Apply. Each object of a group can have its own. Models that come with levels are picked up on import: LOD files beside the model (oak_LOD1.fbx) and LOD meshes inside it (Trunk_LOD1, or a SpeedTree export's LOD0, LOD1, LOD2 and billboard). Use LODs in a group's settings picks which of its objects is each level. The 3D view draws far copies at the lower levels.

The Type setting in an object's or group's settings makes an imported model vegetation: a Plant lists in the Vegetation tab and builds with tree distances and cards in games. A Tree Wall is a plant that is a picture of a tree line: it lights like your trees but never builds as crossed cards and stays still in the wind. Thin plants are taken for tree walls until you pick. Sketchfab downloads from the Vegetation tab start as plants.

Vegetation

Generate Tree, Generate Bush and Generate Grass Clump grow plants from seeded parameters and save them to your library as ordinary models with automatic detail levels. Place them like any object. The Tree and Bush generator is a port of Daniel Greenheck's EZ-Tree, so its presets and seeds grow the same trees.

PresetTrees: Oak, Ash, Aspen and Pine (each Large, Medium or Small), Silver Birch, Sugar Maple, Lombardy Poplar, Weeping Willow, Norway Spruce, Douglas Fir, Scots Pine, Cherry, Palm, Dead Tree. Bushes: Bush 1 to 3, Sword Fern, Lady Fern, Ostrich Fern, Bracken, Small Fern, Boxwood, Blackthorn Scrub, Hawthorn in Bloom, Hazel, Laurel, Rhododendron, Juniper, Gorse, Elder, Dog Rose, Bramble, Willow Scrub, Dead Bush, Sagebrush, Sapling. Grass clumps: Short Lawn, Meadow, Tall Wild Grass, Dry Grass, Reeds, Cattails, Tussock.
OutputDetail (Light, Medium, High or Cards (3 planes)), Card resolution, a Seed with New Seed, and up to 8 Variants.
ParametersThe tree's height and shape, Branches, Leaves and Blossoms. Editing any value switches the preset to Custom. Save Parameters and Load Parameters keep a setup as a file.
TexturesLeaves, blossoms and bark from the built-in photos, generated in your colours, or Use a Photo for any of them, with tints and leaf colour variation.

Make Cards adds a light three-plane version of a tree beside it, for distant copies. Editing a generated tree, bush, grass clump or ground cover grass offers Update and Save as New: Update changes that asset in your library, so every project using it gets the change (it asks first when other saved projects use it), and Save as New keeps the old one.

Ground cover grass

Generate Grass opens the Grass Generator, which makes grass that grows over a texture layer's mask in the 3D view and in game builds that support it. Start from a Preset (Short Lawn, Meadow, Tall Wild Grass, Dry Grass, Pasture, Lush, Sparse, Clover Patch, Meadow Mix, Pasture Mix, Wildflower Meadow or Track Edge), set the Density and a Seed, then mix the Plants (grass, clover, plantain, dandelion, daisy, buttercup, wildflower), their shape, optional Flower Stalks and the Grass Colours, and click Add Grass. The Grass list shows each one; Grows on picks the texture layer it covers, or the whole map.

Water

The Water tab places the water you see. A pond or river carved with Ponds & Rivers adds its water here in the same step: pond water follows its pond's shore and level, and flowing water runs down its river at its Flow speed, each with a Water level offset. Pond / Lake places a lake of your own anywhere (click the terrain), with Shape (ellipse or rectangle), Width, Length, Rotation, Water level and Fit to ground, moved and sized with its handles. Carved Water adds water to any carved pond or river that has none. The Look sets the Color, Clarity, Waves, Roughness and Reflectivity, from a Preset or your own. Water shows only in the Environment view.

Sky

The Sky tab's library has Procedural, Library and Poly Haven tabs, plus Import HDRI (HDR, EXR, JPG, PNG). New projects start with a procedural daylight sky. Generate Sky (or Edit Sky once the sky is procedural) opens the Sky Editor: Sky, Haze (Amount, and Height for how far up it reaches), Sun, Clouds and Wind (the clouds drift while live animations are on), previewed live in the 3D view; Apply Sky keeps it. An imported HDRI has Rotation, Exposure and a Sun heading and height in the right panel. HDRI skies are saved in your library, not in the project file. In the Environment view the sky lights the scene: its sun is the key light, and the sky fills the shadows and shows in reflections.

layersLayers & groups

Every channel and bump becomes a layer. Select one from the panel or click it on the canvas. Selected layers show their stored path, and dragging a slider in the left panel reshapes them with the terrain updating during the drag.

  • Multi-select with Ctrl click or Shift click. Grouped layers can be edited together.
  • Rename by double-clicking. Hide with the eye. Group, delete, move with Select, reopen with Pen.
  • Order matters. Later layers are baked over earlier ones. Drag rows to draft a new order, then press Apply Order. Reset abandons the draft.

Layer mask brush

Enable Mask Brush in the Layers panel hides only the brushed parts of the selected channel and bump layers. The layer stays intact, the mask saves with the project and participates in undo and redo. Hold Shift to restore masked areas.

Path Form, texture and object layers

Path forms have their own panel while the Path Forms tool is active. Texture layers are cards in Texture Painting, and objects are listed in the Environment tool. See Texture Painting and Environment.

file_exportExport

The header Export menu writes the 16-bit grayscale heightmap with full float precision preserved inside the editor. Export size at the top of the menu sets the width and height (16 to 16384 px, with a lock and Source, ½, 2×, 4K, 8K and 16K presets). Game builds live under the Plugins tool, not Export. Texture Painting masks export from its own panel, see Texture Painting.

ExportContents
Full Heightmap (16-bit PNG)The finished 16-bit heightmap with every layer applied.
Heightmap (16-bit RAW)The same heightmap as raw 16-bit data.
Path Guides (.obj)Pathway and entry path center plus left and right edge-crest lines as polylines in real-world meters.

With the deprecated Masks tool turned on (Preferences > Tools), the menu also has its exports: Texture Mask (background plus route masks for the active group as DDS DXT5 or uncompressed TGA 32-bit, optionally with edge masks on top), Path Textures (PNG) (route-only transparent texture maps for pathways, entry paths and custom paths), Background / Paint (PNG) and Edge Mask Only (PNG) (a mask for channels, bumps, erosion and path forms, from the sources you tick).

Using path guides in Blender

  1. Import the .obj with Up Axis: Z and Forward Axis: Y so the guides land flat at the correct orientation.
  2. Shrinkwrap them onto your terrain (Project, Axis Z).
  3. Convert to a curve (Twist: Z-Up) to run markers or banners along the edge.

saveProject files

Saving and opening

Save writes a .hm project. It stores the original heightmap, terrain settings, paths, entry paths, path forms, channels, bumps, texture layers, masks, groups, dimensions and view settings. Open loads .hm projects, legacy .rutforge projects and .hmz project packages and restores the editable stack. Save As saves to a new file and keeps editing it. Closing or opening another project with unsaved changes asks Save, Don't Save or Cancel.

Double-clicking a .hm or .hmz file opens it in Heightmap Studio. If the app is already open, the file goes to that window (after asking about unsaved changes) instead of starting a second copy.

A project opens in a Heightmap tool with the Solid view, so the heightmap is ready to edit first. Its texture layers, objects, sky, water and grass are built the first time you open Texture Painting or the Environment tool or pick View: Environment. Saving, recovery copies, undo, builds and exports always see the whole project.

Race Data objects for game plugins are stored beside the project as YourTrack.plugin.race.json.

Sharing a project

A .hm holds the terrain, paths, channels, bumps, texture layers, masks, water and game settings, but objects, plants and HDRI skies stay in your library. To send a whole project, click Package Project (beside Save As), choose what to include (objects and vegetation, texture layers and masks, the HDRI sky, game settings) and the name shown as who packaged it. It saves one .hmz with the project as it is now, its plugin files and every object, plant, ground cover grass and HDRI sky it uses from your library. A part you leave out is left out of the packaged project too, so it opens with nothing missing, and files the project uses that could not be found are listed when you package it. Only Heightmap Studio reads a .hmz, and it is signed with your library's author key: before it opens, the app shows who packaged it (the name they gave and their author key, marked as you for your own), when, and what it holds, and a package that was changed afterwards does not open. On the other computer, double-click the .hmz or Open it: its objects, plants and skies go into that library (files it already has are not copied twice) and the project opens from the Projects folder.

Autosave and recovery

Your project file only changes when you save. A new project is not written to disk until you save: the first Ctrl S puts it in your library's Projects folder under its title, with no dialog. While you have unsaved changes, Recovery autosave keeps a copy in Projects\.recovery every 5 minutes and when you switch to another app (1, 2, 5 or 10 minutes, or Off, under Preferences > Library). If the app closes unexpectedly, the welcome screen lists that unsaved work to Restore or Discard, and opening the project asks which version you want. The copy is removed as soon as you save or choose Don't Save.

Presets and templates

Path, channel, bump, terrain and path form settings save as reusable presets or templates. Exported preset files are portable, and older preset and project files remain supported where possible. Export User Data and Import User Data in the What's New window back up and restore your saved presets, templates and app settings.

extensionWriting a plugin

A plugin teaches Heightmap Studio to build tracks for one game or engine. It is a folder with two files: plugin.json says what the plugin is and what its panels show, plugin.js turns a project into game files. You need a text editor and the app, nothing else.

How plugins work

  • Your code runs in a sandbox. plugin.js runs in a worker with no network, no filesystem and no access to the app. It receives plain data (settings, the project, pixels) and returns plain data.
  • The app does the reading and writing. Your compile() returns a build plan, a list of steps such as "write the heightmap as a 16-bit PNG" or "call my run('mask') with this layer's mask". The app runs the plan and writes the files you return.
  • Your UI is data. Panels are JSON trees of the app's own components (Section, Slider, Select, TextField...). The app draws them, so a plugin always looks native.
  • Your settings live in the project. What configure() returns is saved in the .hm under your plugin's id, with undo.
  • Content stays the app's. Terrain, paths, texture layers, objects, sky and water are made with the app's tools. A plugin reads them and translates them for its game.

Plugin Starter

A complete, commented plugin to learn from and copy. It uses every hook: panels with tabs, per-layer settings, race markers, actions, a migration, and a build that writes a RAW heightmap, layer textures and masks, the sky, objects and a track.json, with Test Build support. It also includes the MIT plugin kit (kit/), an icon template (icon-template.psd) and an AGENTS.md that tells AI coding assistants how plugins work. Install it with Install from Folder, try it, then copy it as the start of your own.

A complete example

This plugin writes a 16-bit heightmap, one grayscale PNG per masked texture layer and a track.json with the path points. Make a folder my-game with these two files.

plugin.json

{
  "id": "my-game",
  "name": "My Game",
  "version": "1.0.0",
  "apiVersion": 2,
  "platform": "desktop",
  "profile": "terrain-game",
  "game": "my-game",
  "entry": "plugin.js",
  "toolbar": [
    { "id": "textures", "label": "Textures", "icon": "texture", "panel": "textures" }
  ],
  "rightPanel": "project",
  "panels": {
    "project": {
      "tabs": [
        { "id": "track", "label": "Track", "children": [
          { "component": "Section", "title": "Track Information", "children": [
            { "component": "TextField", "label": "Track name", "bind": "info.name" },
            { "component": "StatRow", "label": "Folder", "value": "computed.folder" }
          ] }
        ] },
        { "id": "configuration", "label": "Configuration", "children": [
          { "component": "Section", "title": "Terrain", "children": [
            { "component": "Select", "label": "Terrain size", "bind": "size", "options": [
              { "value": "513", "label": "513" },
              { "value": "1025", "label": "1025" },
              { "value": "2049", "label": "2049" }
            ] }
          ] },
          { "component": "Section", "title": "Folders", "children": [
            { "component": "FolderField", "label": "Build Output", "value": "host.outputPath", "action": "chooseFolder:output" }
          ] }
        ] }
      ],
      "footer": [
        { "component": "BuildButton", "label": "Build My Game Track" }
      ]
    },
    "textures": [
      { "component": "Section", "title": "Texture Masks", "children": [
        { "component": "Toggle", "label": "Export texture masks", "bind": "masks" }
      ] }
    ]
  }
}

plugin.js

// My Game: a minimal Heightmap Studio plugin. Writes a 16-bit heightmap, one
// grayscale PNG per masked texture layer and a track.json description.
const SIZES = ['513', '1025', '2049'];
const folderName = name => String(name || '').trim().replace(/[^A-Za-z0-9 _-]/g, '').replace(/\s+/g, '_');

self.hmsPlugin = {
  // New project settings. Saved in the .hm under this plugin's id.
  configure({ resolution }) {
    return { info: { name: 'My Track' }, size: SIZES.includes(String(resolution)) ? String(resolution) : '1025', masks: true };
  },

  // Settings saved by an older version of this plugin. Fields added since are
  // filled from configure() automatically; only renames need code here.
  migrate({ settings }) {
    return settings;
  },

  // Values the panels show through `computed.*`.
  computed({ settings }) {
    return { folder: folderName(settings.info?.name) || '(name the track)' };
  },

  // The build plan. Called when the build window opens (a settings check:
  // throw to stop, warnings are listed) and again for the real build.
  compile({ config, dimensions, snapshot, environment }) {
    const name = folderName(config.info?.name);
    if (!name) throw new Error('Give the track a name');
    const size = environment.quick ? Math.min(+config.size, 1025) : +config.size;
    const warnings = dimensions.metersX === dimensions.metersY ? [] : ['My Game expects a square map.'];

    const steps = [
      { type: 'height', path: 'terrain.png', format: 'png16', size },
      { type: 'run', fn: 'info', label: 'Writing track info', params: {
        name: config.info.name, size,
        meters: { x: dimensions.metersX, y: dimensions.metersY, z: dimensions.metersZ },
        tracks: snapshot.tracks.filter(t => t.track).map(t => ({ name: t.name, points: t.track.points.map(p => [p.xM, p.zM]) })),
      } },
    ];
    if (config.masks) {
      snapshot.textureLayers.forEach((layer, i) => {
        if (layer.base) return;
        steps.push({
          type: 'run', fn: 'mask', label: `Exporting the ${layer.name} mask`, release: true,
          params: { path: `masks/${i}.png`, size },
          inputs: { mask: { kind: 'paintMask', layer: layer.id, width: size, height: size } },
        });
      });
    }
    return { name, warnings, steps };
  },

  // One `run` build step. Returns the files to write into the build.
  run({ fn, params }, inputs) {
    if (fn === 'info') {
      return { files: [{ path: 'track.json', text: JSON.stringify(params, null, 2) }] };
    }
    if (fn === 'mask') {
      const mask = inputs.mask, rgba = new Uint8Array(mask.length * 4);
      for (let i = 0; i < mask.length; i++) rgba.set([mask[i], mask[i], mask[i], 255], i * 4);
      return { files: [{ path: params.path, image: { width: params.size, height: params.size, rgba } }] };
    }
    throw new Error(`Unknown build step ${fn}`);
  },
};

Install and test it

  1. Open a project with terrain, a Pathway and a couple of Texture Painting layers.
  2. Open Plugins (R) and choose Install from Folder. Pick my-game. The app checks the manifest and calls configure() once before installing, so most mistakes show up here.
  3. Choose My Game. Its dock shows the Configuration tool, and the right panel shows the Track section.
  4. Build. Choose an output folder in Configuration, click Build My Game Track, then Full Build. The output folder gets My_Track/ with terrain.png, track.json and masks/.
lightbulb

To change the plugin, edit the files and Install from Folder again: the new copy replaces the old one. A throw in compile() shows in the build window, a throw in run() fails the build and its Log tab names the step, and errors from action() or computed() show as a message at the bottom of the app.

inventory_2Plugin package

FileWhat it is
plugin.jsonThe manifest, at most 64 KB.
plugin.jsThe script named by entry, at most 2 MB, one self-contained script.
icon.svgOptional catalog and dock icon, square, 256 x 256 px: PNG, JPEG or SVG (SVG at most 64 KB).
anything elseFiles your build copies: templates, textures, tools.

Install from File takes a .zip of the folder. The app copies the package into your user library's Plugins/<id>/ and loads it from there on every launch.

One script, no imports

The app runs plugin.js as a classic script, so it cannot import other files, and it must set self.hmsPlugin to an object holding your hooks. Write one file, or write modules and bundle them into one IIFE with any bundler:

npx esbuild src/entry.js --bundle --format=iife --minify --outfile=plugin.js

Small data can be bundled into the script. Large files belong in the package folder and reach the build through a copy step from the plugin folder.

Manifest fields

FieldWhat it is
idRequired. Lowercase letters, digits, . and -, starting with a letter. Installing another package with the same id replaces it.
nameRequired. Shown in the Plugins window and the dock.
versionRequired. Numbers only, such as 1.0.0, compared part by part.
apiVersion, platform, profileRequired: 2, "desktop", "terrain-game".
entryRequired. The script file, for example "plugin.js".
gameYour game's id (lowercase, digits, -). Always set it: without it the app treats the plugin as MX Bikes.
toolbarRequired. 1 to 16 dock buttons, { id, label, icon, panel }. Each opens that panel on the left. The id objects is reserved for the app's Environment tool.
panelsRequired. Panel id to panel, see Plugin panels.
rightPanelA panel shown on the right while your plugin is open. Put the build button here.
iconCatalog and dock icon file in the package.
uiStarting panel state, plain values: { "tab": "track" }, read as ui.tab.
featurestrue or false flags, read in panels as features.<name>. The app acts on heightBlend and vegetationCards.
buildworkspace, tools and options, see Plugin builds.
raceMarker types for the Race Data editor.
settingsIdStore settings under another package's id, so packages for versions of one game share them.
requirementsPrograms your plugin needs besides the app, up to 8: { name, version?, url?, note? } (url an https page). The app lists them with download buttons when the plugin opens, until the user ticks Don't show again; a Button with action: "showRequirements" shows them again.
minAppVersionPublished plugins: the oldest app version that may install it.
onOpenAn action id to run each time a project opens in your plugin, for upgrades that need the project.

Toolbar icons are any Material Symbols name, such as "light_mode", or an SVG file in the package, drawn in the app's icon colour.

codePlugin hooks

Hooks are the functions on self.hmsPlugin. Only configure is required. A hook may be async, gets one plain object (run and action also get the inputs) and returns plain data. Return big data as typed arrays (Uint8Array, Float32Array): they move without copying.

HookCalled whenGetsReturns
configureInstall check; a project first opens your plugin{ resolution }The starting settings
migrateA project saved with an older version of your plugin opens{ settings, fromVersion }The upgraded settings
computedShortly after settings or the project change{ settings, project, tracks, textureLayers, maskLayers, sky }Values for computed.* paths
actionA plugin:<id> button or field; Race Data{ id, settings, item, value, params, inputKeys, project }, inputs{ patch, message, select, files, need }
compileThe build window opens (a settings check), and on Test or Full Build{ config, dimensions, snapshot, environment }{ name, warnings, steps, exclude }
runEach run step of a build{ fn, params, results }, inputs{ files, continue, report }

The worker stays alive between calls, so module variables last through a build. Time limits: compile 2 minutes, run 10 minutes a step, action 1 minute, others 30 seconds.

Settings versions

The app stores your plugin's version with the settings it saved. Settings from an older version go through migrate, then any field still missing is filled from a fresh configure(), so added fields need no code and only renames do. Settings from a newer version open read-only until the plugin is updated. A migrate that throws leaves them as saved.

migrate({ settings, fromVersion }) {
  if (+fromVersion.split('.')[0] < 2) {           // 2.0.0 split fogDensity into fog
    const d = settings.lighting.fogDensity;
    settings.lighting.fog = { enabled: d > 0, density: d || 0.00003 };
    delete settings.lighting.fogDensity;
  }
  return settings;
}

Computed values

What computed returns, panels read as computed.<key>: a derived file name, a size readout, or the options of a Select ("options": "computed.levels", as [{ value, label }]). tracks lists the paths as { id, name, hidden, track: { closed, lengthMeters } }.

Actions

A button or field with "action": "plugin:<id>" or "onchange": "plugin:<id>" calls action with that id. Return any of:

  • patch: { "path.in.settings": value }, applied with undo.
  • message: shown as a short notice.
  • files: [{ path, text | bytes }]. The app asks for a folder and saves them.
  • need: inputs you want first, such as { snapshot: { kind: 'snapshot' } }. The app makes them and calls again; read them as inputs[inputKeys.snapshot].
action({ id, inputKeys }, inputs) {
  const snapshot = inputs[inputKeys.snapshot];
  if (!snapshot) return { need: { snapshot: { kind: 'snapshot' } } };
  if (id === 'count-paths') return { message: `${snapshot.tracks.length} paths` };
  throw new Error(`Unknown action ${id}`);
}

view_sidebarPlugin panels

A panel is a list of nodes, or { tabs, body, footer }. A footer holds one BuildButton and nothing else. The app checks every panel on install and refuses unknown components or properties, naming the node.

Lay panels out like the bundled plugins: toolbar panels in the order Textures, Objects (object collisions), Environment (deformation, vegetation, water, sounds), Lighting, Sky, Race Data (only the ones the game has), with the icons texture, deployed_code, park, light_mode, cloud and sports_score; a right panel with a Track tab (name, folder, images, game metadata) and a Configuration tab (terrain and build resolution, a Folders section, other files the build uses), and the build button in its footer. Every top-level node sits in a Section with a Title Case title; a Section inside another Section or a list card is drawn as a tight sub-section. Fields stack one per line; a Row only wraps buttons.

Components

Every node may have when. Fields also take label, help (a tooltip), bind, value (show a different path than the one written), onchange and params.

ComponentUse
SectionA titled group: title, help, card, children.
Heading, HintA sub-heading; short explanatory text in grey (tone: info, error, path). Warnings and errors are Alerts.
AlertA message that must stand out (every warning, error, requirement or mode note), in a tinted panel with an icon: text, tone (info, success, warning, error) and an optional title.
Row, StackControls side by side (columns, wrap), or stacked.
DisclosureShow More Options: label, openLabel, children.
StatRowA label and a read-only value path.
Buttonlabel, icon, variant, full, action, params, disabledWhen.
ToggleOn or off.
Selectoptions: a list of { value, label } or a path. Values are strings.
SliderNumbers: min, max, step, unit. Commits when the user lets go.
TextFieldtype text, number or multiline. Prefer Slider for numbers.
ColorFieldA colour, #rrggbb.
FolderFieldA title over a read-only field showing the end of the chosen path, with a folder button that runs action (a chooseFolder action or pickAsset). Title it with what it holds, not a verb.
AssetField, ImagePickerA file from the user library, by accept extensions; ImagePicker shows a thumbnail, and its extra action (labelled extraText) is one more hover action while no file is picked.
RoutePickerPick a Pathway (its id).
ListEdit an array, see Lists below.
TabsTabs inside a panel, bound to a ui. value.
BuildButtonOpens the build window. Footer only.
TerrainSettingsThe project's terrain size (X, Y and the height range), editable.
RaceSetupThe app's Race Data editor, driven by your race markers.

Paths

A path with no prefix is in your settings. Prefixes reach other scopes:

PrefixWhat
none, settings.Your settings, saved with undo.
ui.Panel state, such as the selected tab. Not saved.
computed.What your computed() returned.
features.Your manifest's features.
item.The selected entry of the enclosing List.
host.Read-only app values: outputPath, toolsPath, projectPath, libraryPath, running, project, textureLayers, sky.

{scope.path} inside a path is replaced by its value: weather.{ui.weather}.fog edits whichever weather ui.weather names. name[key=value] picks an array entry by a field.

Conditions

when hides a node and disabledWhen disables it. Conditions are data, never code: eq, ne, truthy, not, and, or.

{ "component": "Slider", "label": "Fog density", "bind": "fog.density", "min": 0, "max": 1, "step": 0.01,
  "when": { "truthy": "fog.enabled" } }

Lists

A List edits a settings array, or lists a read-only host array such as host.textureLayers. Its children edit the selected entry through item. paths. display is a dropdown (the default), list or cards. Keep your own settings per texture layer by keying them with the layer's id:

{ "component": "List", "bind": "host.textureLayers", "display": "cards", "reverse": true, "children": [
  { "component": "Select", "label": "Surface", "bind": "layers.{item.id}.surface", "options": [
    { "value": "dirt", "label": "Dirt" }, { "value": "grass", "label": "Grass" }
  ] }
] }

An add entry with "action": "pickAsset" opens the file browser straight away and sends the picked path to its onchange action, which adds the entry:

"add": [{ "label": "Add File", "action": "pickAsset", "accept": ["tga", "png"], "onchange": "plugin:add-file" }]

Your action() gets the path as value and returns { patch: { files: [...settings.files, { name, file: value }] }, select }.

Host actions

ActionDoes
buildOpens the build window.
chooseFolder:outputChoose the build output folder (host.outputPath).
chooseFolder:toolsChoose the folder your declared tools are in (host.toolsPath).
chooseFolder:projectLink an external editor project, such as a Unity project (host.projectPath).
pickAsset, resetAssetPick a file from the user library into bind, or clear it.
setValueWrite the node's params.value to bind.
exportRawThe app's 16-bit RAW heightmap export.
showRequirementsThe window listing your manifest's requirements, with download buttons.
newTrackShotMoves the track snapshot (trackShot inputs, host.trackShot) to another seeded spot on the race route.

Folders are remembered per plugin on your computer, not in the .hm.

constructionPlugin builds

The build button opens the build window, which calls compile() as a settings check: a throw shows as the error and disables the build, warnings list under it, and no steps run. On Test Build or Full Build the app calls compile() again and runs the steps. Keep compile() cheap and do the heavy work in run steps.

  • config: your settings, plus the placed objects and plants in config.objectLibrary.
  • dimensions: { imgW, imgH, metersX, metersY, metersZ }.
  • snapshot: the project, see Project data.
  • environment: { quick, output, tools, folders, gameOutput }. quick is true for a Test Build, output the output folder's path (empty when none is set), tools which declared programs were found, folders which named folders are linked. In a project export output is the linked project folder and gameOutput the game build's output folder.

name is the folder the build makes in the output folder. A successful build replaces an earlier one of the same name; a failed build leaves it alone. Test builds are for checking scale and layout quickly: keep textures and masks at 2048 or less and leave out objects, vegetation and water. The app caps texture inputs and refuses model and water inputs in a test build.

Steps

StepThe app
write{ path, text | bytes }: writes a file. Text gets LF line endings unless keepLineEndings: true.
height{ path, format: 'png16', size }: the final terrain as a 16-bit PNG (width and height instead of size for a non-square one; at the project resolution it takes layers and scaleMeters like raw16); format: 'raw16' as 16-bit little-endian RAW at the project resolution.
copy{ roots, source, target }: copies a file from the first named folder that has it (plugin, library, tools, project).
copyTree{ root }: copies a named folder into the build.
run{ fn, params, inputs, release, label, cache }: makes the inputs, calls your run(), writes what it returns. cache: {} on a step whose only inputs are model, edfModel or file lets a later build copy its files in when nothing it was made from changed.
tool{ tool, args, expect, ... }: runs a program the manifest declares.

run returns files ([{ path, text | bytes | image }], where image is { width, height, rgba } written as PNG, or { width, height, gray16 } for a 16-bit grayscale PNG), continue (new params, the step runs again) and report ({ summary, warnings }, the build's result). Paths are relative to the build folder. Up to 1 GB of binary data a call. There is no 8-bit grayscale PNG: write the gray value into R, G and B with alpha 255. Any other format (RAW, DDS, your engine's own) you encode yourself and return as bytes.

Inputs

A run step's inputs say what the app should make; run reads them as inputs.<name>. Each is made once per build; release: true drops a step's inputs after it.

Input kindGives
heights{ size }: a Float32Array, size square, of the final terrain, 0 to 1 (times metersZ for metres), row 0 the north (top) edge, west to east.
paintTexture{ layer, map, size?, max? }: a texture layer's color or normal map as { width, height, data }, RGBA rows top down. size asks for a square power-of-two side; otherwise the longest side is capped at max (2048). It fails when the layer has no such map, so check layer.texture.image or layer.normal first.
paintMask{ layer, width, height }: a layer's mask, 0 to 255, rows top down.
snapshotThe project snapshot, in an action or a run step, so big data files can be built in run.
paintMaskNormal{ layer, width, height }: a normal map generated from a layer's mask.
file{ places, path, optional }: bytes of a file in the build or a named folder.
texture{ source, size }: pixels of an image in the user library.
model{ source }: an object's meshes, materials and physics.
audio{ path }: a sound in the build, decoded.
grassStrip, grassMeshes, grassPatchesA layer's ground cover grass as a billboard strip, FBX patches or patch geometry.
waterMesh, waterNormalsA water surface mesh; looping ripple normal maps.
precipitationThe track's rain or snow as cards with a looping flipbook.
skyPanorama, skyLightThe track sky as an equirectangular image; its light level.
trackShotA snapshot of the track for menu art (width, height, up to 4096): the Environment view from a seeded spot on the race route, looking the way the race runs. null in a Test Build or when the app cannot take one; draw your own image then.

Normal maps are OpenGL (green up); flip them for games that want DirectX. The height step writes RAW only at the project's resolution; for another size, encode it from a heights input:

// compile: { type: 'run', fn: 'raw', params: { path: 'heightmap.raw' }, inputs: { heights: { kind: 'heights', size: 1025 } } }
// run, fn 'raw': 16-bit little-endian, rows north to south.
const h = inputs.heights, bytes = new Uint8Array(h.length * 2), view = new DataView(bytes.buffer);
for (let i = 0; i < h.length; i++) view.setUint16(i * 2, Math.round(Math.max(0, Math.min(1, h[i])) * 65535), true);
return { files: [{ path: params.path, bytes }] };

Running tools

A plugin can run programs you already have, such as a game's track compiler or Unity. Declare them in build.tools; you link their folder and allow each one once before it first runs. workspace: true builds in a private temporary folder and exports only the track folder. options are controls the build window shows above Test Build and Full Build.

build.findFolders says where the build folders usually are, so the app fills in any you have not chosen: { "output": [...], "tools": [...], "project": [...] }, each a list of { base, path?, app?, version? } tried in order. base is documents, localAppData, steamApp (the install folder of Steam app app), unityEditor (the newest Unity Hub editor whose version starts with version), unityProject (the most recently opened Unity Hub project that has every file in has and none in lacks), plugin (the plugin's own folder in your library) or library (the user library itself); path is a folder inside it. A folder is used only when it exists, except a library folder with "create": true, which the app makes (for a working folder your builds fill; never put one inside plugin, which installs replace). A tool step's errorFile names a file the program may write when it fails; its text becomes the build error you see. A build replaces the folder of its track's name in the output folder; build.ownedFiles lists files your builds always write there, so a folder of that name with none of them (another mod's, in a shared mods folder) is never replaced. Set build.uniqueName to true when your game finds tracks by folder name anywhere in its mods folder, subfolders included: after a build the app warns about every other folder of the track's name in the output folder and your findFolders.output folder, since the game may load that copy instead. An export for the game's own editor is an Export Mode Select in build.options; build.projectOutput ({ "bind": "exportMode", "value": "editor", "label": "Editor Projects" }) makes that mode write into the linked project folder instead of the output folder; put its picker (a FolderField on host.projectPath with chooseFolder:project) right under the Select with a when for that mode. compile() reads the setting, gets the project folder as environment.output and the game output folder as environment.gameOutput; the export is never packaged.

build.modes adds up to two build buttons of your own between Test Build and Full Build, for a lighter or special build (MX Bikes has a Performance Build): [{ "id": "performance", "label": "Performance Build", "icon": "bolt" }]. Each is a full build as far as the app goes; compile() gets the mode's id as environment.mode and leaves out what that mode drops.

"build": {
  "workspace": true,
  "tools": { "compiler": { "label": "Track Compiler", "files": ["compiler.exe", "bin/compiler.exe"] } },
  "options": [ { "component": "Toggle", "label": "Compile shadows", "bind": "shadows" } ]
}

build.package adds Save buttons to the build window's result that pack the finished track folder into one file to share: saf (MX Simulator) or pkz (a zip holding the track folder, for PiBoSo games). A pkz plugin can add serverPackage, a Save Server button that leaves out the files a dedicated server does not need (exclude: lowercase extensions) and whose save window opens on the Desktop. packageLink adds a button that opens an https page, such as a site that locks packages. Older apps refuse a manifest with these, so set minAppVersion to 26.10.2 or later when you use them.

"package": "pkz",
"serverPackage": { "exclude": ["edf", "map", "tga", "wav", "pnt", "amb"] },
"packageLink": { "label": "Lock with iNLock", "url": "https://lock.mxb-mods.com" }

A locked plugin cannot hold programs. A plugin's own programs ship as its tools: a folder signed with the same author key into a tools file (.hmt), installed into Plugins/<id>/tools when the plugin is installed or updated from the Plugins window, or with Install from File. Declare build.toolkit and find the folder in the plugin's folder. Bump toolkit.version when the tools change. Never put data taken from a game into the tools file; MXGP 26 reads its game schemas from your running game on the first build.

"build": {
  "toolkit": { "version": "1.0.0" },
  "tools": { "builder": { "label": "My Game Builder", "files": ["MyBuilder.exe"] } },
  "findFolders": { "tools": [{ "base": "plugin", "path": "tools" }] }
}

shareProject data & sharing

The snapshot

FieldWhat
project{ filename, imgW, imgH, metersX, metersY, metersZ }.
tracksEach Pathway: { id, name, hidden, trackWidthMeters, track, start }, with track and start (the Entry Path) holding points.
textureLayersVisible Texture Painting layers, bottom to top: { id, name, base, opacity, tileX, tileZ, texture, normal, maps, roughness, maskNormal, blend, grass }. base covers the whole map; tile sizes are metres.
maskLayersEvery layer, hidden ones too, for settings that pick a mask.
jumpsPlaced Path Forms.
rutsVisible Channels as groove centre lines, one per rut of a multi-rut: { id, name, lane, lanes, widthMeters, depthMeters, points }, with path points about every metre along the rut floor.
skyThe track sky: type, sun direction, HDRI or procedural settings.
waterLakes and flowing water.
objectsEvery Environment object placed, by item id. See Placed objects below.

Coordinates, heights and headings

Builds use the game frame: x east from the left edge, z north from the bottom edge, y up, metres, with the heightmap's first and last samples on the map's edges. Objects, water and race markers are already in it.

warning

Path points are not in the game frame: they carry pixel xPx / yPx (image rows, y down). Convert them with the function below. A path is { closed, points }, sampled about every 2 m along the drawn spline, and trackWidthMeters is the full width.

const toGame = (p, d) => ({ x: p.xPx * d.metersX / (d.imgW - 1), z: d.metersY - p.yPx * d.metersY / (d.imgH - 1) });
  • Heights: metres are the 0 to 1 value times metersZ. baseFloorMeters is the editor's sculpt floor; never add it.
  • Headings: degrees, clockwise from north seen from above (0 faces +z, 90 faces +x). An object's ry turns its own +z axis to that heading; rx is pitch and rz roll.

Placed objects

config.objectLibrary lists the objects (models, groups, arrays, scatters, plants), and the app has already worked out where every copy goes. snapshot.objects[item.id] holds, per item:

  • placements: every copy, { name, file, x, y, z, rx, ry, rz, scale, collision } in the game frame (rotations in degrees, ry the heading).
  • error: set instead of placements when the item can't be placed (off the map, a bad scale). Throw it if you build that item.
  • members: for a group, its objects with a local matrix and physics (collisionShape, moveable, weight, invisible), else null.
  • cards: for a plant with a Cards level, the same for that lighter version, for games that draw plants as planes.

Library items have id, name, file (relative to the user library), enabled, mode (free, repeat, scatter) and treeWall (true for a plant that is a picture of a tree line: it never has cards; keep it out of your game's wind and light its leaves by their own facing, not round a tree's crown). Plants may carry a billboard for far away: generator.impostor (generated plants, cells named by generator.models) or impostor (imported models, cells named by its own models, object keys); both are one atlas of side views, cell k at column k % cols, row k / cols, sizes[k] metres square with the plant's foot on the cell's bottom row. Skip an imported one whose models miss an object the item shows. Either may also carry octa, an octahedral impostor (views from every side over the upper hemisphere, for games that can pick the view facing the camera). An item is a group when Array.isArray(item.objects); a group's placement file is its main model, and each member names its own file and key with a 4 x 4 column-major matrix (three.js order) in the group's frame. scale is one uniform number.

Ship a model with { type: 'copy', roots: ['library'], source: item.file, target } (and its textures the same way), or read its geometry, materials and images with a model input ({ kind: 'model', source: item.file, item: item.id }) to convert it.

// Every copy of every enabled object, as game-frame records.
const records = [];
for (const item of config.objectLibrary || []) {
  if (item.enabled === false) continue;
  const entry = snapshot.objects[item.id];
  if (entry.error) throw new Error(entry.error);
  for (const p of entry.placements) records.push({ file: p.file, x: p.x, y: p.y, z: p.z, heading: p.ry, scale: p.scale });
}

An app from before snapshot.objects existed leaves it out: check for it and throw a clear message ("Update the app").

The plugin kit (MIT, in the Plugin Starter's kit/ folder) has object helpers you may copy into your plugin: objectPhysics (an object's collision, resolved from its group), groundHeight(snapshot, x, z) and objectBend (bending a mesh along a path for Connected arrays) and bentRuns (cutting a bent run into chunks of one model each, merging their parts except Moveable and Box / Convex ones).

Race data

To place timing gates, start grids, spawn points or cameras, declare marker types in the manifest's race and put { "component": "RaceSetup" } in any panel. The editor is the app's; your manifest says which markers exist, how they attach and which are required.

"race": {
  "types": [
    { "id": "spawn", "label": "Spawn Point", "icon": "person", "anchor": "track", "letter": "S", "color": "120,190,255", "rotation": true }
  ],
  "required": [{ "type": "spawn", "label": "Spawn Point", "count": 1 }],
  "settings": {},
  "setup": [{ "component": "RoutePicker", "label": "Path", "bind": "raceOverlay.settings.trackId" }],
  "help": "Create spawn points after drawing a Pathway."
}
Type optionWhat
anchortrack (on the route, with side and offset), start (along the Entry Path), junction (where the Entry Path meets the track), edge (left or right track edge) or free (near the route, offset sideways).
rotation, coverage, timing, hideIdleTurnable; drawn as a line across the track ({ width }); moves with the other timing markers; icon only when selected or hovered.
faces: "track"Your game turns it toward the track by itself: the map shows a line and arrow from it to the track point beside it (use it instead of rotation).
slotsRepeated positions from race settings: layout row, stalls or along, with count, spacing, rowSpacing, columns, rows, flip naming race settings, and numbered. rows splits count into rows back from the marker and wins over columns.
placeedge: a click places a free marker on the track edge on the clicked side, its default offsetMeters further out.
defaults, fields, tipA new marker's values; panel nodes for its own values (item. paths); hover text.
iconflag, grid, pit, pitboard, timer, alert, person, camera or board, with letter and color ("r,g,b").

race.required and race.maximum show in the editor but do not stop a build: check them in compile. The editor stores markers in your settings as raceOverlay: { settings, entities }. Each entity is { id, type, trackId, t, side, offsetMeters, rotation, ... }: t runs 0 to 1 along the route's sampled points (startT along the Entry Path for start markers), side is left, right or center, offsetMeters moves it sideways (positive to the right of the driving direction) and rotation is degrees added to the path's heading.

// A track-anchored marker in the game frame (toGame from Coordinates above).
function markerPosition(marker, route, d) {
  const pts = route.track.points, f = Math.min(1, Math.max(0, marker.t || 0)) * (pts.length - 1);
  const i = Math.min(Math.floor(f), pts.length - 2), u = f - i, a = toGame(pts[i], d), b = toGame(pts[i + 1], d);
  const heading = Math.atan2(b.x - a.x, b.z - a.z), half = route.trackWidthMeters / 2;
  const lat = (+marker.offsetMeters || 0) + (marker.side === 'left' ? -half : marker.side === 'right' ? half : 0);
  return { x: a.x + (b.x - a.x) * u + Math.cos(heading) * lat, z: a.z + (b.z - a.z) * u - Math.sin(heading) * lat,
    headingDegrees: heading * 180 / Math.PI + (+marker.rotation || 0) };
}

The editor calls your action with race-defaults (Create or Reset Race Setup: return { race: { settings, entities } } for the route in raceOverlay.settings.trackId, asking for the snapshot first with need) and race-check (return { message } or throw).

Markers your plugin lays out. race.generate ({ types, settings, action }, or a list of them, action starting race-) is for markers the game wants spread along the route, such as checkpoints every so many metres. When one of the race settings named there changes in the Setup tab, the editor calls action (after a short pause, not on every slider step) and replaces the route's markers of types with the { entities } you return. Markers of other types and other routes are kept, and the user can still move or delete each one.

"generate": { "types": ["checkpoint"], "settings": ["checkpointSpacing", "checkpointMargin"], "action": "race-generate" }

Sharing your plugin

  • As a folder or zip. Others use Install from Folder or Install from File. Updates work the same way.
  • Locked. Plugins > Compile Plugin seals a finished folder into one .hmp file, signed with your library's author key in Plugins/.author/. Back that key up: an installed locked plugin only accepts updates signed by the same key. Locking deters casual copying; it is not strong protection. Programs go in the plugin's tools file instead.
  • In the app's catalog. The Available list shows plugins published by Heightmap Studio. Ask on Discord to have yours listed.

Published plugins follow section 5 of the Terms of Use: no malware or hidden data collection, no circumventing licensing, and no extracting the app's code, assets or other people's locked plugins.

Not available yet

  • Plugins cannot draw in the 3D view or add their own editing tools. Race markers are the one placed shape.
  • Outside an AI assistant's developer tools, there is no dev mode: install again after each change.

smart_toyAI assistant (MCP)

The app can run a local MCP server, an open standard any AI client can use (Claude, ChatGPT, Codex, Cursor, VS Code, Gemini CLI and others), so an assistant can read the running app while it helps you write a plugin. It sees what your plugin sees, from the app itself, so it works from the real contract and the real data instead of a guide that may be behind. Your plugin needs nothing extra for this: no manifest field and no hook.

Turn it on

  1. Preferences > AI Assistant, then switch on MCP server.
  2. Give your client the server in whichever form it asks for: Copy Address and Copy Token for a server URL and bearer token, Copy Server Settings for JSON settings that connect to a server address, or Copy Program Settings for a client that only starts a program (the app's own executable runs as a small relay, no extra install).
  3. Keep the app running. The assistant reaches it only while it is open.

Clients that offer prompts list three starting points: new_plugin, upgrade_plugin and debug_build.

What it can do

  • Read the contract. get_plugin_api (components, host actions, input kinds, feature flags, manifest fields, limits, and what changed in each app version) and plugin_upgrade_report (what your plugin uses, and what it could take up).
  • Read the project as your plugin does. get_project, get_layout, sample_heights, get_map_image, get_plugin_input (exactly what compile() receives) and get_build_input (heights, masks and textures as build steps receive them).
  • Run your hooks without changing anything. check_build (your compile() plan or its error), get_plugin_computed, and call_plugin_action, a dry run that returns your action's answer but never applies the patch or saves files. Inputs an action asks for with need are not produced in a dry run.
  • With Plugin developer tools on (a second switch in the same tab): validate_plugin checks a folder as Install from Folder would, load_dev_plugin runs your plugin straight from its folder for the session (it stands in for an installed copy with the same id until the app restarts), reload_plugin picks up your edits, and run_build / get_build_log run a Test or Full Build into your output folder. You approve any program the build runs, as always.

Good to know

  • The project is read-only to the assistant. It cannot edit terrain, paths, layers or settings.
  • Work from your plugin's folder. Locked .hmp plugins are only listed, never run or read.
  • Open your plugin once in the Plugins dock before asking about its settings, so the project has them.
  • What the assistant reads (heights, map images, settings) goes to your AI provider, as if you pasted it into a chat.
warning

The assistant can read every plugin's settings in the project, so never store passwords or keys in plugin settings. The token in the copied settings works like a password: New Token replaces it, then copy the settings again.

keyboardKeyboard shortcuts

Tools

GTerrain (last tool selection)
DTerrain: Sculpt
TPath tool
JPath Forms tool
BChannels in freehand Draw mode
PChannels in Pen mode
KBumps
SSculpt Smooth mode
WPonds & Rivers
RPlugins: choose a game plugin

Canvas and editing

FFit the canvas to the available window
[ ]Resize brush tools, or resize both channel widths while drawing channels
SpaceTemporarily pan the canvas
ScrollZoom toward the cursor
ShiftRaise or lower a path point while dragging, snap new anchors, flip channel side while drawing, restore while masking, invert supported sculpt modes, adjust path form length while dragging
Ctrl dragBank a path point up or down
Alt dragAdjust path width at a point, or duplicate a path form
DeleteRemove selected path anchors, or the selected channel and bump layers
EnterApply an active Pen path
EscCancel an active Pen path
BackspaceRemove the last Pen point

Project

Ctrl ZUndo. In Pen mode, first steps back through pen edits
Ctrl YRedo (also Ctrl Shift Z)
Ctrl SSave the editable .hm project file
Ctrl CCopy the selection of the open tool: objects, channels and bumps, path forms, texture layers, mask layers, ponds and rivers, or lakes
Ctrl VPaste what you copied, in the same tool. Copies land beside the original (2 m on, or beside a pond, river or lake), and each paste steps on from the last
Ctrl DDuplicate the selection of the open tool, beside the original

helpFAQ & licensing

Is it free?

Heightmap Studio is free for personal use, including private projects and free community releases. Commercial use requires a paid license: paid tracks, commissioned builds, client work, subscriber-only or supporter-only releases, paid packs, studio work, free tracks used in a paid series or event, and any project where the track, asset, service or access is sold or monetized. A commercial license is $19.99 per user per year, see Pricing. The full rules are in the Terms of Use.

Which games does it target?

Heightmap Studio is built for motocross, BMX and mountain bike games, but it is game agnostic. You choose the map size and real-world dimensions, and the true 16-bit PNG export works with any game or engine that reads grayscale heightfields. Game plugins handle building straight into a specific game.

Windows says the installer is blocked

The installer is unsigned for now. Right-click the downloaded file, open Properties, tick Unblock under the General tab and click Apply. See Getting started.

Does a slider change my existing channels?

Only when a layer is selected. With nothing selected the sliders set the shape for the next stroke. Select a layer, or several, and the same sliders reshape them live.

Where do I get help?

The in-app help (the question mark in the header) covers the same ground as this page, and the Discord is the place for questions, bug reports and track sharing.