Introduction
MATH NOT MESHES
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.
Generation runs on background threads. No frame hitches, no UI lag, even at high resolutions.
Generate organic, winding tunnels connecting any two points in 3D space automatically.
Quickstart & Demo
IOC includes a complete "Game Ready" demo scene generator plus a capture-ready marketplace showcase.
🚀 Instant Demo Command
- Open Output Log or Console (
~) - Type:
IOC.SpawnTunnelDemo - Press Enter
What happens?
1. A procedural Perlin Tunnel spawns connecting (0,0,0) to (3000, 1500, 800).
2. A complete lighting rig (Sun, Sky, Fog, PostProcess) is created.
3. A playable 3rd Person Character with a Flashlight is spawned and possessed.
You can immediately walk around and explore the generated geometry.
Capture-Ready Showcase
- Open Window > IOC Setup Wizard...
- Click Create Starter Level to create or open
/Game/IOC_Showcase - Press Play
The showcase uses polished captions instead of debug HUD text, avoids external Fab asset paths, runs the real streaming manager, and ends on live generation metrics plus a bake-ready mesh.
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.
The Setup Wizard
The Setup Wizard has been completely reimagined in native C++ to serve as the single source of truth for your IOC configurations, removing any reliance on fragile Python scripts.
Wizard Workflows
- Welcome & System Health The wizard opens with a real-time snapshot of your project's readiness, highlighting any missing dependencies before you even start generating geometry.
- One-Click Starter Levels Quick Start actions allow you to instantly generate the "IOC_Showcase" map or a basic playground level without manually placing actors or compiling blueprints.
- Preset-to-Custom Bridge Start with a preset (e.g., Alien Hive, Tight Crawl), preview the math parameters, and seamlessly break them out into custom variables for advanced tuning.
Automated Showcase & Flythrough
The Cinematic Showcase is a multi-stage flythrough designed to present the full power of Instant Organic Caves without user input. It handles streaming, PCG scattering, and complex asynchronous generation automatically.
Robust Generation Pipeline
The showcase is powered by an extremely robust pipeline. Because caves generate asynchronously on background threads, the showcase camera utilizes a Readiness Guard. It intelligently waits at the start of the sequence until all 8 procedural actors have finished their intense background math (or hits a fallback timeout).
Showcase Launcher Actor
To start the sequence, place an AIOCShowcaseLauncher actor in your level. Select it, and look in the Details Panel for Call In Editor buttons:
- Start Showcase: Standard run with UI and diagnostics.
- Start Capture Showcase: Clean run with immersive captions and no debug text (perfect for recording video).
- Clear Showcase: Instantly deletes all generated showcase actors and restores your viewport camera.
Need the showcase to run all day on a trade show floor? Enable the bLoopShowcase toggle on the Launcher Actor, and the sequence will seamlessly restart upon completion.
Procedural Actor
The core component for manual generation. Configure bounds, voxels, and smoothing here.
| Property | Description |
|---|---|
| GenerationBounds | Defines the X, Y, Z size of the generation volume. No longer forced to be a cube. Allows long, flat tunnels or tall shafts. |
| VoxelSize | The size of each processing cube. Default: 100.0 (1m). |
| NoiseFrequency | Controls the scale of the organic noise features. Lower values (e.g. 0.005) create larger, smoother caves. |
| SmoothIterations | Applies Laplacian smoothing to the mesh vertices. Removes the "blocky" look of voxels. Default: 3. |
UX & Presets
New in v1.1: Intelligent tools to speed up your workflow.
🎛️ Cave Presets
Don't guess the math. Use the CavePreset dropdown to instantly configure the actor for specific styles:
- Large Tunnel: Wide, majestic passages (Radius 450).
- Tight Crawl: Claustrophobic, narrow squeezes (Radius 150).
- Open Cavern: Massive underground halls (Radius 1200).
👁️ Visual Debugging
Enable bShowDebugViz to see exactly where your cave will generate before you press play.
- Cyan Box: Represents the Generation Bounds.
- Green Line: Shows the guaranteed path of the Perlin Tunnel.
Perlin Tunnels
Enable bGenerateTunnel to switch from "Blob Mode" to "Tunnel Mode". This connects two points with a guaranteed organic path.
How it works
Instead of random noise, the algorithm calculates a **Distance Field** to a line segment defined by TunnelStart and TunnelEnd.
It then adds 3D Perlin Noise to the radius, creating an organic, uneven tube that is guaranteed to connect the two points.
New Parameters
- TunnelStart: Start coordinate (Local Space).
- TunnelEnd: End coordinate (Local Space).
- TunnelRadius: Base width of the tunnel.
- WallThickness: Thickness of the tunnel shell.
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
IOC ships with starter assets in plugin content, and the setup wizard can verify and focus them for first-run setup. Optional Python helpers remain available in Resources/ for manual automation.
- 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.
Result: You can drag the generation sliders in real-time or spawn massive caves during gameplay without freezing the main thread. The mesh updates visually as soon as the background task completes.
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.
-
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.
Noise & Scale Guide
Understanding the relationship between Voxel Size and Noise Frequency is critical to avoiding artifacts.
Large, majestic caverns. The noise frequency is low enough that multiple voxels form continuous walls.
White Noise Artifacts. If the frequency is too high, the noise changes randomly every single block. This creates isolated floating cubes ("Confetti") that shatter when smoothed.
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.
Visual Artifact: "Shattered Glass" or "Confetti"
Cause: High Frequency
Noise Scale is too close to Voxel Size. The math oscillates inside a single cube.
Fix: Lower NoiseFrequency to 0.01 or less.
Visual Artifact: "Minecraft / Voxel Look"
The Problem
The cave looks like stacked cubes. There are no curves, only 90-degree angles.
IOCProceduralActor Settings
Increase Smooth Iterations to 3 or 5.
Frequently Asked Questions
Why does the generation take time?
Calculating 3D volume scales cubically. A bounds of 5000x5000x2000 with voxel size 50 is millions of calculations. IOC runs this asynchronously to keep the editor responsive, but the task still takes CPU time to complete.
How do I make the cave collision work?
IOC uses Complex as Simple collision. This gives perfect accuracy matching the visible mesh.
- Ensure your Player Actor has a standard Capsule Component.
- Ensure Project Settings > Physics is not set to ignore Complex collision.