Caves and cutters

The landscape is a heightfield, but you can carve into it as a volume. Volume edits are stored as 0.5 m voxels in 8 m columns, so you get real walls, overhangs, arches and tunnels with a roof. Carved ground renders and collides like the rest of the terrain, saves with the landscape, and can be dug further, blasted open or flooded.

There are four ways to carve: generate a cave system, sculpt voxels by hand, place a Terrain cutter object, or call a carve function from a script or Blueprint.

Generate caves

1. Open the Landscape workspace (Window → Landscape) and expand Caves.
2. Set the recipe.
3. Click Place caves — click the ground, then click the middle of the cave area in the viewport. Press Esc to cancel.

Entrances open on the surface, so the player can walk in. The ground on top keeps its grass and trees. The same recipe on the same ground always carves the same caves; change Seed for a different layout. Each placement is one undo step. Caves are carved into the level, so you cannot place them during Play.

Setting	Field	Panel range	Command range	Default
Area radius m	radius	8–200	8–400	60
Tunnels	tunnels	1–24	1–48	4
Tunnel length m	length	8–160	8–400	70
Tunnel size m	size	1–6	1–8	2.2
Depth m	depth	3–40	3–60	9
Caverns	caverns	0–1	0–1	0.5
Entrances	entrances	0 to Tunnels	0 to tunnels	1
Winding	winding	0–1	0–1	0.5
Rough walls	roughness	0–1	0–1	0.5
Seed	seed	—	0–4,294,967,295	1

Tunnel size is the tunnel radius; tunnels swell and narrow around it. Caverns sets how often a tunnel opens into a wide cavern. Depth is measured below the surface.

Tip

The landscape.caves command returns entrance positions, cavern floor centres, a floor point inside each tunnel, and a ready spawn position in each cavern. Use them to place loot, lights, enemies or the player start.

Sculpt voxels by hand

The Voxel sculpt section of the Landscape workspace adds or removes balls of ground.

1. Set Ball radius m (0.5–8 m, default 1.5 m).
2. Click Carve to remove ground or Add to build it up.
3. Click the ground repeatedly. Clicks also hit cave walls and overhangs, so you can shape arches and tunnels. Press Esc to stop.

Each click is one undo step.

Cut with an object

A Terrain cutter component carves the ground with its object’s collider box, or with the ball inside that box. Use it to sink a room, cut a ramp, a moat or a tunnel mouth, or put it on something that moves to make it dig.

1. Place an object and scale and rotate it to the shape you want.
2. In the Details panel, click Add Component → Terrain cutter.
3. Set the fields below.
4. Click Carve terrain now to bake the cut into the level’s ground, or Carve & remove box to bake it and delete the object. Both are undoable.

If you do not bake it, the cutter carves during Play according to When.

Field	Options or range	Default	Description
Does	Carve / Add ground	Carve	Add ground fills instead of removing
Shape	Box / Ball	Box	Ball cuts the ball inside the box. A sphere collider always cuts a ball
Round edges	0–5 m	0	Softens the cut
When	Play starts / While moving / Only when asked	Play starts	When the cutter carves during Play
Hide in game	On/off	On	Hides the object during Play. Static objects also lose their collider, so the cutter acts as a pure terrain tool
Ground toughness	0–1	0.3	While moving only. How much speed a physics body loses as it digs: 0 digs forever, 1 stops at once

New cutters pick sensible defaults: on a Dynamic physics body, When starts at While moving and Hide in game is off; on other objects the cutter carves once when Play starts and stays hidden.

Digging physics bodies

A dynamic body with a While moving cutter digs ahead of itself while it moves faster than about 3 m/s. The ground slows it according to Ground toughness, so a falling ball or meteor bores a hole on impact and stops once it slows down, instead of sinking forever. Non-physics objects with While moving carve wherever they go, which suits drills and burrowing creatures moved by scripts or animation.

Ground carved by cutters during Play is restored when you press Stop.

Example: carve a tunnel entrance into a hillside

You’ll bake a box-shaped tunnel into the side of a hill, open at the bottom of the slope and roofed further in. Start from the hilltop project built in the Landscape example: a hill centred at X 30, Z 0 whose west slope climbs from about 4 m at X 10 to 13 m at X 18.

1. Choose Add → Cube and name it Tunnel mouth.
2. In Details → Transform, set Location to 14, -1.5, 0 and Scale to 12, 3, 3. The height is relative to the ground, so the box sits 1.5 m into the slope and runs along X into the hill.
3. Click + Add Component → Terrain cutter. Leave Shape on Box and set Round edges to 1 m.
4. Click Carve & remove box. The cut is baked into the ground and the cube is deleted, as one undo step.

Fly the camera to the west side of the hill: the slope opens into a 3 m wide passage whose roof closes over it a few metres in.

Do the same from the command line, in the same project (the cube is object 1 in a project with no other objects):

feather-cli --workspace ./hill-plot --project project.feather.json command scene.add \
  --json '{"kind":"Cube","name":"Tunnel mouth","position":[14,-1.5,0]}' --save project.feather.json

feather-cli --workspace ./hill-plot --project project.feather.json command scene.update \
  --json '{"id":1,"patch":{"scale":[12,3,3],"terrain_cutter":{"shape":"Box","soften":1}}}' \
  --save project.feather.json

feather-cli --workspace ./hill-plot --project project.feather.json command landscape.carve_object \
  --json '{"id":1,"remove":true}' --save project.feather.json

Check it worked: the landscape.carve_object response has "removed": true and a cut with "half": [6.0, 1.5, 1.5]. Then read the ground heights along the tunnel:

feather-cli --workspace ./hill-plot --project project.feather.json command landscape.inspect \
  --json '{"points":[[12,0],[18,0]]}'

At X 12, inside the open mouth, the height drops from about 5.5 m to the tunnel floor at about 3.4 m. At X 18 it still reads the hill surface, about 12.7 m, because the roof is intact there.

Carve from scripts and Blueprints

Scripts can edit the ground at runtime. Every function below is also available as a Call node in Blueprints, in the Destruction group.

Function	Description
carve_box(x, y, z, width, height, depth, yaw)	Removes an oriented box of ground; yaw in degrees
fill_box(x, y, z, width, height, depth, yaw)	Adds an oriented box of ground
carve_object(id)	Carves with that object’s box, or its terrain cutter’s shape. Use it with Only when asked cutters
generate_caves(#{...})	Carves a cave system. Takes the same optional fields as landscape.caves
generate_caves_at(x, z, radius, seed)	Carves caves with the default recipe at a position
dig(x, y, z, radius, depth)	Lowers the surface and heaps the soil beside the hole
fill(x, y, z, radius, height)	Adds soil
dig_trench(x1, z1, x2, z2, width, depth)	Cuts a straight-walled trench between two points
dig_tunnel(x1, y1, z1, x2, y2, z2, radius)	Cuts a tunnel between two points
crater(x, y, z, radius, depth)	Blows a crater into the ground

// Open a cellar under this object when Play begins.
fn start() {
    let p = position();
    carve_box(p[0], p[1] - 2.0, p[2], 6.0, 4.0, 6.0, 0.0);
}

Runtime cuts rebuild only the terrain chunks they touch, and refresh fluids and navigation. For blasts, craters and destructible objects, see Destruction.

Limits

• Volume edits use 0.5 m voxels in 8 m columns, up to 4,096 columns per landscape. A column spans at most 100 m vertically.
• Craters and surface digs use a 0.5 m detail grid, up to 400,000 samples.
• A cave recipe can carve at most 4,000 m of tunnel in total (tunnels × length).
• A box cut must be 0.2–120 m on each axis. A terrain cutter’s box is clamped to that size.

Automate it

This carves a cave system centred on the origin and then bakes object 42’s terrain cutter into the ground, removing the object:

feather-cli --connect .feather-session.json command landscape.caves \
  --json '{"center":[0,0],"radius":80,"tunnels":6,"length":90,"entrances":2,"seed":11}'

feather-cli --connect .feather-session.json command landscape.carve_object \
  --json '{"id":42,"remove":true}'

Command	Purpose
landscape.caves	Carves a generated cave system and returns entrances, caverns, tunnel points and spawns
landscape.carve_object	Bakes an object’s box or terrain cutter into the ground
landscape.dig	Digs a hole, trench or tunnel; mode surface or volume, fill to add ground
landscape.crater	Blasts a crater with an optional rim and scorch
landscape.inspect	With points, returns ground heights including craters and digs
scene.update	Adds or edits a terrain_cutter on an object

landscape.reset clears craters and digs along with the other terrain edits. See Agents & automation for connecting a live session.