Introduction

Instant Organic Caves (IOC) replaces static asset packs with pure mathematics. It generates seamless, watertight, and infinitely varied tunnel networks using advanced 3D Perlin Noise algorithms, running asynchronously on the CPU.

Quickstart & Demo

IOC includes a complete "Game Ready" demo scene generator.

Manual Setup

1. Open the Place Actors panel and search for IOC.

2. Drag IOCProceduralActor into the level.

3. In the Details Panel, configure your Generation Bounds and Voxel Size.

Procedural Actor

The core component for manual generation. Configure bounds, voxels, and smoothing here.

UX & Presets

New in v1.1: Intelligent tools to speed up your workflow.

Perlin Tunnels

Enable bGenerateTunnel to switch from "Blob Mode" to "Tunnel Mode". This connects two points with a guaranteed organic path.

Textures & Content

IOC now comes with built-in content and automatic UV generation.

Triplanar Projection

The system automatically generates UV coordinates for the procedural mesh using a Box Mapping (Triplanar) strategy. UVs are projected based on the dominant normal (X, Y, or Z) of each face.

Included Assets

A Python Automation Script generates optimized assets on first run (or manually via IOC_Setup.py).

• BP_IOC_Cave: A Blueprint wrapper for easy drag-and-drop usage.
• MI_IOC_CaveWalls: A customized Material Instance ready for rock textures.
• TextureTiling: Controls the scale of the UVs. Default is 0.01.

PCG Integration

The IOC Voxel Core PCG node brings this logic into the Procedural Content Generation framework.

The node now supports a Generation Mode switch:

• Cellular Automata: The classic "Game of Life" cave generation logic (Random noise + neighbor smoothing).
• Perlin Tunnel: The new distance-field based tunnel generation logic, matching the Actor implementation.

This allows you to generate point clouds representing cave walls inside your PCG graphs, enabling the spawning of instanced meshes, foliage, or lights along the cave surface.

Performance: Async Generation

Generating millions of voxels and triangulation is computationally expensive. IOC creates a background task (EAsyncExecution::ThreadPool) for all heavy math.

Static Mesh Baking

While UDynamicMeshComponent is powerful for runtime editing, for shipping games you often want Static Meshes to leverage Nanite and Lumen fully.

IOC includes a Bake To Static Mesh button in the Details panel (Editor Only). This allows you to freeze the current procedural result into a permanent asset in your Content Browser.

The Math 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.

1. 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);

2. 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.

3. Face Culling:

   The mesher only generates triangles when a Solid voxel touches an Empty voxel. This creates a hollow shell with no internal geometry.

4. 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.

Noise & Scale Guide

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

Organic Smoothing

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

Parameters

• Smooth Iterations How many times the relaxation kernel runs.
  0 = Minecraft (Blocky).
  3 = Chiseled Rock.
  10 = Melted Wax / Alien Hive.

Troubleshooting & FAQ

Procedural generation is a balancing act. This guide covers common artifacts.