Introduction

Instant Organic Caves (IOC) is a lightweight purist C++ voxel engine designed to bypass the limitations of Blueprint execution and traditional static meshes.

Unlike marketplace assets that assemble pre-made rocks, IOC generates geometry mathematically at runtime using FDynamicMesh3 and custom cellular automata algorithms. The result is a single, seamless, watertight mesh that spans for infinity without seams, texture stretching, or collision holes.

⚡ Pure C++ Performance

No graph editors. No interpreted logic. Direct memory manipulation for sub-second generation times.

🌊 Seamless Infinite Worlds

World-Space Perlin Noise ensures that every chunk connects perfectly to its neighbor.

Quickstart

Get your first cave generated in under 30 seconds.

1. Place the Actor

Compile the plugin. In the Unreal Editor Search Classes bar or Place Actors panel, search for IOC.

Drag IOCProceduralActor into your viewport.

📦

Immediate Feedback

The actor uses PostEditChangeProperty. As soon as you drop it or change a value, the cave regenerates instantly in the editor.

2. Basic Configuration

Select the actor and look at the Details Panel under IOC Generation.

Grid Size: Set to 60. (Defines resolution)
Noise Scale: Set to 2500.0. (Defines tunnel width. Lower = chaos, Higher = wider caves)
Voxel Size: Set to 100.0. (1 meter cubes)

IOCProceduralActor

The core building block of the system. This actor handles the math pipeline.

The Generation Pipeline

IOC does not use standard Marching Cubes. It uses a custom pipeline to achieve a stylized, organic look while maintaining topology that supports Laplacians.

World-Space Perlin Field:
We sample 3D noise using coordinate jitter to avoid "Integer Lattice" artifacts (zebra striping). Coordinates are divided by NoiseScale.
```
float Noise = FMath::PerlinNoise3D((WorldPos + Jitter) / Scale);
```
Linear Vertex Cache:
A cached vertex grid ensures that adjacent voxels share vertices ("Welding"). This prevents the mesh from shattering into individual cubes during smoothing.
Face Culling:
The mesher only generates triangles when a Solid voxel touches an Empty voxel. This creates a hollow shell with no internal geometry.
Laplacian Smoothing:
The algorithm iterates over the welded mesh, pulling vertices toward the average of their neighbors. This turns the blocky grid into smooth, eroded rock.

Infinite Generation

Using the IOCWorldGenerator manager class.

To create an endless world, delete your manual actors and drag in the IOCWorldGenerator. It manages a grid of chunks around the player.

Property	Recommended	Description
ChunkClass	BP_IOC_Cave	A Blueprint child of `IOCProceduralActor` with your material set.
RenderDistance	2 or 3	How many chunks to spawn in each direction (Radius). 2 = 5x5 grid.
UpdateInterval	0.5s	How often to check if the player moved to a new coordinate.

Noise & Scale Guide

Understanding the relationship between Voxel Size and Noise Scale is critical to avoiding artifacts.

✅

Scale 2500+

Large, majestic caverns. The noise frequency is low enough that multiple voxels form continuous walls.

❌

Scale < 500

White Noise Artifacts. If the scale is too close to the voxel size (100), the noise changes randomly every single block. This creates isolated floating cubes ("Confetti") that shatter when smoothed.

Organic Smoothing

IOC uses a custom "Vertex Jitter + Relaxation" pass to create rock-like surfaces.

Parameters

Surface Roughness Adds random Perlin offset to vertices before smoothing.
0.0 = Flat mechanical walls.
1.0 = Maximum safe jaggedness.
Smooth Iterations How many times the relaxation kernel runs.
0 = Minecraft (Blocky).
3 = Chiseled Rock.
10 = Melted Wax / Alien Hive.