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
- Download the installer from the Download button. It is a single
Heightmap-Studio-setup.exe. - 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.
- Run the installer. Updates keep your presets, path form templates, license status and project files.
Your first track
- New project. Pick a map size in pixels and real-world dimensions in meters. Choose Custom terrain, Real-World capture, or Import a heightmap.
- Shape the ground. Tune the terrain generator, then switch to Sculpt (D) for hand-shaped features and erosion.
- 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.
- Place path forms (J). Click on a pathway, pick a template, drag to resize.
- Carve channels and bumps (B, P, K). Draw through corners and braking zones. Reshape any layer later from the Layers panel.
- 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.
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.
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
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.
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.
| Brush | What it does | Shift |
|---|---|---|
| Raise | Pushes terrain up. Max height stops raising at that elevation (0 = no limit). | Lowers instead |
| Lower | Pushes terrain down. Max depth is how far below the surface one stroke can dig. | Raises instead |
| Smooth S | Softens the visible surface under the brush. Uses Brush Size, Hardness and Smooth Amount. | Un-smooths |
| Flatten | Pulls terrain toward the height sampled where the stroke starts. | |
| Flatten Slope | Planes terrain along the grade under the first click, keeping the slope instead of leveling it. | |
| Ramp | Grades the band under the stroke from the start height to the end height. One stroke lays one complete ramp; Strength does not apply. | |
| Noise | Adds rough variation. Size is the feature scale in meters, Variance mixes in finer detail and uneven strength. | Inverts |
| Erosion | Water and sediment simulation on the GPU at full map resolution. Paint an area or Apply to Entire Heightmap. | |
| Clone | Copies terrain from elsewhere on the map. | Shift-click sets the source |
| Terrace | Pulls height toward flat steps. Steps sets how many levels the lowest-to-highest range is cut into. | |
| Erase Sculpt | Removes Sculpt layer changes to reveal the editable objects below. |
Shared sliders
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.
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.
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
Draw stroke
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
Shape
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.
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
Texturesfolder. 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.
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.
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.
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.
| Placement | What it does |
|---|---|
| Follow Path | Lays a grayscale image along the Pathway or Entry Path, with Repetitions (Width), Texture width and Edge fade. |
| Custom Path | The same along a path you draw with Draw Path on the canvas toolbar. |
| Fill | Covers the map with the image, with Repetitions and edge margins that keep it off the pathway, entry path and other paths. |
| Repeat | Tiles the image across the map at a Tile size in meters. |
| Terrain | Computes 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.
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
Texturesfolder 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.pngandrock_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
Masksfolder, 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.
Placement
| Placement | Settings |
|---|---|
| Free | X, Z, Rotation and Height, or a Vertical offset with Snap to surface on. Move and Scale on the canvas toolbar. |
| Path | One 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. |
| Scatter | Copies 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.
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.
| Export | Contents |
|---|---|
| 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
- Import the
.objwith Up Axis: Z and Forward Axis: Y so the guides land flat at the correct orientation. - Shrinkwrap them onto your terrain (Project, Axis Z).
- 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.jsruns 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 myrun('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.hmunder 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
- Open a project with terrain, a Pathway and a couple of Texture Painting layers.
- Open Plugins (R) and choose Install from Folder. Pick
my-game. The app checks the manifest and callsconfigure()once before installing, so most mistakes show up here. - Choose My Game. Its dock shows the Configuration tool, and the right panel shows the Track section.
- Build. Choose an output folder in Configuration, click Build My Game Track, then Full Build. The output folder gets
My_Track/withterrain.png,track.jsonandmasks/.
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
| File | What it is |
|---|---|
plugin.json | The manifest, at most 64 KB. |
plugin.js | The script named by entry, at most 2 MB, one self-contained script. |
icon.svg | Optional catalog and dock icon, square, 256 x 256 px: PNG, JPEG or SVG (SVG at most 64 KB). |
| anything else | Files 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
| Field | What it is |
|---|---|
id | Required. Lowercase letters, digits, . and -, starting with a letter. Installing another package with the same id replaces it. |
name | Required. Shown in the Plugins window and the dock. |
version | Required. Numbers only, such as 1.0.0, compared part by part. |
apiVersion, platform, profile | Required: 2, "desktop", "terrain-game". |
entry | Required. The script file, for example "plugin.js". |
game | Your game's id (lowercase, digits, -). Always set it: without it the app treats the plugin as MX Bikes. |
toolbar | Required. 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. |
panels | Required. Panel id to panel, see Plugin panels. |
rightPanel | A panel shown on the right while your plugin is open. Put the build button here. |
icon | Catalog and dock icon file in the package. |
ui | Starting panel state, plain values: { "tab": "track" }, read as ui.tab. |
features | true or false flags, read in panels as features.<name>. The app acts on heightBlend and vegetationCards. |
build | workspace, tools and options, see Plugin builds. |
race | Marker types for the Race Data editor. |
settingsId | Store settings under another package's id, so packages for versions of one game share them. |
requirements | Programs 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. |
minAppVersion | Published plugins: the oldest app version that may install it. |
onOpen | An 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.
| Hook | Called when | Gets | Returns |
|---|---|---|---|
configure | Install check; a project first opens your plugin | { resolution } | The starting settings |
migrate | A project saved with an older version of your plugin opens | { settings, fromVersion } | The upgraded settings |
computed | Shortly after settings or the project change | { settings, project, tracks, textureLayers, maskLayers, sky } | Values for computed.* paths |
action | A plugin:<id> button or field; Race Data | { id, settings, item, value, params, inputKeys, project }, inputs | { patch, message, select, files, need } |
compile | The build window opens (a settings check), and on Test or Full Build | { config, dimensions, snapshot, environment } | { name, warnings, steps, exclude } |
run | Each 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 asinputs[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.
| Component | Use |
|---|---|
Section | A titled group: title, help, card, children. |
Heading, Hint | A sub-heading; short explanatory text in grey (tone: info, error, path). Warnings and errors are Alerts. |
Alert | A 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, Stack | Controls side by side (columns, wrap), or stacked. |
Disclosure | Show More Options: label, openLabel, children. |
StatRow | A label and a read-only value path. |
Button | label, icon, variant, full, action, params, disabledWhen. |
Toggle | On or off. |
Select | options: a list of { value, label } or a path. Values are strings. |
Slider | Numbers: min, max, step, unit. Commits when the user lets go. |
TextField | type text, number or multiline. Prefer Slider for numbers. |
ColorField | A colour, #rrggbb. |
FolderField | A 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, ImagePicker | A 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. |
RoutePicker | Pick a Pathway (its id). |
List | Edit an array, see Lists below. |
Tabs | Tabs inside a panel, bound to a ui. value. |
BuildButton | Opens the build window. Footer only. |
TerrainSettings | The project's terrain size (X, Y and the height range), editable. |
RaceSetup | The app's Race Data editor, driven by your race markers. |
Paths
A path with no prefix is in your settings. Prefixes reach other scopes:
| Prefix | What |
|---|---|
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
| Action | Does |
|---|---|
build | Opens the build window. |
chooseFolder:output | Choose the build output folder (host.outputPath). |
chooseFolder:tools | Choose the folder your declared tools are in (host.toolsPath). |
chooseFolder:project | Link an external editor project, such as a Unity project (host.projectPath). |
pickAsset, resetAsset | Pick a file from the user library into bind, or clear it. |
setValue | Write the node's params.value to bind. |
exportRaw | The app's 16-bit RAW heightmap export. |
showRequirements | The window listing your manifest's requirements, with download buttons. |
newTrackShot | Moves 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 inconfig.objectLibrary.dimensions:{ imgW, imgH, metersX, metersY, metersZ }.snapshot: the project, see Project data.environment:{ quick, output, tools, folders, gameOutput }.quickis true for a Test Build,outputthe output folder's path (empty when none is set),toolswhich declared programs were found,folderswhich named folders are linked. In a project exportoutputis the linked project folder andgameOutputthe 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
| Step | The 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 kind | Gives |
|---|---|
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. |
snapshot | The 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, grassPatches | A layer's ground cover grass as a billboard strip, FBX patches or patch geometry. |
waterMesh, waterNormals | A water surface mesh; looping ripple normal maps. |
precipitation | The track's rain or snow as cards with a looping flipbook. |
skyPanorama, skyLight | The track sky as an equirectangular image; its light level. |
trackShot | A 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
| Field | What |
|---|---|
project | { filename, imgW, imgH, metersX, metersY, metersZ }. |
tracks | Each Pathway: { id, name, hidden, trackWidthMeters, track, start }, with track and start (the Entry Path) holding points. |
textureLayers | Visible 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. |
maskLayers | Every layer, hidden ones too, for settings that pick a mask. |
jumps | Placed Path Forms. |
ruts | Visible 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. |
sky | The track sky: type, sun direction, HDRI or procedural settings. |
water | Lakes and flowing water. |
objects | Every 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.
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.baseFloorMetersis 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
ryturns its own +z axis to that heading;rxis pitch andrzroll.
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,rythe heading).error: set instead ofplacementswhen 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 localmatrixand 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 option | What |
|---|---|
anchor | track (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, hideIdle | Turnable; 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). |
slots | Repeated 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. |
place | edge: a click places a free marker on the track edge on the clicked side, its default offsetMeters further out. |
defaults, fields, tip | A new marker's values; panel nodes for its own values (item. paths); hover text. |
icon | flag, 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
.hmpfile, signed with your library's author key inPlugins/.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
- Preferences > AI Assistant, then switch on MCP server.
- 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).
- 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) andplugin_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 whatcompile()receives) andget_build_input(heights, masks and textures as build steps receive them). - Run your hooks without changing anything.
check_build(yourcompile()plan or its error),get_plugin_computed, andcall_plugin_action, a dry run that returns your action's answer but never applies the patch or saves files. Inputs an action asks for withneedare not produced in a dry run. - With Plugin developer tools on (a second switch in the same tab):
validate_pluginchecks a folder as Install from Folder would,load_dev_pluginruns 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_pluginpicks up your edits, andrun_build/get_build_logrun 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
.hmpplugins 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.
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
| G | Terrain (last tool selection) |
| D | Terrain: Sculpt |
| T | Path tool |
| J | Path Forms tool |
| B | Channels in freehand Draw mode |
| P | Channels in Pen mode |
| K | Bumps |
| S | Sculpt Smooth mode |
| W | Ponds & Rivers |
| R | Plugins: choose a game plugin |
Canvas and editing
| F | Fit the canvas to the available window |
| [ ] | Resize brush tools, or resize both channel widths while drawing channels |
| Space | Temporarily pan the canvas |
| Scroll | Zoom toward the cursor |
| Shift | Raise 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 drag | Bank a path point up or down |
| Alt drag | Adjust path width at a point, or duplicate a path form |
| Delete | Remove selected path anchors, or the selected channel and bump layers |
| Enter | Apply an active Pen path |
| Esc | Cancel an active Pen path |
| Backspace | Remove the last Pen point |
Project
| Ctrl Z | Undo. In Pen mode, first steps back through pen edits |
| Ctrl Y | Redo (also Ctrl Shift Z) |
| Ctrl S | Save the editable .hm project file |
| Ctrl C | Copy the selection of the open tool: objects, channels and bumps, path forms, texture layers, mask layers, ponds and rivers, or lakes |
| Ctrl V | Paste 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 D | Duplicate 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.
