See it working before you build anything
The plugin ships two demo levels. Nothing to configure, no assets to prepare — open one, press Play.
Interactive tour — walk it
/InstantOrganicCaves/Maps/IOC_InteractiveDemo. A 264 m walk on a stone path through six feature zones, each captioned as you enter, ending in a cave you carve yourself and a portal into an endless streamed tunnel.
Showcase — watch it
/InstantOrganicCaves/Maps/IOC_DemoMap. A camera flies you through eight cave sections with captions explaining what each one demonstrates.
In the Content Browser, enable Show Plugin Content, open either map and press Alt+P. Or go through the menu: Tools › Instant Organic Caves › Open Interactive Demo (or Open Demo Map). The Setup Wizard has a button for each.
The tour, zone by zone
The demo guide walks it with pictures of every zone, and has a script for presenting it.
| Zone | What it shows |
|---|---|
| 1 · The Mouth | One cave actor dropped into a level on the Large Tunnel preset, limestone skin |
| 2 · The Winding Run | A tunnel following a hand-drawn spline; midway a biome volume flares the passage open |
| 3 · Crystal Gallery | A hall carved out of solid rock by carving components, dressed by scatter layers: crystals, stalactites, stalagmites, geodes |
| 4 · Alien Hive | Domain warp folding the noise into hive-like walls |
| 5 · Strata Canyon | Terrace steps, switched on by a second biome volume for the last stretch |
| 6 · The Forge | Sphere, box and capsule carves shaping a hall — then runtime carving: aim and click |
| → Infinite Depths | Walk into the blue crystal by the Forge's far wall: a streaming manager builds cave around you as you walk |
Controls
| Action | Keyboard & mouse | Gamepad |
|---|---|---|
| Walk | W A S D | Left stick |
| Look | Mouse | Right stick |
| Jump | Space | Bottom face button |
| Carve (in the Forge, crosshair on the rock) | Left mouse button | Right trigger |
| Leave Play-In-Editor | Esc | — |
Prefer the console? These work in any level, and each one cleans up after itself.
When you are done, IOC.ClearAllDemos removes everything any demo command
added — caves, lights, the playtest character — and leaves your level as you
found it.
Your first cave, in five steps
The Setup Wizard is the intended way in. It picks a style, previews it live, checks your project is ready, warns you if the settings are expensive, and then places a configured cave actor with lighting and a playtest character.
Open it from Tools › Instant Organic Caves, or with:
| Step | What it asks | What to do the first time |
|---|---|---|
| 1 · Welcome | Project snapshot — existing caves, validation, estimated cost | Press Validate Now, then Prepare Starter Assets |
| 2 · Choose Cave | Preset or custom, with a live preview | Take Large Tunnel; it is the most forgiving |
| 3 · Environment | Lighting, fog, playtest character | Leave everything on |
| 4 · Review | Readiness checks and a voxel budget | Fix anything red before continuing |
| 5 · Finish | Generate, then next actions | Press Play and walk around |
Changed your mind? Undo Added Actors in the wizard footer removes everything that run placed, in one click. It is safe to experiment.
Pick a shape
Five presets, and they are not just size variations — each one moves the noise and the shaping controls to a different place. Pick one below to see its real values and how big the space actually is.
Preset explorer
Cross-section drawn to scale · 1.8 m figure for referenceCustom is the sixth option. Choosing it in the wizard unlocks every value on this list, and Convert Preset to Custom copies the current preset's numbers in as a starting point rather than dropping you on defaults.
Size it safely
This is the one thing that will bite you. The generator fills your bounds with voxels, and the count is cubic — doubling the bounds is eight times the work, and halving the voxel size is another eight. A number that looks harmless can become a multi-minute build.
The calculator below is the same arithmetic the wizard's Review page runs, with the same thresholds. Use it before you type a big number into the actor.
Voxel budget
Bounds in cm · matches the wizard's preflight estimateThe six dials that matter
There are a lot of properties on the cave actor. These six do most of the work; everything else is refinement once these are right.
| Property | Does | Turn it up when |
|---|---|---|
| TunnelRadius | Half-width of the open space, in cm | The space feels cramped. 150 is a crawl, 1200 is a cathedral |
| WallThickness | Rock kept around the bore | You can see daylight through the wall, or the shell feels papery |
| VoxelSize | Grid resolution, cm per cell | Never, unless you need finer detail — lower it and cost explodes |
| NoiseFrequency | How quickly the wall shape varies | Walls look smooth and artificial. Small numbers, big effect |
| DomainWarpIntensity | Bends the noise field itself | You want organic, alien, non‑geological forms |
| TerraceSteps | Quantises height into ledges | You want sedimentary strata and walkable shelves |
Regenerating an existing cave with new settings changes its shape. If a level has been built around a particular cave, duplicate the actor before you experiment on it.
Dress the cave
Scatter layers place meshes across the generated surface as instanced geometry. The plugin ships eight props built for this, so you get a furnished cave without sourcing art:
Rocks A / B / C
Floor debris at three scales, from boulder to gravel.
Crystals A / B
Clustered formations for the lit, cyan-tinted set pieces.
Geode
A single hero prop — use it sparingly, at low density.
Stalactite / Stalagmite
Ceiling and floor spikes. Both grow from their base; with bAlignToNormal on, a ceiling's normal is what hangs a stalactite.
Each layer has a slope range that decides where its mesh can land, and this is the control
people miss. MinSlopeZ and MaxSlopeZ run from
1.0 — flat floor, through 0.0 — vertical wall, to
−1.0 — ceiling.
| To place on | MinSlopeZ | MaxSlopeZ |
|---|---|---|
| Floors only | 0.7 | 1.0 |
| Walls | −0.3 | 0.3 |
| Ceilings — stalactites | −1.0 | −0.6 |
Set Density in instances per square metre and start far lower than feels right
— 0.1 already covers a large cavern, and 0.02 is plenty for boulders.
bAlignToNormal grows each prop out of the surface along its normal: keep it on
for anything on walls or ceilings.
PoissonMinSeparation is a spacing, not a limiter. With it set, the scatter
throws thirty times the candidates and keeps every one far enough apart — so the
surface fills up to that spacing whatever Density says. A 120 cm spacing
on rocks puts one every metre or so, over every wall. Use a large spacing to thin props
out evenly, or leave it at 0 and let Density decide.
Past one cave
Once a single cave behaves, these are the systems worth learning, roughly in the order most projects need them.
Spline tunnels
Drive the bore along a spline instead of a straight line — the way to author a route rather than accept one.
Carving volumes
Cut extra space out of a generated cave in the editor, or at runtime for destructible digging. AIOCCharacter can carve where it aims once you turn on bEnableCaveCarving and tag the cave IOC_PlayerCarvable.
Biome volumes
Override parameters inside a region so one cave changes character along its length. Give them a BlendDistance so a wider radius flares in rather than stepping.
Streaming manager
Generate and release sections around the player for caves larger than memory.
PCG integration
Shipped graph nodes so cave surfaces can feed your existing PCG networks.
Bake to static mesh
Freeze a finished cave into a normal asset when you no longer need it procedural.
Each has a full section in the reference manual, which documents every property. This tutorial deliberately does not.
When it looks wrong
The failures people actually hit, and what each one really means.
Generation takes minutes, or the editor stops responding
Almost always the voxel budget. Run the numbers in chapter 4 — if it lands in High or Very high, raise the voxel size before anything else.
Generation is asynchronous, so the editor should stay usable. If it does not, the grid is large enough that the mesh build itself is the cost.
I pressed Generate and nothing appeared
Check the actor is not still building — large caves finish over several
seconds. If it stays empty, the bounds are probably smaller than
TunnelRadius + WallThickness, so there is no room for a cave
inside them.
IOC.ValidateInstallation will confirm the plugin's own content resolved
correctly.
I fall through the floor
Collision is built with the mesh, but not instantly — if you press Play the moment generation starts, the cave exists visually before it is collidable. Wait for the build to finish.
Scatter props never have collision by design. Hundreds of instanced rocks with collision would cost more than they are worth; the cave surface underneath carries it.
The lighting looks flat and grey
Lumen only accepts lights with Movable mobility. A Static or Stationary light contributes nothing to global illumination, which is exactly what a cave interior depends on.
The wizard sets this for lights it places. Lights you add yourself are yours to set.
Scatter props are not showing up
Check the layer's slope range first — a floor prop with a ceiling range has nowhere valid to land, and places nothing without complaining.
Then check Density. It is instances per square metre, so a value that
looks small is often still too small on a first attempt.
The AI will not path through my cave
A procedural surface needs the navmesh rebuilt after it generates. Place a NavMeshBoundsVolume that covers the cave and set it to dynamic generation, so it rebuilds when the geometry appears rather than once at load.
Stalactites are missing, or point up into the ceiling
Turn on bAlignToNormal for the layer. Every shipped prop grows from its
base along its own up axis, and alignment points that axis along the surface normal
— down, on a ceiling. With alignment off, props keep the world's up and a
ceiling layer grows into the rock.
A biome volume leaves a ledge or a ring in the tunnel
With BlendDistance at 0 the volume switches its overrides at its face, so
a wider radius drops the floor there in one step, and if the walls are thin the old and
new walls may not even meet. Set BlendDistance to a few metres and the
passage flares open instead.
Demo actors are cluttering my level
IOC.ClearAllDemos removes everything any demo command added, including
the playtest character and lights. The demo commands are meant to leave no residue.